From 8f5d6c77b6bbe0390b683cea649de6ad24d80fef Mon Sep 17 00:00:00 2001 From: Ng Zhi An Date: Sun, 11 Jan 2015 20:02:33 +0000 Subject: [PATCH] Fixed #23878 -- Moved Query and Prefetch documentation --- docs/index.txt | 1 - docs/ref/models/index.txt | 1 - docs/ref/models/queries.txt | 51 -------------------------------- docs/ref/models/querysets.txt | 55 +++++++++++++++++++++++++++++++++++ 4 files changed, 55 insertions(+), 53 deletions(-) delete mode 100644 docs/ref/models/queries.txt diff --git a/docs/index.txt b/docs/index.txt index f390d06dd2..5204f00085 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -67,7 +67,6 @@ manipulating the data of your Web application. Learn more about it below: * **QuerySets:** :doc:`Executing queries ` | :doc:`QuerySet method reference ` | - :doc:`Query-related classes ` | :doc:`Lookup expressions ` * **Model instances:** diff --git a/docs/ref/models/index.txt b/docs/ref/models/index.txt index 284743e7d0..c860ee2e04 100644 --- a/docs/ref/models/index.txt +++ b/docs/ref/models/index.txt @@ -14,7 +14,6 @@ Model API reference. For introductory material, see :doc:`/topics/db/models`. options instances querysets - queries lookups expressions database-functions diff --git a/docs/ref/models/queries.txt b/docs/ref/models/queries.txt deleted file mode 100644 index 283983aef3..0000000000 --- a/docs/ref/models/queries.txt +++ /dev/null @@ -1,51 +0,0 @@ -===================== -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 -` 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. diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 6784f352ed..397eea0782 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -180,6 +180,9 @@ 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. +If you need to execute more complex queries (for example, queries with ``OR`` statements), +you can use :class:`Q objects `. + exclude ~~~~~~~ @@ -215,6 +218,9 @@ In SQL terms, that evaluates to:: Note the second example is more restrictive. +If you need to execute more complex queries (for example, queries with ``OR`` statements), +you can use :class:`Q objects `. + annotate ~~~~~~~~ @@ -2843,3 +2849,52 @@ Variance extension. .. _SQLite documentation: http://www.sqlite.org/contrib + +Query-related classes +===================== + +This section 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 +` 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.