[Django] #25212: Document RawSQL expression

[Django]

#25212: Document RawSQL expression
-------------------------------------+-------------------------------------
Reporter: timgraham | Owner: timgraham
Type: | Status: new
Cleanup/optimization |
Component: | Version: 1.8
Documentation |
Severity: Normal | Keywords:
Triage Stage: Accepted | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------+-------------------------------------
from Anssi [https://groups.google.com/d/msg/django-
developers/FojuU0syO8Y/YjUFY1jqCAAJ on django-developers]:

There doesn't seem to be direct documentation about RawSQL expression.
The RawSQL is once mentioned in the documentation, but it definitely needs
a bit more in the database functions documentation.
[[BR]]
The usage of RawSQL is really simple: `qs.annotate(val=RawSQL("(select
col from sometable where othercol= %s)", (someparam,)))`
[[BR]]
This is equivalent to `qs.extra(select={'val': "select col from sometable
where othercol = %s"}, select_params=(someparam,))`
[[BR]]
The main benefit of using RawSQL is that you can set output_field if
needed. The main downside is that if you refer to some table alias of the
qs in the raw sql, then it is possible that Django changes that alias (for
example, when the qs is used as a subquery in yet another query).
[[BR]]
Combining raw SQL with alias relabeling support is possible, too with the
following library: https://github.com/akaariai/django-refsql

--
Ticket URL: <https://code.djangoproject.com/ticket/25212>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#25212: Document RawSQL expression
-------------------------------------+-------------------------------------
Reporter: timgraham | Owner: timgraham
Type: | Status: new
Cleanup/optimization |

Component: Documentation | Version: 1.8
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by timgraham):

* has_patch: 0 => 1

Comment:

[https://github.com/django/django/pull/5095 PR]

--
Ticket URL: <https://code.djangoproject.com/ticket/25212#comment:1>

[Django]

#25212: Document RawSQL expression
-------------------------------------+-------------------------------------
Reporter: timgraham | Owner: timgraham

Type: | Status: closed

Cleanup/optimization |
Component: Documentation | Version: 1.8

Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Tim Graham <timograham@…>):

* status: new => closed
* resolution: => fixed

Comment:

In [changeset:"97fa7fe961f961b6c93a11b50a7a1ed35c8bce8d" 97fa7fe]:
{{{
#!CommitTicketReference repository=""
revision="97fa7fe961f961b6c93a11b50a7a1ed35c8bce8d"
Fixed #25212 -- Documented the RawSQL expression.
}}}

--
Ticket URL: <https://code.djangoproject.com/ticket/25212#comment:2>

[Django]

#25212: Document RawSQL expression
-------------------------------------+-------------------------------------
Reporter: timgraham | Owner: timgraham

Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: 1.8
Severity: Normal | Resolution: fixed

Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Tim Graham <timograham@…>):

In [changeset:"6f6043fd26a83bd0625ce34e1f64a1663fec26db" 6f6043fd]:
{{{
#!CommitTicketReference repository=""
revision="6f6043fd26a83bd0625ce34e1f64a1663fec26db"
[1.8.x] Fixed #25212 -- Documented the RawSQL expression.

Backport of 97fa7fe961f961b6c93a11b50a7a1ed35c8bce8d from master
}}}

--
Ticket URL: <https://code.djangoproject.com/ticket/25212#comment:3>