Remarque : Python 2.7 n'est plus compatible à partir du 31 janvier 2024. Vos applications Python 2.7 existantes continueront à fonctionner et à recevoir du trafic. Toutefois, App Engine peut bloquer le redéploiement des applications qui utilisent des environnements d'exécution après leur date de fin de compatibilité. Nous vous recommandons de migrer vers la dernière version compatible de Python.

Classe de requête NDB

Un objet Query représente une requête NDB, qui est une requête pour une liste filtrée et triée d'entités.

Cette page contient une documentation de référence. Pour une discussion générale sur les requêtes NDB, consultez la section Requêtes.

Options de requête

De nombreuses méthodes de requête utilisent un ensemble standard d'options supplémentaires, sous la forme d'arguments de mot clé tels que keys_only=True, ou en tant qu'objet QueryOptions transmis avec options=QueryOptions(...).

Les requêtes prennent en charge diverses options de configuration. Celles-ci sont spécifiées par des arguments de mot clé associés aux méthodes Query :

Argument	Type	Par défaut	Description
keys_only	`bool`	`False`	Toutes les opérations renvoient des clés au lieu d'entités.
projection	tuple (ou liste) de propriétés (ou de chaînes)	`None`	Les opérations renvoient des entités comportant uniquement les propriétés spécifiées définies. `projection=[Article.title, Article.date]` ou `projection=['title', 'date']` récupère des entités contenant uniquement ces deux champs définis. (Consultez la section Requêtes de projection.)
offset	`int`	`0`	Nombre de résultats de requêtes à ignorer.
limit	`int`	Aucune limite	Nombre maximal de résultats de requêtes à renvoyer.
batch_size	`int`	`20`	Taille du lot. N'affecte que l'efficacité des requêtes ; les lots plus volumineux utilisent plus de mémoire, mais émettent moins d'appels RPC.
prefetch_size	`int`	`None`	Remplace la taille du premier lot renvoyé.
produce_cursors	`bool`	`False`	Génère des curseurs à partir d'une requête (consultez les sections Itérateurs de requêtes et Curseurs de requêtes).
start_cursor	`Cursor`	`None`	Point de départ de la recherche (consultez la section Curseurs de requête).
end_cursor	`Cursor`	`None`	Point d'arrivée de la recherche (consultez la section Curseurs de requête).
deadline	`int`	Dépend de `Context`	Remplace le délai RPC (défini par défaut sur 5 secondes s'il n'est pas remplacé à la création du `Context`).
read_policy	`ndb.EVENTUAL_CONSISTENCY`		Règles de lecture. Définissez sur `ndb.EVENTUAL_CONSISTENCY` pour obtenir des résultats potentiellement plus rapides sans attendre que le datastore applique les modifications en attente à tous les enregistrements renvoyés.

Pour exécuter une requête avec un ensemble d'options spécifiques, transmettez les arguments de mot clé à la méthode applicable :

qry = Employee.query().filter(...).order(...) # Create a query
for acct in qry.fetch(10, offset=20): # Skip the first 20
  print acct

Vous devriez parfois conserver un ensemble d'options de requête pour les utiliser à différents endroits. Bien que vous puissiez simplement les conserver dans un dictionnaire et transmettre ce dernier aux méthodes à l'aide de **kwds, vous pouvez également créer un objet QueryOptions et le transmettre à l'aide de l'argument de mot clé des options. Les deux exemples suivants sont équivalents :

qo = ndb.QueryOptions(keys_only=True, offset=20)
results = qry.fetch(10, options=qo)
results = qry.fetch(10, keys_only=True, offset=20)

Constructeur

En règle générale, une application crée une Query en appelant Model.query(). Toutefois, il est également possible d'appeler ndb.Query().

Arguments

kind: Chaîne de genre facultative. Normalement, le nom d'une classe d'entité.
ancêtre: Clé d'ancêtre facultative.
filters: Nœud facultatif représentant une arborescence d'expression de filtre.
orders: Objet datastore_query.Order facultatif.
app: Identifiant facultatif d'application.
namespace: Espace de noms facultatif. S'il n'est pas spécifié, l'espace de noms par défaut au moment de l'exécution de la requête est utilisé.
projection: Liste ou tuple facultatif de propriétés à projeter.
group_by: Liste ou tuple facultatif de propriétés à regrouper.
default_options: Objet QueryOptions facultatif donnant les options de requêtes par défaut à utiliser lors de l'exécution de la requête.

Méthodes des instances

filter(filter1, filter2, ...)

Renvoie une nouvelle Query avec un ou plusieurs filtres supplémentaires appliqués. Prend les arguments de filtre comme décrit dans Requêtes. qry.filter(filter1).filter(filter2) équivaut à qry.filter(filter1, filter2)

get(**q_options)

Renvoie le premier résultat de la requête, le cas échéant (sinon None). Cette démarche est semblable à l'appel de q.fetch(1) et au renvoi du premier élément de la liste des résultats.

Arguments

**q_options: Tous les arguments de mot clé des options de requête sont pris en charge.

order(order1, order2, ...)

Renvoie une nouvelle Query à laquelle un ou plusieurs ordres de tri sont appliqués. Prend un ou plusieurs arguments qui sont des propriétés ou des propriétés "inversées". Par exemple, pour trier les utilisateurs par âge et les "départager" par nom, vous pouvez utiliser un élément tel que qry.order(-Account.birthday, Account.name)

