1413 sections across all versions Narrow to Django 6.0 (current) →
Reference QuerySet API reference QuerySet APIMethods that do not return QuerySetsupdate()
Chaining order_by() with update() is supported only on MariaDB and MySQL, and is ignored for different databases. This is useful for updating a unique field in the order that is specified without conflicts.
Topic guide Models Model inheritanceProxy models
There is no way to have Django return, say, a MyPerson object whenever you query for Person objects. A queryset for Person objects will return those types of objects.
Topic guide Making queries Retrieving objectsRetrieving specific objects with filters
QuerySet objects are lazy – the act of creating a QuerySet doesn’t involve any database activity. You can stack filters together all day long, and Django won’t actually run the query until the QuerySet is evaluated.
Topic guide Making queries Asynchronous queries
Some methods on managers and querysets - like get() and first() - force execution of the queryset and are blocking. Some, like filter() and exclude(), don’t force execution and so are safe to run from asynchronous code.
Reference
Topic guide Managers
classmethodfrom_queryset(queryset_class) For advanced usage you might want both a custom Manager and a custom QuerySet.
Topic guide Database access optimization
Understanding QuerySets is vital to getting good performance with simple code. In particular:
Topic guide Database access optimization
To avoid performance problems, it is important to understand: that QuerySets are lazy. when they are evaluated. how the data is held in memory.
Topic guide Database access optimization
When the FETCH_PEERS fetch mode is not appropriate or efficient enough, use select_related() and prefetch_related(). Understand their documentation thoroughly and apply them where needed. It may be useful to apply these methods in managers and default managers.
Topic guide Database access optimization
When you only want a dict or list of values, and don’t need ORM model objects, make appropriate usage of values().
Topic guide Database access optimization
Use defer() and only() if there are database columns you know that you won’t need (or won’t need in most cases) to avoid loading them.
Topic guide Database access optimization
…if you only want to find out if obj is in the queryset, rather than if obj in queryset.
Topic guide Database access optimization
…if you only want the count, rather than doing len(queryset).
Topic guide Database access optimization
…if you only want to find out if at least one result exists, rather than if queryset. But:
Topic guide Database access optimization
Rather than retrieve a load of objects, set some values, and save them individual, use a bulk SQL UPDATE statement, via QuerySet.update(). Similarly, do bulk deletes where possible.
Topic guide Making queries
Each time you refine a QuerySet, you get a brand-new QuerySet that is in no way bound to the previous QuerySet. Each refinement creates a separate and distinct QuerySet that can be stored, used and reused.
Topic guide Making queries
However, that’s far from all there is; see the QuerySet API Reference for a complete list of all the various QuerySet methods.
Topic guide Making queries
Use a subset of Python’s array-slicing syntax to limit your QuerySet to a certain number of results. This is the equivalent of SQL’s LIMIT and OFFSET clauses.
Topic guide Making queries
Querysets do not always cache their results. When evaluating only part of the queryset, the cache is checked, but if it is not populated then the items returned by the subsequent query are not cached.
Reference