SQLAlchemy 0.3 Documentation
module sqlalchemy.orm.query
class Query(object)
Encapsulates the object-fetching operations provided by Mappers.
Given a WHERE criterion, produce a ClauseElement-based statement suitable for usage in the execute() method.
Given a WHERE criterion, create a SELECT COUNT statement, execute and return the resulting count value.
Return the count of instances based on the given clauses and key/value criterion.
The criterion is constructed in the same way as the select_by() method.
Execute the given ClauseElement-based statement against this Query's session/mapper, return the resulting list of instances.
After execution, close the ResultProxy and its underlying resources. This method is one step above the instances() method, which takes the executed statement's ResultProxy directly.
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.
apply the given filtering criterion to the query and return the newly resulting Query
The criterion is constructed in the same way as the select_by() method.
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.
Return a single object instance based on the given key/value criterion.
The criterion is constructed in the same way as the select_by() method.
apply one or more GROUP BY criterion to the query and return the newly resulting Query
Return a list of mapped instances corresponding to the rows in a given cursor (i.e. ResultProxy).
*mappers_or_columns is an optional list containing one or more of classes, mappers, strings or sql.ColumnElements which will be applied to each row and added horizontally to the result set, which becomes a list of tuples. The first element in each tuple is the usual result based on the mapper represented by this Query. Each additional element in the tuple corresponds to an entry in the *mappers_or_columns list.
For each element in *mappers_or_columns, if the element is a mapper or mapped class, an additional class instance will be present in the tuple. If the element is a string or sql.ColumnElement, the corresponding result column from each row will be present in the tuple.
Note that when *mappers_or_columns is present, "uniquing" for the result set is disabled, so that the resulting tuples contain entities as they actually correspond. this indicates that multiple results may be present if this option is used.
create a join of this Query object's criterion to a relationship and return the newly resulting Query.
'prop' may be a string property name in which it is located in the same manner as keyword arguments in select_by, or it may be a list of strings in which case the property is located by direct traversal of each keyname (i.e. like join_via()).
Return a ClauseElement representing the WHERE clause that would normally be sent to select_whereclause() by select_by().
The criterion is constructed in the same way as the select_by() method.
Given the key name of a property, will recursively descend through all child properties from this Query's mapper to locate the property, and will return a ClauseElement representing a join from this Query's mapper to the endmost mapper.
Given a list of keys that represents a path from this Query's mapper to a related mapper based on names of relations from one mapper to the next, return a ClauseElement representing a join from this Query's mapper to the endmost mapper.
Return the results represented by this Query as a list.
This results in an execution of the underlying query.
Return an instance of the object based on the given identifier.
If not found, raises an exception. The method will remove all pending changes to the object already existing in the Session. The ident argument is a scalar or tuple of primary key column values in the order of the table def's primary key columns.
Return a new Query object, applying the given list of MapperOptions.
apply one or more ORDER BY criterion to the query and return the newly resulting Query
create a left outer join of this Query object's criterion to a relationship and return the newly resulting Query.
'prop' may be a string property name in which it is located in the same manner as keyword arguments in select_by, or it may be a list of strings in which case the property is located by direct traversal of each keyname (i.e. like join_via()).
Select instances of the object from the database.
arg can be any ClauseElement, which will form the criterion with which to load the objects.
For more advanced usage, arg can also be a Select statement object, which will be executed and its resulting rowset used to build new object instances.
In this case, the developer must ensure that an adequate set of columns exists in the rowset with which to build new object instances.
Return an array of object instances based on the given clauses and key/value criterion.
- *args
- a list of zero or more ClauseElements which will be connected by AND operators.
- **params
a set of zero or more key/value parameters which are converted into ClauseElements. the keys are mapped to property or column names mapped by this mapper's Table, and the values are coerced into a WHERE clause separated by AND operators. If the local property/column names dont contain the key, a search will be performed against this mapper's immediate list of relations as well, forming the appropriate join conditions if a matching property is located.
if the located property is a column-based property, the comparison value should be a scalar with an appropriate type. If the property is a relationship-bound property, the comparison value should be an instance of the related class.
E.g.:
result = usermapper.select_by(user_name = 'fred')
Set the from_obj parameter of the query.
from_obj is a list of one or more tables.
Given a ClauseElement-based statement, execute and return the resulting instances.
Given a literal string-based statement, execute and return the resulting instances.
Given a WHERE criterion, create a SELECT statement, execute and return the resulting instances.
Like select(), but only return the first result by itself, or None if no objects returned.
Like select_by(), but only return the first result by itself, or None if no objects returned. Synonymous with get_by().
The criterion is constructed in the same way as the select_by() method.
Like selectfirst(), but throw an error if not exactly one result was returned.
Like selectfirst_by(), but throws an error if not exactly one result was returned.
The criterion is constructed in the same way as the select_by() method.
class QueryContext(OperationContext)
Created within the Query.compile() method to store and share state among all the Mappers and MapperProperty objects used in a query construction.
Accept a MapperOption which will process (modify) the state of this QueryContext.
Return a dictionary of attributes from this QueryContext that can be applied to a sql.Select statement.
class SelectionContext(OperationContext)
Created within the query.instances() method to store and share state among all the Mappers and MapperProperty objects used in a load operation.
SelectionContext contains these attributes:
- mapper
- The Mapper which originated the instances() call.
- session
- The Session that is relevant to the instances call.
- identity_map
- A dictionary which stores newly created instances that have not yet been added as persistent to the Session.
- attributes
- A dictionary to store arbitrary data; eager loaders use it to store additional result lists.
- populate_existing
- Indicates if its OK to overwrite the attributes of instances that were already in the Session.
- version_check
- Indicates if mappers that have version_id columns should verify that instances existing already within the Session should have this attribute compared to the freshly loaded value.
