# SQLAlchemy 0.5.0 Documentation

Search:
Version: 0.5.0 Last Updated: 01/06/2009 13:41:02

# Querying

## The Query Object

`Query` is produced in terms of a given `Session`, using the `query()` function:

    q = session.query(SomeMappedClass)

Following is the full interface for the `Query` object.

class `sqlalchemy.orm.query.``Query`(entities, session=None)

  Encapsulates the object-fetching operations provided by Mappers.

  `__init__`(entities, session=None)
  `add_column`(column)
    Add a SQL ColumnElement to the list of result columns to be returned.
  `add_entity`(entity, alias=None)
    add a mapped entity to the list of result columns to be returned.
  `all`()

    Return the results represented by this `Query` as a list.

    This results in an execution of the underlying query.

  `autoflush`(setting)

    Return a Query with a specific ‘autoflush’ setting.

    Note that a Session with autoflush=False will not autoflush, even if this flag is set to True at the Query level. Therefore this flag is usually used only to disable autoflush for a specific Query.

  `correlate`(*args)
  `count`()

    Apply this query’s criterion to a SELECT COUNT statement.

    If column expressions or LIMIT/OFFSET/DISTINCT are present, the query “SELECT count(1) FROM (SELECT ...)” is issued, so that the result matches the total number of rows this query would return. For mapped entities, the primary key columns of each is written to the columns clause of the nested SELECT statement.

    For a Query which is only against mapped entities, a simpler “SELECT count(1) FROM table1, table2, ... WHERE criterion” is issued.

  `delete`(synchronize_session='fetch')

    Perform a bulk delete query.

    Deletes rows matched by this query from the database. The synchronize_session parameter chooses the strategy for the removal of matched objects from the session. Valid values are:

    False
      don’t synchronize the session. Use this when you don’t need to use the session after the delete or you can be sure that none of the matched objects are in the session. The behavior of deleted objects still in the session is undefined.
    ‘fetch’
      performs a select query before the delete to find objects that are matched by the delete query and need to be removed from the session. Matched objects are removed from the session. ‘fetch’ is the default strategy.
    ‘evaluate’

      experimental feature. Tries to evaluate the querys criteria in Python straight on the objects in the session. If evaluation of the criteria isn’t implemented, the ‘fetch’ strategy will be used as a fallback.

      The expression evaluator currently doesn’t account for differing string collations between the database and Python.

    Returns the number of rows deleted, excluding any cascades.

    Warning - this currently doesn’t account for any foreign key/relation cascades.

  `distinct`()
    Apply a `DISTINCT` to the query and return the newly resulting `Query`.
  `filter`(criterion)

    apply the given filtering criterion to the query and return the newly resulting `Query`

    the criterion is any sql.ClauseElement applicable to the WHERE clause of a select.

  `filter_by`(**kwargs)
    apply the given filtering criterion to the query and return the newly resulting `Query`.
  `first`()

    Return the first result of this `Query` or None if the result doesn’t contain any row.

    This results in an execution of the underlying query.

  `from_self`(*entities)

    return a Query that selects from this Query’s SELECT statement.

    *entities - optional list of entities which will replace those being selected.

  `from_statement`(statement)

    Execute the given SELECT statement and return results.

    This method bypasses all internal statement compilation, and the statement is executed without modification.

    The statement argument is either a string, a `select()` construct, or a `text()` construct, and should return the set of columns appropriate to the entity class represented by this `Query`.

    Also see the `instances()` method.

  `get`(ident)

    Return an instance of the object based on the given identifier, or None if not found.

    The ident argument is a scalar or tuple of primary key column values in the order of the table def’s primary key columns.

  `group_by`(*criterion)
    apply one or more GROUP BY criterion to the query and return the newly resulting `Query`
  `having`(criterion)
    apply a HAVING criterion to the query and return the newly resulting `Query`.
  `instances`(cursor, _Query__context=None)

    Given a ResultProxy cursor as returned by connection.execute(), return an ORM result as an iterator.

    e.g.:

        result = engine.execute("select * from users")
        for u in session.query(User).instances(result):
            print u

  `iterate_instances`(cursor, _Query__context=None)

    Given a ResultProxy cursor as returned by connection.execute(), return an ORM result as an iterator.

    Deprecated.

    e.g.:

        result = engine.execute("select * from users")
        for u in session.query(User).instances(result):
            print u

  `join`(*props, **kwargs)

    Create a join against this `Query` object’s criterion and apply generatively, returning the newly resulting `Query`.

    Each element in *props may be:

    > - a string property name, i.e. “rooms”. This will join along the relation of the same name from this Query’s “primary” mapper, if one is present.
    > - a class-mapped attribute, i.e. Houses.rooms. This will create a join from “Houses” table to that of the “rooms” relation.
    > - a 2-tuple containing a target class or selectable, and an “ON” clause. The ON clause can be the property name/ attribute like above, or a SQL expression.

    e.g.:

        # join along string attribute names
        session.query(Company).join('employees')
        session.query(Company).join('employees', 'tasks')

        # join the Person entity to an alias of itself,
        # along the "friends" relation
        PAlias = aliased(Person)
        session.query(Person).join((Palias, Person.friends))

        # join from Houses to the "rooms" attribute on the
        # "Colonials" subclass of Houses, then join to the
        # "closets" relation on Room
        session.query(Houses).join(Colonials.rooms, Room.closets)

        # join from Company entities to the "employees" collection,
        # using "people JOIN engineers" as the target.  Then join
        # to the "computers" collection on the Engineer entity.
        session.query(Company).join((people.join(engineers), 'employees'), Engineer.computers)

        # join from Articles to Keywords, using the "keywords" attribute.
        # assume this is a many-to-many relation.
        session.query(Article).join(Article.keywords)

        # same thing, but spelled out entirely explicitly
        # including the association table.
        session.query(Article).join(
            (article_keywords, Articles.id==article_keywords.c.article_id),
            (Keyword, Keyword.id==article_keywords.c.keyword_id)
            )

    **kwargs include:

    > aliased - when joining, create anonymous aliases of each table. This is used for self-referential joins or multiple joins to the same table. Consider usage of the aliased(SomeClass) construct as a more explicit approach to this.

    > from_joinpoint - when joins are specified using string property names, locate the property from the mapper found in the most recent previous join() call, instead of from the root entity.

  `limit`(limit)

    Apply a `LIMIT` to the query and return the newly resulting

    `Query`.

  `offset`(offset)
    Apply an `OFFSET` to the query and return the newly resulting `Query`.
  `one`()

    Return exactly one result or raise an exception.

    Raises `sqlalchemy.orm.exc.NoResultFound` if the query selects no rows. Raises `sqlalchemy.orm.exc.MultipleResultsFound` if multiple rows are selected.

    This results in an execution of the underlying query.

  `options`(*args)
    Return a new Query object, applying the given list of MapperOptions.
  `order_by`(*criterion)
    apply one or more ORDER BY criterion to the query and return the newly resulting `Query`
  `outerjoin`(*props, **kwargs)

    Create a left outer join against this `Query` object’s criterion and apply generatively, retunring the newly resulting `Query`.

    Usage is the same as the `join()` method.

  `params`(*args, **kwargs)

    add values for bind parameters which may have been specified in filter().

    parameters may be specified using **kwargs, or optionally a single dictionary as the first positional argument. The reason for both is that **kwargs is convenient, however some parameter dictionaries contain unicode keys in which case **kwargs cannot be used.

  `populate_existing`()

    Return a Query that will refresh all instances loaded.

    This includes all entities accessed from the database, including secondary entities, eagerly-loaded collection items.

    All changes present on entities which are already present in the session will be reset and the entities will all be marked “clean”.

    An alternative to populate_existing() is to expire the Session fully using session.expire_all().

  `query_from_parent`

    Return a new Query with criterion corresponding to a parent instance.

    Deprecated. Use sqlalchemy.orm.with_parent in conjunction with filter().

    Return a newly constructed Query object, with criterion corresponding to a relationship to the given parent instance.

    instance

      > a persistent or detached instance which is related to class represented by this query.

      property
        string name of the property which relates this query’s class to the instance.
      **kwargs
        all extra keyword arguments are propagated to the constructor of Query.
  `reset_joinpoint`()

    return a new Query reset the ‘joinpoint’ of this Query reset back to the starting mapper. Subsequent generative calls will be constructed from the new joinpoint.

    Note that each call to join() or outerjoin() also starts from the root.

  `scalar`()

    Return the first element of the first result or None.

        >>> session.query(Item).scalar()
        <Item>
        >>> session.query(Item.id).scalar()
        1
        >>> session.query(Item.id).filter(Item.id < 0).scalar()
        None
        >>> session.query(Item.id, Item.name).scalar()
        1
        >>> session.query(func.count(Parent.id)).scalar()
        20

    This results in an execution of the underlying query.

  `select_from`(from_obj)

    Set the from_obj parameter of the query and return the newly resulting `Query`. This replaces the table which this Query selects from with the given table.

    from_obj is a single table or selectable.

  `slice`(start, stop)
    apply LIMIT/OFFSET to the `Query` based on a range and return the newly resulting `Query`.
  `statement`
    The full SELECT statement represented by this Query.
  `subquery`()
    return the full SELECT statement represented by this Query, embedded within an Alias.
  `update`(values, synchronize_session='expire')

    Perform a bulk update query.

    Updates rows matched by this query in the database. The values parameter takes a dictionary with object attributes as keys and literal values or sql expressions as values. The synchronize_session parameter chooses the strategy to update the attributes on objects in the session. Valid values are:

    False
      don’t synchronize the session. Use this when you don’t need to use the session after the update or you can be sure that none of the matched objects are in the session.
    ‘expire’
      performs a select query before the update to find objects that are matched by the update query. The updated attributes are expired on matched objects.
    ‘evaluate’

      experimental feature. Tries to evaluate the querys criteria in Python straight on the objects in the session. If evaluation of the criteria isn’t implemented, the ‘expire’ strategy will be used as a fallback.

      The expression evaluator currently doesn’t account for differing string collations between the database and Python.

    Returns the number of rows matched by the update.

    Warning - this currently doesn’t account for any foreign key/relation cascades.

  `value`(column)
    Return a scalar result corresponding to the given column expression.
  `values`(*columns)
    Return an iterator yielding result tuples corresponding to the given list of columns
  `whereclause`
    The WHERE criterion for this Query.
  `with_labels`()

    Apply column labels to the return value of Query.statement.

    Indicates that this Query’s statement accessor should return a SELECT statement that applies labels to all columns in the form <tablename>_<columnname>; this is commonly used to disambiguate columns from multiple tables which have the same name.

    When the Query actually issues SQL to load rows, it always uses column labeling.

  `with_lockmode`(mode)
    Return a new Query object with the specified locking mode.
  `with_parent`(instance, property=None)

    Add a join criterion corresponding to a relationship to the given parent instance.

    instance
      a persistent or detached instance which is related to class represented by this query.
    property
      string name of the property which relates this query’s class to the instance. if None, the method will attempt to find a suitable property.

    Currently, this method only works with immediate parent relationships, but in the future may be enhanced to work across a chain of parent mappers.

  `with_polymorphic`(cls_or_mappers, selectable=None, discriminator=None)

    Load columns for descendant mappers of this Query’s mapper.

    Using this method will ensure that each descendant mapper’s tables are included in the FROM clause, and will allow filter() criterion to be used against those tables. The resulting instances will also have those columns already loaded so that no “post fetch” of those columns will be required.

    Parameters:

    - cls_or_mappers – a single class or mapper, or list of class/mappers, which inherit from this Query’s mapper. Alternatively, it may also be the string `'*'`, in which case all descending mappers will be added to the FROM clause.
    - selectable – a table or select() statement that will be used in place of the generated FROM clause. This argument is required if any of the desired mappers use concrete table inheritance, since SQLAlchemy currently cannot generate UNIONs among tables automatically. If used, the `selectable` argument must represent the full set of tables and columns mapped by every desired mapper. Otherwise, the unaccounted mapped columns will result in their table being appended directly to the FROM clause which will usually lead to incorrect results.
    - discriminator – a column to be used as the “discriminator” column for the given selectable. If not given, the polymorphic_on attribute of the mapper will be used, if any. This is useful for mappers that don’t have polymorphic loading behavior by default, such as concrete table mappers.

  `yield_per`(count)

    Yield only `count` rows at a time.

    WARNING: use this method with caution; if the same instance is present in more than one batch of rows, end-user changes to attributes will be overwritten.

    In particular, it’s usually impossible to use this setting with eagerly loaded collections (i.e. any lazy=False) since those collections will be cleared for a new load when encountered in a subsequent result batch.

