Encapsulates the object-fetching operations provided by Mappers.
add a SQL ColumnElement to the list of result columns to be returned.
This will have the effect of all result-returning methods returning a tuple of results, the first element being an instance of the primary class for this Query, and subsequent elements matching columns or entities which were specified via add_column or add_entity.
When adding columns to the result, its generally desireable to add limiting criterion to the query which can associate the primary entity of this Query along with the additional columns, if the column is based on a table or selectable that is not the primary mapped selectable. The Query selects from all tables with no joining criterion by default.
When tuple-based results are returned, the 'uniquing' of returned entities is disabled to maintain grouping.
- column
- a string column name or sql.ColumnElement to be added to the results.
add a mapped entity to the list of result columns to be returned.
This will have the effect of all result-returning methods returning a tuple of results, the first element being an instance of the primary class for this Query, and subsequent elements matching columns or entities which were specified via add_column or add_entity.
When adding entities to the result, its generally desireable to add limiting criterion to the query which can associate the primary entity of this Query along with the additional entities. The Query selects from all tables with no joining criterion by default.
When tuple-based results are returned, the 'uniquing' of returned entities is disabled to maintain grouping.
- entity
- a class or mapper which will be added to the results.
apply the SQL avg() function against the given column to the query and return the newly resulting Query.
apply the SQL max() function against the given column to the query and return the newly resulting Query.
apply the SQL min() function against the given column to the query and return the newly resulting Query.
apply the SQL sum() function against the given column to the query and return the newly resulting Query.
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.
Like select_by(), but only return the first as a scalar, or None if no object found. Synonymous with selectfirst_by().
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()).
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 propigated to the constructor of Query.
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.
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.
Query for a single instance using the given criterion.
Arguments are the same as select(). In the case that the given criterion represents WHERE criterion only, LIMIT 1 is applied to the fully generated statement.
Like select_by(), but only return the first as a scalar, or None if no object found. Synonymous with get_by().
The criterion is constructed in the same way as the select_by() method.
Query for a single instance using the given criterion.
Unlike selectfirst, this method asserts that only one row exists. In the case that the given criterion represents WHERE criterion only, LIMIT 2 is applied to the fully generated statement.
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.
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.
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.
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:
Accept a MapperOption which will process (modify) the state of this SelectionContext.