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

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