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

В данном документе представлены ссылки на API поиска, Django API для построения части 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, базовый класс всех полей моделей, и Aggregate, базовый класс всех агрегатов Django.

class lookups.RegisterLookupMixin

Миксин, который реализует API поиска для класса.

classmethod register_lookup(lookup)

Регистрирует новый тип поиска в классе. Например, DateField.register_lookup(YearExact) зарегистрирует тип поиска YearExact в DateField. Он перезаписывает уже существующий тип поиска с тем же именем.

get_lookup(lookup_name)

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

get_transform(transform_name)

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

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

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

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

as_sql(self, compiler, connection)

Ответственен за создание строки запроса и параметров для выражения. compiler — это объект SQLCompiler, который имеет метод compile(), который можно использовать для компиляции других выражений. connection — это соединение, используемое для выполнения запроса.

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

as_vendorname(self, 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.

Справочник по преобразованиям

class Transform [source]

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

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

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

bilateral

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

lhs

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

lookup_name

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

output_field

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

as_sql() [source]

Для переопределения; вызывает NotImplementedError.

get_lookup(lookup_name)

То же, что и get_lookup().

get_transform(transform_name)

То же, что и get_transform().

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

class Lookup [source]

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

Запись для использования поискового запроса в выражении — <lhs>__<lookup_name>=<rhs>.

Этот класс не следует API выражений запроса, поскольку он имеет =<rhs> при создании: поисковые запросы всегда являются концом выражения запроса.

lhs

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

rhs

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

lookup_name

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

process_lhs(compiler, connection, lhs=None) [source]

Возвращает кортеж (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) [source]

Ведёт себя аналогично process_lhs() для правой части.