## ORM-Specific Query Constructs

class `sqlalchemy.orm.``aliased`(cls, alias=None, name=None)

  Represents an ‘alias’ed form of a mapped class for usage with Query.

  The ORM equivalent of a `Alias` object, this object mimics the mapped class using a __getattr__ scheme and maintains a reference to a real Alias object. It indicates to Query that the selectable produced for this class should be aliased, and also adapts PropComparators produced by the class’ InstrumentedAttributes so that they adapt the “local” side of SQL expressions against the alias.

`sqlalchemy.orm.``join`(left, right, onclause=None, isouter=False)

  Produce an inner join between left and right clauses.

  In addition to the interface provided by `join()`, left and right may be mapped classes or AliasedClass instances. The onclause may be a string name of a relation(), or a class-bound descriptor representing a relation.

`sqlalchemy.orm.``outerjoin`(left, right, onclause=None)

  Produce a left outer join between left and right clauses.

  In addition to the interface provided by `outerjoin()`, left and right may be mapped classes or AliasedClass instances. The onclause may be a string name of a relation(), or a class-bound descriptor representing a relation.

## Query Options

Options which are passed to `query.options()`, to affect the behavior of loading.

`sqlalchemy.orm.``contains_eager`(*keys, **kwargs)

  Return a `MapperOption` that will indicate to the query that the given attribute will be eagerly loaded.

  Used when feeding SQL result sets directly into `query.instances()`. Also bundles an `EagerLazyOption` to turn on eager loading in case it isn’t already.

  alias is the string name of an alias, or an `sql.Alias` object, which represents the aliased columns in the query. This argument is optional.

`sqlalchemy.orm.``defer`(*keys)

  Return a `MapperOption` that will convert the column property of the given name into a deferred load.

  Used with `query.options()`

`sqlalchemy.orm.``eagerload`(*keys)

  Return a `MapperOption` that will convert the property of the given name into an eager load.

  Used with `query.options()`.

`sqlalchemy.orm.``eagerload_all`(*keys)

  Return a `MapperOption` that will convert all properties along the given dot-separated path into an eager load.

  For example, this:

      query.options(eagerload_all('orders.items.keywords'))...

  will set all of ‘orders’, ‘orders.items’, and ‘orders.items.keywords’ to load in one eager load.

  Used with `query.options()`.

`sqlalchemy.orm.``extension`(ext)

  Return a `MapperOption` that will insert the given `MapperExtension` to the beginning of the list of extensions that will be called in the context of the `Query`.

  Used with `query.options()`.

`sqlalchemy.orm.``lazyload`(*keys)

  Return a `MapperOption` that will convert the property of the given name into a lazy load.

  Used with `query.options()`.

`sqlalchemy.orm.``undefer`(*keys)

  Return a `MapperOption` that will convert the column property of the given name into a non-deferred (regular column) load.

  Used with `query.options()`.