=====================
Query-related classes
=====================

.. currentmodule:: django.db.models

This document provides reference material for query-related tools not
documented elsewhere.

``Q()`` objects
===============

.. class:: Q

A ``Q()`` object, like an :class:`~django.db.models.F` object, encapsulates a
SQL expression in a Python object that can be used in database-related
operations.

In general, ``Q() objects`` make it possible to define and reuse conditions.
This permits the :ref:`construction of complex database queries
<complex-lookups-with-q>` using ``|`` (``OR``) and ``&`` (``AND``) operators;
in particular, it is not otherwise possible to use ``OR`` in ``QuerySets``.

``Prefetch()`` objects
======================

.. versionadded:: 1.7

.. class:: Prefetch(lookup, queryset=None, to_attr=None)

The ``Prefetch()`` object can be used to control the operation of
:meth:`~django.db.models.query.QuerySet.prefetch_related()`.

The ``lookup`` argument describes the relations to follow and works the same
as the string based lookups passed to
:meth:`~django.db.models.query.QuerySet.prefetch_related()`.

The ``queryset`` argument supplies a base ``QuerySet`` for the given lookup.
This is useful to further filter down the prefetch operation, or to call
:meth:`~django.db.models.query.QuerySet.select_related()` from the prefetched
relation, hence reducing the number of queries even further.

The ``to_attr`` argument sets the result of the prefetch operation to a custom
attribute.

.. note::

    When using ``to_attr`` the prefetched result is stored in a list.
    This can provide a significant speed improvement over traditional
    ``prefetch_related`` calls which store the cached result within a
    ``QuerySet`` instance.