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 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 DB vers NDB.

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

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

Remarque : Le mécanisme de requête basé 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 en mode Datastore. Pour connaître les limites associées aux requêtes 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 genre d'entité. Le constructeur GqlQuery prend pour argument une chaîne de requête, qui est 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 :

Utilisez l'objet de requête comme un itérable afin de traiter les entités correspondantes une par une :
```
for song in q:
  print song.title
```
Ce code appelle implicitement la méthode run() de la requête pour générer les entités correspondantes. Il est comparable au contenu suivant :
```
for song in q.run():
  print song.title
```
L'argument de mot-clé limit vous permet de définir une limite du nombre de résultats à traiter :
```
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 de l'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.

Il est plus rapide de réattribuer des paramètres à un objet GqlQuery existant que de créer un objet GqlQuery, car la chaîne de requête n'a pas besoin d'être analysée à 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 ne contient que 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 afin d'effectuer une boucle sur les résultats de la requête. Cela permet de spécifier le fonctionnement de la requête avec des paramètres et d'accéder aux résultats de manière itérative :

Récupère et supprime le nombre de résultats spécifié par l'argument offset.
Récupère et renvoie jusqu'au nombre maximal de résultats spécifié 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 récupérer 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 fortement cohérentes, 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 renvoyer une réponse plus rapide à l'utilisateur, retenter une opération, lancer une autre opération ou ajouter l'opération à une file d'attente de tâches).

offset

Nombre de résultats à ignorer avant de renvoyer le premier.

limit

nombre maximal 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 l'argument limit est défini, la valeur par défaut est la limite spécifiée. Sinon, elle correspond à 20.

keys_only

Si la valeur est 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 sont 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 fortement cohérentes, mais cela n'est pas garanti.

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

deadline

offset

Nombre de résultats à ignorer avant de renvoyer le premier.

keys_only

projection

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) :

Récupère et supprime le nombre de résultats spécifié par l'argument offset.
Récupère et renvoie jusqu'au nombre maximal de résultats spécifié 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 de bas niveau pour 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 la méthode fetch(), qui est principalement fournie pour des raisons pratiques lorsque vous devez récupérer la liste complète des résultats de requête en mémoire.

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

Arguments

limit

Nombre maximal de résultats sur une page. Si cette valeur est définie sur None, tous les résultats disponibles sont 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 fortement cohérentes, mais cela n'est pas garanti.

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

deadline

offset

Nombre de résultats à ignorer avant de renvoyer le premier.

keys_only

projection

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. Il est plus rapide d'utiliser un facteur constant que de récupérer tous les résultats. Toutefois, le temps d'exécution reste linéaire avec la somme offset + limit. Si vous ne vous attendez pas à obtenir un faible nombre de résultats, il est préférable de spécifier un argument limit. Dans le cas contraire, 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 fortement cohérentes, mais cela n'est pas garanti.

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

deadline

offset

Nombre de résultats à ignorer avant de compter le premier.

limit

Nombre maximal de résultats à compter.

Remarque : Si ce paramètre est spécifié de manière explicite, il remplace la valeur définie dans la clause LIMIT de la chaîne de requête GQL. Toutefois, si le paramètre est omis, la valeur par défaut (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 la liste des index utilisés par une requête exécutée, y compris les index primaires, composites, de types et à propriété unique.

Attention : L'appel de cette méthode sur une requête n'ayant pas encore été exécutée génère une exception AssertionError.

Remarque : Cette fonctionnalité n'est pas entièrement compatible avec le serveur de développement. Lorsqu'elle est utilisée avec ce dernier, vous obtenez une liste vide ou une liste ne contenant qu'un index composite.

Par exemple, le code suivant affiche 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 au suivant :

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

cursor ()

Renvoie une chaîne de curseur encodée en base64 qui indique la position suivant le dernier résultat récupéré dans l'ensemble de résultats de la requête. La chaîne de curseur peut être utilisée en toute sécurité dans les paramètres HTTP GET et POST et ê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 : L'appel de cette méthode sur une requête n'ayant pas encore été exécutée génère une exception AssertionError.

Remarque : Les requêtes ne sont pas toutes compatibles avec les curseurs. Pour en savoir plus, consultez la page Requêtes Datastore.

with_cursor (start_cursor, end_cursor=None)

Spécifie les positions de départ et (éventuellement) de fin dans l'ensemble de résultats d'une requête depuis lequel vous récupérez des 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 genre d'entité, les filtres de propriétés, les filtres d'ancêtre et les ordres de tri.

Arguments

start_cursor: Chaîne de curseur encodé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.