Consultas do Datastore

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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

A consulta opera em entidades de um determinado tipo. Ela especifica filtros nos valores de propriedades, chaves e ancestrais das entidades e retorna zero ou mais entidades como resultados. Uma consulta também pode especificar ordens de classificação para colocar os resultados em sequência pelos respectivos valores de propriedade. Os resultados incluem todas as entidades que tenham pelo menos um valor para cada propriedade nomeada nos filtros e ordens de classificação e cujos valores de propriedade atendam a todos os critérios de filtro especificados. A consulta pode retornar entidades inteiras, entidades projetadas ou apenas chaves de entidade.

Uma consulta típica inclui o seguinte:

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

Observação: para economizar memória e melhorar o desempenho, sempre que possível uma consulta precisa especificar um limite para o número de resultados retornados.

Em todas as consultas, os resultados são calculados com o uso de um ou mais índices, que contêm chaves de entidade em uma sequência especificada pelas propriedades do índice ou pelos ancestrais da entidade. Os índices são atualizados para refletir as alterações feitas pelo aplicativo nas entidades. Assim, os resultados corretos de todas as consultas ficam disponíveis sem precisar computar mais nada.

O mecanismo de consulta baseado nos índices é compatível com uma grande variedade de consultas e adequado à maioria dos aplicativos. No entanto, ele não aceita alguns tipos de consulta comuns em outras tecnologias de banco de dados. Em particular, as consultas agregadas e conjuntas não são compatíveis com o mecanismo de consulta do modo Datastore. Consulte o artigo Restrições em consultas para ver as limitações em consultas do modo Datastore.

Interface de consulta

Veja a seguir um exemplo básico de consulta gerada em um banco de dados do modo Datastore. Ela recupera todas as tarefas com prioridades maiores ou iguais a 4 que ainda não foram realizadas, classificadas em ordem decrescente por prioridade:

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.Equal("done", false),
        Filter.GreaterThanOrEqual("priority", 4)),
    Order = { { "priority", PropertyOrder.Types.Direction.Descending } }
};

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

query := datastore.NewQuery("Task").
	Filter("Done =", false).
	Filter("Priority >=", 4).
	Order("-Priority")

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(
            CompositeFilter.and(
                PropertyFilter.eq("done", false), PropertyFilter.ge("priority", 4)))
        .setOrderBy(OrderBy.desc("priority"))
        .build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const query = datastore
  .createQuery('Task')
  .filter('done', '=', false)
  .filter('priority', '>=', 4)
  .order('priority', {
    descending: true,
  });

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$query = $datastore->query()
    ->kind('Task')
    ->filter('done', '=', false)
    ->filter('priority', '>=', 4)
    ->order('priority', Query::ORDER_DESCENDING);

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.add_filter("done", "=", False)
query.add_filter("priority", ">=", 4)
query.order = ["-priority"]

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

query = datastore.query("Task")
                 .where("done", "=", false)
                 .where("priority", ">=", 4)
                 .order("priority", :desc)

GQL


SELECT * FROM Task
WHERE done = FALSE AND priority >= 4
ORDER BY priority DESC

Veja como executar uma consulta:

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task");
DatastoreQueryResults tasks = _db.RunQuery(query);

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

it := client.Run(ctx, query)
for {
	var task Task
	_, err := it.Next(&task)
	if err == iterator.Done {
		break
	}
	if err != nil {
		log.Fatalf("Error fetching next task: %v", err)
	}
	fmt.Printf("Task %q, Priority %d\n", task.Description, task.Priority)
}

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

QueryResults<Entity> tasks = datastore.run(query);

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const [tasks] = await datastore.runQuery(query);
console.log('Tasks:');
tasks.forEach(task => console.log(task));

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$result = $datastore->runQuery($query);

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query()
results = list(query.fetch())

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

tasks = datastore.run query

GQL

Não relevante

Estrutura da consulta

Com uma consulta, é possível especificar um tipo de entidade e zero ou mais filtros ou ordens de classificação.

Filtros

O conjunto de filtros de uma consulta restringe as propriedades, as chaves e os ancestrais das entidades a serem recuperadas.

