.. TBD

This document describes the details of the ``QuerySet`` API. It builds on the

material presented in the :ref:`model <topics-db-models>` and `database query

<topics-db-queries>` guides, so you'll probably want to read and understand

those documents before reading this one.

Throughout this reference we'll use the :ref:`example weblog models

<queryset-model-example>` presented in the :ref:`database query guide

<topics-db-queries>`.

.. TBD

Internally, a ``QuerySet`` can be constructed, filter, sliced, and generally

passed around without actually hitting the database. No database activity

actually occurs until you do something to evaluate the queryset.

QuerySet API

============

.. TBD

Though you usually won't create one manually -- you'll go through a :class:`Manager` -- here's the formal declaration of a ``QuerySet``:

Usually when you'll interact with a ``QuerySet`` you'll use it by :ref:`chaining

filters <chaining-filters>`. To make this work, most ``QuerySet`` methods return new querysets.

..TBD

Be cautious when ordering by fields in related models if you are also using

``distinct()``. See the note in the `distinct()`_ section for an explanation

of how related model ordering can change the expected results.

.. TBD

Also, note that ``reverse()`` should generally only be called on a

``QuerySet`` which has a defined ordering (e.g., when querying against

a model which defines a default ordering, or when using

``order_by()``). If no such ordering is defined for a given

``QuerySet``, calling ``reverse()`` on it has no real effect (the

ordering was undefined prior to calling ``reverse()``, and will remain

undefined afterward).

.. TBD

The only thing to be careful about when using select parameters in

``extra()`` is to avoid using the substring ``"%%s"`` (that's *two*

percent characters before the ``s``) in the select strings. Django's

tracking of parameters looks for ``%s`` and an escaped ``%`` character

like this isn't detected. That will lead to incorrect results.

.. TBD

``get()`` raises ``AssertionError`` if more than one object was found.

.. TBD

The :ref:`force_insert <ref-models-force-insert>` parameter is documented

elsewhere, but all it means is that a new object will always be created.

Normally you won't need to worry about this. However, if your model contains a

manual primary key value that you set and if that value already exists in the

database, a call to ``create()`` will fail with an ``IntegrityError`` since

primary keys must be unique. So remember to be prepared to handle the

exception if you are using manual primary keys.

.. TBD

すときのキーワード引数に使います。 As hinted at

above, this is a simplification of the algorithm that is used, but it contains

all the pertinent details. The internal implementation has some more

error-checking than this and handles some extra edge-conditions; if you're

interested, read the code.

.. TBD

The ``get_or_create()`` method has similar error behaviour to ``create()``

when you are 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.

.. TBD

Field lookups are how you specify the meat of an SQL ``WHERE`` clause. They're

specified as keyword arguments to the ``QuerySet`` methods ``filter()``,

For an introduction, see :ref:`field-lookups-intro`.

.. TBD

.. admonition:: MySQL comparisons

In MySQL, whether or not ``exact`` comparisons are case-insensitive by

default. This is controlled by the collation setting on the database

tables (this is a database setting, *not* a Django setting). It is

possible to configured you MySQL tables to use case-sensitive comparisons,

however there are some trade-offs involved. For more information about

this, see the :ref:`collation section <mysql-collation>` in the

:ref:`databases <ref-databases>` documentation.

.. TBD

This ``query`` attribute should be considered an opaque internal attribute.

It's fine to use it like above, but its API may change between Django

versions.

(The exact SQL syntax varies for each database engine.)

.. admonition:: ``__isnull=True`` vs ``__exact=None``

There is an important difference between ``__isnull=True`` and

``__exact=None``. ``__exact=None`` will *always* return an empty result

set, because SQL requires that no value is equal to ``NULL``.

``__isnull`` determines if the field is currently holding the value

of ``NULL`` without performing a comparison.

.. TBD