Справочник по 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, lookup_name=None)

Регистрирует новый поиск в классе. Например, DateField.register_lookup(YearExact) зарегистрирует поиск YearExact в DateField. Он перезаписывает поиск, который уже существует с тем же именем. lookup_name будет использоваться для этого поиска, если предоставлен, в противном случае используется lookup.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-выражения. Примеры, которые следуют этому 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]

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