API de référence des expressions de recherche¶
Ce document contient les références d’API des expressions de recherches, l’API Django pour la construction des clauses WHERE
des requêtes de bases de données. Pour apprendre comment utiliser ces expressions, consultez Making queries. Pour apprendre comment créer de nouvelles expressions, consultez Expressions de recherche personnalisées.
L’API des expressions de recherche possède deux parties : une classe RegisterLookupMixin
qui inscrit les expressions et l”API des expressions de recherche, un ensemble de méthodes qu’une classe doit implémenter afin d’être inscriptible comme expression de recherche.
Django possède deux classes de base qui respectent l’API d’expression de recherche et à partir desquelles toutes les expressions de recherche fournies par Django sont dérivées :
Lookup
: pour rechercher un champ (par ex. la partieexact
denom_champ__exact
)Transform
: pour transformer un champ
Une expression de recherche est formée de trois parties :
- la partie des champs (par ex.
Livre.objects.filter(auteur__meilleurs_amis__prenom...
) ; - la partie de transformation (peut être omise) (par ex.
__lower__troispremierscars__reversed
) ; - la partie de recherche (par ex.
__icontains
) qui, si elle est omise, correspond à__exact
.
API d’inscription¶
Django utilise RegisterLookupMixin
pour donner à une classe l’interface pour inscrire des recherches avec elle-même. Les deux exemples majeurs sont Field
, la classe de base de tous les champs de modèles, et Transform
, la classe de base de toutes les transformations de Django.
-
class
lookups.
RegisterLookupMixin
¶ Une classe mixin qui implémente l’API de recherche pour une classe.
-
classmethod
register_lookup
(lookup, lookup_name=None)¶ Inscrit une nouvelle recherche pour cette classe. Par exemple,
DateField.register_lookup(YearExact)
inscrit la rechercheYearExact
pour le champDateField
. Elle remplace une recherche de même nom qui existe déjà. Si présent,lookup_name
sera utilisé pour cette recherche, sinon ce seralookup.lookup_name
.
-
get_lookup
(lookup_name)¶ Renvoie la recherche
Lookup
nomméelookup_name
inscrite dans la classe. L’implémentation par défaut cherche récursivement dans toutes les classes parentes et vérifie si l’une d’elles possède une recherche inscrite sous le nomlookup_name
, et renvoie la première qu’elle rencontre.
-
get_lookups
()¶ Renvoie un dictionnaire faisant correspondre chaque nom de requête inscrit dans la classe avec sa classe
Lookup
.
-
get_transform
(transform_name)¶ Renvoie une transformation
Transform
nomméetransform_name
. L’implémentation par défaut cherche récursivement dans toutes les classes parentes et vérifie si l’une d’elles possède une transformation inscrite sous le nomtransform_name
, et renvoie la première qu’elle rencontre.
-
classmethod
Pour qu’une classe soit considérée comme une recherche, elle doit suivre l”API d’expression de recherche. Lookup
et Transform
suivent naturellement cette API.
L’API d’expression de recherche¶
L’API d’expression de recherche est un ensemble commun de méthodes que les classes définissent afin de pouvoir être utilisées dans les expressions de recherche avec la capacité de se traduire en expressions SQL. Les références directes aux champs, les agrégations et les expressions Transform
sont des exemples qui respectent cette API. On dit d’une classe qu’elle respecte l’API d’expression de recherche lorsqu’elle implémente les méthodes suivantes :
-
as_sql
(compiler, connection)¶ Responsable de produire le contenu et les paramètres de la requête correspondant à l’expression.
compiler
est un objetSQLCompiler
comportant une méthodecompile()
pouvant être utilisée pour compiler d’autres expressions.connection
est la connexion utilisée pour exécuter la requête.Il n’est normalement pas correct d’appeler
expression.as_sql()
, c’est plutôtcompiler.compile(expression)
qui doit être utilisé. La méthodecompiler.compile()
se charge d’appeler les méthodes spécifiques au fournisseur de base de données pour l’expression donnée.Des paramètres nommés personnalisés peuvent être définis pour cette méthode s’il est probable que des méthodes
as_nomfournisseur()
ou des sous-classes pourraient vouloir fournir des données pour surcharger la génération de la chaîne SQL. VoirFunc.as_sql()
pour un exemple d’utilisation.
-
as_vendorname
(compiler, connection)¶ Fonctionne comme la méthode
as_sql()
. Lorsqu’une expression est compilée aveccompiler.compile()
, Django essaie d’abord d’appeleras_nomfournisseur()
oùnomfournisseur
correspond au nom du fournisseur de la base de données utilisée pour exécuter la requête. Pour les moteurs fournis avec Django,nomfournisseur
peut correspondre àpostgresql
,oracle
,sqlite
oumysql
.
-
get_lookup
(lookup_name)¶ Doit renvoyer la recherche nommée
lookup_name
. Par exemple, en renvoyantself.output_field.get_lookup(lookup_name)
.
-
get_transform
(transform_name)¶ Doit renvoyer la transformation nommée
transform_name
. Par exemple, en renvoyantself.output_field.get_transform(transform_name)
.
Référence de Transform
¶
-
class
Transform
[source]¶ Transform
est une classe générique pour implémenter des transformations de champs. Un exemple typique est__year
(année) qui transforme un champDateField
en champIntegerField
.La notation utilisée pour placer
Transform
dans une expression de recherche est<expression>__<transformation>
(par ex.date__year
).Cette classe respecte l”API d’expression de recherche, ce qui signifie que vous pouvez utiliser
<expression>__<transform1>__<transform2>
. Il s’agit d’une expression Func() spécialisée qui n’accepte qu’un seul paramètre. Elle peut également être utilisée dans la partie droite d’un filtre ou directement sous forme d’annotation.-
bilateral
¶ Une valeur booléenne indiquant si cette transformation doit s’appliquer aux deux parties
lhs
etrhs
. Les transformations bilatérales seront appliquées àrhs
dans leur ordre d’apparition dans l’expression de requête. Par défaut, cet attribut vautFalse
. Pour des exemples d’utilisation, voir Expressions de recherche personnalisées.
-
lhs
¶ La partie gauche de l’expression, ce qui est transformé. Elle doit respecter l”API d’expression de recherche.
-
lookup_name
¶ Le nom de la transformation, utilisé pour l’identifier lors de l’analyse des expressions de recherche. Il ne peut pas contenir la chaîne
"__"
.
-
Référence de Lookup
¶
-
class
Lookup
[source]¶ Lookup
est une classe générique pour implémenter des recherches. Une recherche est une expression de requête avec un côté gauchelhs
, un côté droitrhs
et un nomlookup_name
utilisé pour produire une comparaison booléenne entrelhs
etrhs
telle quelhs in rhs
oulhs > rhs
.La notation utilisée pour placer une recherche
Lookup
dans une expression de recherche est<cote_gauche>__<nom_recherche>=<cote_droit>
.Cette classe ne respecte pas l”API d’expression de recherche car elle possède
=<rhs>
dans sa construction : les recherches sont toujours en fin d’expression de recherche.-
lhs
¶ Le côté gauche, le contenu recherché. L’objet doit respecter l”API d’expression de recherche.
-
rhs
¶ Le côté droit, ce qui est comparé avec
lhs
. Il peut s’agir d’une valeur brute ou de quelque chose qui se compile en SQL, typiquement un objetF()
ou unQuerySet
.
-
lookup_name
¶ Le nom de la recherche, utilisé pour l’identifier lors de l’analyse des expressions de recherche. Il ne peut pas contenir la chaîne
"__"
.
-
process_lhs
(compiler, connection, lhs=None)[source]¶ Renvoie un tuple
(lhs_string, lhs_params)
, tel que renvoyé parcompiler.compile(lhs)
. Cette méthode peut être surchargée pour affiner le traitement delhs
.compiler
est un objetSQLCompiler
destiné à la compilation delhs
, comme aveccompiler.compile(lhs)
. Le paramètreconnection
peut être utilisé pour compiler du SQL selon un fournisseur particulier. Silhs
n’est pasNone
, ce paramètre est employé commelhs
à la place deself.lhs
.
-
process_rhs
(compiler, connection)[source]¶ Se comporte de la même manière que
process_lhs()
, mais pour le côté droit.
-