Skip to content

Commit

Permalink
Fixed #9033 - Add bullets to QuerySet extra() arguments. thanks julie…
Browse files Browse the repository at this point in the history 
…n for the suggestion and dwillis for the patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14816 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information
@timgraham
timgraham committed Dec 4, 2010
1 parent 76c2c30 commit 00f36e0
Showing 1 changed file with 108 additions and 108 deletions.
216 changes: 108 additions & 108 deletions docs/ref/models/querysets.txt
View file
Expand Up @@ -709,151 +709,151 @@ principle, so you should avoid them if possible.
Specify one or more of ``params``, ``select``, ``where`` or ``tables``. None
of the arguments is required, but you should use at least one of them.

``select``
The ``select`` argument lets you put extra fields in the ``SELECT`` clause.
It should be a dictionary mapping attribute names to SQL clauses to use to
calculate that attribute.
* ``select``
The ``select`` argument lets you put extra fields in the ``SELECT`` clause.
It should be a dictionary mapping attribute names to SQL clauses to use to
calculate that attribute.

Example::
Example::

Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})

As a result, each ``Entry`` object will have an extra attribute,
``is_recent``, a boolean representing whether the entry's ``pub_date`` is
greater than Jan. 1, 2006.
Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})

As a result, each ``Entry`` object will have an extra attribute,
``is_recent``, a boolean representing whether the entry's ``pub_date`` is
greater than Jan. 1, 2006.

Django inserts the given SQL snippet directly into the ``SELECT``
statement, so the resulting SQL of the above example would be something
like::
Django inserts the given SQL snippet directly into the ``SELECT``
statement, so the resulting SQL of the above example would be something
like::

SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent
FROM blog_entry;
SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent
FROM blog_entry;


The next example is more advanced; it does a subquery to give each
resulting ``Blog`` object an ``entry_count`` attribute, an integer count
of associated ``Entry`` objects::
The next example is more advanced; it does a subquery to give each
resulting ``Blog`` object an ``entry_count`` attribute, an integer count
of associated ``Entry`` objects::

Blog.objects.extra(
select={
'entry_count': 'SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id'
},
)
Blog.objects.extra(
select={
'entry_count': 'SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id'
},
)

(In this particular case, we're exploiting the fact that the query will
already contain the ``blog_blog`` table in its ``FROM`` clause.)
(In this particular case, we're exploiting the fact that the query will
already contain the ``blog_blog`` table in its ``FROM`` clause.)

The resulting SQL of the above example would be::
The resulting SQL of the above example would be::

SELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count
FROM blog_blog;
SELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count
FROM blog_blog;

Note that the parenthesis required by most database engines around
subqueries are not required in Django's ``select`` clauses. Also note that
some database backends, such as some MySQL versions, don't support
subqueries.
Note that the parenthesis required by most database engines around
subqueries are not required in Django's ``select`` clauses. Also note that
some database backends, such as some MySQL versions, don't support
subqueries.

.. versionadded:: 1.0
.. versionadded:: 1.0

In some rare cases, you might wish to pass parameters to the SQL fragments
in ``extra(select=...)``. For this purpose, use the ``select_params``
parameter. Since ``select_params`` is a sequence and the ``select``
attribute is a dictionary, some care is required so that the parameters
are matched up correctly with the extra select pieces. In this situation,
you should use a ``django.utils.datastructures.SortedDict`` for the
``select`` value, not just a normal Python dictionary.
In some rare cases, you might wish to pass parameters to the SQL fragments
in ``extra(select=...)``. For this purpose, use the ``select_params``
parameter. Since ``select_params`` is a sequence and the ``select``
attribute is a dictionary, some care is required so that the parameters
are matched up correctly with the extra select pieces. In this situation,
you should use a ``django.utils.datastructures.SortedDict`` for the
``select`` value, not just a normal Python dictionary.

This will work, for example::
This will work, for example::

Blog.objects.extra(
select=SortedDict([('a', '%s'), ('b', '%s')]),
select_params=('one', 'two'))
Blog.objects.extra(
select=SortedDict([('a', '%s'), ('b', '%s')]),
select_params=('one', 'two'))

The only thing to be careful about when using select parameters in
``extra()`` is to avoid using the substring ``"%%s"`` (that's *two*
percent characters before the ``s``) in the select strings. Django's
tracking of parameters looks for ``%s`` and an escaped ``%`` character
like this isn't detected. That will lead to incorrect results.
The only thing to be careful about when using select parameters in
``extra()`` is to avoid using the substring ``"%%s"`` (that's *two*
percent characters before the ``s``) in the select strings. Django's
tracking of parameters looks for ``%s`` and an escaped ``%`` character
like this isn't detected. That will lead to incorrect results.

``where`` / ``tables``
You can define explicit SQL ``WHERE`` clauses -- perhaps to perform
non-explicit joins -- by using ``where``. You can manually add tables to
the SQL ``FROM`` clause by using ``tables``.
* ``where`` / ``tables``
You can define explicit SQL ``WHERE`` clauses -- perhaps to perform
non-explicit joins -- by using ``where``. You can manually add tables to
the SQL ``FROM`` clause by using ``tables``.

