Consultas de Datastore

Esta API es compatible con entornos de ejecución de primera generación y se puede usar en actualizaciones a los entornos de ejecución de segunda generación correspondientes. Si actualizas al entorno de ejecución de Go 1.12+ de App Engine, consulta la guía de migración para obtener información sobre tus opciones de migración para servicios empaquetados heredados.

Una consulta de Datastore recupera entidades de Cloud Datastore que cumplen con un conjunto específico de condiciones.

Una consulta típica incluye lo siguiente:

• Una categoría de entidad a la que se aplica la consulta
• Filtros opcionales basados en los valores de las propiedades, las claves y los principales de las entidades
• Órdenes de clasificación opcionales para secuenciar los resultados

Cuando se ejecuta, la consulta recupera todas las entidades de esa categoría que satisfacen todos los filtros indicados, en el orden que se especificó. Las consultas se ejecutan en modo de solo lectura.

En esta página se describe la estructura y las categorías de consultas usadas dentro de App Engine para recuperar datos de Cloud Datastore.

Filtros

El conjunto de filtros de una consulta limita las propiedades, las claves y los principales de las entidades que se recuperarán.

Filtros de propiedades

Un filtro de propiedad especifica lo siguiente:

• El nombre de una propiedad
• Un operador de comparación
• El valor de una propiedad

Por ejemplo:

q := datastore.NewQuery("Person").Filter("Height <=", maxHeight)

La aplicación debe proporcionar el valor de la propiedad. No se le puede hacer referencia ni se puede calcular en términos de otras propiedades. Una entidad satisface el filtro si tiene una propiedad con el nombre dado, cuyo valor se compara con el valor especificado en el filtro, de acuerdo con la descripción del operador de comparación.

El operador de comparación puede ser cualquiera de las siguientes opciones:

Operador	Significado
=	Igual a
<	Inferior a
<=	Menor que o igual que
>	Mayor que
>=	Superior o igual a

Filtros de clave

Para filtrar el valor de la clave de una entidad, usa la propiedad especial __key__:

q := datastore.NewQuery("Person").Filter("__key__ >", lastSeenKey)

Cuando se usa un comparador de desigualdad, se aplican los siguientes criterios para clasificar las claves, en orden:

1. Ruta del principal
2. Tipo de entidad
3. Identificador (nombre de clave o ID numérico)

Los elementos de la ruta principal se comparan de manera similar: por tipo (string) y, luego, por nombre de clave o ID numérico. Los tipos y los nombres de clave son strings y se ordenan por valor de byte. Los ID numéricos son números enteros ordenados de forma numérica. Si varias entidades que tienen el mismo principal y tipo usan una combinación de ID numéricos y strings con nombre de clave, las entidades que tienen ID numéricos anteceden a las que tienen nombres de clave.

Las consultas sobre claves usan índices, al igual que las consultas sobre propiedades, y requieren índices personalizados en los mismos casos, salvo algunas excepciones: cuando se usan filtros de desigualdad o un orden de clasificación ascendente en la clave, no se necesita un índice personalizado; cuando se usa un orden de clasificación descendente en la clave, sí se necesita. Al igual que con todas las consultas, el servidor web de desarrollador crea entradas adecuadas en el archivo de configuración de índices cuando se prueba una consulta que requiere un índice personalizado.

Filtros principales

Puedes filtrar tus consultas de Datastore según un principal específico para que los resultados incluyan solo las entidades que descienden de él.

q := datastore.NewQuery("Person").Ancestor(ancestorKey)

Precaución: Pasar null como la clave del principal no consultará las entidades raíz (aquellas sin principales). Este tipo de consulta no se admite en la actualidad y mostrará un error.

Tipos especiales de consultas

Hay algunos tipos específicos de consultas que merecen una mención especial:

Consultas sin categoría

Cuando una consulta no especifica el tipo ni el principal, se muestran todas las entidades de una aplicación del almacén de datos. Esto incluye entidades creadas y administradas por otras funciones de App Engine, como las entidades de estadísticas y las entidades de metadatos de Blobstore, si las hubiera. Estas consultas sin categoría no pueden incluir filtros ni órdenes de clasificación en los valores de las propiedades. Sin embargo, pueden filtrar las claves de entidad con solo especificar __key__ como el nombre de la propiedad:

q := datastore.NewQuery("").Filter("__key__ >", lastSeenKey)

Consultas principales

Una consulta con un filtro de principal limita sus resultados a la entidad especificada y a sus secundarios.

// Create two Photo entities in the datastore with a Person as their ancestor.
tomKey := datastore.NewKey(ctx, "Person", "Tom", 0, nil)

wPhoto := Photo{URL: "http://example.com/some/path/to/wedding_photo.jpg"}
wKey := datastore.NewKey(ctx, "Photo", "", 0, tomKey)
_, err := datastore.Put(ctx, wKey, wPhoto)
// check err

bPhoto := Photo{URL: "http://example.com/some/path/to/baby_photo.jpg"}
bKey := datastore.NewKey(ctx, "Photo", "", 0, tomKey)
_, err = datastore.Put(ctx, bKey, bPhoto)
// check err

// Now fetch all Photos that have tomKey as an ancestor.
// This will populate the photos slice with wPhoto and bPhoto.
q := datastore.NewQuery("Photo").Ancestor(tomKey)
var photos []Photo
_, err = q.GetAll(ctx, &photos)
// check err
// do something with photos

Consultas principales sin categoría

Una consulta sin categoría que incluye un filtro principal recuperará el principal especificado y todos sus descendientes, sin importar la categoría. Este tipo de consulta no requiere índices personalizados. Al igual que todas las consultas sin categoría, no pueden incluir filtros ni órdenes de clasificación para los valores de las propiedades, pero pueden filtrarse según la clave de la entidad.

