From 6f6043fd26a83bd0625ce34e1f64a1663fec26db Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Mon, 3 Aug 2015 16:27:49 -0400 Subject: [1.8.x] Fixed #25212 -- Documented the RawSQL expression. Backport of 97fa7fe961f961b6c93a11b50a7a1ed35c8bce8d from master --- docs/ref/models/expressions.txt | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'docs/ref/models') diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt index f83523145e..2f780e4205 100644 --- a/docs/ref/models/expressions.txt +++ b/docs/ref/models/expressions.txt @@ -395,6 +395,33 @@ Conditional expressions allow you to use :keyword:`if` ... :keyword:`elif` ... :keyword:`else` logic in queries. Django natively supports SQL ``CASE`` expressions. For more details see :doc:`conditional-expressions`. +Raw SQL expressions +------------------- + +.. versionadded:: 1.8 + +.. currentmodule:: django.db.models.expressions + +.. class:: RawSQL(sql, params, output_field=None) + +Sometimes database expressions can't easily express a complex ``WHERE`` clause. +In these edge cases, use the ``RawSQL`` expression. For example:: + + >>> from django.db.models.expressions import RawSQL + >>> queryset.annotate(val=RawSQL("select col from sometable where othercol = %s", (someparam,))) + +These extra lookups may not be portable to different database engines (because +you're explicitly writing SQL code) and violate the DRY principle, so you +should avoid them if possible. + +.. warning:: + + You should be very careful to escape any parameters that the user can + control by using ``params`` in order to protect against :ref:`SQL injection + attacks `. + +.. currentmodule:: django.db.models + Technical Information ===================== -- cgit v1.3