Справочник по 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, базовый класс всех полей модели, и 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-выражения. Примеры, которые следуют этому API, — это прямые ссылки на поля, агрегаты и Transform. Класс считается, что он следует API выражений запроса, если он реализует следующие методы:

as_sql(compiler, connection)

Отвечает за создание строки запроса и параметров для выражения. 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 [source]

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

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

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

bilateral

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

lhs

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

lookup_name

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

output_field

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

Lookup справочник

class Lookup [source]

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