Выражения запросов¶

F() выражения¶

class F[исходный код]¶

An F() object represents the value of a model field, transformed value of a model field, or annotated column. It makes it possible to refer to model field values and perform database operations using them without actually having to pull them out of the database into Python memory.

Вместо этого Django использует объект F() для генерации SQL-выражения, которое описывает требуемую операцию на уровне базы данных.

Давайте попробуем сделать это на примере. Обычно можно поступить следующим образом:

# Tintin filed a news story!
reporter = Reporters.objects.get(name='Tintin')
reporter.stories_filed += 1
reporter.save()

Здесь мы извлекли значение reporter.stories_filed из базы данных в память и манипулировали им с помощью знакомых операторов Python, а затем сохранили объект обратно в базу данных. Но вместо этого мы могли бы также сделать:

from django.db.models import F

reporter = Reporters.objects.get(name='Tintin')
reporter.stories_filed = F('stories_filed') + 1
reporter.save()

Хотя reporter.stories_filed = F('stories_filed') + 1 выглядит как обычное присвоение значения атрибуту экземпляра в Python, на самом деле это SQL-конструкция, описывающая операцию над базой данных.

Когда Django встречает экземпляр F(), он переопределяет стандартные операторы Python, чтобы создать инкапсулированное выражение SQL; в данном случае, выражение, которое инструктирует базу данных увеличить поле базы данных, представленное reporter.stories_filed.

Каким бы ни было значение reporter.stories_filed, Python никогда не узнает о нем - оно полностью обрабатывается базой данных. Все, что делает Python через класс Django F(), это создает синтаксис SQL для ссылки на поле и описывает операцию.

Чтобы получить доступ к новому значению, сохраненному таким образом, объект должен быть перезагружен:

reporter = Reporters.objects.get(pk=reporter.pk)
# Or, more succinctly:
reporter.refresh_from_db()

Помимо использования в операциях над отдельными экземплярами, как описано выше, F() может использоваться над QuerySets экземплярами объектов, с update(). Это сокращает два запроса, которые мы использовали выше - get() и save() - до одного:

reporter = Reporters.objects.filter(name='Tintin')
reporter.update(stories_filed=F('stories_filed') + 1)

Мы также можем использовать update() для увеличения значения поля для нескольких объектов - что может быть намного быстрее, чем перетаскивать их все в Python из базы данных, перебирать их, увеличивать значение поля каждого из них и сохранять каждое из них обратно в базу данных:

Reporter.objects.update(stories_filed=F('stories_filed') + 1)

F() поэтому может обеспечить преимущества в производительности:

• заставить базу данных, а не Python, выполнять работу
• сокращение количества запросов, необходимых для выполнения некоторых операций

reporter = Reporters.objects.get(name='Tintin')
reporter.stories_filed = F('stories_filed') + 1
reporter.save()

reporter.name = 'Tintin Jr.'
reporter.save()

company = Company.objects.annotate(
    chairs_needed=F('num_employees') - F('num_chairs'))

from django.db.models import DateTimeField, ExpressionWrapper, F

Ticket.objects.annotate(
    expires=ExpressionWrapper(
        F('active_at') + F('duration'), output_field=DateTimeField()))

>> car = Company.objects.annotate(built_by=F('manufacturer'))[0]
>> car.manufacturer
<Manufacturer: Toyota>
>> car.built_by
3

from django.db.models import F
Company.objects.order_by(F('last_contacted').desc(nulls_last=True))

from django.db.models import F

Company.objects.update(is_active=~F('is_active'))

Func() выражения¶

Выражения Func() являются базовым типом всех выражений, в которых используются функции базы данных, такие как COALESCE и LOWER, или агрегаты, такие как SUM. Их можно использовать напрямую:

from django.db.models import F, Func

queryset.annotate(field_lower=Func(F('field'), function='LOWER'))

или они могут быть использованы для создания библиотеки функций базы данных:

class Lower(Func):
    function = 'LOWER'

queryset.annotate(field_lower=Lower('field'))

Но оба случая приведут к набору запросов, где каждая модель аннотирована дополнительным атрибутом field_lower, полученным, примерно, из следующего SQL:

SELECT
    ...
    LOWER("db_table"."field") as "field_lower"

Список встроенных функций базы данных см. в Функции базы данных.

API Func выглядит следующим образом:

class Func(*expressions, **extra)[исходный код]¶

function¶

