Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

select_related(*fields) Returns a QuerySet that will join in the named foreign-key relationships, selecting additional related objects when it executes its query.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

prefetch_related(*lookups) Returns a QuerySet that will automatically retrieve the given lookups, each in one extra batch query.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

Note that the result cache of the primary QuerySet and all specified related objects will then be fully loaded into memory.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

This means that for a large QuerySet a large ‘IN’ clause could be generated, which, depending on the database, might have performance problems of its own when it comes to parsing or executing the SQL query.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

This will raise a ValueError because of the attempt to redefine the > queryset of a previously seen lookup. Note that an implicit queryset was > created to traverse 'pizzas' as part of the 'pizzas__toppings' > lookup.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

extra(select=None,where=None,params=None,tables=None,order_by=None,select_params=None) Sometimes, the Django query syntax by itself can’t easily express a complex WHERE clause. For these edge cases, Django provides the extra() QuerySet modifier — a hook for injecting specific clauses into the SQL generated by a QuerySet.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

If that isn’t possible, put your extra() call at the front of the queryset construction so that your table is the first use of that table.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

If you are using the results of a queryset in some situation where you don’t know if you need those particular fields when you initially fetch the data, you can tell Django not to retrieve them from the database.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

using the result of annotate()) doesn’t make sense: doing so will raise an exception. The aggregated values will always be fetched into the resulting queryset. NOTE: The defer() method (and its cousin, only(), below) are only for > advanced use-cases.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

only(*fields) The only() method is essentially the opposite of defer(). Only the fields passed into this method and that are not already specified as deferred are loaded immediately when the queryset is evaluated.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

using(alias) This method is for controlling which database the QuerySet will be evaluated against if you are using more than one database. The only argument this method takes is the alias of a database, as defined in DATABASES. For example:

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

select_for_update(nowait=False,skip_locked=False,of=(),no_key=False) Returns a queryset that will lock rows until the end of the transaction, generating a SELECT ... FOR UPDATE SQL statement on supported databases.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

Evaluating a queryset with select_for_update() in autocommit mode on backends which support SELECT ... FOR UPDATE is a TransactionManagementError error because the rows are not locked in that case.

Reference QuerySet API reference QuerySet APIMethods that return new QuerySets

raw(raw_query,params=(),translations=None,using=None) Takes a raw SQL query, executes it, and returns a django.db.models.query.RawQuerySet instance. This RawQuerySet instance can be iterated over just like a normal QuerySet to provide object instances. See the Performing raw SQL queries for more information.

Reference QuerySet API reference QuerySet APIOperators that return new QuerySets

Combines two QuerySets using the SQL AND operator in a manner similar to chaining filters. The following are equivalent: SQL equivalent:

Reference QuerySet API reference QuerySet APIOperators that return new QuerySets

Combines two QuerySets using the SQL OR operator. The following are equivalent: SQL equivalent: | is not a commutative operation, as different (though equivalent) queries may be generated.

Reference QuerySet API reference QuerySet APIOperators that return new QuerySets

Combines two QuerySets using the SQL XOR operator. A XOR expression matches rows that are matched by an odd number of operands. The following are equivalent: SQL equivalent: NOTE: XOR is natively supported on MariaDB and MySQL.

Reference QuerySet API reference QuerySet APIMethods that do not return QuerySets

… are guaranteed unique, such as the primary key or fields in a unique constraint. For example: If you expect a queryset to already return one row, you can use get() without any arguments to return the object for that row: …

Reference QuerySet API reference QuerySet APIMethods that do not return QuerySets

get_or_create(defaults=None,**kwargs) aget_or_create(defaults=None,**kwargs) Asynchronous version: aget_or_create() A convenience method for looking up an object with the given kwargs (may be empty if your model has defaults for all fields), creating one if necessary.

Reference QuerySet API reference QuerySet APIMethods that do not return QuerySets

The get_or_create() method has similar error behavior to create() when you’re using manually specified primary keys. If an object needs to be created and the key already exists in the database, an IntegrityError will be raised.