Changeset 5488 for django/branches/per-object-permissions/docs/db-api.txt
- Timestamp:
- 06/17/07 17:18:54 (2 years ago)
- Files:
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
django/branches/per-object-permissions/docs/db-api.txt
r4242 r5488 7 7 objects. This document explains that API. 8 8 9 .. _`data models`: http://www.djangoproject.com/documentation/model_api/9 .. _`data models`: ../model-api/ 10 10 11 11 Throughout this reference, we'll refer to the following models, which comprise … … 86 86 `AutoField documentation`_.) 87 87 88 .. _AutoField documentation: http://www.djangoproject.com/documentation/model_api/#autofield88 .. _AutoField documentation: ../model-api/#autofield 89 89 90 90 Explicitly specifying auto-primary-key values … … 113 113 b4.save() # Overrides the previous blog with ID=3! 114 114 115 See _`How Django knows to UPDATE vs. INSERT`, below, for the reason this115 See `How Django knows to UPDATE vs. INSERT`_, below, for the reason this 116 116 happens. 117 117 … … 134 134 135 135 The ``save()`` method has no return value. 136 137 Updating ``ForeignKey`` fields works exactly the same way; simply assign an 138 object of the right type to the field in question:: 139 140 joe = Author.objects.create(name="Joe") 141 entry.author = joe 142 entry.save() 143 144 Django will complain if you try to assign an object of the wrong type. 136 145 137 146 How Django knows to UPDATE vs. INSERT … … 144 153 145 154 * 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 155 ``True`` (i.e., a value other than ``None`` or the empty string), Django 156 executes a ``SELECT`` query to determine whether a record with the given 148 157 primary key already exists. 149 158 * If the record with the given primary key does already exist, Django … … 380 389 underlying SQL statement, and the whole thing is enclosed in a ``NOT()``. 381 390 382 This example excludes all entries whose ``pub_date`` is the current date/time391 This example excludes all entries whose ``pub_date`` is later than 2005-1-3 383 392 AND whose ``headline`` is "Hello":: 384 393 … … 390 399 WHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello') 391 400 392 This example excludes all entries whose ``pub_date`` is the current date/time393 OR whose ``headline`` is"Hello"::401 This example excludes all entries whose ``pub_date`` is later than 2005-1-3 402 AND whose headline is NOT "Hello":: 394 403 395 404 Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3)).exclude(headline='Hello') … … 527 536 [datetime.datetime(2005, 3, 20)] 528 537 538 ``none()`` 539 ~~~~~~~~~~ 540 541 **New in Django development version** 542 543 Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to 544 an empty list. This can be used in cases where you know that you should 545 return an empty result set and your caller is expecting a ``QuerySet`` 546 object (instead of returning an empty list, for example.) 547 548 Examples:: 549 550 >>> Entry.objects.none() 551 [] 552 529 553 ``select_related()`` 530 554 ~~~~~~~~~~~~~~~~~~~~ … … 575 599 c = p.hometown # Doesn't hit the database. 576 600 577 sv= Book.objects.get(id=4) # No select_related() in this example.601 b = Book.objects.get(id=4) # No select_related() in this example. 578 602 p = b.author # Hits the database. 579 603 c = p.hometown # Hits the database. … … 581 605 Note that ``select_related()`` does not follow foreign keys that have 582 606 ``null=True``. 607 608 Usually, using ``select_related()`` can vastly improve performance because your 609 app can avoid many database calls. However, in situations with deeply nested 610 sets of relationships ``select_related()`` can sometimes end up following "too 611 many" relations, and can generate queries so large that they end up being slow. 612 613 In these situations, you can use the ``depth`` argument to ``select_related()`` 614 to control how many "levels" of relations ``select_related()`` will actually 615 follow:: 616 617 b = Book.objects.select_related(depth=1).get(id=4) 618 p = b.author # Doesn't hit the database. 619 c = p.hometown # Requires a database call. 620 621 The ``depth`` argument is new in the Django development version. 583 622 584 623 ``extra(select=None, where=None, params=None, tables=None)`` … … 685 724 something *other than* a ``QuerySet``. 686 725 687 These methods do not use a cache (see _`Caching and QuerySets`below). Rather,726 These methods do not use a cache (see `Caching and QuerySets`_ below). Rather, 688 727 they query the database each time they're called. 689 728 … … 877 916 ~~~~~ 878 917 879 Exact match. If the value provided for comparison is ``None``, it will 880 be interpreted as an SQL ``NULL`` (See isnull_ for more details). 918 Exact match. If the value provided for comparison is ``None``, it will 919 be interpreted as an SQL ``NULL`` (See isnull_ for more details). 881 920 882 921 Examples:: … … 1107 1146 ~~~~~~ 1108 1147 1109 Takes either ``True`` or ``False``, which correspond to SQL queries of 1148 Takes either ``True`` or ``False``, which correspond to SQL queries of 1110 1149 ``IS NULL`` and ``IS NOT NULL``, respectively. 1111 1150 … … 1120 1159 .. admonition:: ``__isnull=True`` vs ``__exact=None`` 1121 1160 1122 There is an important difference between ``__isnull=True`` and 1161 There is an important difference between ``__isnull=True`` and 1123 1162 ``__exact=None``. ``__exact=None`` will *always* return an empty result 1124 set, because SQL requires that no value is equal to ``NULL``. 1125 ``__isnull`` determines if the field is currently holding the value 1163 set, because SQL requires that no value is equal to ``NULL``. 1164 ``__isnull`` determines if the field is currently holding the value 1126 1165 of ``NULL`` without performing a comparison. 1127 1166 … … 1152 1191 1153 1192 For convenience, Django provides a ``pk`` lookup type, which stands for 1154 "primary_key". 1193 "primary_key". 1155 1194 1156 1195 In the example ``Blog`` model, the primary key is the ``id`` field, so these … … 1161 1200 Blog.objects.get(pk=14) # pk implies id__exact 1162 1201 1163 The use of ``pk`` isn't limited to ``__exact`` queries -- any query term 1202 The use of ``pk`` isn't limited to ``__exact`` queries -- any query term 1164 1203 can be combined with ``pk`` to perform a query on the primary key of a model:: 1165 1204 … … 1167 1206 Blog.objects.filter(pk__in=[1,4,7]) 1168 1207 # Get all blog entries with id > 14 1169 Blog.objects.filter(pk__gt=14) 1170 1208 Blog.objects.filter(pk__gt=14) 1209 1171 1210 ``pk`` lookups also work across joins. For example, these three statements are 1172 1211 equivalent:: … … 1200 1239 Blog.objects.filter(entry__headline__contains='Lennon') 1201 1240 1202 Escaping p arenthesis and underscores in LIKE statements1203 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1241 Escaping percent signs and underscores in LIKE statements 1242 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1204 1243 1205 1244 The field lookups that equate to ``LIKE`` SQL statements (``iexact``, … … 1607 1646 Entry.objects.filter(pub_date__year=2005).delete() 1608 1647 1648 When Django deletes an object, it emulates the behavior of the SQL 1649 constraint ``ON DELETE CASCADE`` -- in other words, any objects which 1650 had foreign keys pointing at the object to be deleted will be deleted 1651 along with it. For example:: 1652 1653 b = Blog.objects.get(pk=1) 1654 # This will delete the Blog and all of its Entry objects. 1655 b.delete() 1656 1609 1657 Note that ``delete()`` is the only ``QuerySet`` method that is not exposed on a 1610 1658 ``Manager`` itself. This is a safety mechanism to prevent you from accidentally … … 1705 1753 returns the height (or width) of the image, as an integer, in pixels. 1706 1754 1755 Shortcuts 1756 ========= 1757 1758 As you develop views, you will discover a number of common idioms in the 1759 way you use the database API. Django encodes some of these idioms as 1760 shortcuts that can be used to simplify the process of writing views. These 1761 functions are in the ``django.shortcuts`` module. 1762 1763 get_object_or_404() 1764 ------------------- 1765 1766 One common idiom to use ``get()`` and raise ``Http404`` if the 1767 object doesn't exist. This idiom is captured by ``get_object_or_404()``. 1768 This function takes a Django model as its first argument and an 1769 arbitrary number of keyword arguments, which it passes to the manager's 1770 ``get()`` function. It raises ``Http404`` if the object doesn't 1771 exist. For example:: 1772 1773 # Get the Entry with a primary key of 3 1774 e = get_object_or_404(Entry, pk=3) 1775 1776 When you provide a model to this shortcut function, the default manager 1777 is used to execute the underlying ``get()`` query. If you don't want to 1778 use the default manager, or if you want to search a list of related objects, 1779 you can provide ``get_object_or_404()`` with a manager object instead. 1780 For example:: 1781 1782 # Get the author of blog instance `e` with a name of 'Fred' 1783 a = get_object_or_404(e.authors, name='Fred') 1784 1785 # Use a custom manager 'recent_entries' in the search for an 1786 # entry with a primary key of 3 1787 e = get_object_or_404(Entry.recent_entries, pk=3) 1788 1789 get_list_or_404() 1790 ----------------- 1791 1792 ``get_list_or_404`` behaves the same way as ``get_object_or_404()`` 1793 -- except that it uses ``filter()`` instead of ``get()``. It raises 1794 ``Http404`` if the list is empty. 1795 1707 1796 Falling back to raw SQL 1708 1797 ======================= … … 1723 1812 about your database. 1724 1813 1725 .. _Executing custom SQL: http://www.djangoproject.com/documentation/model_api/#executing-custom-sql1814 .. _Executing custom SQL: ../model-api/#executing-custom-sql
