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

class lookups.RegisterLookupMixin

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

classmethod register_lookup(lookup, lookup_name=None)

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

Параметр lookup_name был добавлен.

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.

Transform справочник

class Transform [source]

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

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

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

Transform теперь является подклассом Func.

bilateral

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

lhs

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

lookup_name

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

output_field

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

Lookup справочник

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(), для правой части.