Атрибут класса, описывающий функцию, которая будет сгенерирована. В частности, function будет интерполироваться как function в template. По умолчанию None.

template¶

Атрибут класса в виде строки формата, которая описывает SQL, генерируемый для этой функции. По умолчанию имеет значение '%(function)s(%(expressions)s)'.

Если вы строите SQL типа strftime('%W', 'date') и вам нужен литеральный символ % в запросе, удвойте его (%%%%) в атрибуте template, потому что строка интерполируется дважды: один раз при интерполяции шаблона в as_sql() и один раз при интерполяции SQL с параметрами запроса в курсоре базы данных.

arg_joiner¶

Атрибут класса, обозначающий символ, используемый для соединения списка expressions вместе. По умолчанию ', '.

arity¶

Атрибут класса, обозначающий количество аргументов, принимаемых функцией. Если этот атрибут установлен и функция вызывается с другим числом выражений, будет выдано сообщение TypeError. По умолчанию установлено значение None.

as_sql(compiler, connection, function=None, template=None, arg_joiner=None, **extra_context)[исходный код]¶

Генерирует фрагмент SQL для функции базы данных. Возвращает кортеж (sql, params), где sql - строка SQL, а params - список или кортеж параметров запроса.

Методы as_vendor() должны использовать function, template, arg_joiner и любые другие **extra_context параметры для настройки SQL по мере необходимости. Например:

django/db/models/functions.py¶

class ConcatPair(Func):
    ...
    function = 'CONCAT'
    ...

    def as_mysql(self, compiler, connection, **extra_context):
        return super().as_sql(
            compiler, connection,
            function='CONCAT_WS',
            template="%(function)s('', %(expressions)s)",
            **extra_context
        )

Чтобы избежать уязвимости SQL-инъекции, extra_context must not contain untrusted user input, так как эти значения интерполируются в строку SQL, а не передаются как параметры запроса, где драйвер базы данных мог бы избежать их.

Аргумент *expressions представляет собой список позиционных выражений, к которым будет применена функция. Выражения будут преобразованы в строки, объединены вместе с помощью arg_joiner, а затем интерполированы в template в качестве заполнителя expressions.

Позиционные аргументы могут быть выражениями или значениями Python. Строки считаются ссылками на столбцы и будут обернуты в выражения F(), в то время как другие значения будут обернуты в выражения Value().

Значения **extra kwargs представляют собой пары key=value, которые могут быть интерполированы в атрибут template. Чтобы избежать уязвимости SQL-инъекции, extra must not contain untrusted user input, поскольку эти значения интерполируются в строку SQL, а не передаются как параметры запроса, где драйвер базы данных мог бы их избежать.

Ключевые слова function, template и arg_joiner могут быть использованы для замены одноименных атрибутов без необходимости определения собственного класса. output_field можно использовать для определения ожидаемого типа возврата.

Aggregate() выражения¶

Агрегатное выражение - это частный случай выражения Func() expression, которое сообщает запросу, что требуется предложение GROUP BY. Все aggregate functions, как и Sum() и Count(), наследуются от Aggregate().

Поскольку Aggregates являются выражениями и обертывают выражения, вы можете представлять некоторые сложные вычисления:

from django.db.models import Count

Company.objects.annotate(
    managers_required=(Count('num_employees') / 4) + Count('num_managers'))

API Aggregate выглядит следующим образом:

class Aggregate(*expressions, output_field=None, distinct=False, filter=None, default=None, **extra)[исходный код]¶

template¶

Атрибут класса в виде строки формата, которая описывает SQL, генерируемый для данного агрегата. По умолчанию имеет значение '%(function)s(%(distinct)s%(expressions)s)'.

function¶

Атрибут класса, описывающий агрегированную функцию, которая будет сгенерирована. В частности, function будет интерполироваться как function в template. По умолчанию None.

window_compatible¶

По умолчанию True, поскольку большинство агрегатных функций можно использовать в качестве исходного выражения в Window.

allow_distinct¶

Атрибут класса, определяющий, позволяет ли данная агрегатная функция передавать аргумент с ключевым словом distinct. Если установлено значение False (по умолчанию), то при передаче TypeError возникает ошибка distinct=True.

empty_result_set_value¶

Defaults to None since most aggregate functions result in NULL when applied to an empty result set.

The expressions positional arguments can include expressions, transforms of the model field, or the names of model fields. They will be converted to a string and used as the expressions placeholder within the template.

