diff options
Diffstat (limited to 'docs/ref/models')
| -rw-r--r-- | docs/ref/models/querysets.txt | 28 |
1 files changed, 28 insertions, 0 deletions
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 8170a86e8c..c794bb27ef 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -1136,6 +1136,34 @@ Sometimes, the Django query syntax by itself can't easily express a complex ``QuerySet`` modifier — a hook for injecting specific clauses into the SQL generated by a ``QuerySet``. +.. admonition:: Use this method as a last resort + + This is an old API that we aim to deprecate at some point in the future. + Use it only if you cannot express your query using other queryset methods. + If you do need to use it, please `file a ticket + <https://code.djangoproject.com/newticket>`_ using the `QuerySet.extra + keyword <https://code.djangoproject.com/query?status=assigned&status=new&keywords=~QuerySet.extra>`_ + with your use case (please check the list of existing tickets first) so + that we can enhance the QuerySet API to allow removing ``extra()``. We are + no longer improving or fixing bugs for this method. + + For example, this use of ``extra()``:: + + >>> qs.extra( + ... select={'val': "select col from sometable where othercol = %s"}, + ... select_params=(someparam,), + ... ) + + is equivalent to:: + + >>> qs.annotate(val=RawSQL("select col from sometable where othercol = %s", (someparam,))) + + The main benefit of using :class:`~django.db.models.expressions.RawSQL` is + that you can set ``output_field`` if needed. The main downside is that if + you refer to some table alias of the queryset in the raw SQL, then it is + possible that Django might change that alias (for example, when the + queryset is used as a subquery in yet another query). + .. warning:: You should be very careful whenever you use ``extra()``. Every time you use |