Reference Databases SQLite notes

SQLite does not support the SELECT ... FOR UPDATE syntax. Calling it will have no effect.

Reference

This document describes the details of the QuerySet API. It builds on the material presented in the model and database query guides, so you’ll probably want to read and understand those documents before reading this one.

Reference QuerySet API reference

Internally, a QuerySet can be constructed, filtered, sliced, and generally passed around without actually hitting the database. No database activity actually occurs until you do something to evaluate the queryset. You can evaluate a QuerySet in the following ways: Iteration.

Reference QuerySet API reference When QuerySets are evaluated

If you pickle a QuerySet, this will force all the results to be loaded into memory prior to pickling.

Reference QuerySet API reference

Here’s the formal declaration of a QuerySet: classQuerySet(model=None,query=None,using=None,hints=None)[source] : Usually when you’ll interact with a QuerySet you’ll use it by chaining filters. To make this work, most QuerySet methods return new querysets.

Reference QuerySet API reference QuerySet API

Django provides a range of QuerySet refinement methods that modify either the types of results returned by the QuerySet or the way its SQL query is executed.

Reference QuerySet API reference QuerySet API

Combined querysets must use the same model.

Reference QuerySet API reference QuerySet API

The following QuerySet methods evaluate the QuerySet and return something other than a QuerySet. These methods do not use a cache (see Caching and QuerySets). Rather, they query the database each time they’re called.

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

QuerySets 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 Custom managersCreating a manager with QuerySet methods

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 Understand QuerySets

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 Retrieve everything at once if you know you will need it

Understand select_related() and prefetch_related() thoroughly, and use them: in managers and default managers where appropriate. Be aware when your manager is and is not used; sometimes this is tricky so don’t make assumptions.

Topic guide Database access optimization Don’t retrieve things you don’t need

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 Don’t retrieve things you don’t need

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 Don’t retrieve things you don’t need

…if you only want to find out if obj is in the queryset, rather than if obj in queryset.