Аргумент output_field требует наличия экземпляра поля модели, например IntegerField() или BooleanField(), в которое Django будет загружать значение после его извлечения из базы данных. Обычно при инстанцировании модельного поля аргументы не требуются, поскольку любые аргументы, относящиеся к проверке данных (max_length, max_digits и т.д.), не будут применяться к выходному значению выражения.

Обратите внимание, что output_field требуется только тогда, когда Django не может определить, какой тип поля должен быть в результате. Сложные выражения, в которых смешиваются типы полей, должны определять желаемый output_field. Например, при сложении IntegerField() и FloatField() вместе, вероятно, следует определить output_field=FloatField().

Аргумент distinct определяет, следует ли вызывать агрегатную функцию для каждого отдельного значения expressions (или набора значений, для множества expressions). Этот аргумент поддерживается только для агрегатов, у которых allow_distinct установлено значение True.

Аргумент filter принимает Q object, который используется для фильтрации агрегируемых строк. Примеры использования см. в Условная агрегация и Фильтрация по аннотациям.

Аргумент default принимает значение, которое будет передано вместе с агрегатом в Coalesce. Это полезно для указания возвращаемого значения, отличного от None, когда набор запросов (или группировка) не содержит записей.

Кармашки **extra представляют собой пары key=value, которые могут быть интерполированы в атрибут template.

Создание собственных агрегатных функций¶

Вы также можете создавать свои собственные агрегатные функции. Как минимум, вам нужно определить function, но вы также можете полностью настроить SQL, который генерируется. Вот краткий пример:

from django.db.models import Aggregate

class Sum(Aggregate):
    # Supports SUM(ALL field).
    function = 'SUM'
    template = '%(function)s(%(all_values)s%(expressions)s)'
    allow_distinct = False

    def __init__(self, expression, all_values=False, **extra):
        super().__init__(
            expression,
            all_values='ALL ' if all_values else '',
            **extra
        )

Value() выражения¶

class Value(value, output_field=None)[исходный код]¶

Объект Value() представляет наименьший возможный компонент выражения: простое значение. Когда вам нужно представить значение целого числа, булевой или строки в выражении, вы можете обернуть это значение в объект Value().

Вам редко придется использовать Value() напрямую. Когда вы пишете выражение F('field') + 1, Django неявно оборачивает 1 в Value(), позволяя использовать простые значения в более сложных выражениях. Вам придется использовать Value(), когда вы хотите передать строку в выражение. Большинство выражений интерпретируют строковый аргумент как имя поля, например Lower('name').

Аргумент value описывает значение, которое должно быть включено в выражение, например 1, True или None. Django знает, как преобразовать эти значения Python в соответствующий им тип базы данных.

Аргумент output_field должен быть экземпляром поля модели, например IntegerField() или BooleanField(), в которое Django будет загружать значение после его извлечения из базы данных. Обычно при инстанцировании поля модели аргументы не нужны, так как любые аргументы, относящиеся к проверке данных (max_length, max_digits и т.д.), не будут применяться к выходному значению выражения. Если не указано output_field, то оно будет предварительно выведено из type предоставленного value, если это возможно. Например, если передать экземпляр :py<<<<8 >>> как <<<<9 >>>, то по умолчанию <<<10 >>> будет равно <<<11 >>>.

ExpressionWrapper() выражения¶

class ExpressionWrapper(expression, output_field)[исходный код]¶

ExpressionWrapper окружает другое выражение и предоставляет доступ к свойствам, таким как output_field, которые могут быть недоступны для других выражений. ExpressionWrapper необходим при использовании арифметики на F() выражениях с различными типами, как описано в Использование F() с аннотациями.

Условные выражения¶

Условные выражения позволяют использовать if … elif … else логику в запросах. Django нативно поддерживает SQL CASE выражения. Более подробную информацию можно найти в разделе Условные выражения.

Subquery() выражения¶

class Subquery(queryset, output_field=None)[исходный код]¶

Вы можете добавить явный подзапрос к QuerySet с помощью выражения Subquery.

Например, для аннотации каждого сообщения указывается адрес электронной почты автора самого нового комментария к этому сообщению:

>>> from django.db.models import OuterRef, Subquery
>>> newest = Comment.objects.filter(post=OuterRef('pk')).order_by('-created_at')
>>> Post.objects.annotate(newest_commenter_email=Subquery(newest.values('email')[:1]))