bind(...values...)

Cette fonction est destinée aux requêtes GQL utilisant des liaisons de paramètres (:1, :2, etc.) ou des liaisons nommées (:foo, :bar, etc.). Elle lie les valeurs transmises aux paramètres.

Pour lier des paramètres, vous pouvez appeler qry.bind("USA", 49). Pour lier des paramètres nommés, vous pouvez appeler qry.bind(region = "USA", threshold = 49).

Renvoie un nouvel objet Query dans lequel les valeurs de paramètres sont liées.

count(limit=None, **q_options)

Renvoie le nombre de résultats de la requête, jusqu'à une certaine limite. Cette méthode renvoie le même résultat que len(q.fetch(limit)), mais de manière plus efficace.

Arguments

limit: Nombre maximum de résultats à compter.
**q_options: Tous les arguments de mot clé des options de requête et options de contexte sont pris en charge.

count_async(limit, **q_options)

Compte de manière asynchrone le nombre de résultats de la requête, jusqu'à une certaine limite et renvoie un Future dont le résultat est un nombre. Il s'agit de la version asynchrone de count().

fetch(limit, **q_options)

Récupère une liste de résultats de la requête, jusqu'à une certaine limite.

Arguments

limit: Nombre maximum de résultats à compter.
**q_options: Tous les arguments de mot clé des options de requête sont pris en charge.

fetch_async(limit, **q_options)

Récupère de manière asynchrone une liste de résultats de la requête, jusqu'à une certaine limite. Renvoie un Future dont le résultat est une liste de résultats. Il s'agit de la version asynchrone de fetch().

fetch_page(page_size, **q_options)

Récupère une "page" de résultats. Il s'agit d'une méthode spécialisée, utilisée par les interfaces utilisateur de pagination.

Arguments

page_size: Nombre maximal de résultats renvoyés.
**q_options: Tous les arguments de mot clé des options de requête sont pris en charge.

Renvoie un tuple

(results,
     cursor, more)

results : liste des résultats de la requête
cursor : un curseur de requête pointant vers le "prochain" lot de résultats. S'il n'y a plus de résultats, il peut afficher None.
more bool indique s'il y a (probablement) plus de résultats après ce lot. Si la valeur est False, il n'y a plus de résultats. Si la valeur est True, il y a probablement plus de résultats.

Pour récupérer la page suivante, transmettez le curseur renvoyé par un appel à l'appel suivant à l'aide de start_cursor=cursor. Un idiome courant doit transmettre le curseur au client à l'aide de cursor.urlsafe() et reconstruire ce curseur lors d'une requête ultérieure à l'aide de Cursor(urlsafe=string).

fetch_page_async(page_size, **q_options)

Récupère de manière asynchrone une "page" de résultats. Il s'agit de la version asynchrone de fetch_page().

get_async(**q_options)

Renvoie de manière asynchrone le résultat de la première requête, le cas échéant (sinon, None). Il s'agit de la version asynchrone de get().

iter(**q_options)

Construit et renvoie un itérateur sur la requête.

Arguments

**q_options: Tous les arguments de mot clé des options de requête sont pris en charge.

Renvoie un objet QueryIterator.

map(callback, pass_batch_into_callback=None, merge_future=None, **q_options)

Mappez une fonction de rappel ou un tasklet sur les résultats de la requête. Autrement dit, appliquez la fonction (ou le tasklet) à chaque entité dans les résultats de la requête.

Arguments

callback: Une fonction ou un tasklet à appliquer à chaque résultat.
pass_batch_into_callback: Si la valeur est True, il appelle le rappel avec des arguments d'informations de lot comme décrit ci-dessous.
merge_future: Sous-classe Future facultative ; voir ci-dessous.
**q_options: Tous les arguments de mot clé des options de requête sont pris en charge.

Signature de rappel : le rappel est normalement appelé avec une entité comme argument. Cependant, si la valeur keys_only=True est donnée, il est appelé avec une clé. Si la valeur pass_batch_into_callback=True est donnée, le rappel est appelé avec trois arguments : le lot en cours, l'index du lot et l'entité ou la Key de cet index. Le rappel peut renvoyer ce qu'il veut. Si le rappel a la valeur None, un rappel trivial par défaut renvoie l'entité ou la clé transmise.

Argument merge_future facultatif : merge_future est un argument avancé qui peut être utilisé pour modifier la façon dont les résultats de rappel sont combinés dans la valeur de retour map() globale. Par défaut, une liste de valeurs de retour de rappel est générée. En remplaçant l'une des quelques alternatives spécialisées, vous pouvez vous organiser différemment. Consultez le code source de tasklets.MultiFuture pour obtenir la mise en œuvre par défaut et une description du protocole que l'objet merge_future doit mettre en œuvre. Les alternatives du même module incluent QueueFuture, SerialQueueFuture et ReducingFuture.

Renvoie une liste des résultats de tous les rappels. Consultez la section "merge_future facultatif" ci-dessus. Il apparaît lorsque la requête est terminée et que tous les rappels ont été renvoyés.

map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)

Mappez de manière asynchrone une fonction de rappel ou un tasklet sur les résultats de la requête. Il s'agit de la version asynchrone de map().