Topic guide Managers Custom managers

A Manager’s base QuerySet returns all objects in the system. For example, using this model: …the statement Book.objects.all() will return all books in the database. You can override a Manager’s base QuerySet by overriding the Manager.get_queryset() method.

Topic guide Multiple databases Manually selecting a database

You can select the database for a QuerySet at any point in the QuerySet “chain.” Call using() on the QuerySet to get another QuerySet that uses the specified database.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

filter(*args,**kwargs) Returns a new QuerySet containing objects that match the given lookup parameters. The lookup parameters (**kwargs) should be in the format described in Field lookups below. Multiple parameters are joined via AND in the underlying SQL statement.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

exclude(*args,**kwargs) Returns a new QuerySet containing objects that do not match the given lookup parameters. The lookup parameters (**kwargs) should be in the format described in Field lookups below.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

annotate(*args,**kwargs) Annotates each object in the QuerySet with the provided list of query expressions or Q objects.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

alias(*args,**kwargs) Same as annotate(), but instead of annotating objects in the QuerySet, saves the expression for later reuse with other QuerySet methods.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

order_by(*fields) By default, results returned by a QuerySet are ordered by the ordering tuple given by the ordering option in the model’s Meta. You can override this on a per-QuerySet basis by using the order_by method.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

You can tell if a query is ordered or not by checking the QuerySet.ordered attribute, which will be True if the QuerySet has been ordered in any way. Each order_by() call will clear any previous ordering.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

reverse() Use the reverse() method to reverse the order in which a queryset’s elements are returned. Calling reverse() a second time restores the ordering back to the normal direction.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

distinct(*fields) Returns a new QuerySet that uses SELECT DISTINCT in its SQL query. This eliminates duplicate rows from the query results. By default, a QuerySet will not eliminate duplicate rows.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

values(*fields,**expressions) Returns a QuerySet that returns dictionaries, rather than model instances, when used as an iterable. Each of those dictionaries represents an object, with the keys corresponding to the attribute names of model objects.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

For example: When using values() together with distinct(), be aware that ordering can affect the results. See the note in distinct() for details.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

dates(field,kind,order='ASC') Returns a QuerySet that evaluates to a list of datetime.date objects representing all available dates of a particular kind within the contents of the QuerySet. field should be the name of a DateField of your model.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

datetimes(field_name,kind,order='ASC',tzinfo=None) Returns a QuerySet that evaluates to a list of datetime.datetime objects representing all available dates of a particular kind within the contents of the QuerySet. field_name should be the name of a DateTimeField of your model.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

none() Calling none() will create a queryset that never returns any objects and no query will be executed when accessing the results. A qs.none() queryset is an instance of EmptyQuerySet. Examples:

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

all() Returns a copy of the current QuerySet (or QuerySet subclass). This can be useful in situations where you might want to pass in either a model manager or a QuerySet and do further filtering on the result.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

union(*other_qs,all=False) Uses SQL’s UNION operator to combine the results of two or more QuerySets. For example: The UNION operator selects only distinct values by default. To allow duplicate values, use the all=True argument.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

intersection(*other_qs) Uses SQL’s INTERSECT operator to return the shared elements of two or more QuerySets. For example: See union() for some restrictions.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

difference(*other_qs) Uses SQL’s EXCEPT operator to keep only elements present in the QuerySet but not in some other QuerySets. For example: See union() for some restrictions.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

select_related(*fields) Returns a QuerySet that will “follow” foreign-key relationships, selecting additional related-object data when it executes its query.