Classe GqlQuery

Remarque : Les développeurs qui créent des applications sont vivement encouragés à utiliser la bibliothèque cliente NDB, qui présente plusieurs avantages supplémentaires par rapport à cette bibliothèque cliente, tels que la mise en cache automatique des entités via l'API Memcache. Si vous utilisez actuellement l'ancienne bibliothèque cliente DB, consultez le guide de migration de la bibliothèque cliente DB vers NDB.

La classe GqlQuery représente une requête permettant de récupérer des entités à partir du datastore App Engine à l'aide du langage de requête GQL App Engine de type SQL. Pour une analyse complète de la syntaxe et des fonctionnalités GQL, consultez la référence GQL. Vous pouvez également vous reporter à la classe associée Query, qui utilise des objets et des méthodes, plutôt que GQL, pour préparer les requêtes.

GqlQuery est définie dans le module google.appengine.ext.db.

Remarque : Le mécanisme de requêtes basées sur les index permet l'exécution d'un large éventail de requêtes et convient à la plupart des applications. Toutefois, il n'est pas compatible avec certains genres de requêtes couramment rencontrés dans d'autres technologies de base de données. Plus précisément, les requêtes de jointure et d'agrégation ne sont pas acceptées dans le moteur de requêtes Cloud Datastore. Pour connaître les limites relatives aux requêtes Cloud Datastore, consultez la page Requêtes Datastore.

Présentation

Une application crée un objet de requête GQL en appelant directement le constructeur GqlQuery ou la méthode de classe gql() de la classe de modèle d'un type d'entité. Le constructeur GqlQuery prend en argument une chaîne de requête, une instruction GQL complète commençant par SELECT ... FROM model-name. Les valeurs des clauses WHERE peuvent être des littéraux numériques ou de chaîne, ou peuvent utiliser une liaison de paramètre pour les valeurs. Les paramètres peuvent être liés à l'aide d'arguments de position ou de mot clé :

q = GqlQuery("SELECT * FROM Song WHERE composer = 'Lennon, John'")

q = GqlQuery("SELECT __key__ FROM Song WHERE composer = :1", "Lennon, John")

q = GqlQuery("SELECT * FROM Song WHERE composer = :composer", composer="Lennon, John")

Pour plus de commodité, les classes Model et Expando ont une méthode de classe gql() qui renvoie une instance GqlQuery. Cette méthode prend une chaîne de requête GQL sans le préfixe SELECT ... FROM model-name qui est implicite :

q = Song.gql("WHERE composer = 'Lennon, John'")

L'application peut ensuite exécuter la requête et accéder aux résultats de l'une des manières suivantes :

  • Traitez l’objet de requête comme un élément itératif, pour traiter les entités correspondantes une par une :

    for song in q:
      print song.title

    Ceci appelle implicitement la méthode run() de la requête de manière à générer les entités correspondantes. Ceci équivaut à

    for song in q.run():
      print song.title

    Vous pouvez définir une limite du nombre de résultats à traiter à l'aide de l'argument de mot clé limit :

    for song in q.run(limit=5):
      print song.title

    L'interface de l'itérateur ne met pas en cache les résultats. Par conséquent, la création d'un itérateur à partir de l'objet de requête a pour effet de réitérer la même requête depuis le début.

  • Appelez la méthode get() de la requête pour obtenir la première entité correspondante trouvée dans le datastore :

    song = q.get()
    print song.title
  • Appelez la méthode fetch() de la requête pour obtenir la liste de toutes les entités correspondantes jusqu'à un nombre défini de résultats :

    results = q.fetch(limit=5)
    for song in results:
      print song.title

    Comme avec run(), l'objet de requête ne met pas en cache les résultats. Le fait d'appeler fetch() une seconde fois a pour effet de renvoyer la même requête.

    Remarque : Il est rare d'avoir besoin de cette méthode. Il est presque toujours préférable d'utiliser run().

Constructeur