В PostgreSQL SQL выглядит следующим образом:

SELECT "post"."id", (
    SELECT U0."email"
    FROM "comment" U0
    WHERE U0."post_id" = ("post"."id")
    ORDER BY U0."created_at" DESC LIMIT 1
) AS "newest_commenter_email" FROM "post"

>>> Book.objects.filter(author=OuterRef(OuterRef('pk')))

>>> from datetime import timedelta
>>> from django.utils import timezone
>>> one_day_ago = timezone.now() - timedelta(days=1)
>>> posts = Post.objects.filter(published_at__gte=one_day_ago)
>>> Comment.objects.filter(post__in=Subquery(posts.values('pk')))

>>> subquery = Subquery(newest.values('email')[:1])
>>> Post.objects.annotate(newest_commenter_email=subquery)

>>> from django.db.models import Exists, OuterRef
>>> from datetime import timedelta
>>> from django.utils import timezone
>>> one_day_ago = timezone.now() - timedelta(days=1)
>>> recent_comments = Comment.objects.filter(
...     post=OuterRef('pk'),
...     created_at__gte=one_day_ago,
... )
>>> Post.objects.annotate(recent_comment=Exists(recent_comments))

SELECT "post"."id", "post"."published_at", EXISTS(
    SELECT (1) as "a"
    FROM "comment" U0
    WHERE (
        U0."created_at" >= YYYY-MM-DD HH:MM:SS AND
        U0."post_id" = "post"."id"
    )
    LIMIT 1
) AS "recent_comment" FROM "post"

>>> recent_comments = Comment.objects.filter(...)  # From above
>>> Post.objects.filter(Exists(recent_comments))

>>> from django.db.models import OuterRef, Subquery, Sum
>>> comments = Comment.objects.filter(post=OuterRef('pk')).order_by().values('post')
>>> total_comments = comments.annotate(total=Sum('length')).values('total')
>>> Post.objects.filter(length__gt=Subquery(total_comments))

Необработанные выражения SQL¶

class RawSQL(sql, params, output_field=None)[исходный код]¶

Иногда выражения базы данных не могут легко выразить сложное предложение WHERE. В этих крайних случаях используйте выражение RawSQL. Например:

>>> from django.db.models.expressions import RawSQL
>>> queryset.annotate(val=RawSQL("select col from sometable where othercol = %s", (param,)))

Эти дополнительные поиски могут не переноситься на различные движки баз данных (потому что вы явно пишете код SQL) и нарушают принцип DRY, поэтому их следует избегать, если это возможно.

Выражения RawSQL можно также использовать в качестве цели фильтров __in:

>>> queryset.filter(id__in=RawSQL("select id from sometable where col = %s", (param,)))

RawSQL("select col from sometable where othercol = '%s'")  # unsafe!

Функции окна¶

Оконные функции обеспечивают возможность применения функций на разделах. В отличие от обычной агрегатной функции, которая вычисляет конечный результат для каждого набора, определенного группой by, оконные функции работают над frames и разделами и вычисляют результат для каждой строки.

Вы можете указать несколько окон в одном запросе, что в Django ORM было бы эквивалентно включению нескольких выражений в вызов QuerySet.annotate(). ORM не использует именованные окна, вместо этого они являются частью выбранных столбцов.

class Window(expression, partition_by=None, order_by=None, frame=None, output_field=None)[исходный код]¶

template¶

По умолчанию имеет значение %(expression)s OVER (%(window)s)'. Если указан только аргумент expression, то пункт окна будет пустым.

Класс Window является основным выражением для клаузулы OVER.

Аргумент expression является либо window function, либо aggregate function, либо выражением, совместимым в клаузе окна.

The partition_by argument accepts an expression or a sequence of expressions (column names should be wrapped in an F-object) that control the partitioning of the rows. Partitioning narrows which rows are used to compute the result set.

output_field указывается либо в качестве аргумента, либо выражением.

The order_by argument accepts an expression on which you can call asc() and desc(), a string of a field name (with an optional "-" prefix which indicates descending order), or a tuple or list of strings and/or expressions. The ordering controls the order in which the expression is applied. For example, if you sum over the rows in a partition, the first result is the value of the first row, the second is the sum of first and second row.

Параметр frame указывает, какие еще строки должны быть использованы в вычислениях. Подробнее см. в разделе Рамки.

Например, чтобы аннотировать каждый фильм средним рейтингом для фильмов той же студии в том же жанре и году выпуска:

>>> from django.db.models import Avg, F, Window
>>> Movie.objects.annotate(
>>>     avg_rating=Window(
>>>         expression=Avg('rating'),
>>>         partition_by=[F('studio'), F('genre')],
>>>         order_by='released__year',
>>>     ),
>>> )

Это позволяет проверить, оценивается ли фильм лучше или хуже своих аналогов.

Вы можете захотеть применить несколько выражений к одному и тому же окну, т.е. к одному и тому же разделу и кадру. Например, вы можете модифицировать предыдущий пример, чтобы также включить лучший и худший рейтинг в группе каждого фильма (та же студия, жанр и год выпуска), используя три функции окна в одном запросе. Разбиение и упорядочивание из предыдущего примера извлекается в словарь для сокращения повторений:

>>> from django.db.models import Avg, F, Max, Min, Window
>>> window = {
>>>    'partition_by': [F('studio'), F('genre')],
>>>    'order_by': 'released__year',
>>> }
>>> Movie.objects.annotate(
>>>     avg_rating=Window(
>>>         expression=Avg('rating'), **window,
>>>     ),
>>>     best=Window(
>>>         expression=Max('rating'), **window,
>>>     ),
>>>     worst=Window(
>>>         expression=Min('rating'), **window,
>>>     ),
>>> )

Фильтрация по оконным функциям поддерживается, если поиск не дизъюнктивный (не использует OR или XOR в качестве соединителя) и по набору запросов, выполняющему агрегацию.

Например, запрос, основанный на агрегировании и имеющий OR-ed фильтр против оконной функции и поля, не поддерживается. Применение комбинированных предикатов после агрегации может привести к тому, что строки, которые обычно исключаются из групп, будут включены:

>>> qs = Movie.objects.annotate(
>>>     category_rank=Window(
>>>         Rank(), partition_by='category', order_by='-rating'
>>>     ),
>>>     scenes_count=Count('actors'),
>>> ).filter(
>>>     Q(category_rank__lte=3) | Q(title__contains='Batman')
>>> )
>>> list(qs)
NotImplementedError: Heterogeneous disjunctive predicates against window functions
are not implemented when performing conditional aggregation.

Среди встроенных в Django бэкендов баз данных, MySQL 8.0.2+, PostgreSQL и Oracle поддерживают оконные выражения. Поддержка различных функций оконных выражений варьируется в разных базах данных. Например, опции asc() и desc() могут не поддерживаться. При необходимости обратитесь к документации по вашей базе данных.

%(frame_type)s BETWEEN %(start)s AND %(end)s

ValueRange(start=0, end=0)

>>> from django.db.models import Avg, F, RowRange, Window
>>> Movie.objects.annotate(
>>>     avg_rating=Window(
>>>         expression=Avg('rating'),
>>>         partition_by=[F('studio'), F('genre')],
>>>         order_by='released__year',
>>>         frame=RowRange(start=-2, end=2),
>>>     ),
>>> )

>>> from django.db.models import Avg, F, ValueRange, Window
>>> Movie.objects.annotate(
>>>     avg_rating=Window(
>>>         expression=Avg('rating'),
>>>         partition_by=[F('studio'), F('genre')],
>>>         order_by='released__year',
>>>         frame=ValueRange(start=-12, end=12),
>>>     ),
>>> )

API выражения¶

Выражения запроса реализуют query expression API, но также предоставляют ряд дополнительных методов и атрибутов, перечисленных ниже. Все выражения запроса должны наследоваться от Expression() или соответствующего подкласса.

Когда выражение запроса обертывает другое выражение, оно отвечает за вызов соответствующих методов обернутого выражения.

class Expression[исходный код]¶

contains_aggregate¶

Сообщает Django, что данное выражение содержит агрегат и что в запрос необходимо добавить предложение GROUP BY.

contains_over_clause¶

Сообщает Django, что данное выражение содержит выражение Window. Это используется, например, для запрета выражений оконных функций в запросах, изменяющих данные.

filterable¶

Сообщает Django, что на это выражение можно ссылаться в QuerySet.filter(). По умолчанию True.

window_compatible¶

Сообщает Django, что это выражение может быть использовано в качестве исходного выражения в Window. По умолчанию используется False.

empty_result_set_value¶

Говорит Django, какое значение должно быть возвращено, когда выражение используется для применения функции над пустым набором результатов. По умолчанию NotImplemented, что заставляет выражение вычисляться на базе данных.

