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

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

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

class lookups.RegisterLookupMixin

Примесь, реализующая API операторов поиска для класса.

classmethod register_lookup(lookup, lookup_name=None)

Регистрирует новый оператор поиска для класса или экземпляра класса. Например:

DateField.register_lookup(YearExact)
User._meta.get_field("date_joined").register_lookup(MonthExact)

зарегистрирует оператор поиска YearExact для DateField и оператор поиска MonthExact для User.date_joined (для получения экземпляра отдельного поля можно использовать API доступа к полям). Он заменяет уже существующий оператор поиска с тем же именем. Операторы поиска, зарегистрированные для экземпляров полей, имеют приоритет над операторами поиска, зарегистрированными для классов. Для этого оператора поиска будет использоваться lookup_name, если оно указано; в противном случае будет использоваться lookup.lookup_name.

get_lookup(lookup_name)

Возвращает оператор поиска Lookup с именем lookup_name, зарегистрированный для класса или экземпляра класса, в зависимости от того, что вызывает этот метод. Реализация по умолчанию рекурсивно проверяет все родительские классы и ищет зарегистрированный оператор поиска с именем 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 — имя поставщика используемой для выполнения запроса серверной части. Для встроенных серверных частей Django vendorname принимает одно из значений: postgresql, oracle, sqlite или mysql.

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 [исходный код]

Lookup — это универсальный класс для реализации условий поиска. Условие поиска — это выражение запроса с левой частью lhs, правой частью rhs и lookup_name, которая используется для выполнения логического сравнения между lhs и rhs, например lhs in rhs или lhs > rhs.

Основной способ использовать условие поиска в выражении — <lhs>__<lookup_name>=<rhs>. Условия поиска также можно использовать непосредственно в фильтрах QuerySet:

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

…или в аннотациях:

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

lhs

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

rhs

Правая часть — то, с чем сравнивается lhs. Это может быть простое значение или объект, преобразуемый в SQL, обычно объект F() или QuerySet.

lookup_name

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

prepare_rhs

По умолчанию — True. Если rhs — простое значение, prepare_rhs определяет, нужно ли подготовить его к использованию в качестве параметра запроса. Для этого вызывается lhs.output_field.get_prep_value(), если он определён; в противном случае rhs оборачивается в Value().

process_lhs(compiler, connection, lhs=None) [исходный код]

Возвращает кортеж (lhs_string, lhs_params), как и compiler.compile(lhs). Этот метод можно переопределить, чтобы настроить обработку lhs.

compiler — это объект SQLCompiler, который используется, например, как compiler.compile(lhs) для компиляции lhs. connection можно использовать для компиляции SQL для конкретной СУБД. Если lhs не равен None, используйте его в качестве обработанного lhs вместо self.lhs.

process_rhs(compiler, connection) [исходный код]

Для правой части работает так же, как process_lhs().