Curseurs de requêtes

Les curseurs de requêtes permettent à une application de récupérer les résultats d'une requête sous forme de lots pratiques. Il est recommandé de privilégier leur utilisation à celle de décalages d'entiers pour la pagination. Pour savoir comment structurer des requêtes pour l'application, consultez la page Requêtes.

Curseurs de requêtes

Les curseurs de requêtes permettent à une application de récupérer les résultats d'une requête sous forme de lots pratiques sans entraîner la surcharge d'un décalage de requête. Après avoir effectué une opération de récupération, l'application peut obtenir un curseur, qui est une chaîne opaque encodée en base64 indiquant la position d'index du dernier résultat récupéré. L'application peut enregistrer cette chaîne, par exemple dans Datastore, dans Memcache, dans une charge utile de tâche de la file d'attente de tâches, ou en l'intégrant dans une page Web en tant que paramètre HTTP GET ou POST. Elle peut ensuite utiliser le curseur comme point de départ d'une opération de récupération ultérieure, afin d'obtenir le prochain lot de résultats à partir du point où la récupération précédente s'est terminée. Une récupération peut également spécifier un curseur de fin afin de limiter l'étendue de l'ensemble de résultats renvoyé.

Décalages et curseurs

Bien que Datastore accepte les décalages d'entiers, vous devriez éviter de les utiliser. Employez plutôt des curseurs. L'utilisation d'un décalage permet uniquement d'éviter de renvoyer les entités ignorées à l'application, mais ces dernières sont tout de même récupérées en interne. Les entités ignorées ont une incidence sur la latence de la requête, et l'application est facturée pour les opérations de lecture nécessaires à leur récupération. En faisant appel à des curseurs plutôt qu'à des décalages, vous évitez tous ces coûts.

Exemple de curseur de requête

Dans Go, une application obtient un curseur après avoir récupéré les résultats de la requête en appelant la méthode Cursor de la valeur Iterator. Pour récupérer des résultats supplémentaires à partir du point du curseur, l'application prépare une requête similaire avec le même genre d'entité, les mêmes filtres et les mêmes ordres de tri, puis transmet le curseur à la méthode Start de la requête avant de procéder à la récupération :

// Create a query for all Person entities.
q := datastore.NewQuery("Person")

// If the application stored a cursor during a previous request, use it.
item, err := memcache.Get(ctx, "person_cursor")
if err == nil {
	cursor, err := datastore.DecodeCursor(string(item.Value))
	if err == nil {
		q = q.Start(cursor)
	}
}

// Iterate over the results.
t := q.Run(ctx)
for {
	var p Person
	_, err := t.Next(&p)
	if err == datastore.Done {
		break
	}
	if err != nil {
		log.Errorf(ctx, "fetching next Person: %v", err)
		break
	}
	// Do something with the Person p
}

// Get updated cursor and store it for next time.
if cursor, err := t.Cursor(); err == nil {
	memcache.Set(ctx, &memcache.Item{
		Key:   "person_cursor",
		Value: []byte(cursor.String()),
	})
}

Limites relatives aux curseurs

Les curseurs sont soumis aux limites suivantes :

  • Un curseur ne peut être utilisé que par l'application qui a exécuté la requête d'origine et uniquement pour poursuivre la même requête. Pour utiliser le curseur dans une opération de récupération ultérieure, vous devez reconstituer exactement la requête d'origine, avec le même genre d'entité, le même filtre d'ancêtre, les mêmes filtres de propriétés et les mêmes ordres de tri. Il est impossible de récupérer des résultats à l'aide d'un curseur sans configurer une requête identique à celle à partir de laquelle il a été généré.
  • Les curseurs ne fonctionnent pas toujours comme prévu avec une requête utilisant un filtre d'inégalité ou un ordre de tri sur une propriété comportant plusieurs valeurs. Comme la logique de déduplication de ces propriétés à valeurs multiples ne persiste pas entre les récupérations, le même résultat peut être renvoyé plusieurs fois.
  • Les nouvelles versions d'App Engine peuvent modifier des détails de mise en œuvre interne, et ainsi invalider les curseurs qui en dépendent. Si une application tente d'utiliser un curseur qui n'est plus valide, Datastore renvoie une erreur.

Mises à jour des curseurs et des données

La position du curseur se définit comme l'emplacement dans la liste de résultats après renvoi du dernier résultat. Un curseur n'est pas une position relative dans la liste (ce n'est pas un décalage). Il s'agit d'un marqueur auquel Datastore peut accéder lors du lancement d'une analyse des résultats dans un index. Si les résultats d'une requête changent entre les différentes utilisations d'un curseur, la requête remarque uniquement les modifications apportées aux résultats situés après le curseur. Si un nouveau résultat apparaît avant la position du curseur pour cette requête, il n'est pas renvoyé lors de la récupération des résultats situés après le curseur. De la même façon, si une entité ne constitue plus un résultat d'une requête, alors qu'elle apparaissait avant le curseur, les résultats situés après le curseur ne changent pas. Si le dernier résultat renvoyé est supprimé de l'ensemble de résultats, le curseur est toujours capable de localiser le résultat suivant.

Lors de la récupération des résultats de la requête, vous pouvez utiliser un curseur de début et un curseur de fin pour renvoyer un groupe continu de résultats à partir de Datastore. Lorsque vous utilisez un curseur de début et de fin pour récupérer les résultats, il n'est pas certain que vous obteniez la même taille de résultats que celle obtenue lorsque vous avez généré les curseurs. Des entités peuvent être ajoutées ou supprimées de Datastore entre le moment où les curseurs sont générés et celui où ils sont employés dans une requête.

Étapes suivantes