Filtros de propriedade

Um filtro de propriedade especifica:

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

O exemplo a seguir retorna entidades Task marcadas como não concluídas:

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task")
{
    Filter = Filter.Equal("done", false)
};

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

query := datastore.NewQuery("Task").Filter("Done =", false)

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.eq("done", false))
        .build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const query = datastore.createQuery('Task').filter('done', '=', false);

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$query = $datastore->query()
    ->kind('Task')
    ->filter('done', '=', false);

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.add_filter("done", "=", False)

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

query = datastore.query("Task")
                 .where("done", "=", false)

GQL


SELECT * FROM Task WHERE done = FALSE

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. Se a propriedade com o nome determinado tiver seu valor atribuído por matriz, a entidade satisfaz ao filtro se qualquer um dos valores for igual ao valor especificado no filtro da maneira descrita pelo operador de comparação.

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

Operador Significado
EQUAL Igual a
LESS_THAN Menor que
LESS_THAN_OR_EQUAL Menor que ou igual a
GREATER_THAN Maior que
GREATER_THAN_OR_EQUAL Maior que ou igual a
NOT_EQUAL Diferente de
IN Membro da lista especificada. Igual a qualquer um dos valores em uma lista especificada.
NOT_IN Não faz parte da lista especificada. Diferente de qualquer um dos valores em uma lista especificada.

Filtros compostos

Um filtro composto consiste em mais de um filtro de propriedade. O exemplo a seguir retorna entidades Task marcadas como não concluídas e têm prioridade 4:

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.Equal("done", false),
        Filter.Equal("priority", 4)),
};

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

query := datastore.NewQuery("Task").Filter("Done =", false).Filter("Priority =", 4)

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(
            CompositeFilter.and(
                PropertyFilter.eq("done", false), PropertyFilter.eq("priority", 4)))
        .build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const query = datastore
  .createQuery('Task')
  .filter('done', '=', false)
  .filter('priority', '=', 4);

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$query = $datastore->query()
    ->kind('Task')
    ->filter('done', '=', false)
    ->filter('priority', '=', 4);

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.add_filter("done", "=", False)
query.add_filter("priority", "=", 4)

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

query = datastore.query("Task")
                 .where("done", "=", false)
                 .where("priority", "=", 4)

GQL


SELECT * FROM Task WHERE done = FALSE AND priority = 4

O Firestore no modo Datastore oferece suporte nativo a combinações de filtros com o operador AND.

Principais filtros

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

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task")
{
    Filter = Filter.GreaterThan("__key__", _keyFactory.CreateKey("aTask"))
};

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

key := datastore.NameKey("Task", "someTask", nil)
query := datastore.NewQuery("Task").Filter("__key__ >", key)

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.gt("__key__", keyFactory.newKey("someTask")))
        .build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const query = datastore
  .createQuery('Task')
  .filter('__key__', '>', datastore.key(['Task', 'someTask']));

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$query = $datastore->query()
    ->kind('Task')
    ->filter('__key__', '>', $datastore->key('Task', 'someTask'));

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
first_key = client.key("Task", "first_task")
# key_filter(key, op) translates to add_filter('__key__', op, key).
query.key_filter(first_key, ">")

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

query = datastore.query("Task")
                 .where("__key__", ">", datastore.key("Task", "someTask"))

GQL


SELECT * FROM Task WHERE __key__ > KEY(Task, 'someTask')

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, com 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 de desenvolvimento cria as entradas apropriadas no arquivo de configuração de índice quando uma consulta que precisa de um índice personalizado é usada no ambiente de desenvolvimento.

Ordens de classificação

A ordem de classificação de uma consulta especifica:

  • um nome de propriedade;
  • uma direção de classificação (crescente ou decrescente). Por padrão, a ordem de classificação é crescente.

O exemplo a seguir classifica entidades Task por hora de criação em ordem crescente:

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task")
{
    Order = { { "created", PropertyOrder.Types.Direction.Ascending } }
};

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

