Ticket #17794: doc_links_topic_db_queries.patch
| File doc_links_topic_db_queries.patch, 11.3 KB (added by , 13 years ago) |
|---|
-
docs/topics/db/queries.txt
53 53 class represents a particular record in the database table. 54 54 55 55 To create an object, instantiate it using keyword arguments to the model class, 56 then call ``save()`` to save it to the database.56 then call :meth:`~django.db.models.Model.save` to save it to the database. 57 57 58 58 You import the model class from wherever it lives on the Python path, as you 59 59 may expect. (We point this out here because previous Django versions required … … 72 72 73 73 .. seealso:: 74 74 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. 76 76 See the documentation for ``save()`` for complete details. 77 77 78 78 To create an object and save it all in one step see the ``create()`` … … 95 95 Saving ``ForeignKey`` and ``ManyToManyField`` fields 96 96 ---------------------------------------------------- 97 97 98 Updating a ``ForeignKey`` field works exactly the same way as saving a normal98 Updating a :class:`~django.db.models.ForeignKey` field works exactly the same way as saving a normal 99 99 field; simply assign an object of the right type to the field in question. 100 100 This example updates the ``blog`` attribute of an ``Entry`` instance ``entry``:: 101 101 … … 105 105 >>> entry.blog = cheese_blog 106 106 >>> entry.save() 107 107 108 Updating a ``ManyToManyField`` works a little differently; use the ``add()``108 Updating a ``ManyToManyField`` works a little differently; use the :meth:`~django.db.models.fields.related.RelatedManager.add` 109 109 method on the field to add a record to the relation. This example adds the 110 110 ``Author`` instance ``joe`` to the ``entry`` object:: 111 111 … … 114 114 >>> entry.authors.add(joe) 115 115 116 116 To add multiple records to a ``ManyToManyField`` in one go, include multiple 117 arguments in the call to ``add()``, like this::117 arguments in the call to :meth:`~django.db.models.fields.related.RelatedManager.add`, like this:: 118 118 119 119 >>> john = Author.objects.create(name="John") 120 120 >>> paul = Author.objects.create(name="Paul") … … 127 127 Retrieving objects 128 128 ================== 129 129 130 To retrieve objects from your database, you construct a ``QuerySet`` via a131 ``Manager`` on your model class.130 To 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. 132 132 133 133 A ``QuerySet`` represents a collection of objects from your database. It can 134 134 have zero, one or many *filters* -- criteria that narrow down the collection … … 162 162 ---------------------- 163 163 164 164 The 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``::165 To do this, use the :meth:`~django.db.models.query.QuerySet.all` method on a ``Manager``:: 166 166 167 167 >>> all_entries = Entry.objects.all() 168 168 169 The ``all()`` method returns a ``QuerySet`` of all the objects in the database.169 The :meth:`~django.db.models.query.QuerySet.all` method returns a ``QuerySet`` of all the objects in the database. 170 170 171 171 (If ``Entry.objects`` is a ``QuerySet``, why can't we just do ``Entry.objects``? 172 172 That's because ``Entry.objects``, the root ``QuerySet``, is a special case 173 that cannot be evaluated. The ``all()`` method returns a ``QuerySet`` that173 that cannot be evaluated. The :meth:`~django.db.models.query.QuerySet.all` method returns a ``QuerySet`` that 174 174 *can* be evaluated.) 175 175 176 176 … … 196 196 be in the format described in `Field lookups`_ below. 197 197 198 198 For 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:: 200 200 201 201 Entry.objects.filter(pub_date__year=2006) 202 202 … … 275 275 Retrieving a single object with get 276 276 ----------------------------------- 277 277 278 ``.filter()`` will always give you a ``QuerySet``, even if only a single278 :meth:`~django.db.models.query.QuerySet.filter` will always give you a ``QuerySet``, even if only a single 279 279 object matches the query - in this case, it will be a ``QuerySet`` containing 280 280 a single element. 281 281 282 282 If 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::283 the :meth:`~django.db.models.query.QuerySet.get` method on a `Manager` which returns the object directly:: 284 284 285 285 >>> one_entry = Entry.objects.get(pk=1) 286 286 … … 354 354 ------------- 355 355 356 356 Field lookups are how you specify the meat of an SQL ``WHERE`` clause. They're 357 specified as keyword arguments to the ``QuerySet`` methods ``filter()``,357 specified as keyword arguments to the :class:`~django.db.models.query.QuerySet` methods ``filter()``, 358 358 ``exclude()`` and ``get()``. 359 359 360 360 Basic lookups keyword arguments take the form ``field__lookuptype=value``. … … 377 377 .. versionchanged:: 1.4 378 378 The field specified in a lookup has to be the name of a model field. 379 379 There's one exception though, in case of a 380 :class:`~django.db.models. fields.ForeignKey` you can specify the field380 :class:`~django.db.models.ForeignKey` you can specify the field 381 381 name suffixed with ``_id``. In this case, the value parameter is expected 382 382 to contain the raw value of the foreign model's primary key. For example:: 383 383 … … 479 479 associated with an entry, it would be treated as if there was also no ``name`` 480 480 attached, rather than raising an error because of the missing ``author``. 481 481 Usually 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::482 might be confusing is if you are using :lookup:`isnull`. Thus:: 483 483 484 484 Blog.objects.filter(entry__authors__name__isnull=True) 485 485 … … 493 493 Spanning multi-valued relationships 494 494 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 495 495 496 When you are filtering an object based on a ``ManyToManyField`` or a reverse497 ``ForeignKey``, there are two different sorts of filter you may be496 When 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 498 498 interested in. Consider the ``Blog``/``Entry`` relationship (``Blog`` to 499 499 ``Entry`` is a one-to-many relation). We might be interested in finding blogs 500 500 that have an entry which has both *"Lennon"* in the headline and was published … … 509 509 entry that contains a tag with a name of *"music"* and a status of *"public"*. 510 510 511 511 To 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. 513 Everything inside a single ``filter()`` 513 514 call is applied simultaneously to filter out items matching all those 514 515 requirements. Successive ``filter()`` calls further restrict the set of 515 516 objects, but for multi-valued relations, they apply to any object linked to … … 552 553 the value of a model field with a constant. But what if you want to compare 553 554 the value of a model field with another field on the same model? 554 555 555 Django provides the ``F()`` objectto allow such comparisons. Instances556 Django provides the :ref:`F() expressions <query-expressions>` to allow such comparisons. Instances 556 557 of ``F()`` act as a reference to a model field within a query. These 557 558 references can then be used in query filters to compare the values of two 558 559 different fields on the same model instance. … … 587 588 588 589 .. versionadded:: 1.3 589 590 590 For date and date/time fields, you can add or subtract a ``datetime.timedelta``591 For date and date/time fields, you can add or subtract a :class:`~datetime.timedelta` 591 592 object. The following would return all entries that were modified more than 3 days 592 593 after they were published:: 593 594 … … 654 655 Caching and QuerySets 655 656 --------------------- 656 657 657 Each ``QuerySet`` contains a cache, to minimize database access. It's important658 Each :class:`~django.db.models.query.QuerySet` contains a cache, to minimize database access. It's important 658 659 to understand how it works, in order to write the most efficient code. 659 660 660 661 In a newly created ``QuerySet``, the cache is empty. The first time a … … 687 688 Complex lookups with Q objects 688 689 ============================== 689 690 690 Keyword argument queries -- in ``filter()``, etc. -- are "AND"ed together. If691 Keyword argument queries -- in :meth:`~django.db.models.query.QuerySet.filter`, etc. -- are "AND"ed together. If 691 692 you need to execute more complex queries (for example, queries with ``OR`` 692 693 statements), you can use ``Q`` objects. 693 694 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 697 A :class:`~django.db.models.Q` object (``django.db.models.Q``) is an object used to encapsulate a 695 698 collection of keyword arguments. These keyword arguments are specified as in 696 699 "Field lookups" above. 697 700 … … 784 787 Deleting objects 785 788 ================ 786 789 787 The delete method, conveniently, is named ``delete()``. This method immediately790 The delete method, conveniently, is named :meth:`~django.db.models.Model.delete`. This method immediately 788 791 deletes the object and has no return value. Example:: 789 792 790 793 e.delete() … … 874 877 ================================= 875 878 876 879 Sometimes 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::880 a ``QuerySet``. You can do this with the :meth:`~django.db.models.query.QuerySet.update` method. For example:: 878 881 879 882 # Update all the headlines with pub_date in 2007. 880 883 Entry.objects.filter(pub_date__year=2007).update(headline='Everything is the same') … … 931 934 Related objects 932 935 =============== 933 936 934 When you define a relationship in a model (i.e., a ``ForeignKey``,935 ``OneToOneField``, or ``ManyToManyField``), instances of that model will have937 When 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 936 939 a convenient API to access the related object(s). 937 940 938 941 Using the models at the top of this page, for example, an ``Entry`` object ``e`` … … 989 992 >>> print e.blog # Hits the database to retrieve the associated Blog. 990 993 >>> print e.blog # Doesn't hit the database; uses cached version. 991 994 992 Note that the ``select_related()`` ``QuerySet`` method recursively prepopulates995 Note that the :meth:`~django.db.models.query.QuerySet.select_related` ``QuerySet`` method recursively prepopulates 993 996 the cache of all one-to-many relationships ahead of time. Example:: 994 997 995 998 >>> e = Entry.objects.select_related().get(id=2) … … 1084 1087 end. The API works just as a "backward" one-to-many relationship, above. 1085 1088 1086 1089 The only difference is in the attribute naming: The model that defines the 1087 ``ManyToManyField`` uses the attribute name of that field itself, whereas the1090 :class:`~django.db.models.ManyToManyField` uses the attribute name of that field itself, whereas the 1088 1091 "reverse" model uses the lowercased model name of the original model, plus 1089 1092 ``'_set'`` (just like reverse one-to-many relationships). 1090 1093