=== modified file 'docs/db-api.txt'
|
|
|
143 | 143 | follows this algorithm: |
144 | 144 | |
145 | 145 | * If the object's primary key attribute is set to a value that evaluates to |
146 | | ``True`` (i.e., a value other than ``None`` or the empty string), Django |
147 | | executes a ``SELECT`` query to determine whether a record with the given |
| 146 | ``True`` (i.e., a value other than ``None`` or the empty string), Django |
| 147 | executes a ``SELECT`` query to determine whether a record with the given |
148 | 148 | primary key already exists. |
149 | 149 | * If the record with the given primary key does already exist, Django |
150 | 150 | executes an ``UPDATE`` query. |
… |
… |
|
525 | 525 | [datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)] |
526 | 526 | >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day') |
527 | 527 | [datetime.datetime(2005, 3, 20)] |
528 | | |
| 528 | |
529 | 529 | ``none()`` |
530 | 530 | ~~~~~~~~~~ |
531 | 531 | |
532 | 532 | **New in Django development version** |
533 | 533 | |
534 | | Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to |
| 534 | Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to |
535 | 535 | an empty list. This can be used in cases where you know that you should |
536 | 536 | return an empty result set and your caller is expecting a ``QuerySet`` |
537 | 537 | object (instead of returning an empty list, for example.) |
538 | 538 | |
539 | 539 | Examples:: |
540 | | |
| 540 | |
541 | 541 | >>> Entry.objects.none() |
542 | 542 | [] |
543 | 543 | |
… |
… |
|
610 | 610 | c = p.hometown # Requires a database call. |
611 | 611 | |
612 | 612 | The ``depth`` argument is new in the Django development version. |
613 | | |
| 613 | |
614 | 614 | ``extra(select=None, where=None, params=None, tables=None)`` |
615 | 615 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
616 | 616 | |
… |
… |
|
1136 | 1136 | isnull |
1137 | 1137 | ~~~~~~ |
1138 | 1138 | |
1139 | | Takes either ``True`` or ``False``, which correspond to SQL queries of |
| 1139 | Takes either ``True`` or ``False``, which correspond to SQL queries of |
1140 | 1140 | ``IS NULL`` and ``IS NOT NULL``, respectively. |
1141 | 1141 | |
1142 | 1142 | Example:: |
… |
… |
|
1149 | 1149 | |
1150 | 1150 | .. admonition:: ``__isnull=True`` vs ``__exact=None`` |
1151 | 1151 | |
1152 | | There is an important difference between ``__isnull=True`` and |
| 1152 | There is an important difference between ``__isnull=True`` and |
1153 | 1153 | ``__exact=None``. ``__exact=None`` will *always* return an empty result |
1154 | | set, because SQL requires that no value is equal to ``NULL``. |
1155 | | ``__isnull`` determines if the field is currently holding the value |
| 1154 | set, because SQL requires that no value is equal to ``NULL``. |
| 1155 | ``__isnull`` determines if the field is currently holding the value |
1156 | 1156 | of ``NULL`` without performing a comparison. |
1157 | 1157 | |
1158 | 1158 | search |
… |
… |
|
1181 | 1181 | ---------------------- |
1182 | 1182 | |
1183 | 1183 | For convenience, Django provides a ``pk`` lookup type, which stands for |
1184 | | "primary_key". |
| 1184 | "primary_key". |
1185 | 1185 | |
1186 | 1186 | In the example ``Blog`` model, the primary key is the ``id`` field, so these |
1187 | 1187 | three statements are equivalent:: |
… |
… |
|
1190 | 1190 | Blog.objects.get(id=14) # __exact is implied |
1191 | 1191 | Blog.objects.get(pk=14) # pk implies id__exact |
1192 | 1192 | |
1193 | | The use of ``pk`` isn't limited to ``__exact`` queries -- any query term |
| 1193 | The use of ``pk`` isn't limited to ``__exact`` queries -- any query term |
1194 | 1194 | can be combined with ``pk`` to perform a query on the primary key of a model:: |
1195 | 1195 | |
1196 | 1196 | # Get blogs entries with id 1, 4 and 7 |
1197 | 1197 | Blog.objects.filter(pk__in=[1,4,7]) |
1198 | 1198 | # Get all blog entries with id > 14 |
1199 | | Blog.objects.filter(pk__gt=14) |
1200 | | |
| 1199 | Blog.objects.filter(pk__gt=14) |
| 1200 | |
1201 | 1201 | ``pk`` lookups also work across joins. For example, these three statements are |
1202 | 1202 | equivalent:: |
1203 | 1203 | |
… |
… |
|
1754 | 1754 | ------------------- |
1755 | 1755 | |
1756 | 1756 | One common idiom to use ``get()`` and raise ``Http404`` if the |
1757 | | object doesn't exist. This idiom is captured by ``get_object_or_404()``. |
1758 | | This function takes a Django model as its first argument and an |
1759 | | arbitrary number of keyword arguments, which it passes to the manager's |
| 1757 | object doesn't exist. This idiom is captured by ``get_object_or_404()``. |
| 1758 | This function takes a Django model as its first argument and an |
| 1759 | arbitrary number of keyword arguments, which it passes to the manager's |
1760 | 1760 | ``get()`` function. It raises ``Http404`` if the object doesn't |
1761 | | exist. For example:: |
1762 | | |
| 1761 | exist. For example:: |
| 1762 | |
1763 | 1763 | # Get the Entry with a primary key of 3 |
1764 | 1764 | e = get_object_or_404(Entry, pk=3) |
1765 | 1765 | |
1766 | | When you provide a model to this shortcut function, the default manager |
1767 | | is used to execute the underlying ``get()`` query. If you don't want to |
1768 | | use the default manager, or you want to search a list of related objects, |
1769 | | you can provide ``get_object_or_404()`` with a manager object, instead. |
| 1766 | When you provide a model to this shortcut function, the default manager |
| 1767 | is used to execute the underlying ``get()`` query. If you don't want to |
| 1768 | use the default manager, or if you want to search a list of related objects, |
| 1769 | you can provide ``get_object_or_404()`` with a manager object instead. |
1770 | 1770 | For example:: |
1771 | 1771 | |
1772 | 1772 | # Get the author of blog instance `e` with a name of 'Fred' |
… |
… |
|
1779 | 1779 | get_list_or_404() |
1780 | 1780 | ----------------- |
1781 | 1781 | |
1782 | | ``get_list_or_404`` behaves the same was as ``get_object_or_404()`` |
1783 | | -- except that it uses using ``filter()`` instead of ``get()``. It raises |
| 1782 | ``get_list_or_404`` behaves the same way as ``get_object_or_404()`` |
| 1783 | -- except that it uses ``filter()`` instead of ``get()``. It raises |
1784 | 1784 | ``Http404`` if the list is empty. |
1785 | 1785 | |
1786 | 1786 | Falling back to raw SQL |