Le constructeur de la classe GqlQuery est défini comme suit :

class GqlQuery (query_string, *args, **kwds)

Crée une instance de la classe GqlQuery pour récupérer des entités à partir d'App Engine Datastore à l'aide du langage de requête GQL.

Arguments

query_string
Chaîne contenant une instruction GQL complète.
args
Valeurs des paramètres de position.
kwds
Valeurs des paramètres de mot clé.

Méthodes des instances

Les instances de la classe GqlQuery utilisent les méthodes suivantes :

bind (*args, **kwds)

Réattribue les valeurs de paramètre de la requête. La requête modifiée sera exécutée lors du premier accès aux résultats après la réattribution de ses paramètres.

La réattribution de paramètres à un objet GqlQuery existant est plus rapide que la création d'un objet GqlQuery, car la chaîne de requête n'a pas besoin d'être analysée de nouveau.

Arguments

args
Nouvelles valeurs de paramètre de position.
kwds
Nouvelles valeurs de paramètre de mot clé.
projection ()

Renvoie le tuple de propriétés dans la projection ou None.

is_keys_only ()

Renvoie une valeur booléenne indiquant si la requête est une requête contenant uniquement des clés.

run (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, limit=None, batch_size=20, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

Renvoie un itérable pour effectuer une boucle sur les résultats de la requête. Cela permet de spécifier le fonctionnement de la requête avec les paramètres et d'accéder aux résultats de manière itérative :

  1. Récupère et ignore le nombre de résultats défini par l'argument offset.
  2. Récupère et renvoie jusqu'à concurrence du nombre maximal de résultats défini par l'argument limit.

La performance de la boucle évolue donc de manière linéaire avec la somme offset + limit. Si vous connaissez le nombre de résultats à récupérer, vous devez toujours définir une valeur limit explicite.

Cette méthode utilise la prérécupération asynchrone pour améliorer les performances. Par défaut, elle extrait ses résultats du datastore par petits lots, ce qui permet à l'application d'arrêter l'itération et d'éviter de récupérer plus de résultats que nécessaire.

Conseil : Pour extraire tous les résultats disponibles lorsque leur nombre est inconnu, définissez batch_size sur une valeur élevée, telle que 1000.

Conseil : Si vous n'avez pas besoin de modifier les valeurs d'argument par défaut, il vous suffit d'utiliser l'objet de requête directement comme itérable pour contrôler la boucle. Cela appelle implicitement run() avec les arguments par défaut.

Arguments

read_policy
Règles de lecture indiquant le niveau de cohérence des données souhaité :
STRONG_CONSISTENCY
Garantit l'obtention des résultats les plus récents, mais se limite à un seul groupe d'entités.
EVENTUAL_CONSISTENCY
Peut s'étendre à plusieurs groupes d'entités, mais peut parfois renvoyer des résultats obsolètes. En général, les requêtes cohérentes à terme s'exécutent plus rapidement que les requêtes à cohérence forte, mais cela n'est pas garanti.

Remarque : Les requêtes globales (non ascendantes) ignorent cet argument.

deadline
Délai d'attente maximal exprimé en secondes au terme duquel Datastore renvoie un résultat avant d'abandonner en signalant une erreur. Accepte un entier ou une valeur à virgule flottante. Ne peut pas être défini sur une valeur supérieure à la valeur par défaut (60 secondes). Toutefois, il est possible de définir une durée plus courte pour garantir qu'une opération particulière échoue rapidement (par exemple, pour afficher une réponse plus rapide à l'utilisateur, retenter une opération ou ajouter l'opération à une file d'attente).
offset
Nombre de résultats à ignorer avant de renvoyer le premier.
limit
Nombre maximum de résultats à renvoyer. Si ce paramètre est omis, la valeur spécifiée dans la clause LIMIT de la chaîne de requête GQL sera utilisée. S'il est défini de manière explicite sur None, tous les résultats disponibles seront récupérés.
batch_size
Nombre de résultats à tenter de récupérer par lot. Si limit est défini, la valeur par défaut est la limite spécifiée. Sinon, la valeur par défaut est 20.
keys_only
Si true ne renvoie que des clés au lieu d'entités complètes. Les requêtes portant uniquement sur des clés sont plus rapides et moins coûteuses que celles renvoyant des entités complètes.
projection
Liste ou tuple de noms de propriétés à renvoyer. Seules les entités possédant les propriétés spécifiées seront renvoyées. Si cet argument n'est pas spécifié, les entités entières sont renvoyées par défaut. Les requêtes portant sur des projections sont plus rapides et moins coûteuses que celles renvoyant des entités complètes.