query := datastore.NewQuery("Task").Order("created")

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<Entity> query =
    Query.newEntityQueryBuilder().setKind("Task").setOrderBy(OrderBy.asc("created")).build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const query = datastore.createQuery('Task').order('created');

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$query = $datastore->query()
    ->kind('Task')
    ->order('created');

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.order = ["created"]

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

query = datastore.query("Task")
                 .order("created", :asc)

GQL


SELECT * FROM Task ORDER BY created ASC

O exemplo a seguir classifica entidades Task por hora de criação em ordem decrescente:

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task")
{
    Order = { { "created", PropertyOrder.Types.Direction.Descending } }
};

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

query := datastore.NewQuery("Task").Order("-created")

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<Entity> query =
    Query.newEntityQueryBuilder().setKind("Task").setOrderBy(OrderBy.desc("created")).build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const query = datastore.createQuery('Task').order('created', {
  descending: true,
});

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$query = $datastore->query()
    ->kind('Task')
    ->order('created', Query::ORDER_DESCENDING);

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.order = ["-created"]

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

query = datastore.query("Task")
                 .order("created", :desc)

GQL


SELECT * FROM Task ORDER BY created DESC

Se uma consulta incluir várias ordens de classificação, elas serão aplicadas na sequência especificada. O exemplo a seguir classifica primeiro por prioridade decrescente e depois por tempo de criação crescente:

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task")
{
    Order = { { "priority", PropertyOrder.Types.Direction.Descending },
        { "created", PropertyOrder.Types.Direction.Ascending } }
};

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

query := datastore.NewQuery("Task").Order("-priority").Order("created")

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setOrderBy(OrderBy.desc("priority"), OrderBy.asc("created"))
        .build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const query = datastore
  .createQuery('Task')
  .order('priority', {
    descending: true,
  })
  .order('created');

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$query = $datastore->query()
    ->kind('Task')
    ->order('priority', Query::ORDER_DESCENDING)
    ->order('created');

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.order = ["-priority", "created"]

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

query = datastore.query("Task")
                 .order("priority", :desc)
                 .order("created", :asc)

GQL


SELECT * FROM Task ORDER BY priority DESC, created ASC

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

Observação: devido à maneira como o modo 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.

Tipos de consulta especiais

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

!= Not equal

Use o operador "diferente de" (!=) para retornar entidades em que a propriedade especificada existe e não corresponde ao valor da comparação.

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Não relevante

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

Não relevante

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.neq("category", "Work"))
        .build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

Não relevante

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

Não relevante

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

query = client.query(kind="Task")
query.add_filter("category", "!=", "work")

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

Não relevante

GQL


SELECT * FROM Task WHERE category != 'work'

Essa consulta retorna todas as entidades Task em que a propriedade category existe e é definida como qualquer valor diferente de Work.

Essa consulta não retorna entidades em que a propriedade category não existe. As consultas "diferente de" (!=) e NOT_IN excluim entidades em que a propriedade especificada não existe ou em que a propriedade está excluída da indexação. Existe uma propriedade quando ela está definida como qualquer valor, incluindo uma string vazia ou null.

Limitações

Observe as seguintes limitações para as consultas !=:

  • Apenas as entidades em que a propriedade especificada existe podem corresponder à consulta.
  • Não é possível combinar NOT_IN e != em uma consulta composta.
  • Em uma consulta composta, os filtros de desigualdade (<, <=, >, >=, !=, NOT_IN) precisam filtrar na mesma propriedade.

IN

Use o operador IN para combinar até 10 cláusulas de igualdade (==) na mesma propriedade usando um OR lógico. Uma consulta IN retorna entidades em que a propriedade especificada corresponde a qualquer um dos valores de comparação.

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Não relevante

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

Não relevante

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.in("tag", ListValue.of("learn", "study")))
        .build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

Não relevante

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

Não relevante

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

query = client.query(kind="Task")
query.add_filter("tag", "IN", ["learn", "study"])

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

Não relevante

GQL


SELECT * FROM Task WHERE tag IN ARRAY('learn', 'study')

