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

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

Django uses RegisterLookupMixin to give a class the interface to register lookups on itself or its instances. The two prominent examples are Field, the base class of all model fields, and Transform, the base class of all Django transforms.

class lookups.RegisterLookupMixin¶

Миксин, который реализует API поиска в классе.

classmethod register_lookup(lookup, lookup_name=None)¶

Регистрирует новый поиск в классе или экземпляре класса. Например:

DateField.register_lookup(YearExact)
User._meta.get_field('date_joined').register_lookup(MonthExact)

will register YearExact lookup on DateField and MonthExact lookup on the User.date_joined (you can use Field Access API to retrieve a single field instance). It overrides a lookup that already exists with the same name. Lookups registered on field instances take precedence over the lookups registered on classes. lookup_name will be used for this lookup if provided, otherwise lookup.lookup_name will be used.

get_lookup(lookup_name)¶

Returns the Lookup named lookup_name registered in the class or class instance depending on what calls it. The default implementation looks recursively on all parent classes and checks if any has a registered lookup named lookup_name, returning the first match. Instance lookups would override any class lookups with the same lookup_name.

get_lookups()¶

Returns a dictionary of each lookup name registered in the class or class instance mapped to the Lookup class.

get_transform(transform_name)¶

Returns a Transform named transform_name registered in the class or class instance. The default implementation looks recursively on all parent classes to check if any has the registered transform named transform_name, returning the first match.

Чтобы класс был поиском, он должен следовать 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.

The primary notation to use a lookup in an expression is <lhs>__<lookup_name>=<rhs>. Lookups can also be used directly in QuerySet filters:

Book.objects.filter(LessThan(F('word_count'), 7500))

…или аннотации:

Book.objects.annotate(is_short_story=LessThan(F('word_count'), 7500))

lhs¶

The left-hand side - what is being looked up. The object typically follows the Query Expression API. It may also be a plain value.

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