Remarque : La spécification de ce paramètre peut modifier les exigences d'index de la requête.

start_cursor
Position du curseur à laquelle lancer la requête.
end_cursor
Position du curseur à laquelle terminer la requête.
get (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

Exécute la requête et renvoie le premier résultat, ou None si aucun résultat n'est trouvé. Au plus un résultat est extrait du datastore. La clause LIMIT de la chaîne de requête GQL, le cas échéant, est ignorée.

Arguments

read_policy
Règles de lecture indiquant le niveau de cohérence des données souhaité :
STRONG_CONSISTENCY
Garantit l'obtention des résultats les plus récents, mais se limite à un seul groupe d'entités.
EVENTUAL_CONSISTENCY
Peut s'étendre à plusieurs groupes d'entités, mais peut parfois renvoyer des résultats obsolètes. En général, les requêtes cohérentes à terme s'exécutent plus rapidement que les requêtes à cohérence forte, mais cela n'est pas garanti.

Remarque : Les requêtes globales (non ascendantes) ignorent cet argument.

deadline
Délai d'attente maximal exprimé en secondes au terme duquel Datastore renvoie un résultat avant d'abandonner en signalant une erreur. Accepte un entier ou une valeur à virgule flottante. Ne peut pas être défini sur une valeur supérieure à la valeur par défaut (60 secondes). Toutefois, il est possible de définir une durée plus courte pour garantir qu'une opération particulière échoue rapidement (par exemple, pour afficher une réponse plus rapide à l'utilisateur, retenter une opération ou ajouter l'opération à une file d'attente).
offset
Nombre de résultats à ignorer avant de renvoyer le premier.
keys_only
Si true ne renvoie que des clés au lieu d'entités complètes. Les requêtes portant uniquement sur des clés sont plus rapides et moins coûteuses que celles renvoyant des entités complètes.
projection
Liste ou tuple de noms de propriétés à renvoyer. Seules les entités possédant les propriétés spécifiées seront renvoyées. Si cet argument n'est pas spécifié, les entités entières sont renvoyées par défaut. Les requêtes portant sur des projections sont plus rapides et moins coûteuses que celles renvoyant des entités complètes.

Remarque : La spécification de ce paramètre peut modifier les exigences d'index de la requête.

