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

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

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