Справочник по API поиска

В этом документе представлены ссылки на API поиска, API Django для построения WHERE условия базы данных запроса. Чтобы узнать, как использовать поиск, см. Выполнение запросов; чтобы узнать, как создать новые поиски, см. Написание пользовательских поисков.

API поиска имеет две составляющие: класс RegisterLookupMixin, который регистрирует поиски, и API выражений запроса, набор методов, которые класс должен реализовать, чтобы быть зарегистрированным в качестве поиска.

Django имеет два базовых класса, которые следуют API выражений запроса и от которых происходят все встроенные поиски Django:

• Lookup: для поиска поля (например, exact поля field_name__exact)
• Transform: для преобразования поля

Выражение поиска состоит из трех частей:

• Часть поля (например, Book.objects.filter(author__best_friends__first_name...);
• Часть преобразований (может быть опущена) (например, __lower__first3chars__reversed);
• Поиск (например, __icontains), который, если опущен, по умолчанию равен __exact.

API регистрации

Django использует RegisterLookupMixin, чтобы дать классу интерфейс для регистрации поисков в нем. Два наиболее ярких примера — Field, базовый класс всех полей модели, и Transform, базовый класс всех преобразований Django.

class lookups.RegisterLookupMixin

Mixin, реализующий API поиска для класса.

classmethod register_lookup(lookup, lookup_name=None)

Регистрирует новый поиск в классе. Например, DateField.register_lookup(YearExact) зарегистрирует YearExact поиск для DateField. Он перезаписывает поиск, который уже существует с тем же именем. lookup_name будет использоваться для этого поиска, если он предоставлен, в противном случае lookup.lookup_name будет использоваться.

get_lookup(lookup_name)

Возвращает Lookup с именем lookup_name зарегистрированным в классе. Реализация по умолчанию рекурсивно просматривает все родительские классы и проверяет, есть ли у какого-либо из них зарегистрированный поиск с именем lookup_name, возвращая первую совпавшую запись.

get_lookups()

Возвращает словарь, где каждое имя поиска сопоставлено классу Lookup.

get_transform(transform_name)

Возвращает Transform с именем transform_name. Реализация по умолчанию рекурсивно просматривает все родительские классы, чтобы проверить, есть ли у какого-либо из них зарегистрированное преобразование с именем transform_name, возвращая первую совпавшую запись.

Для того, чтобы класс был поиском, он должен следовать API выражений запроса. Lookup и Transform естественным образом следуют этому API.

API выражений запроса

API выражений запроса — это общий набор методов, которые классы определяют для использования в выражениях запросов, чтобы преобразовать себя в выражения SQL. Прямые ссылки на поля, агрегаты и Transform — это примеры, которые следуют этому API. Класс считается следующим API выражений запроса, когда он реализует следующие методы:

as_sql(compiler, connection)

Генерирует фрагмент SQL для выражения. Возвращает кортеж (sql, params), где sql — строка SQL, а params — список или кортеж параметров запроса. compiler — объект SQLCompiler, который имеет метод compile(), который можно использовать для компиляции других выражений. connection — это подключение, используемое для выполнения запроса.

Вызов expression.as_sql() обычно является ошибкой; вместо этого следует использовать compiler.compile(expression). Метод compiler.compile() позаботится о вызове специфичных для поставщика методов выражения.

В этом методе могут быть определены пользовательские ключевые аргументы, если вероятно, что методы as_vendorname() или их подклассы потребуют предоставления данных для переопределения генерации строки SQL. См. пример использования в Func.as_sql().

as_vendorname(compiler, connection)

Работает как метод as_sql(). Когда выражение компилируется compiler.compile(), Django сначала попытается вызвать as_vendorname(), где vendorname — имя поставщика базы данных, используемой для выполнения запроса. vendorname — одно из значений postgresql, oracle, sqlite, или mysql для встроенных баз данных Django.

get_lookup(lookup_name)

Должен вернуть поиск с именем lookup_name. Например, вернув self.output_field.get_lookup(lookup_name).

get_transform(transform_name)

Должен вернуть поиск с именем transform_name. Например, вернув self.output_field.get_transform(transform_name).

output_field

Определяет тип класса, возвращаемого методом get_lookup(). Он должен быть экземпляром Field.

Transform справочник

class Transform

Transform — это общий класс для реализации преобразований поля. Яркий пример — __year, который преобразует DateField в IntegerField.

Использование Transform в выражении поиска — <expression>__<transformation> (например, date__year).

Этот класс следует API выражений запроса, что подразумевает возможность использования <expression>__<transform1>__<transform2>. Это специализированное выражение Func(), которое принимает только один аргумент. Его также можно использовать в правой части фильтра или непосредственно как аннотацию.

bilateral

Булево значение, указывающее, должно ли это преобразование применяться к lhs и rhs. Двусторонние преобразования будут применяться к rhs в том же порядке, в котором они появляются в выражении поиска. По умолчанию он равен False. Пример использования см. в Написание пользовательских поисков.

lhs

Левая часть — то, что преобразуется. Он должен следовать API выражений запроса.

lookup_name

Имя поиска, используемое для его идентификации при разборе выражений запроса. Оно не должно содержать строку "__".

output_field

Определяет класс, который выдает это преобразование. Он должен быть экземпляром Field. По умолчанию равен его lhs.output_field.

Lookup справочник

class Lookup

A Lookup is a generic class to implement lookups. A lookup is a query expression with a left-hand side, lhs; a right-hand side, rhs; and a lookup_name that is used to produce a boolean comparison between lhs and rhs such as lhs in rhs or lhs > rhs.

The primary notation to use a lookup in an expression is <lhs>__<lookup_name>=<rhs>. Lookups can also be used directly in QuerySet filters:

Book.objects.filter(LessThan(F('word_count'), 7500))

…or annotations:

Book.objects.annotate(is_short_story=LessThan(F('word_count'), 7500))

lhs

The left-hand side - what is being looked up. The object typically follows the Выражение запроса. It may also be a plain value.

rhs

The right-hand side - what lhs is being compared against. It can be a plain value, or something that compiles into SQL, typically an F() object or a QuerySet.

lookup_name

The name of this lookup, used to identify it on parsing query expressions. It cannot contain the string "__".

process_lhs(compiler, connection, lhs=None)

Returns a tuple (lhs_string, lhs_params), as returned by compiler.compile(lhs). This method can be overridden to tune how the lhs is processed.

compiler is an SQLCompiler object, to be used like compiler.compile(lhs) for compiling lhs. The connection can be used for compiling vendor specific SQL. If lhs is not None, use it as the processed lhs instead of self.lhs.

process_rhs(compiler, connection)

Behaves the same way as process_lhs(), for the right-hand side.

Изменено в Django 4.0:

Добавлена поддержка использования lookups в QuerySet аннотациях, агрегациях и непосредственно в фильтрах.