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

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 [source]

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

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

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

bilateral

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

lhs [source]

Левая часть — то, что преобразуется. Он должен следовать 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>. Поиск также можно использовать напрямую в фильтрах 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) [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(), для правой части.