Cursores de consulta

Los cursores de consulta permiten que una aplicación recupere los resultados de una consulta en lotes prácticos, y se recomienda usarlos en lugar de desplazamientos de números enteros para la paginación. Si deseas obtener más información sobre la estructuración de consultas para tu aplicación, revisa Consultas.

Cursores de consulta

Los cursores de consulta permiten que una aplicación recupere los resultados de una consulta en lotes prácticos sin la sobrecarga de un desplazamiento de consulta. Después de realizar una operación de recuperación, la aplicación puede obtener un cursor, que es una string opaca con codificación base64 que marca la posición en el índice del último resultado recuperado. La aplicación puede guardar esta string, por ejemplo, en Cloud Datastore, en Memcache, en la carga útil de una tarea de la lista de tareas en cola, o incorporada en una página web como un parámetro GET o POST de HTTP, y luego puede usar el cursor como punto de partida para una operación de recuperación posterior a fin de obtener el siguiente lote de resultados del punto donde terminó la recuperación anterior. Una recuperación también puede especificar un cursor de fin para limitar la extensión del conjunto de resultados que se muestran.

Desplazamientos frente a cursores

Si bien Cloud Datastore admite desplazamientos de números enteros, no es recomendable usarlos. En su lugar, usa cursores. Usar un desplazamiento solo evita que se muestren las entidades omitidas en la aplicación, pero se siguen recuperando internamente. Las entidades omitidas afectan a la latencia de la consulta y tu aplicación se factura por las operaciones de lectura necesarias para recuperarlas. Usar cursores en lugar de desplazamientos te permite evitar todos estos costos.

Ejemplo de cursor de consulta

En Go, una aplicación obtiene un cursor después de recuperar los resultados de la consulta mediante la llamada al método Cursor del valor Iterator. Para recuperar resultados adicionales desde el punto del cursor, la aplicación prepara una consulta similar con el mismo grupo de tipos de entidad, los mismos filtros y los mismos órdenes de clasificación, y pasa el cursor al método Start de la consulta antes de realizar la recuperación:

// 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()),
	})
}

Limitaciones de los cursores

Los cursores están sujetos a las siguientes limitaciones:

  • Un cursor solo puede usarse en la misma aplicación que realizó la consulta original y solo para continuar la misma consulta. Para usar el cursor en una operación de recuperación posterior, debes reconstituir la consulta original exactamente, incluidos el mismo de tipo de entidad, filtro de principal, filtros de propiedades y órdenes de clasificación. No es posible recuperar resultados con un cursor sin configurar la misma consulta desde la que se generó.
  • Los cursores no siempre se comportan de la forma esperada con una consulta que usa un filtro de desigualdad o un orden de clasificación que depende de una propiedad con valores múltiples. La lógica de deduplicación para esas propiedades con varios valores no persiste entre las recuperaciones, lo que, posiblemente, hará que el mismo resultado se muestre más de una vez.
  • Es posible que versiones nuevas de App Engine cambien algunos detalles de la implementación interna, lo cual invalidaría los cursores que dependen de ellos. Si una aplicación intenta usar un cursor que ya no es válido, Cloud Datastore muestra un error.

Cursores y actualizaciones de datos

La posición del cursor se define como la ubicación en la lista de resultados que le sigue al último resultado que se mostró. Un cursor no es una posición relativa en la lista (no es un desplazamiento); es un marcador al que puede saltar Cloud Datastore cuando se inicia un análisis de índice para obtener resultados. Si los resultados de una consulta cambian entre los usos de un cursor, la consulta notará solo los cambios que se producen en los resultados que aparecen después del cursor. Si aparece un resultado nuevo antes de la posición del cursor para la consulta, este no se mostrará cuando se recuperen los resultados que aparecen después del cursor. De igual modo, si una entidad ya no es un resultado para una consulta, pero ha aparecido antes del cursor, los resultados que aparecen después del cursor no se modifican. Si se quita el último resultado que se muestra del conjunto de resultados, el cursor aún podrá localizar el resultado siguiente.

Cuando se recuperan resultados de consulta, puedes usar un cursor de inicio y un cursor de fin para que se muestre un grupo continuo de resultados de Cloud Datastore. Cuando se usa un cursor de inicio y de fin para recuperar los resultados, no hay garantía de que el tamaño de los resultados será el mismo que cuando se generaron los cursores. Es posible agregar o borrar entidades desde Cloud Datastore entre el momento en que se generan los cursores y en el que se los utiliza en una consulta.

Pasos siguientes

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Entorno estándar de App Engine para Go