resolve_expression(query=None, allow_joins=True, reuse=None, summarize=False, for_save=False)¶

Provides the chance to do any preprocessing or validation of the expression before it’s added to the query. resolve_expression() must also be called on any nested expressions. A copy() of self should be returned with any necessary transformations.

query - это реализация бэкенд-запроса.

allow_joins - это булево значение, которое разрешает или запрещает использование объединений в запросе.

reuse - это набор многократно используемых джоинов для сценариев с несколькими джоинами.

summarize - это булево значение, которое при True сигнализирует о том, что вычисляемый запрос является терминальным агрегатным запросом.

for_save - это булево значение, которое при True сигнализирует о том, что выполняемый запрос выполняет создание или обновление.

get_source_expressions()¶

Возвращает упорядоченный список внутренних выражений. Например:

>>> Sum(F('foo')).get_source_expressions()
[F('foo')]

set_source_expressions(expressions)¶

Берет список выражений и сохраняет их так, чтобы get_source_expressions() мог их вернуть.

relabeled_clone(change_map)¶

Возвращает клон (копию) self, с переименованными псевдонимами столбцов. Псевдонимы столбцов переименовываются при создании подзапросов. relabeled_clone() также должен быть вызван для всех вложенных выражений и присвоен клону.

change_map - это словарь, отображающий старые псевдонимы на новые псевдонимы.

Пример:

def relabeled_clone(self, change_map):
    clone = copy.copy(self)
    clone.expression = self.expression.relabeled_clone(change_map)
    return clone

convert_value(value, expression, connection)¶

Крючок, позволяющий перевести выражение value в более подходящий тип.

expression это то же самое, что и self.

get_group_by_cols()¶

Responsible for returning the list of columns references by this expression. get_group_by_cols() should be called on any nested expressions. F() objects, in particular, hold a reference to a column.

Changed in Django 4.2:

The alias=None keyword argument was removed.

asc(nulls_first=None, nulls_last=None)¶

Возвращает выражение, готовое к сортировке по возрастанию.

nulls_first и nulls_last определяют, как сортируются нулевые значения. Пример использования см. в Использование F() для сортировки нулевых значений.

Changed in Django Development version:

В старых версиях nulls_first и nulls_last по умолчанию использовалось значение False.

Не рекомендуется, начиная с версии 4.1: Передача nulls_first=False или nulls_last=False в asc() устарела. Вместо этого используйте None.

desc(nulls_first=None, nulls_last=None)¶

Возвращает выражение, готовое к сортировке в порядке убывания.

nulls_first и nulls_last определяют, как сортируются нулевые значения. Пример использования см. в Использование F() для сортировки нулевых значений.

Changed in Django Development version:

В старых версиях nulls_first и nulls_last по умолчанию использовалось значение False.

Не рекомендуется, начиная с версии 4.1: Передача nulls_first=False или nulls_last=False в desc() устарела. Вместо этого используйте None.

reverse_ordering()¶

Возвращает self с любыми изменениями, необходимыми для изменения порядка сортировки в рамках вызова order_by. Например, выражение, реализующее NULLS LAST, изменит свое значение на NULLS FIRST. Модификации требуются только для выражений, реализующих порядок сортировки типа OrderBy. Этот метод вызывается при вызове reverse() на наборе запросов.

Написание собственных выражений запросов¶

Вы можете написать свои собственные классы выражений запросов, которые используют другие выражения запросов и могут интегрироваться с ними. Давайте рассмотрим пример, написав реализацию SQL-функции COALESCE, без использования встроенной Func() expressions.

SQL-функция COALESCE определяется как прием списка столбцов или значений. Она возвращает первый столбец или значение, которое не является NULL.

Мы начнем с определения шаблона, который будет использоваться для генерации SQL, и метода __init__() для установки некоторых атрибутов:

import copy
from django.db.models import Expression

class Coalesce(Expression):
    template = 'COALESCE( %(expressions)s )'

    def __init__(self, expressions, output_field):
      super().__init__(output_field=output_field)
      if len(expressions) < 2:
          raise ValueError('expressions must have at least 2 elements')
      for expression in expressions:
          if not hasattr(expression, 'resolve_expression'):
              raise TypeError('%r is not an Expression' % expression)
      self.expressions = expressions