start_cursor
Position du curseur à laquelle lancer la requête.
end_cursor
Position du curseur à laquelle terminer la requête.
fetch (limit, read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

Exécute la requête et renvoie une liste de résultats (éventuellement vide) :

  1. Récupère et ignore le nombre de résultats défini par l'argument offset.
  2. Récupère et renvoie jusqu'à concurrence du nombre maximal de résultats défini par l'argument limit.

La performance de la méthode évolue donc de manière linéaire avec la somme offset + limit.

Remarque : Cette méthode est simplement un wrapper léger autour de la méthode run(). Elle est moins efficace et nécessite davantage de mémoire que l'utilisation directe de run(). Vous devriez rarement avoir besoin d'utiliser fetch(). Cette méthode est principalement fournie pour des raisons pratiques lorsque vous devez extraire une liste complète des résultats de requête en mémoire.

Conseil : La méthode fetch() est conçue pour extraire uniquement le nombre de résultats spécifiés par l'argument limit. Pour récupérer tous les résultats disponibles d'une requête lorsque leur nombre est inconnu, utilisez run() avec une taille de lot importante, telle que run(batch_size=1000), au lieu de fetch().

Arguments

limit
Nombre maximum de résultats à renvoyer. S'il est défini sur None, tous les résultats disponibles seront récupérés.
read_policy
Règles de lecture indiquant le niveau de cohérence des données souhaité :
STRONG_CONSISTENCY
Garantit l'obtention des résultats les plus récents, mais se limite à un seul groupe d'entités.
EVENTUAL_CONSISTENCY
Peut s'étendre à plusieurs groupes d'entités, mais peut parfois renvoyer des résultats obsolètes. En général, les requêtes cohérentes à terme s'exécutent plus rapidement que les requêtes à cohérence forte, mais cela n'est pas garanti.

Remarque : Les requêtes globales (non ascendantes) ignorent cet argument.

deadline
Délai d'attente maximal exprimé en secondes au terme duquel Datastore renvoie un résultat avant d'abandonner en signalant une erreur. Accepte un entier ou une valeur à virgule flottante. Ne peut pas être défini sur une valeur supérieure à la valeur par défaut (60 secondes). Toutefois, il est possible de définir une durée plus courte pour garantir qu'une opération particulière échoue rapidement (par exemple, pour afficher une réponse plus rapide à l'utilisateur, retenter une opération ou ajouter l'opération à une file d'attente).
offset
Nombre de résultats à ignorer avant de renvoyer le premier.
keys_only
Si true ne renvoie que des clés au lieu d'entités complètes. Les requêtes portant uniquement sur des clés sont plus rapides et moins coûteuses que celles renvoyant des entités complètes.
projection
Liste ou tuple de noms de propriétés à renvoyer. Seules les entités possédant les propriétés spécifiées seront renvoyées. Si cet argument n'est pas spécifié, les entités entières sont renvoyées par défaut. Les requêtes portant sur des projections sont plus rapides et moins coûteuses que celles renvoyant des entités complètes.

Remarque : La spécification de ce paramètre peut modifier les exigences d'index de la requête.

start_cursor
Position du curseur à laquelle lancer la requête.
end_cursor
Position du curseur à laquelle terminer la requête.
count (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, limit=1000, start_cursor=None, end_cursor=None)

Renvoie le nombre de résultats correspondant à la requête. L'utilisation d’un facteur constant est plus rapide que la récupération de tous les résultats, toutefois le temps d’exécution reste linéaire avec la somme de offset + limit. À moins que le nombre de résultats ne soit censé être faible, il est préférable de spécifier un argument limit, dans la mesure où la méthode continue jusqu'à ce qu'elle ait fini de compter ou expire.

Arguments

read_policy
Règles de lecture indiquant le niveau de cohérence des données souhaité :
STRONG_CONSISTENCY
Garantit l'obtention des résultats les plus récents, mais se limite à un seul groupe d'entités.
EVENTUAL_CONSISTENCY
Peut s'étendre à plusieurs groupes d'entités, mais peut parfois renvoyer des résultats obsolètes. En général, les requêtes cohérentes à terme s'exécutent plus rapidement que les requêtes à cohérence forte, mais cela n'est pas garanti.

Remarque : Les requêtes globales (non ascendantes) ignorent cet argument.

deadline
Délai d'attente maximal exprimé en secondes au terme duquel Datastore renvoie un résultat avant d'abandonner en signalant une erreur. Accepte un entier ou une valeur à virgule flottante. Ne peut pas être défini sur une valeur supérieure à la valeur par défaut (60 secondes). Toutefois, il est possible de définir une durée plus courte pour garantir qu'une opération particulière échoue rapidement (par exemple, pour afficher une réponse plus rapide à l'utilisateur, retenter une opération ou ajouter l'opération à une file d'attente).
offset
Nombre de résultats à ignorer avant de compter le premier.
limit
Nombre maximum de résultats à compter.

