Defines the Query class, the central construct used by the ORM to construct database queries.
The Query class should not be confused with the Select class, which defines database SELECT operations at the SQL (non-ORM) level. Query differs from Select in that it returns ORM-mapped objects and interacts with an ORM session, whereas the Select construct interacts directly with the database to return iterable result sets.
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.
- 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.
- entity
- a class or mapper which will be added to the results.
- alias
- a sqlalchemy.sql.Alias object which will be used to select rows. this will match the usage of the given Alias in filter(), order_by(), etc. expressions
- id
- a string ID matching that given to query.join() or query.outerjoin(); rows will be selected from the aliased join created via those methods.
Return the results represented by this Query as a list.
This results in an execution of the underlying query.
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.
compiles and returns a SQL statement based on the criterion and conditions within this Query.
Apply this query's criterion to a SELECT COUNT statement.
the whereclause, params and **kwargs arguments are deprecated. use filter() and other generative methods to establish modifiers.
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.
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.
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.
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.
apply one or more GROUP BY criterion to the query and return the newly resulting Query
apply a HAVING criterion to the quer and return the newly resulting Query.
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 or a list of string property names.
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 the first result of this Query, raising an exception if more than one row exists.
This results in an execution of the underlying query.
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 or a list of string property names.
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.
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".
This is essentially the en-masse version of load().
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.
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.
DEPRECATED. use query.filter(whereclause).all(), or query.from_statement(statement).all()
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.
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.