Consultas do Datastore

Uma consulta do Datastore recupera entidades do Cloud Datastore que atendem a um conjunto específico de condições.

Uma consulta típica inclui:

Quando executada, a consulta recupera todas as entidades do tipo determinado que satisfaçam a todos os filtros fornecidos, classificadas na ordem especificada. As consultas são executadas no modo somente leitura.

Nesta página, descrevemos a estrutura e tipos de consultas usadas no App Engine para recuperar dados do Cloud Datastore.

Filtros

O conjunto de filtros de uma consulta restringe as propriedades, chaves e ancestrais das entidades que serão recuperadas.

Filtros de propriedade

Um filtro de propriedade especifica:

  • um nome de propriedade;
  • um operador de comparação;
  • um valor de propriedade.
Exemplo:

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

O valor da propriedade deve ser fornecido pelo aplicativo. Ele não pode referir-se a outras propriedades nem ser calculado em relação a elas. Uma entidade satisfaz ao filtro se tiver uma propriedade com o nome determinado com valor igual ao especificado no filtro, da maneira descrita pelo operador de comparação.

O operador de comparação pode ser qualquer um destes:

Operador Significado
= Igual a
< Menor que
<= Menor que ou igual a
> Maior que
>= Maior que ou igual a

Filtros de chave

Para filtrar o valor da chave de uma entidade, use a propriedade especial __key__.

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

Na comparação por desigualdade, as chaves são ordenadas pelos seguintes critérios, nesta ordem:

  1. Caminho do ancestral
  2. Tipo de entidade
  3. Identificador (nome da chave ou ID numérico)

Os elementos do caminho ancestral são comparados de forma análoga: por tipo (string) e, em seguida, por nome de chave ou ID numérico. Os tipos e nomes de chave são strings e estão ordenados por valor de bytes. Os IDs numéricos são representados em números inteiros e ordenados numericamente. Se entidades com o mesmo pai e do mesmo tipo usarem uma combinação de strings de nomes de chave e IDs numéricos, aquelas com códigos numéricos precederão as entidades com nomes de chave.

As consultas por chaves usam índices da mesma maneira que as consultas por propriedades e exigem índices personalizados nos mesmos casos. Porém, há algumas exceções: filtros de desigualdade ou uma ordem de classificação crescente na chave não exigem um índice personalizado, mas uma ordem de classificação decrescente na chave, sim. Como em todas as consultas, o servidor da Web de desenvolvimento cria as entradas adequadas no arquivo de configuração de índices quando uma consulta que precisa de um índice personalizado é testada.

Filtros de ancestrais

É possível filtrar as consultas do Datastore de acordo com um ancestral especificado para que os resultados retornados incluam apenas entidades descendentes desse ancestral:

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

Tipos de consulta especiais

Alguns tipos específicos de consulta merecem uma menção especial:

Consultas sem tipo

Uma consulta sem tipo e sem nenhum filtro ancestral recupera todas as entidades de um aplicativo do Datastore. Isso inclui entidades criadas e gerenciadas por outros recursos do App Engine, como entidades de estatísticas e entidades de metadados do Blobstore (se houver). Essas consultas sem tipo não podem incluir filtros ou ordens de classificação para valores de propriedade. Eles podem, no entanto, filtrar chaves de entidade especificando __key__ como o nome da propriedade:

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

Consultas de ancestral

Uma consulta com um filtro ancestral limita os resultados à entidade especificada e seus descendentes:

// 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 de ancestral sem tipo

Uma consulta sem tipo que inclui um filtro ancestral recuperará o ancestral especificado e todos os descendentes dele, independentemente do tipo. Esse tipo de consulta não requer índices personalizados. Como todas as consultas sem tipo, ela não inclui filtros ou ordens de classificação em valores de propriedade, mas pode filtrar a chave da entidade:

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

O exemplo a seguir mostra como recuperar todas as entidades descendentes de um determinado ancestral:

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 apenas de chaves

Uma consulta apenas de chaves retorna somente as chaves das entidades resultantes em vez das próprias entidades, o que resulta em menor latência e custo do que a recuperação de entidades inteiras:

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

Muitas vezes, é mais econômico fazer uma consulta apenas de chaves primeiro e, em seguida, buscar um subconjunto de entidades nos resultados em vez de executar uma consulta geral, que pode buscar mais entidades do que você realmente precisa.

Observe que uma consulta somente de chaves pode retornar mais de 1.000 resultados, mas GetAll só pode recuperar 1.000 chaves por vez e falhará com um erro se for chamado em um resultado maior. Portanto, recomendamos a adição de um limite de 1.000 chaves à consulta.

Consultas de projeção

Às vezes a única coisa de que você precisa dos resultados de uma consulta são os valores de algumas propriedades específicas. Nesses casos, é possível usar uma consulta de projeção para recuperar apenas as propriedades relevantes, com latência e custos menores do que recuperar toda a entidade. Para mais detalhes, acesse a página Consultas de projeção.

Ordens de classificação

A ordem de classificação de uma consulta específica:

  • um nome de propriedade;
  • uma direção de classificação (crescente ou decrescente);

no Go, a ordem de classificação decrescente é indicada por um hífen (-) antes do nome da propriedade. A omissão do hífen especifica a ordem crescente por padrão. Por exemplo:

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

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

Se uma consulta incluir várias ordens de classificação, elas serão aplicadas na sequência especificada. O exemplo a seguir classifica primeiro pelo sobrenome crescente e, em seguida, pela altura decrescente:

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

Se nenhuma ordem de classificação for especificada, os resultados serão retornados na ordem em que forem recuperados do Datastore.

Observação: devido à maneira como o Datastore executa consultas, se uma consulta especificar filtros de desigualdade em uma propriedade e ordens de classificação em outras propriedades, a propriedade usada nos filtros de desigualdade precisará ser ordenada antes das outras propriedades.

Índices

Toda consulta do Datastore calcula os resultados usando um ou mais índices. Eles contêm chaves de entidade em uma sequência especificada pelas propriedades deles ou pelos ancestrais da entidade. Os índices são atualizados de forma incremental para refletir as alterações feitas pelo aplicativo nas entidades. Assim, os resultados corretos de todas as consultas ficam disponíveis sem que nenhum outro cálculo seja necessário.

O App Engine predefine um índice simples em cada propriedade de uma entidade. Um aplicativo do App Engine pode definir outros índices personalizados em um arquivo de configuração de índice chamado index.yaml. O servidor de desenvolvimento adiciona sugestões a esse arquivo automaticamente quando encontra consultas não executáveis com os índices atuais. Você pode ajustar os índices manualmente editando o arquivo antes de fazer o upload do aplicativo.

Exemplo de interface de consulta

A API Datastore para Go fornece um tipo de consulta para preparação e execução de 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.
	}
	// ...
}

A seguir