q := datastore.NewQuery("").Ancestor(ancestorKey).Filter("__key__ >", lastSeenKey)

El siguiente ejemplo muestra cómo recuperar todas las entidades descendientes de determinado principal:

tomKey := datastore.NewKey(ctx, "Person", "Tom", 0, nil)

weddingPhoto := &Photo{URL: "http://example.com/some/path/to/wedding_photo.jpg"}
_, err := datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Photo", tomKey), weddingPhoto)

weddingVideo := &Video{URL: "http://example.com/some/path/to/wedding_video.avi"}
_, err = datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Video", tomKey), weddingVideo)

// The following query returns both weddingPhoto and weddingVideo,
// even though they are of different entity kinds.
q := datastore.NewQuery("").Ancestor(tomKey)
t := q.Run(ctx)
for {
	var x interface{}
	_, err := t.Next(&x)
	if err == datastore.Done {
		break
	}
	if err != nil {
		log.Errorf(ctx, "fetching next Photo/Video: %v", err)
		break
	}
	// Do something (e.g. switch on types)
	doSomething(x)
}

Consultas de solo clave

Una consulta de solo clave muestra solo las claves de las entidades resultantes, en lugar de las entidades en sí, con una latencia y un costo más bajos que recuperar entidades completas:

q := datastore.NewQuery("Person").KeysOnly()

A menudo, es más rentable hacer primero consultas de solo claves y, luego, elegir un subconjunto de entidades de los resultados, en lugar de ejecutar una consulta general que puede arrojar más entidades de las que necesitas.

Ten en cuenta que una consulta de solo claves puede mostrar más de 1,000 resultados, pero GetAll solo puede recuperar 1,000 claves a la vez y mostrará un error si se la llama con un resultado mayor. Por lo tanto, es recomendable que agregues un límite de 1,000 claves a la consulta.

Consultas de proyección

En ocasiones, lo único que necesitas de los resultados de una consulta son los valores de unas pocas propiedades específicas. En estos casos, puedes usar una consulta de proyección a fin de recuperar solo las propiedades que en realidad te interesan, con costos y latencia menores que los de recuperar toda la entidad. Revisa la página Consultas de proyección para obtener más detalles.

Órdenes de clasificación

Un orden de clasificación de consulta especifica lo siguiente:

• El nombre de una propiedad
• Un orden de clasificación (ascendente o descendente)

En Go, el orden de clasificación descendente se denota por medio de un guion (-) que precede al nombre de la propiedad. Cuando se omite el guion, se especifica un orden ascendente como valor predeterminado. Por ejemplo:

// Order alphabetically by last name:
q := datastore.NewQuery("Person").Order("LastName")

// Order by height, tallest to shortest:
q = datastore.NewQuery("Person").Order("-Height")

Si una consulta incluye varios órdenes de clasificación, estos se aplican en la secuencia especificada. En el siguiente ejemplo, primero se clasifica por apellido ascendente, luego, por altura descendente:

q := datastore.NewQuery("Person").Order("LastName").Order("-Height")

Si no se especifica ningún orden de clasificación, los resultados se muestran en el orden en que se recuperan de Datastore.

Nota: Debido a la forma en que Datastore ejecuta las consultas, si una consulta especifica filtros de desigualdad en una propiedad y órdenes de clasificación en otras propiedades, la propiedad que se use en los filtros de desigualdad deberá ordenarse antes de las demás propiedades.

Índices

Cada consulta de Datastore calcula los resultados con uno o más índices, que contienen claves de entidad en una secuencia especificada por las propiedades del índice y, de forma opcional, los principales de la entidad. Los índices se actualizan de forma incremental con los cambios que la aplicación haga a sus entidades, de modo que los resultados correctos de todas las consultas estén disponibles sin necesidad de realizar cálculos adicionales.

App Engine predefine un índice simple en cada propiedad de una entidad. Una aplicación de App Engine puede definir más índices personalizados en un archivo de configuración de índice llamado index.yaml. El servidor de desarrollo agrega sugerencias a este archivo de forma automática cuando encuentra consultas que no pueden ejecutarse con los índices existentes. Para ajustar los índices de manera manual, edita el archivo antes de subir la aplicación.

Ejemplo de interfaz de consulta

La API de Datastore de Go brinda un tipo de consulta para preparar y ejecutar consultas.

type Person struct {
	FirstName string
	LastName  string
	City      string
	BirthYear int
	Height    int
}

func handle(w http.ResponseWriter, r *http.Request) {
	ctx := appengine.NewContext(r)

	// The Query type and its methods are used to construct a query.
	q := datastore.NewQuery("Person").
		Filter("LastName =", "Smith").
		Filter("Height <=", maxHeight).
		Order("-Height")

	// To retrieve the results,
	// you must execute the Query using its GetAll or Run methods.
	var people []Person
	if _, err := q.GetAll(ctx, &people); err != nil {
		// Handle error.
	}
	// ...
}

Nota: Las propiedades filtradas deben tener un índice predefinido correspondiente que se puede definir en el archivo de configuración del índice (index.yaml).

Próximos pasos

• Aprende a especificar lo que muestra una consulta y cómo controlar en mayor medida los resultados de consultas.
• Aprende las restricciones comunes para las consultas en Cloud Datastore.
• Obtén información sobre los cursores de consulta, que permiten que una aplicación recupere los resultados de una consulta en lotes convenientes.
• Comprende la coherencia de datos y su funcionamiento con diferentes tipos de consultas en Cloud Datastore.