Essa consulta retorna todas as entidades Task em que a propriedade tag está definida como learn ou study. Isso inclui entidades Task em que a propriedade tag inclui um desses valores, mas não o outro.

NOT_IN

Use o operador NOT_IN para combinar até 10 cláusulas "diferente de" (!=) na mesma propriedade com um AND lógico. Uma consulta NOT_IN retorna entidades em que a propriedade especificada existe e não corresponde a nenhum dos valores de comparação.

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Não relevante

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

Não relevante

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.not_in("category", ListValue.of("Work", "Chores", "School")))
        .build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

Não relevante

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

Não relevante

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

query = client.query(kind="Task")
query.add_filter("category", "NOT_IN", ["work", "chores", "school"])

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

Não relevante

GQL


SELECT * FROM Task WHERE category NOT IN ARRAY('work', 'chores', 'school')

Essa consulta não retorna entidades em que a entidade category não existe. As consultas "diferente de" (!=) e NOT_IN excluim entidades em que a propriedade especificada não existe. Existe uma propriedade quando ela está definida como qualquer valor, incluindo uma string vazia ou null.

Limitações

Observe as seguintes limitações para as consultas NOT_IN:

  • Apenas as entidades em que a propriedade especificada existe podem corresponder à consulta.
  • Não é possível combinar NOT_IN e != em uma consulta composta.
  • Em uma consulta composta, os filtros de desigualdade (<, <=, >, >=, !=, NOT_IN) precisam filtrar na mesma propriedade.

Consultas de ancestral

Uma consulta de ancestral limita seus resultados à entidade especificada e seus descendentes. O exemplo a seguir retorna todas as entidades Task com a entidade TaskList especificada como um ancestral:

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task")
{
    Filter = Filter.HasAncestor(_db.CreateKeyFactory("TaskList")
        .CreateKey(keyName))
};

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

ancestor := datastore.NameKey("TaskList", "default", nil)
query := datastore.NewQuery("Task").Ancestor(ancestor)

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(
            PropertyFilter.hasAncestor(
                datastore.newKeyFactory().setKind("TaskList").newKey("default")))
        .build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const ancestorKey = datastore.key(['TaskList', 'default']);

const query = datastore.createQuery('Task').hasAncestor(ancestorKey);

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$ancestorKey = $datastore->key('TaskList', 'default');
$query = $datastore->query()
    ->kind('Task')
    ->hasAncestor($ancestorKey);

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

# Query filters are omitted in this example as any ancestor queries with a
# non-key filter require a composite index.
ancestor = client.key("TaskList", "default")
query = client.query(kind="Task", ancestor=ancestor)

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

# task_list_name = "default"
ancestor_key = datastore.key "TaskList", task_list_name

query = datastore.query("Task")
                 .ancestor(ancestor_key)

GQL


SELECT * FROM Task WHERE __key__ HAS ANCESTOR KEY(TaskList, 'default')

Consultas sem tipo

Uma consulta sem tipo e sem ancestral recupera todas as entidades de um aplicativo do modo Datastore. Essas consultas sem tipo não podem incluir filtros ou ordens de classificação para valores de propriedade. No entanto, elas podem filtrar chaves de entidade e usar filtros ancestrais. Os filtros de chave podem ser usados ao especificar __key__ como o nome da propriedade:

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query()
{
    Filter = Filter.GreaterThan("__key__",
        _keyFactory.CreateKey("aTask"))
};

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

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

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<Entity> query =
    Query.newEntityQueryBuilder().setFilter(PropertyFilter.gt("__key__", lastSeenKey)).build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const query = datastore
  .createQuery()
  .filter('__key__', '>', lastSeenKey)
  .limit(1);

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$query = $datastore->query()
    ->filter('__key__', '>', $lastSeenKey);

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

last_seen_key = client.key("Task", "a")
query = client.query()
query.key_filter(last_seen_key, ">")

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

query = Google::Cloud::Datastore::Query.new
query.where "__key__", ">", last_seen_key

GQL


SELECT * WHERE __key__ > KEY(Task, 'someTask')

Consultas de projeção

