Classe de requête NDB

Cette page explique comment utiliser les anciens services groupés et les anciennes API. Cette API ne peut s'exécuter que dans des environnements d'exécution de première génération dans l'environnement standard App Engine. Si vous effectuez une mise à jour vers l'environnement d'exécution Python 3 d'App Engine, consultez le guide de migration pour en savoir plus sur les options de migration des anciens services groupés.

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().