Справочник по API поиска ¶
В этом документе есть ссылки API поиска, API Django для создания WHERE
предложения запроса к базе данных. Чтобы узнать, как использовать поиск, см.
Создание запросов ; чтобы узнать, как создавать новые поисковые запросы, см.
Пользовательские поисковые запросы .
API поиска состоит из двух компонентов: RegisterLookupMixin
класса, который регистрирует поиск, и API выражения запроса , набора методов, которые класс должен реализовать, чтобы его можно было зарегистрировать как поиск.
Django имеет два базовых класса, которые следуют API выражений запросов и откуда берутся все встроенные поисковые запросы Django:
Выражение поиска состоит из трех частей:
- Часть полей (например
Book.objects.filter(author__best_friends__first_name...
); - Преобразует часть (может быть опущено) (например
__lower__first3chars__reversed
); - Поиск (например
__icontains
), если он не указан, по умолчанию используется__exact
.
API регистрации ¶
Django использует, RegisterLookupMixin
чтобы предоставить классу интерфейс для регистрации поиска на самом себе. Двумя яркими примерами являются
Field
базовый класс всех полей модели и
Transform
базовый класс всех преобразований Django.
-
класс
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
, возвращая первое совпадение.
-
classmethod
Чтобы класс был подстановочным, он должен соответствовать API выражения запроса . Lookup
и Transform
естественно следовать этому API.
API выражений запросов ¶
API выражения запроса - это общий набор методов, которые классы определяют для использования в выражениях запросов, чтобы преобразовать себя в выражения SQL. Прямые ссылки на поля, агрегаты и Transform
примеры, следующие за этим API. Говорят, что класс следует API выражения запроса, если он реализует следующие методы:
-
as_sql
( компилятор , подключение ) ¶ Создает фрагмент SQL для выражения. Возвращает кортеж , где - строка SQL, а - список или кортеж параметров запроса. Является объектом, который имеет метод , который может быть использован для компиляции других выражений. Это соединение, используемое для выполнения запроса.
(sql, params)
sql
params
compiler
SQLCompiler
compile()
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)
.
Transform
ссылка ¶
-
класс
Transform
¶ A
Transform
- это общий класс для реализации преобразований полей. Ярким примером является__year
преобразование aDateField
вIntegerField
.Обозначение для использования
Transform
в выражении поиска<expression>__<transformation>
(напримерdate__year
).Этот класс следует API-интерфейсу Query Expression , что означает, что вы можете использовать
<expression>__<transform1>__<transform2>
. Это специализированное выражение Func (), которое принимает только один аргумент. Его также можно использовать с правой стороны фильтра или непосредственно в качестве аннотации.-
bilateral
¶ Логическое значение, указывающее, следует ли применять это преобразование к обоим
lhs
иrhs
. Двусторонние преобразования будут применятьсяrhs
в том же порядке, в котором они отображаются в выражении поиска. По умолчанию установлено значениеFalse
. Для примера использования см. Пользовательские поиски .
-
lhs
¶ Левая часть - то, что трансформируется. Он должен соответствовать API выражений запросов .
-
lookup_name
¶ Имя поиска, используемое для его идентификации при синтаксическом анализе выражений запроса. Он не может содержать строку
"__"
.
-
Lookup
ссылка ¶
-
класс
Lookup
¶ A
Lookup
- это общий класс для реализации поиска. Поиск - это выражение запроса с левой сторонойlhs
,; правая частьrhs
,; и,lookup_name
который используется для логического сравнения междуlhs
и,rhs
например или .lhs in rhs
lhs > 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()
и для правой стороны.
-