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 Création de requêtes. 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 partie exact
de nom_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
.
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 Aggregate
, la classe de base de toutes les fonctions d’agrégation de Django.
lookups.
RegisterLookupMixin
¶Une classe mixin qui implémente l’API de recherche pour une classe.
register_lookup
(lookup, lookup_name=None)¶Inscrit une nouvelle recherche pour cette classe. Par exemple, DateField.register_lookup(YearExact)
inscrit la recherche YearExact
pour le champ DateField
. Elle remplace une recherche de même nom qui existe déjà. Si présent, lookup_name
sera utilisé pour cette recherche, sinon ce sera lookup.lookup_name
.
Le paramètre lookup_name
a été ajouté.
get_lookup
(lookup_name)¶Renvoie la recherche Lookup
nommée lookup_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 nom lookup_name
, et renvoie la première qu’elle rencontre.
get_transform
(transform_name)¶Renvoie une transformation Transform
nommée transform_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 nom transform_name
, et renvoie la première qu’elle rencontre.
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 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
(self, compiler, connection)¶Responsable de produire le contenu et les paramètres de la requête correspondant à l’expression. compiler
est un objet SQLCompiler
comportant une méthode compile()
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ôt compiler.compile(expression)
qui doit être utilisé. La méthode compiler.compile()
se charge d’appeler les méthodes spécifiques au fournisseur de base de données pour l’expression donnée.
as_vendorname
(self, compiler, connection)¶Fonctionne comme la méthode as_sql()
. Lorsqu’une expression est compilée avec compiler.compile()
, Django essaie d’abord d’appeler as_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
ou mysql
.
get_lookup
(lookup_name)¶Doit renvoyer la recherche nommée lookup_name
. Par exemple, en renvoyant self.output_field.get_lookup(lookup_name)
.
get_transform
(transform_name)¶Doit renvoyer la transformation nommée transform_name
. Par exemple, en renvoyant self.output_field.get_transform(transform_name)
.
Transform
¶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 champ DateField
en champ IntegerField
.
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.
Transform
est dorénavant une sous-classe de Func
.
bilateral
¶Une valeur booléenne indiquant si cette transformation doit s’appliquer aux deux parties lhs
et rhs
. Les transformations bilatérales seront appliquées à rhs
dans leur ordre d’apparition dans l’expression de requête. Par défaut, cet attribut vaut False
. 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 "__"
.
Lookup
¶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é gauche lhs
, un côté droit rhs
et un nom lookup_name
utilisé pour produire une comparaison booléenne entre lhs
et rhs
telle que lhs in rhs
ou lhs > 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 objet F()
ou un QuerySet
.
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é par compiler.compile(lhs)
. Cette méthode peut être surchargée pour affiner le traitement de lhs
.
compiler
est un objet SQLCompiler
destiné à la compilation de lhs
, comme avec compiler.compile(lhs)
. Le paramètre connection
peut être utilisé pour compiler du SQL selon un fournisseur particulier. Si lhs
n’est pas None
, ce paramètre est employé comme lhs
à la place de self.lhs
.
process_rhs
(compiler, connection)[source]¶Se comporte de la même manière que process_lhs()
, mais pour le côté droit.
août 01, 2016