Na maioria das consultas, entidades inteiras são retornadas como resultados, mas normalmente apenas algumas propriedades da entidade são relevantes para o aplicativo. As consultas de projeção permitem que você consulte apenas as propriedades específicas de uma entidade que você realmente precisa, com latência e custo menores do que recuperar entidades inteiras.

Consultas de projeção exigem que as propriedades especificadas sejam indexadas.

Consultas apenas de chaves

Uma consulta apenas de chaves é um tipo de consulta de projeção e retorna apenas as chaves das entidades resultantes em vez das entidades inteiras, o que resulta em menor latência e custo.

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

Veja como criar uma consulta apenas de chaves:

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task")
{
    Projection = { "__key__" }
};

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

query := datastore.NewQuery("Task").KeysOnly()

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<Key> query = Query.newKeyQueryBuilder().setKind("Task").build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const query = datastore.createQuery().select('__key__').limit(1);

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$query = $datastore->query()
    ->keysOnly();

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query()
query.keys_only()

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

query = datastore.query("Task")
                 .select("__key__")

GQL


SELECT __key__ FROM Task

Uma consulta apenas de chaves é uma operação pequena e conta como uma única leitura de entidade para a consulta.

Projeções

As consultas de projeção são semelhantes às de SQL do formulário:

SELECT priority, percent_complete FROM Task

Use todos os recursos de classificação e filtragem disponíveis para fazer consultas de entidade padrão. No entanto, é importante observar estas limitações.

A consulta SQL de exemplo retorna resultados abreviados apenas com as propriedades especificadas, priority e percent_complete, preenchidas com valores. Todas as outras propriedades não são preenchidas. Veja como colocar isso em prática como uma consulta de projeção:

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task")
{
    Projection = { "priority", "percent_complete" }
};

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

query := datastore.NewQuery("Task").Project("Priority", "PercentComplete")

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<ProjectionEntity> query =
    Query.newProjectionEntityQueryBuilder()
        .setKind("Task")
        .setProjection("priority", "percent_complete")
        .build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const query = datastore
  .createQuery('Task')
  .select(['priority', 'percent_complete']);

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$query = $datastore->query()
    ->kind('Task')
    ->projection(['priority', 'percent_complete']);

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.projection = ["priority", "percent_complete"]

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

query = datastore.query("Task")
                 .select("priority", "percent_complete")

GQL


SELECT priority, percent_complete FROM Task

Para executar a consulta de projeção:

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task")
{
    Projection = { "priority", "percent_complete" }
};
List<long> priorities = new List<long>();
List<double> percentCompletes = new List<double>();
foreach (var entity in _db.RunQuery(query).Entities)
{
    priorities.Add((long)entity["priority"]);
    percentCompletes.Add((double)entity["percent_complete"]);
}

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

var priorities []int
var percents []float64
it := client.Run(ctx, query)
for {
	var task Task
	if _, err := it.Next(&task); err == iterator.Done {
		break
	} else if err != nil {
		log.Fatal(err)
	}
	priorities = append(priorities, task.Priority)
	percents = append(percents, task.PercentComplete)
}

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

List<Long> priorities = new LinkedList<>();
List<Double> percentCompletes = new LinkedList<>();
QueryResults<ProjectionEntity> tasks = datastore.run(query);
while (tasks.hasNext()) {
  ProjectionEntity task = tasks.next();
  priorities.add(task.getLong("priority"));
  percentCompletes.add(task.getDouble("percent_complete"));
}

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

async function runProjectionQuery() {
  const priorities = [];
  const percentCompletes = [];
  const [tasks] = await datastore.runQuery(query);
  tasks.forEach(task => {
    priorities.push(task.priority);
    percentCompletes.push(task.percent_complete);
  });

  return {
    priorities: priorities,
    percentCompletes: percentCompletes,
  };
}

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$priorities = array();
$percentCompletes = array();
$result = $datastore->runQuery($query);
/* @var Entity $task */
foreach ($result as $task) {
    $priorities[] = $task['priority'];
    $percentCompletes[] = $task['percent_complete'];
}

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

priorities = []
percent_completes = []

