diff options
Diffstat (limited to 'docs/db-api.txt')
| -rw-r--r-- | docs/db-api.txt | 57 |
1 files changed, 40 insertions, 17 deletions
diff --git a/docs/db-api.txt b/docs/db-api.txt index ce6bb0ab3b..2f0c8b0589 100644 --- a/docs/db-api.txt +++ b/docs/db-api.txt @@ -578,6 +578,9 @@ related ``Person`` *and* the related ``City``:: p = b.author # Hits the database. c = p.hometown # Hits the database. +Note that ``select_related()`` does not follow foreign keys that have +``null=True``. + ``extra(select=None, where=None, params=None, tables=None)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -715,12 +718,12 @@ The ``DoesNotExist`` exception inherits from A convenience method for creating an object and saving it all in one step. Thus:: p = Person.objects.create(first_name="Bruce", last_name="Springsteen") - + and:: p = Person(first_name="Bruce", last_name="Springsteen") p.save() - + are equivalent. ``get_or_create(**kwargs)`` @@ -873,15 +876,18 @@ The database API supports the following lookup types: exact ~~~~~ -Exact match. +Exact match. If the value provided for comparison is ``None``, it will +be interpreted as an SQL ``NULL`` (See isnull_ for more details). -Example:: +Examples:: Entry.objects.get(id__exact=14) + Entry.objects.get(id__exact=None) -SQL equivalent:: +SQL equivalents:: SELECT ... WHERE id = 14; + SELECT ... WHERE id = NULL; iexact ~~~~~~ @@ -1100,8 +1106,8 @@ such as January 3, July 3, etc. isnull ~~~~~~ -``NULL`` or ``IS NOT NULL`` match. Takes either ``True`` or ``False``, which -correspond to ``IS NULL`` and ``IS NOT NULL``, respectively. +Takes either ``True`` or ``False``, which correspond to SQL queries of +``IS NULL`` and ``IS NOT NULL``, respectively. Example:: @@ -1111,6 +1117,14 @@ SQL equivalent:: SELECT ... WHERE pub_date IS NULL; +.. 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. + search ~~~~~~ @@ -1137,7 +1151,7 @@ The pk lookup shortcut ---------------------- For convenience, Django provides a ``pk`` lookup type, which stands for -"primary_key". This is shorthand for "an exact lookup on the primary-key." +"primary_key". In the example ``Blog`` model, the primary key is the ``id`` field, so these three statements are equivalent:: @@ -1146,6 +1160,14 @@ three statements are equivalent:: Blog.objects.get(id=14) # __exact is implied Blog.objects.get(pk=14) # pk implies id__exact +The use of ``pk`` isn't limited to ``__exact`` queries -- any query term +can be combined with ``pk`` to perform a query on the primary key of a model:: + + # Get blogs entries with id 1, 4 and 7 + Blog.objects.filter(pk__in=[1,4,7]) + # Get all blog entries with id > 14 + Blog.objects.filter(pk__gt=14) + ``pk`` lookups also work across joins. For example, these three statements are equivalent:: @@ -1468,11 +1490,12 @@ the ``ForeignKey`` ``Manager`` has these additional methods: b.entry_set.remove(e) # Disassociates Entry e from Blog b. In order to prevent database inconsistency, this method only exists on - ``ForeignKey``s where ``null=True``. If the related field can't be set to - ``None`` (``NULL``), then an object can't be removed from a relation - without being added to another. In the above example, removing ``e`` from - ``b.entry_set()`` is equivalent to doing ``e.blog = None``, and because - the ``blog`` ``ForeignKey`` doesn't have ``null=True``, this is invalid. + ``ForeignKey`` objects where ``null=True``. If the related field can't be + set to ``None`` (``NULL``), then an object can't be removed from a + relation without being added to another. In the above example, removing + ``e`` from ``b.entry_set()`` is equivalent to doing ``e.blog = None``, + and because the ``blog`` ``ForeignKey`` doesn't have ``null=True``, this + is invalid. * ``clear()``: Removes all objects from the related object set. @@ -1507,7 +1530,7 @@ Many-to-many relationships -------------------------- Both ends of a many-to-many relationship get automatic API access to the other -end. The API works just as a "backward" one-to-many relationship. See _Backward +end. The API works just as a "backward" one-to-many relationship. See Backward_ above. The only difference is in the attribute naming: The model that defines the @@ -1556,13 +1579,13 @@ Queries over related objects ---------------------------- Queries involving related objects follow the same rules as queries involving -normal value fields. When specifying the the value for a query to match, you -may use either an object instance itself, or the primary key value for the +normal value fields. When specifying the the value for a query to match, you +may use either an object instance itself, or the primary key value for the object. For example, if you have a Blog object ``b`` with ``id=5``, the following three queries would be identical:: - + Entry.objects.filter(blog=b) # Query using object instance Entry.objects.filter(blog=b.id) # Query using id from instance Entry.objects.filter(blog=5) # Query using id directly |