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

класс lookups.RegisterLookupMixin

Примесь, реализующая API поиска в классе.

classmethodregister_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( компилятор , подключение )

Создает фрагмент SQL для выражения. Возвращает кортеж , где - строка SQL, а - список или кортеж параметров запроса. Является объектом, который имеет метод , который может быть использован для компиляции других выражений. Это соединение, используемое для выполнения запроса.(sql, params)sqlparamscompilerSQLCompilercompile()connection

Вызов expression.as_sql()обычно неверен - вместо этого compiler.compile(expression)следует использовать. compiler.compile() Метод будет заботиться о вызове методов поставщика конкретных выражений.

Настраиваемые аргументы ключевого слова могут быть определены в этом методе, если вероятно, что as_vendorname()методы или подклассы должны будут предоставить данные для переопределения генерации строки SQL. См., Func.as_sql()Например, использование.

as_vendorname( компилятор , подключение )

Работает как 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ссылка

класс Transform

A Transform- это общий класс для реализации преобразований полей. Ярким примером является __yearпреобразование a DateFieldв IntegerField.

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

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

bilateral

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

lhs

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

lookup_name

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

output_field

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

Lookupссылка

класс Lookup

A Lookup- это общий класс для реализации поиска. Поиск - это выражение запроса с левой стороной lhs,; правая часть rhs,; и, lookup_nameкоторый используется для логического сравнения между lhsи, rhsнапример или .lhs in rhslhs > rhs

Обозначения использовать поиск в выражении является <lhs>__<lookup_name>=<rhs>.

Этот класс действует как выражение запроса, но, поскольку он =<rhs>построен, поиск всегда должен быть концом выражения поиска.

lhs

Левая часть - то, что ищется. Объект должен соответствовать API выражения запроса .

rhs

Правая часть - с чем lhsсравнивается. Это может быть простое значение или что-то, что компилируется в SQL, обычно F()объект или QuerySet.

lookup_name

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

process_lhs( компилятор , соединение , lhs = Нет )

Возвращает кортеж , возвращенный . Этот метод можно переопределить, чтобы настроить способ обработки.(lhs_string, lhs_params)compiler.compile(lhs)lhs

compilerэто SQLCompilerобъект, который будет использоваться как compiler.compile(lhs)при компиляции lhs. connection Могут быть использованы для составления конкретного поставщика SQL. Если lhsнет None, используйте его как обработанный lhsвместо self.lhs.

process_rhs( компилятор , подключение )

Действует так же, как process_lhs()и для правой стороны.

Copyright ©2021 All rights reserved