for task in query.fetch():
    priorities.append(task["priority"])
    percent_completes.append(task["percent_complete"])

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

priorities = []
percent_completes = []
datastore.run(query).each do |task|
  priorities << task["priority"]
  percent_completes << task["percent_complete"]
end

GQL

Não relevante

Uma consulta de projeção que não usa a cláusula distinct on é uma operação pequena e conta como apenas uma única leitura de entidade para a própria consulta.

Agrupamento

As consultas de projeção podem usar a cláusula distinct on para garantir que seja retornado apenas o primeiro resultado de cada combinação distinta de valores das propriedades especificadas. Isso fará com que seja retornado apenas o primeiro resultado de entidades com os mesmos valores das propriedades projetadas.

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task")
{
    Projection = { "category", "priority" },
    DistinctOn = { "category" },
    Order = {
        { "category", PropertyOrder.Types.Direction.Ascending},
        {"priority", PropertyOrder.Types.Direction.Ascending }
    }
};

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

query := datastore.NewQuery("Task").
	Project("Priority", "Category").
	DistinctOn("Category").
	Order("Category").Order("Priority")

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<ProjectionEntity> query =
    Query.newProjectionEntityQueryBuilder()
        .setKind("Task")
        .setProjection("category", "priority")
        .setDistinctOn("category")
        .setOrderBy(OrderBy.asc("category"), OrderBy.asc("priority"))
        .build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const query = datastore
  .createQuery('Task')
  .groupBy('category')
  .order('category')
  .order('priority');

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$query = $datastore->query()
    ->kind('Task')
    ->order('category')
    ->order('priority')
    ->projection(['category', 'priority'])
    ->distinctOn('category');

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.distinct_on = ["category"]
query.order = ["category", "priority"]

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

query = datastore.query("Task")
                 .select("category", "priority")
                 .distinct_on("category")
                 .order("category")
                 .order("priority")

GQL


SELECT DISTINCT ON (category) category, priority FROM Task
ORDER BY category, priority

Valores de matriz

O modo Datastore indexa cada valor de propriedade de matriz única uma vez por índice. Assim, para consultar se uma matriz contém um valor, use um filtro de igualdade.

Ao incluir propriedades com valores de matriz na sua consulta, leve em conta as seguintes questões:

Filtros de desigualdade

Devido à maneira como elas são indexadas, é possível que entidades com vários valores para a mesma propriedade às vezes interajam com filtros de consulta e ordens de classificação de maneiras inesperadas.

Se uma consulta tiver vários filtros de desigualdade para determinada propriedade, uma entidade só corresponderá à consulta se pelo menos um dos valores individuais dela satisfizer a todos os filtros. Por exemplo, se uma entidade do tipo Task tiver os valores fun e programming para a propriedade tag, ela não corresponderá à consulta:

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.GreaterThan("tag", "learn"),
        Filter.LessThan("tag", "math"))
};

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

query := datastore.NewQuery("Task").
	Filter("Tag >", "learn").
	Filter("Tag <", "math")

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(
            CompositeFilter.and(
                PropertyFilter.gt("tag", "learn"), PropertyFilter.lt("tag", "math")))
        .build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const query = datastore
  .createQuery('Task')
  .filter('tag', '>', 'learn')
  .filter('tag', '<', 'math');

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$query = $datastore->query()
    ->kind('Task')
    ->filter('tag', '>', 'learn')
    ->filter('tag', '<', 'math');

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.add_filter("tag", ">", "learn")
query.add_filter("tag", "<", "math")

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

query = datastore.query("Task")
                 .where("tag", ">", "learn")
                 .where("tag", "<", "math")

GQL


SELECT * FROM Task WHERE tag > 'learn' AND tag < 'math'

Cada um dos valores de tag da entidade satisfaz a um dos filtros, mas nenhum dos dois valores satisfaz aos dois.

Vários filtros de igualdade

Ao contrário dos filtros de desigualdade, é possível que vários filtros de igualdade sejam usados para consultar entidades que contenham um conjunto de valores. Por exemplo, uma entidade do tipo Task com os valores fun e programming para a propriedade tag satisfará a consulta

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.Equal("tag", "fun"),
        Filter.Equal("tag", "programming"))
};

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

