Ticket #17794: doc_links_topic_db_queries.patch

File doc_links_topic_db_queries.patch, 11.3 KB (added by Thomas Güttler, 13 years ago)

Patch to docs/topics/db/queries.txt

  • docs/topics/db/queries.txt

     
    5353class represents a particular record in the database table.
    5454
    5555To create an object, instantiate it using keyword arguments to the model class,
    56 then call ``save()`` to save it to the database.
     56then call :meth:`~django.db.models.Model.save` to save it to the database.
    5757
    5858You import the model class from wherever it lives on the Python path, as you
    5959may expect. (We point this out here because previous Django versions required
     
    7272
    7373.. seealso::
    7474
    75     ``save()`` takes a number of advanced options not described here.
     75    :meth:`~django.db.models.Model.save` takes a number of advanced options not described here.
    7676    See the documentation for ``save()`` for complete details.
    7777
    7878    To create an object and save it all in one step see the ``create()``
     
    9595Saving ``ForeignKey`` and ``ManyToManyField`` fields
    9696----------------------------------------------------
    9797
    98 Updating a ``ForeignKey`` field works exactly the same way as saving a normal
     98Updating a :class:`~django.db.models.ForeignKey` field works exactly the same way as saving a normal
    9999field; simply assign an object of the right type to the field in question.
    100100This example updates the ``blog`` attribute of an ``Entry`` instance ``entry``::
    101101
     
    105105    >>> entry.blog = cheese_blog
    106106    >>> entry.save()
    107107
    108 Updating a ``ManyToManyField`` works a little differently; use the ``add()``
     108Updating a ``ManyToManyField`` works a little differently; use the :meth:`~django.db.models.fields.related.RelatedManager.add`
    109109method on the field to add a record to the relation. This example adds the
    110110``Author`` instance ``joe`` to the ``entry`` object::
    111111
     
    114114    >>> entry.authors.add(joe)
    115115
    116116To add multiple records to a ``ManyToManyField`` in one go, include multiple
    117 arguments in the call to ``add()``, like this::
     117arguments in the call to :meth:`~django.db.models.fields.related.RelatedManager.add`, like this::
    118118
    119119    >>> john = Author.objects.create(name="John")
    120120    >>> paul = Author.objects.create(name="Paul")
     
    127127Retrieving objects
    128128==================
    129129
    130 To retrieve objects from your database, you construct a ``QuerySet`` via a
    131 ``Manager`` on your model class.
     130To retrieve objects from your database, you construct a :class:`~django.db.models.query.QuerySet` via a
     131:class:`~django.db.models.Manager` on your model class.
    132132
    133133A ``QuerySet`` represents a collection of objects from your database. It can
    134134have zero, one or many *filters* -- criteria that narrow down the collection
     
    162162----------------------
    163163
    164164The simplest way to retrieve objects from a table is to get all of them.
    165 To do this, use the ``all()`` method on a ``Manager``::
     165To do this, use the :meth:`~django.db.models.query.QuerySet.all` method on a ``Manager``::
    166166
    167167    >>> all_entries = Entry.objects.all()
    168168
    169 The ``all()`` method returns a ``QuerySet`` of all the objects in the database.
     169The :meth:`~django.db.models.query.QuerySet.all` method returns a ``QuerySet`` of all the objects in the database.
    170170
    171171(If ``Entry.objects`` is a ``QuerySet``, why can't we just do ``Entry.objects``?
    172172That's because ``Entry.objects``, the root ``QuerySet``, is a special case
    173 that cannot be evaluated. The ``all()`` method returns a ``QuerySet`` that
     173that cannot be evaluated. The :meth:`~django.db.models.query.QuerySet.all` method returns a ``QuerySet`` that
    174174*can* be evaluated.)
    175175
    176176
     
    196196be in the format described in `Field lookups`_ below.
    197197
    198198For example, to get a ``QuerySet`` of blog entries from the year 2006, use
    199 ``filter()`` like so::
     199:meth:`~django.db.models.query.QuerySet.filter` like so::
    200200
    201201    Entry.objects.filter(pub_date__year=2006)
    202202
     
    275275Retrieving a single object with get
    276276-----------------------------------
    277277
    278 ``.filter()`` will always give you a ``QuerySet``, even if only a single
     278:meth:`~django.db.models.query.QuerySet.filter` will always give you a ``QuerySet``, even if only a single
    279279object matches the query - in this case, it will be a ``QuerySet`` containing
    280280a single element.
    281281
    282282If you know there is only one object that matches your query, you can use
    283 the ``get()`` method on a `Manager` which returns the object directly::
     283the :meth:`~django.db.models.query.QuerySet.get` method on a `Manager` which returns the object directly::
    284284
    285285    >>> one_entry = Entry.objects.get(pk=1)
    286286
     
    354354-------------
    355355
    356356Field lookups are how you specify the meat of an SQL ``WHERE`` clause. They're
    357 specified as keyword arguments to the ``QuerySet`` methods ``filter()``,
     357specified as keyword arguments to the :class:`~django.db.models.query.QuerySet` methods ``filter()``,
    358358``exclude()`` and ``get()``.
    359359
    360360Basic lookups keyword arguments take the form ``field__lookuptype=value``.
     
    377377.. versionchanged:: 1.4
    378378    The field specified in a lookup has to be the name of a model field.
    379379    There's one exception though, in case of a
    380     :class:`~django.db.models.fields.ForeignKey` you can specify the field
     380    :class:`~django.db.models.ForeignKey` you can specify the field
    381381    name suffixed with ``_id``. In this case, the value parameter is expected
    382382    to contain the raw value of the foreign model's primary key. For example::
    383383
     
    479479associated with an entry, it would be treated as if there was also no ``name``
    480480attached, rather than raising an error because of the missing ``author``.
    481481Usually this is exactly what you want to have happen. The only case where it
    482 might be confusing is if you are using ``isnull``. Thus::
     482might be confusing is if you are using :lookup:`isnull`. Thus::
    483483
    484484    Blog.objects.filter(entry__authors__name__isnull=True)
    485485
     
    493493Spanning multi-valued relationships
    494494~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    495495
    496 When you are filtering an object based on a ``ManyToManyField`` or a reverse
    497 ``ForeignKey``, there are two different sorts of filter you may be
     496When you are filtering an object based on a :class:`~django.db.models.ManyToManyField` or a reverse
     497:class:`~django.db.models.ForeignKey`, there are two different sorts of filter you may be
    498498interested in. Consider the ``Blog``/``Entry`` relationship (``Blog`` to
    499499``Entry`` is a one-to-many relation). We might be interested in finding blogs
    500500that have an entry which has both *"Lennon"* in the headline and was published
     
    509509entry that contains a tag with a name of *"music"* and a status of *"public"*.
    510510
    511511To handle both of these situations, Django has a consistent way of processing
    512 ``filter()`` and ``exclude()`` calls. Everything inside a single ``filter()``
     512:meth:`~django.db.models.query.QuerySet.filter` and :meth:`~django.db.models.query.QuerySet.exclude` calls.
     513Everything inside a single ``filter()``
    513514call is applied simultaneously to filter out items matching all those
    514515requirements. Successive ``filter()`` calls further restrict the set of
    515516objects, but for multi-valued relations, they apply to any object linked to
     
    552553the value of a model field with a constant. But what if you want to compare
    553554the value of a model field with another field on the same model?
    554555
    555 Django provides the ``F()`` object to allow such comparisons. Instances
     556Django provides the :ref:`F() expressions <query-expressions>` to allow such comparisons. Instances
    556557of ``F()`` act as a reference to a model field within a query. These
    557558references can then be used in query filters to compare the values of two
    558559different fields on the same model instance.
     
    587588
    588589.. versionadded:: 1.3
    589590
    590 For date and date/time fields, you can add or subtract a ``datetime.timedelta``
     591For date and date/time fields, you can add or subtract a :class:`~datetime.timedelta`
    591592object.  The following would return all entries that were modified more than 3 days
    592593after they were published::
    593594
     
    654655Caching and QuerySets
    655656---------------------
    656657
    657 Each ``QuerySet`` contains a cache, to minimize database access. It's important
     658Each :class:`~django.db.models.query.QuerySet` contains a cache, to minimize database access. It's important
    658659to understand how it works, in order to write the most efficient code.
    659660
    660661In a newly created ``QuerySet``, the cache is empty. The first time a
     
    687688Complex lookups with Q objects
    688689==============================
    689690
    690 Keyword argument queries -- in ``filter()``, etc. -- are "AND"ed together. If
     691Keyword argument queries -- in :meth:`~django.db.models.query.QuerySet.filter`, etc. -- are "AND"ed together. If
    691692you need to execute more complex queries (for example, queries with ``OR``
    692693statements), you can use ``Q`` objects.
    693694
    694 A ``Q`` object (``django.db.models.Q``) is an object used to encapsulate a
     695.. comment: Link to Q does not work, since this documentation does not exist yet.
     696
     697A :class:`~django.db.models.Q` object (``django.db.models.Q``) is an object used to encapsulate a
    695698collection of keyword arguments. These keyword arguments are specified as in
    696699"Field lookups" above.
    697700
     
    784787Deleting objects
    785788================
    786789
    787 The delete method, conveniently, is named ``delete()``. This method immediately
     790The delete method, conveniently, is named :meth:`~django.db.models.Model.delete`. This method immediately
    788791deletes the object and has no return value. Example::
    789792
    790793    e.delete()
     
    874877=================================
    875878
    876879Sometimes you want to set a field to a particular value for all the objects in
    877 a ``QuerySet``. You can do this with the ``update()`` method. For example::
     880a ``QuerySet``. You can do this with the :meth:`~django.db.models.query.QuerySet.update` method. For example::
    878881
    879882    # Update all the headlines with pub_date in 2007.
    880883    Entry.objects.filter(pub_date__year=2007).update(headline='Everything is the same')
     
    931934Related objects
    932935===============
    933936
    934 When you define a relationship in a model (i.e., a ``ForeignKey``,
    935 ``OneToOneField``, or ``ManyToManyField``), instances of that model will have
     937When you define a relationship in a model (i.e., a :class:`~django.db.models.ForeignKey`,
     938:class:`~django.db.models.OneToOneField`, or :class:`~django.db.models.ManyToManyField`), instances of that model will have
    936939a convenient API to access the related object(s).
    937940
    938941Using the models at the top of this page, for example, an ``Entry`` object ``e``
     
    989992    >>> print e.blog  # Hits the database to retrieve the associated Blog.
    990993    >>> print e.blog  # Doesn't hit the database; uses cached version.
    991994
    992 Note that the ``select_related()`` ``QuerySet`` method recursively prepopulates
     995Note that the :meth:`~django.db.models.query.QuerySet.select_related` ``QuerySet`` method recursively prepopulates
    993996the cache of all one-to-many relationships ahead of time. Example::
    994997
    995998    >>> e = Entry.objects.select_related().get(id=2)
     
    10841087end. The API works just as a "backward" one-to-many relationship, above.
    10851088
    10861089The only difference is in the attribute naming: The model that defines the
    1087 ``ManyToManyField`` uses the attribute name of that field itself, whereas the
     1090:class:`~django.db.models.ManyToManyField` uses the attribute name of that field itself, whereas the
    10881091"reverse" model uses the lowercased model name of the original model, plus
    10891092``'_set'`` (just like reverse one-to-many relationships).
    10901093
Back to Top