Мы выполняем некоторую базовую проверку параметров, включая требование наличия как минимум 2 столбцов или значений, а также убеждаемся, что они являются выражениями. Здесь мы требуем output_field, чтобы Django знал, к какому полю модели отнести конечный результат.

Now we implement the preprocessing and validation. Since we do not have any of our own validation at this point, we delegate to the nested expressions:

def resolve_expression(self, query=None, allow_joins=True, reuse=None, summarize=False, for_save=False):
    c = self.copy()
    c.is_summary = summarize
    for pos, expression in enumerate(self.expressions):
        c.expressions[pos] = expression.resolve_expression(query, allow_joins, reuse, summarize, for_save)
    return c

Далее мы напишем метод, отвечающий за генерацию SQL:

def as_sql(self, compiler, connection, template=None):
    sql_expressions, sql_params = [], []
    for expression in self.expressions:
        sql, params = compiler.compile(expression)
        sql_expressions.append(sql)
        sql_params.extend(params)
    template = template or self.template
    data = {'expressions': ','.join(sql_expressions)}
    return template % data, sql_params

def as_oracle(self, compiler, connection):
    """
    Example of vendor specific handling (Oracle in this case).
    Let's make the function name lowercase.
    """
    return self.as_sql(compiler, connection, template='coalesce( %(expressions)s )')

Методы as_sql() могут поддерживать пользовательские аргументы ключевых слов, что позволяет методам as_vendorname() переопределять данные, используемые для генерации строки SQL. Использование as_sql() аргументов ключевых слов для настройки предпочтительнее, чем мутирование self внутри as_vendorname() методов, так как последнее может привести к ошибкам при работе на различных бэкендах баз данных. Если ваш класс полагается на атрибуты класса для определения данных, подумайте о возможности переопределения в методе as_sql().

Мы генерируем SQL для каждого из expressions с помощью метода compiler.compile() и соединяем результат запятыми. Затем шаблон заполняется нашими данными и возвращаются SQL и параметры.

Мы также определили пользовательскую реализацию, специфичную для бэкенда Oracle. Функция as_oracle() будет вызвана вместо as_sql(), если используется бэкенд Oracle.

Наконец, мы реализуем остальные методы, которые позволяют нашему выражению запроса хорошо играть с другими выражениями запроса:

def get_source_expressions(self):
    return self.expressions

def set_source_expressions(self, expressions):
    self.expressions = expressions

Давайте посмотрим, как это работает:

>>> from django.db.models import F, Value, CharField
>>> qs = Company.objects.annotate(
...    tagline=Coalesce([
...        F('motto'),
...        F('ticker_name'),
...        F('description'),
...        Value('No Tagline')
...        ], output_field=CharField()))
>>> for c in qs:
...     print("%s: %s" % (c.name, c.tagline))
...
Google: Do No Evil
Apple: AAPL
Yahoo: Internet Company
Django Software Foundation: No Tagline

from django.db.models import Func

class Position(Func):
    function = 'POSITION'
    template = "%(function)s('%(substring)s' in %(expressions)s)"

    def __init__(self, expression, substring):
        # substring=substring is an SQL injection vulnerability!
        super().__init__(expression, substring=substring)

class Position(Func):
    function = 'POSITION'
    arg_joiner = ' IN '

    def __init__(self, expression, substring):
        super().__init__(substring, expression)

Добавление поддержки в бэкендах баз данных сторонних производителей¶

Если вы используете бэкенд базы данных, который использует другой синтаксис SQL для определенной функции, вы можете добавить ее поддержку, добавив новый метод в класс функции.

Допустим, мы пишем бэкэнд для Microsoft SQL Server, который использует SQL LEN вместо LENGTH для функции Length. Мы добавим новый метод под названием as_sqlserver() к классу Length:

from django.db.models.functions import Length

def sqlserver_length(self, compiler, connection):
    return self.as_sql(compiler, connection, function='LEN')

Length.as_sqlserver = sqlserver_length

Вы также можете настроить SQL, используя параметр template as_sql().

Мы используем as_sqlserver(), потому что django.db.connection.vendor возвращает sqlserver для бэкенда.

Сторонние бэкенды могут регистрировать свои функции в файле верхнего уровня __init__.py пакета бэкенда или в файле верхнего уровня expressions.py (или пакете), который импортируется из файла верхнего уровня __init__.py.

Для пользовательских проектов, желающих внести изменения в используемый ими бэкенд, этот код должен находиться в методе AppConfig.ready().