query := datastore.NewQuery("Task").
	Filter("Tag =", "fun").
	Filter("Tag =", "programming")

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(
            CompositeFilter.and(
                PropertyFilter.eq("tag", "fun"), PropertyFilter.eq("tag", "programming")))
        .build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const query = datastore
  .createQuery('Task')
  .filter('tag', '=', 'fun')
  .filter('tag', '=', 'programming');

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$query = $datastore->query()
    ->kind('Task')
    ->filter('tag', '=', 'fun')
    ->filter('tag', '=', 'programming');

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.add_filter("tag", "=", "fun")
query.add_filter("tag", "=", "programming")

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

query = datastore.query("Task")
                 .where("tag", "=", "fun")
                 .where("tag", "=", "programming")

GQL


SELECT * FROM Task WHERE tag = 'fun' AND tag = 'programming'

Mesmo que nenhum dos valores de tag individuais da entidade satisfaça às duas condições de filtro.

Ordem de classificação

Da mesma forma, a ordem de classificação para propriedades de múltiplos valores é incomum. Como essas propriedades aparecem uma vez no índice para cada valor exclusivo, o primeiro valor exibido no índice determina a ordem de classificação de uma entidade.

Se uma propriedade de vários valores não for usada em qualquer filtro:

  • e os resultados da consulta forem classificados em ordem crescente pela propriedade, o menor valor da propriedade será usado para ordenação;
  • e os resultados da consulta forem classificados em ordem decrescente pela propriedade, o maior valor será usado para ordenação.
  • outros valores não afetam a ordem de classificação, nem o número de valores.

A consequência incomum disso é que uma entidade com valores de propriedade 1 e 9 precede outra entidade com valores 4, 5, 6 e 7 na ordem crescente e decrescente.

Se uma propriedade com vários valores for usada em um filtro de igualdade, qualquer ordem de classificação dessa propriedade será ignorada.

Se uma propriedade de vários valores for usada em um filtro de desigualdade ou NOT_IN:

  • e os resultados da consulta forem classificados em ordem crescente pela propriedade, o menor valor que satisfizer a todos os filtros de desigualdade da consulta será usado para ordenação;
  • e os resultados da consulta forem classificados em ordem decrescente pela propriedade, o maior valor que satisfizer a todos os filtros de desigualdade da consulta será usado para ordenação.

Note que se um conjunto de filtros de desigualdade em uma propriedade se traduzir em um filtro de igualdade, como em

WHERE tag >= 'math' AND tag <= 'math'

qualquer ordem de classificação nessa propriedade será ignorada, já que os filtros avaliam o mesmo que o filtro de igualdade

WHERE tag = 'math'

Projeções e propriedades com valores de matriz

A projeção de uma propriedade com valores de matriz não preencherá todos os valores dessa propriedade. Em vez disso, uma entidade separada será retornada para cada combinação exclusiva de valores projetados correspondentes à consulta. Por exemplo, suponha que você tenha uma entidade do tipo Task com duas propriedades de múltiplos valores, tag e collaborators:

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["collaborators"] = new ArrayValue() { Values = { "alice", "bob" } },
    ["tags"] = new ArrayValue() { Values = { "fun", "programming" } }
};

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

type Task struct {
	Tags          []string
	Collaborators []string
}
task := &Task{
	Tags:          []string{"fun", "programming"},
	Collaborators: []string{"alice", "bob"},
}

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Entity task =
    Entity.newBuilder(taskKey)
        .set("tags", "fun", "programming")
        .set("collaborators", ListValue.of("alice", "bob"))
        .build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const task = {
  tags: ['fun', 'programming'],
  collaborators: ['alice', 'bob'],
};

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$task = $datastore->entity(
    $key,
    [
        'tags' => ['fun', 'programming'],
        'collaborators' => ['alice', 'bob']
    ]
);

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

key = client.key("Task")
task = datastore.Entity(key)
task.update({"tags": ["fun", "programming"], "collaborators": ["alice", "bob"]})

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

