Changeset 2748

Timestamp:

04/26/06 10:38:30 (3 years ago)

Author:

adrian

Message:

magic-removal: Beginning of substantial rewrite to docs/db-api.txt. Not yet finished.

Files:

• django/branches/magic-removal/docs/db-api.txt (modified) (3 diffs)

django/branches/magic-removal/docs/db-api.txt

@@ -3 +3 @@
-======================
-
-you'll need to retrieve data from the
-. This document explains the database abstraction API derived from th
-models, and how to create, retrieve and update objects
+Django automatically gives you a
+-abstraction API that lets you create, retrieve, update and delet
+objects. This document explains that API
-
-.. _`data models`: http://www.djangoproject.com/documentation/model_api/
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-        pub_date = models.DateTimeField()
-expire_date = models.DateTimeField(
+authors = models.ManyToManyField(Author
-
-        def __repr__(self):
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
-================
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-complete set of objects.
-
-
-
-
+
+
-
-``filter(**kwargs)``
-
+
+
-
-``exclude(**kwargs)``
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-            pub_date__gte=datetime.now()).filter(
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-    q2 = q1.exclude(pub_date__gte=datetime.now())
-    q3 = q1.filter(pub_date__gte=datetime.now())
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-Field lookups
@@ -304 +772 @@
-.. _OR lookups examples page: http://www.djangoproject.com/documentation/models/or_lookups/
-
-QuerySet evaluation
-===================
-
-A Query Set must be evaluated to return the objects that are contained in the
-set. This can be achieved by iteration, slicing, or by specialist function.
-
-A Query Set is an iterable object. Therefore, it can be used in loop
-constructs. For example::
-
-    for p in Poll.objects.all():
-        print p
-
-will print all the Poll objects, using the ``__repr__()`` method of Poll.
-
-A Query Set can also be sliced, using array notation::
-
-    fifth_poll = Poll.objects.all()[4]
-    all_polls_but_the_first_two = Poll.objects.all()[2:]
-    every_second_poll = Poll.objects.all()[::2]
-
-Query Sets are lazy objects - that is, they are not *actually* sets (or
-lists) that contain all the objects that they represent. Python protocol
-magic is used to make the Query Set *look* like an iterable, sliceable
-object, but behind the scenes, Django is using caching to only instantiate
-objects as they are required.
-
-If you really need to have a list, you can force the evaluation of the
-lazy object::
-
-    querylist = list(Poll.objects.all())
-
-However - be warned; this could have a large memory overhead, as Django will
-create an in-memory representation of every element of the list.
-
-Caching and QuerySets
-=====================
-
-Each Query Set contains a cache. In a newly created Query Set, this cache
-is unpopulated. When a Query Set is evaluated for the first time, Django
-makes a database query to populate the cache, and then returns the results
-that have been explicitly requested (e.g., the next element if iteration
-is in use). Subsequent evaluations of the Query Set reuse the cached results.
-
-This caching behavior must be kept in mind when using Query Sets. For
-example, the following will cause two temporary Query Sets to be created,
-evaluated, and thrown away::
-
-    print [p for p in Poll.objects.all()] # Evaluate the Query Set
-    print [p for p in Poll.objects.all()] # Evaluate the Query Set again
-
-On a small, low-traffic website, this may not pose a serious problem. However,
-on a high traffic website, it effectively doubles your database load. In
-addition, there is a possibility that the two lists may not be identical,
-since a poll may be added or deleted by another user between making the two
-requests.
-
-To avoid this problem, simply save the Query Set and reuse it::
-
-    queryset = Poll.objects.all()
-    print [p for p in queryset] # Evaluate the query set
-    print [p for p in queryset] # Re-use the cache from the evaluation
-
-Specialist QuerySet evaluation
@@ -564 +971 @@
-and conditions required for the SQL query.
-
-Specialist QuerySets refinement
-===============================
-
-In addition to ``filter`` and ``exclude()``, Django provides a range of
-Query Set refinement methods that modify the types of results returned by
-the Query Set, or modify the way the SQL query is executed on the database.
-
-``order_by(*fields)``
-----------------------
-
-The results returned by a Query Set are automatically ordered by the ordering
-tuple given by the ``ordering`` meta key in the model. However, ordering may be
-explicitly provided by using the ``order_by`` method::
-
-    Poll.objects.filter(pub_date__year=2005,
-        pub_date__month=1).order_by('-pub_date', 'question')
-
-The result set above will be ordered by ``pub_date`` descending, then
-by ``question`` ascending. The negative sign in front of "-pub_date" indicates
-descending order. Ascending order is implied. To order randomly, use "?", like
-so::
-
-    Poll.objects.order_by=('?')
-
-To order by a field in a different table, add the other table's name and a dot,
-like so::
-
-    Choice.objects.order_by=('Poll.pub_date', 'choice')
-
-There's no way to specify whether ordering should be case sensitive. With
-respect to case-sensitivity, Django will order results however your database
-backend normally orders them.
-
-``distinct()``
---------------
-
-By default, a Query Set will not eliminate duplicate rows. This will not
-happen during simple queries; however, if your query spans relations,
-or you are using a Values Query Set with a ``fields`` clause, it is possible
-to get duplicated results when a Query Set is evaluated.
-
-``distinct()`` returns a new Query Set that eliminates duplicate rows from the
-results returned by the Query Set. This is equivalent to a ``SELECT DISTINCT``
-SQL clause.
-
-``values(*fields)``
---------------------
-
-Returns a Values Query Set - a Query Set that evaluates to a list of
-dictionaries instead of model-instance objects. Each dictionary in the
-list will represent an object matching the query, with the keys matching
-the attribute names of the object.
-
-It accepts an optional parameter, ``fields``, which should be a list or tuple
-of field names. If you don't specify ``fields``, each dictionary in the list
-returned by ``get_values()`` will have a key and value for each field in the
-database table. If you specify ``fields``, each dictionary will have only the
-field keys/values for the fields you specify. For example::
-
-    >>> Poll.objects.values()
-    [{'id': 1, 'slug': 'whatsup', 'question': "What's up?",
-            'pub_date': datetime.datetime(2005, 2, 20),
-            'expire_date': datetime.datetime(2005, 3, 20)},
-     {'id': 2, 'slug': 'name', 'question': "What's your name?",
-            'pub_date': datetime.datetime(2005, 3, 20),
-            'expire_date': datetime.datetime(2005, 4, 20)}]
-    >>> Poll.objects.values('id', 'slug')
-    [{'id': 1, 'slug': 'whatsup'}, {'id': 2, 'slug': 'name'}]
-
-A Values Query Set is useful when you know you're only going to need values
-from a small number of the available fields and you won't need the
-functionality of a model instance object. It's more efficient to select only
-the fields you need to use.
-
-``dates(field, kind, order='ASC')``
------------------------------------
-
-Returns a Date Query Set - a Query Set that evaluates to a list of
-``datetime.datetime`` objects representing all available dates of a
-particular kind within the contents of the Query Set.
-
-``field`` should be the name of a ``DateField`` or ``DateTimeField`` of your
-model.
-
-``kind`` should be either ``"year"``, ``"month"`` or ``"day"``. Each
-``datetime.datetime`` object in the result list is "truncated" to the given
-``type``.
-
-    * ``"year"`` returns a list of all distinct year values for the field.
-    * ``"month"`` returns a list of all distinct year/month values for the field.
-    * ``"day"`` returns a list of all distinct year/month/day values for the field.
-
-``order``, which defaults to ``'ASC'``, should be either ``"ASC"`` or ``"DESC"``.
-This specifies how to order the results.
-
-For example::
-
-    >>> Poll.objects.dates('pub_date', 'year')
-    [datetime.datetime(2005, 1, 1)]
-    >>> Poll.objects.dates('pub_date', 'month')
-    [datetime.datetime(2005, 2, 1), datetime.datetime(2005, 3, 1)]
-    >>> Poll.objects.dates('pub_date', 'day')
-    [datetime.datetime(2005, 2, 20), datetime.datetime(2005, 3, 20)]
-    >>> Poll.objects.dates('pub_date', 'day', order='DESC')
-    [datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)]
-    >>> Poll.objects.filter(question__contains='name').dates('pub_date', 'day')
-    [datetime.datetime(2005, 3, 20)]
-
-``select_related()``
---------------------
-
-Relations are the bread and butter of databases, so there's an option to "follow"
-all relationships and pre-fill them in a simple cache so that later calls to
-objects with a one-to-many relationship don't have to hit the database. Do this by
-passing ``select_related=True`` to a lookup. This results in (sometimes much) larger
-queries, but it means that later use of relationships is much faster.
-
-For example, using the Poll and Choice models from above, if you do the following::
-
-    c = Choice.objects.select_related().get(id=5)
-
-Then subsequent calls to ``c.poll`` won't hit the database.
-
-Note that ``select_related`` follows foreign keys as far as possible. If you have the
-following models::
-
-    class Poll(models.Model):
-        # ...
-
-    class Choice(models.Model):
-        # ...
-        poll = models.ForeignKey(Poll)
-
-    class SingleVote(meta.Model):
-        # ...
-        choice = models.ForeignKey(Choice)
-
-then a call to ``SingleVotes.objects.select_related().get(id=4)`` will
-cache the related choice *and* the related poll::
-
-    >>> sv = SingleVotes.objects.select_related().get(id=4)
-    >>> c = sv.choice        # Doesn't hit the database.
-    >>> p = c.poll           # Doesn't hit the database.
-
-    >>> sv = SingleVotes.objects.get(id=4)
-    >>> c = sv.choice        # Hits the database.
-    >>> p = c.poll           # Hits the database.
-
-
-``extra(params, select, where, tables)``
-----------------------------------------
-
-Sometimes, the Django query syntax by itself isn't quite enough. To cater for these
-edge cases, Django provides the ``extra()`` Query Set modifier - a mechanism
-for injecting specific clauses into the SQL generated by a Query Set.
-
-Note that by definition these extra lookups may not be portable to different
-database engines (because you're explicitly writing SQL code) and should be
-avoided if possible.:
-
-``params``
-    All the extra-SQL params described below may use standard Python string
-    formatting codes to indicate parameters that the database engine will
-    automatically quote.  The ``params`` argument can contain any extra
-    parameters to be substituted.
-
-``select``
-    The ``select`` keyword allows you to select extra fields.  This should be a
-    dictionary mapping attribute names to a SQL clause to use to calculate that
-    attribute. For example::
-
-        Poll.objects.extra(
-            select={
-                'choice_count': 'SELECT COUNT(*) FROM choices WHERE poll_id = polls.id'
-            }
-        )
-
-    Each of the resulting ``Poll`` objects will have an extra attribute, ``choice_count``,
-    an integer count of associated ``Choice`` objects. Note that the parenthesis required by
-    most database engines around sub-selects are not required in Django's ``select``
-    clauses.
-
-``where`` / ``tables``
-    If you need to explicitly pass extra ``WHERE`` clauses -- perhaps to perform
-    non-explicit joins -- use the ``where`` keyword. If you need to
-    join other tables into your query, you can pass their names to ``tables``.
-
-    ``where`` and ``tables`` both take a list of strings. All ``where`` parameters
-    are "AND"ed to any other search criteria.
-
-    For example::
-
-        Poll.objects.filter(
-            question__startswith='Who').extra(where=['id IN (3, 4, 5, 20)'])
-
-    ...translates (roughly) into the following SQL::
-
-        SELECT * FROM polls_polls WHERE question LIKE 'Who%' AND id IN (3, 4, 5, 20);
-
-Changing objects
-================
-
-Once you've retrieved an object from the database using any of the above
-options, changing it is extremely easy.  Make changes directly to the
-objects fields, then call the object's ``save()`` method::
-
-    >>> p = Polls.objects.get(id__exact=15)
-    >>> p.slug = "new_slug"
-    >>> p.pub_date = datetime.datetime.now()
-    >>> p.save()
-
-Creating new objects
-====================