``where`` and ``tables`` both take a list of strings. All ``where``
parameters are "AND"ed to any other search criteria.
``where`` and ``tables`` both take a list of strings. All ``where``
parameters are "AND"ed to any other search criteria.

Example::
Example::

Entry.objects.extra(where=['id IN (3, 4, 5, 20)'])
Entry.objects.extra(where=['id IN (3, 4, 5, 20)'])

...translates (roughly) into the following SQL::
...translates (roughly) into the following SQL::

SELECT * FROM blog_entry WHERE id IN (3, 4, 5, 20);
SELECT * FROM blog_entry WHERE id IN (3, 4, 5, 20);

Be careful when using the ``tables`` parameter if you're specifying
tables that are already used in the query. When you add extra tables
via the ``tables`` parameter, Django assumes you want that table included
an extra time, if it is already included. That creates a problem,
since the table name will then be given an alias. If a table appears
multiple times in an SQL statement, the second and subsequent occurrences
must use aliases so the database can tell them apart. If you're
referring to the extra table you added in the extra ``where`` parameter
this is going to cause errors.
Be careful when using the ``tables`` parameter if you're specifying
tables that are already used in the query. When you add extra tables
via the ``tables`` parameter, Django assumes you want that table included
an extra time, if it is already included. That creates a problem,
since the table name will then be given an alias. If a table appears
multiple times in an SQL statement, the second and subsequent occurrences
must use aliases so the database can tell them apart. If you're
referring to the extra table you added in the extra ``where`` parameter
this is going to cause errors.

Normally you'll only be adding extra tables that don't already appear in
the query. However, if the case outlined above does occur, there are a few
solutions. First, see if you can get by without including the extra table
and use the one already in the query. If that isn't possible, put your
``extra()`` call at the front of the queryset construction so that your
table is the first use of that table. Finally, if all else fails, look at
the query produced and rewrite your ``where`` addition to use the alias
given to your extra table. The alias will be the same each time you
construct the queryset in the same way, so you can rely upon the alias
name to not change.
Normally you'll only be adding extra tables that don't already appear in
the query. However, if the case outlined above does occur, there are a few
solutions. First, see if you can get by without including the extra table
and use the one already in the query. If that isn't possible, put your
``extra()`` call at the front of the queryset construction so that your
table is the first use of that table. Finally, if all else fails, look at
the query produced and rewrite your ``where`` addition to use the alias
given to your extra table. The alias will be the same each time you
construct the queryset in the same way, so you can rely upon the alias
name to not change.

``order_by``
If you need to order the resulting queryset using some of the new fields
or tables you have included via ``extra()`` use the ``order_by`` parameter
to ``extra()`` and pass in a sequence of strings. These strings should
either be model fields (as in the normal ``order_by()`` method on
querysets), of the form ``table_name.column_name`` or an alias for a column
that you specified in the ``select`` parameter to ``extra()``.
* ``order_by``
If you need to order the resulting queryset using some of the new fields
or tables you have included via ``extra()`` use the ``order_by`` parameter
to ``extra()`` and pass in a sequence of strings. These strings should
either be model fields (as in the normal ``order_by()`` method on
querysets), of the form ``table_name.column_name`` or an alias for a column
that you specified in the ``select`` parameter to ``extra()``.

For example::
For example::

q = Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})
q = q.extra(order_by = ['-is_recent'])
q = Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})
q = q.extra(order_by = ['-is_recent'])

This would sort all the items for which ``is_recent`` is true to the front
of the result set (``True`` sorts before ``False`` in a descending
ordering).
This would sort all the items for which ``is_recent`` is true to the front
of the result set (``True`` sorts before ``False`` in a descending
ordering).

This shows, by the way, that you can make multiple calls to
``extra()`` and it will behave as you expect (adding new constraints each
time).
This shows, by the way, that you can make multiple calls to
``extra()`` and it will behave as you expect (adding new constraints each
time).

``params``
The ``where`` parameter described above may use standard Python database
string placeholders -- ``'%s'`` to indicate parameters the database engine
should automatically quote. The ``params`` argument is a list of any extra
parameters to be substituted.
* ``params``
The ``where`` parameter described above may use standard Python database
string placeholders -- ``'%s'`` to indicate parameters the database engine
should automatically quote. The ``params`` argument is a list of any extra
parameters to be substituted.

Example::
Example::

Entry.objects.extra(where=['headline=%s'], params=['Lennon'])
Entry.objects.extra(where=['headline=%s'], params=['Lennon'])

Always use ``params`` instead of embedding values directly into ``where``
because ``params`` will ensure values are quoted correctly according to
your particular backend. (For example, quotes will be escaped correctly.)
Always use ``params`` instead of embedding values directly into ``where``
because ``params`` will ensure values are quoted correctly according to
your particular backend. (For example, quotes will be escaped correctly.)

Bad::
Bad::

Entry.objects.extra(where=["headline='Lennon'"])
Entry.objects.extra(where=["headline='Lennon'"])

Good::
Good::

Entry.objects.extra(where=['headline=%s'], params=['Lennon'])
Entry.objects.extra(where=['headline=%s'], params=['Lennon'])

defer
~~~~~
Expand Down

0 comments on commit 00f36e0

Please sign in to comment.