# task_name = "sampleTask"
task = datastore.entity "Task", task_name do |t|
  t["tags"] = ["fun", "programming"]
  t["collaborators"] = ["alice", "bob"]
end

GQL

Não relevante

Neste caso, a consulta de projeção

SELECT tag, collaborators FROM Task WHERE collaborators < 'charlie'

retornará quatro entidades com as seguintes combinações de valores:

tag = 'fun', collaborators = 'alice'
tag = 'fun', collaborators = 'bob'
tag = 'programming', collaborators = 'alice'
tag = 'programming', collaborators = 'bob'

Cursores, limites e deslocamentos

Você pode especificar um limite para sua consulta para controlar o número máximo de resultados retornados em um lote. O exemplo a seguir recupera no máximo cinco entidades Task:

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task")
{
    Limit = 5,
};

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

query := datastore.NewQuery("Task").Limit(5)

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

Query<Entity> query = Query.newEntityQueryBuilder().setKind("Task").setLimit(5).build();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.

const query = datastore.createQuery('Task').limit(5);

PHP

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API PHP do Cloud Datastore.

$query = $datastore->query()
    ->kind('Task')
    ->limit(5);

Python

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Python do Cloud Datastore.

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query()
tasks = list(query.fetch(limit=5))

Ruby

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Ruby do Cloud Datastore.

query = datastore.query("Task")
                 .limit(5)

GQL


SELECT * FROM Task LIMIT 5

Os cursores de consulta permitem que um aplicativo receba os resultados de uma consulta em lotes convenientes sem a sobrecarga de um deslocamento de consulta. Depois de executar uma operação de recuperação, é possível que o aplicativo receba um cursor, que é uma sequência de bytes opaca marcando a posição de índice do último resultado recuperado. Por exemplo, o aplicativo salva essa string no banco de dados do modo Datastore, em um cache ou a incorpora em uma página da Web como parâmetro HTTP GET ou POST codificado em base-64 e depois usa o cursor como ponto de partida para uma operação de recuperação subsequente. Nesse caso, o próximo lote de resultados será obtido a partir do ponto em que a recuperação anterior terminou. É possível que uma recuperação especifique também um cursor de término para limitar a extensão do conjunto de resultados retornado.

O exemplo a seguir demonstra o uso de cursores para paginação:

C#

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API C# do Cloud Datastore.

Query query = new Query("Task")
{
    Limit = pageSize,
};
if (!string.IsNullOrEmpty(pageCursor))
    query.StartCursor = ByteString.FromBase64(pageCursor);

return _db.RunQuery(query).EndCursor?.ToBase64();

Go

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Go do Cloud Datastore.

// cursorStr is a cursor to start querying at.
cursorStr := ""

const pageSize = 5
query := datastore.NewQuery("Tasks").Limit(pageSize)
if cursorStr != "" {
	cursor, err := datastore.DecodeCursor(cursorStr)
	if err != nil {
		log.Fatalf("Bad cursor %q: %v", cursorStr, err)
	}
	query = query.Start(cursor)
}

// Read the tasks.
var tasks []Task
var task Task
it := client.Run(ctx, query)
_, err := it.Next(&task)
for err == nil {
	tasks = append(tasks, task)
	_, err = it.Next(&task)
}
if err != iterator.Done {
	log.Fatalf("Failed fetching results: %v", err)
}

// Get the cursor for the next page of results.
// nextCursor.String can be used as the next page's token.
nextCursor, err := it.Cursor()

Java

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Java do Cloud Datastore.

EntityQuery.Builder queryBuilder =
    Query.newEntityQueryBuilder().setKind("Task").setLimit(pageSize);
if (pageCursor != null) {
  queryBuilder.setStartCursor(pageCursor);
}
QueryResults<Entity> tasks = datastore.run(queryBuilder.build());
while (tasks.hasNext()) {
  Entity task = tasks.next();
  // do something with the task
}
Cursor nextPageCursor = tasks.getCursorAfter();

Node.js

Para saber como instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte Bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API Node.js do Cloud Datastore.