Справочник по API поиска¶

API регистрации¶

Django использует RegisterLookupMixin, чтобы дать классу интерфейс для регистрации поисков на себя. Два выдающихся примера Field, базовый класс всех полей модели и Transform, базовый класс всех преобразований 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_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. Для примера использования смотрите howto/custom-lookups.

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¶

Левая часть - то, что ищется. Объект обычно следует за Query Expression 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(), для правой части.

Changed in Django 4.0:

Добавлена поддержка использования поиска в аннотациях QuerySet, агрегациях и непосредственно в фильтрах.