Remarque : Si ce paramètre est défini de manière explicite, la valeur spécifiée dans la clause LIMIT de la chaîne de requête GQL sera utilisée. Toutefois, si le paramètre est omis, la valeur par défaut de 1000 ne remplace pas la clause LIMIT de la requête GQL et ne s'applique que si aucune clause LIMIT n'a été spécifiée.

start_cursor
Position du curseur à laquelle lancer la requête.
end_cursor
Position du curseur à laquelle terminer la requête.
index_list ()

Renvoie une liste des index utilisés par une requête exécutée, y compris des index primaires, composites, de types et à propriété unique.

Attention : Le fait de faire appel à cette méthode sur une requête n'ayant pas encore été exécutée déclenche une exception AssertionError.

Remarque : Cette fonctionnalité n'est pas entièrement prise en charge sur le serveur de développement. Lorsqu'elle est utilisée avec le serveur de développement, le résultat obtenu est soit la liste vide, soit une liste contenant exactement un index composite.

Par exemple, le code suivant imprime diverses informations sur les index utilisés par une requête :

# other imports ...
import webapp2
from google.appengine.api import users
from google.appengine.ext import db

class Greeting(db.Model):
  author = db.StringProperty()
  content = db.StringProperty(multiline=True)
  date = db.DateTimeProperty(auto_now_add=True)

class MainPage(webapp2.RequestHandler):
  def get(self):
    user = users.get_current_user()
    q = db.GqlQuery(Greeting)
    q.filter("author =", user.user_id())
    q.order("-date")
    q.fetch(100)
    index_list = q.index_list()
    for ix in index_list:
      self.response.out.write("Kind: %s" % ix.kind())
      self.response.out.write("<br />")
      self.response.out.write("Has ancestor? %s" % ix.has_ancestor())
      self.response.out.write("<br />")
      for name, direction in ix.properties():
        self.response.out.write("Property name: "+name)
        self.response.out.write("<br />")
        if direction == db.Index.DESCENDING:
          self.response.out.write("Sort direction: DESCENDING")
        else:
          self.response.out.write("Sort direction: ASCENDING")
        self.response.out.write("<br />")

Vous devriez voir un résultat semblable à ce qui suit :

Kind: Greeting
Has ancestor? False
Property name: author
Sort direction: ASCENDING
Property name: date
Sort direction: DESCENDING
cursor ()

Renvoie une chaîne de curseur codée en base64 indiquant la position dans le jeu de résultats de la requête à la suite du dernier résultat récupéré. La chaîne de curseur peut être utilisée en toute sécurité dans les paramètres HTTP GET et POST et peut également être stockée dans le datastore ou dans Memcache. Un appel ultérieur de la même requête peut fournir cette chaîne via le paramètre start_cursor ou la méthode with_cursor() pour reprendre la récupération des résultats à partir de cette position.

Attention : Le fait de faire appel à cette méthode sur une requête n'ayant pas encore été exécutée déclenche une exception AssertionError.

Remarque : Toutes les requêtes ne sont pas compatibles avec les curseurs. Consultez la page Requêtes Datastore pour plus d'informations.

with_cursor (start_cursor, end_cursor=None)

Spécifie les positions de départ et (éventuellement) de fin dans le jeu de résultats d'une requête à partir de laquelle extraire les résultats. Les chaînes de curseur indiquant les positions de début et de fin peuvent être obtenues en appelant cursor() après un précédent appel de la requête. La requête en cours doit être identique à l'appel précédent, y compris le type d'entité, les filtres de propriétés, les filtres d'ancêtres et les ordres de tri.

Arguments

start_cursor
Chaîne de curseur codée en Base64 indiquant où démarrer la requête.
end_cursor
Chaîne de curseur codée en Base64 indiquant où terminer la requête.
Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Environnement standard App Engine pour Python