Справочник по 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) зарегистрирует запрос 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() expression, которое принимает только один аргумент. Он также может использоваться в правой части фильтра или напрямую в качестве аннотации.

bilateral

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

lhs

Левая часть — то, что преобразуется. Она должна следовать API выражений запроса.

lookup_name

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

output_field

Определяет класс, выводимый этим преобразованием. Он должен быть экземпляром Field. По умолчанию совпадает с lhs.output_field.

Lookup справочник

class Lookup

A Lookup is a generic class to implement lookups. A lookup is a query expression with a left-hand side, lhs; a right-hand side, rhs; and a lookup_name that is used to produce a boolean comparison between lhs and rhs such as lhs in rhs or lhs > rhs.

The notation to use a lookup in an expression is <lhs>__<lookup_name>=<rhs>.

This class acts as a query expression, but, since it has =<rhs> on its construction, lookups must always be the end of a lookup expression.

lhs

The left-hand side — what is being looked up. The object must follow the API выражений запроса.

rhs

The right-hand side — what lhs is being compared against. It can be a plain value, or something that compiles into SQL, typically an F() object or a QuerySet.

lookup_name

The name of this lookup, used to identify it on parsing query expressions. It cannot contain the string "__".

process_lhs(compiler, connection, lhs=None)

Returns a tuple (lhs_string, lhs_params), as returned by compiler.compile(lhs). This method can be overridden to tune how the lhs is processed.

compiler is an SQLCompiler object, to be used like compiler.compile(lhs) for compiling lhs. The connection can be used for compiling vendor specific SQL. If lhs is not None, use it as the processed lhs instead of self.lhs.

process_rhs(compiler, connection)

Behaves the same way as process_lhs(), for the right-hand side.