Consultas do Datastore

Uma consulta recupera entidades do Cloud 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 em valores de propriedade, chaves e ancestrais das entidades e retorna zero ou mais entidades como resultados. Também especifica 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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para C#.

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

Go

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

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

Java

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

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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Storage para Node.js.

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

PHP

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

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

Python

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

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

Ruby

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

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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para C#.

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

Go

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

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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para Java.

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

Node.js

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

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

PHP

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

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

Python

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

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

Ruby

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

tasks = datastore.run query

GQL

Não aplicável

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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para C#.

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

Go

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

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

Java

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

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

Node.js

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

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

PHP

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

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

Python

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

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

Ruby

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

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 fazer referência 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

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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para C#.

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

Go

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

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

Java

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

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

Node.js

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

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

PHP

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

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

Python

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

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

Ruby

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

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

GQL


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

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

Filtros de chaves

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

C#

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

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

Go

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

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

Java

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

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

Node.js

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

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

PHP

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

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

Python

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

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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para Ruby.

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

GQL


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

Ao comparar quanto à desigualdade, as chaves são ordenadas pelos seguintes critérios, por ordem:

  1. caminho ancestral
  2. tipo de entidade
  3. identificador (nome da chave ou código numérico)

Os elementos do caminho ancestral são comparados de forma similar: por tipo (string) e depois pelo nome da chave ou código numérico. Tipos e nomes de chaves são strings e são ordenados por valor de byte. Já os códigos numéricos são números inteiros e são ordenados numericamente. Se as entidades com a mesma mãe e o mesmo tipo usarem uma combinação de strings de nomes de chave e códigos numéricos, aquelas com códigos numéricos precedem as 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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para C#.

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

Go

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

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

Java

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

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

Node.js

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

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

PHP

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

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

Python

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

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

Ruby

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

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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para C#.

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

Go

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

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

Java

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

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

Node.js

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

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

PHP

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

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

Python

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

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

Ruby

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

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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para C#.

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

Go

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

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

Java

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

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

Node.js

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

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

PHP

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

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

Python

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

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

Ruby

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

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:

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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para C#.

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

Go

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

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

Java

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

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

Node.js

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

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

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

PHP

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

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

Python

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

# 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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para Ruby.

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

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. Para usar filtros de chave, basta especificar __key__ como o nome da propriedade:

C#

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

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

Go

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

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

Java

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

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

Node.js

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

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

PHP

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

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

Python

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

query = client.query()
query.key_filter(last_seen_key, '>')

Ruby

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

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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para C#.

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

Go

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

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

Java

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

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

Node.js

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

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

PHP

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

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

Python

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

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

Ruby

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

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 padrão retorna resultados abreviados, e apenas as propriedades especificadas (no exemplo, priority e percent_complete) são preenchidas com valores. Nenhuma das outras propriedades é preenchida. Veja como colocar isso em prática como uma consulta de projeção:

C#

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

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

Go

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

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

Java

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

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

Node.js

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

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

PHP

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

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

Python

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

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

Ruby

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

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

GQL


SELECT priority, percent_complete FROM Task

Para executar a consulta de projeção:

C#

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

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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para Go.

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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para Java.

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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Storage para Node.js.

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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para PHP.

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

Python

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

priorities = []
percent_completes = []

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

Ruby

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

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

GQL

Não aplicável

Uma consulta de projeção que não usa a cláusula distinct on é uma operação pequena, contabilizada como 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 somente o retorno do primeiro resultado de cada combinação distinta de valores para as propriedades especificadas. Isso fará com que seja retornado apenas o primeiro resultado de entidades com os mesmos valores das propriedades projetadas.

C#

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

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

Go

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

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

Java

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

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

Node.js

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

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

PHP

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

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

Python

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

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

Ruby

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

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

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

Propriedades com valores de matriz podem se comportar de maneiras inesperadas

Devido à maneira como elas são indexadas, entidades com vários valores para a mesma propriedade às vezes podem interagir 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 na propriedade tag, ela não corresponderá à consulta:

C#

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

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

Go

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

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

Java

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

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

Node.js

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

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

PHP

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

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

Python

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

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

Ruby

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

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 a ambos. Note que isso não se aplica a filtros de igualdade. Por exemplo, a mesma entidade satisfará à consulta.

C#

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

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

Go

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

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

Java

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

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

Node.js

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

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

PHP

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

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

Python

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

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

Ruby

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

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.

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 com vários valores for usada em um filtro de desigualdade:

  • 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 tags >= 'math' AND tags <= 'math'

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

WHERE tags = '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ê tem uma entidade do tipo Task com duas propriedades de múltiplos valores, tags e collaborators:

C#

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

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

Go

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

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

Java

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

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

Node.js

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

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

PHP

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

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

Python

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

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

Ruby

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

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

GQL

Não aplicável

Neste caso, a consulta de projeção

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

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

tags = 'fun', collaborators = 'alice'
tags = 'fun', collaborators = 'bob'
tags = 'programming', collaborators = 'alice'
tags = '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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para C#.

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

Go

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

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

Java

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

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

Node.js

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

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

PHP

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

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

Python

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

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

Ruby

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

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, o aplicativo pode receber 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. Uma recuperação também pode especificar 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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Datastore para C#.

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

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

Go

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

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, err := it.Cursor()

Java

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

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 aprender a instalar e usar a biblioteca de cliente para o Cloud Datastore, consulte as bibliotecas de cliente do Cloud Datastore. Para mais informações, consulte a documentação de referência da API do Cloud Storage para Node.js.

// By default, google-cloud-node will automatically paginate through all of
// the results that match a query. However, this sample implements manual
// pagination using limits and cursor tokens.
async function runPageQuery(pageCursor) {
  let query = datastore.createQuery('Task').limit(pageSize);

  if (pageCursor) {
    query = query.start(pageCursor);
  }
  const results = await datastore.runQuery(query);
  const entities = results[0];
  const info = results[1];

  if (info.moreResults !== Datastore.NO_MORE_RESULTS) {
    // If there are more results to retrieve, the end cursor is
    // automatically set on `info`. To get this value directly, access
    // the `endCursor` property.
    const results = await runPageQuery(info.endCursor);

    // Concatenate entities
    results[0] = entities.concat(results[0]);
    return results;
  }

  return [entities, info];
}

PHP

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

/**
 * Fetch a query cursor.
 *
 * @param DatastoreClient $datastore
 * @param string $pageSize
 * @param string $pageCursor
 * @return array
 */
function cursor_paging(DatastoreClient $datastore, $pageSize, $pageCursor = '')
{
    $query = $datastore->query()
        ->kind('Task')
        ->limit($pageSize)
        ->start($pageCursor);
    $result = $datastore->runQuery($query);
    $nextPageCursor = '';
    $entities = [];
    /* @var Entity $entity */
    foreach ($result as $entity) {
        $nextPageCursor = $entity->cursor();
        $entities[] = $entity;
    }
    return array(
        'nextPageCursor' => $nextPageCursor,
        'entities' => $entities
    );
}

Python

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

def get_one_page_of_tasks(cursor=None):
    query = client.query(kind='Task')
    query_iter = query.fetch(start_cursor=cursor, limit=5)
    page = next(query_iter.pages)

    tasks = list(page)
    next_cursor = query_iter.next_page_token

    return tasks, next_cursor

Ruby

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

page_size = 2
query = datastore.query("Task")
                 .limit(page_size)
tasks = datastore.run query

page_cursor = tasks.cursor

query = datastore.query("Task")
                 .limit(page_size)
                 .start(page_cursor)

GQL

Não aplicável

Os bancos de dados do modo Datastore aceitam deslocamentos de números inteiros, mas convém evitá-los. Em vez disso, use cursores. O uso de deslocamentos apenas evita o retorno das entidades ignoradas para o aplicativo. No entanto, essas entidades ainda são recuperadas internamente. As entidades ignoradas afetam a latência da consulta. Além disso, as operações de leitura necessárias para recuperar essas entidades serão cobradas do seu aplicativo. Use cursores em vez de deslocamentos para evitar todos esses custos.

Limitações dos cursores

Os cursores estão sujeitos às seguintes limitações:

  • Um cursor somente pode ser usado pelo mesmo projeto que executou a consulta original e apenas para continuar a mesma consulta. Não é possível recuperar resultados usando um cursor sem configurar a mesma consulta da qual ele foi originalmente gerado.
  • Se qualquer um dos itens a seguir for alterado, um cursor ainda poderá ser usado para recuperações subsequentes.
    • cursor de início
    • cursor de término
    • deslocamentos
    • limite
  • Se qualquer um dos itens a seguir for alterado, não será possível usar um cursor para recuperações subsequentes.
    • projeção
    • tipo
    • ancestral
    • filtro
    • distinct on
    • ordem de classificação

      A exceção é se a ordem de classificação final da consulta original estava em __key__. Nesse caso, você pode usar o cursor em uma consulta reversa, que é a consulta original com cada ordem de classificação invertida. A consulta reversa pode modificar o cursor de início, o cursor de término, o deslocamento e o limite.

  • Cursores nem sempre funcionam como esperado em uma consulta que usa um filtro de desigualdade ou uma ordem de classificação em uma propriedade com valores múltiplos. A lógica de desduplicação para essas propriedades não persiste entre recuperações, o que pode fazer com que o mesmo resultado seja retornado mais de uma vez.
  • Novas versões do modo Datastore podem alterar detalhes de implementação internos, invalidando cursores que dependem deles. Quando um aplicativo tenta usar um cursor que não é mais válido, o Cloud Firestore no modo Datastore gera uma exceção.

Cursores e atualizações de dados

O cursor representa o local na lista de resultados após o último resultado retornado. Um cursor não é uma posição relativa na lista (ou seja, não é um deslocamento). Ele é um marcador capaz de receber um banco de dados do modo Datastore quando uma verificação de resultados de índice é iniciada. Se os resultados de uma consulta mudarem entre as utilizações de um cursor, a consulta perceberá apenas as alterações que ocorrem nos resultados após o cursor. Se um novo resultado aparecer antes da posição do cursor na consulta, ele não será retornado quando os resultados após o cursor forem recuperados. Da mesma forma, se uma entidade não for mais um resultado de uma consulta, mas tiver aparecido antes do cursor, os resultados que aparecerem após o cursor não mudarão. Se o último resultado retornado for removido do conjunto de resultados, o cursor ainda saberá como localizar o próximo resultado.

Ao recuperar os resultados da consulta, use um cursor inicial e um cursor final para retornar um grupo contínuo de resultados. Ao usar um cursor de início e de término para recuperar os resultados, não há garantia de que o tamanho dos resultados será o mesmo de quando você gerou os cursores. As entidades podem ser adicionadas ou excluídas do banco de dados entre o momento em que os cursores são gerados e o momento em que eles são usados em uma consulta.

Restrições em consultas

A natureza do mecanismo de consulta de índice impõe certas restrições sobre o que uma consulta pode fazer. As consultas do modo Datastore não são compatíveis com correspondências de substring, correspondências sem distinção entre maiúsculas e minúsculas ou a chamada pesquisa de texto completo. Os operadores NOT, OR e != não são nativamente compatíveis, mas é possível usar algumas bibliotecas de cliente para adicionar compatibilidade ao modo Datastore. Além disso:

Entidades que não possuem uma propriedade nomeada na consulta são ignoradas

Entidades do mesmo tipo não precisam ter as mesmas propriedades. Para ser elegível como resultado de consulta, uma entidade deve ter um valor (que pode ser nulo) para cada propriedade nomeada nos filtros da consulta e ordens de classificação. Caso contrário, ela é omitida dos índices usados para executar a consulta e, consequentemente, não será incluída nos resultados.

Filtragens de propriedades não indexadas não retornam resultados

Uma consulta não pode localizar valores de propriedade que não estão indexados e nem classificar essas propriedades. Consulte a seção Propriedades não indexadas para ver uma discussão detalhada sobre propriedades não indexadas.

Os filtros de desigualdade são limitados a no máximo uma propriedade

Para evitar que o mecanismo de consulta verifique todo o índice, é necessário que os possíveis resultados de uma consulta estejam adjacentes um ao outro no índice. Para satisfazer a essa restrição, uma única consulta não pode usar comparações de desigualdade (LESS_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL) ou mais de uma propriedade em todos os seus filtros. Por exemplo, a consulta a seguir é válida porque ambos os filtros de desigualdade se aplicam à mesma propriedade:

C#

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

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.GreaterThan("created", _startDate),
        Filter.LessThan("created", _endDate))
};

Go

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

query := datastore.NewQuery("Task").
	Filter("Created >", time.Date(1990, 1, 1, 0, 0, 0, 0, time.UTC)).
	Filter("Created <", time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC))

Java

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

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(CompositeFilter.and(
        PropertyFilter.gt("created", startDate), PropertyFilter.lt("created", endDate)))
    .build();

Node.js

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

const query = datastore
  .createQuery('Task')
  .filter('created', '>', new Date('1990-01-01T00:00:00z'))
  .filter('created', '<', new Date('2000-12-31T23:59:59z'));

PHP

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

$query = $datastore->query()
    ->kind('Task')
    ->filter('created', '>', new DateTime('1990-01-01T00:00:00z'))
    ->filter('created', '<', new DateTime('2000-12-31T23:59:59z'));

Python

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

start_date = datetime.datetime(1990, 1, 1)
end_date = datetime.datetime(2000, 1, 1)
query = client.query(kind='Task')
query.add_filter(
    'created', '>', start_date)
query.add_filter(
    'created', '<', end_date)

Ruby

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

query = datastore.query("Task")
                 .where("created", ">=", Time.utc(1990, 1, 1))
                 .where("created", "<", Time.utc(2000, 1, 1))

GQL


SELECT * FROM Task
WHERE created > DATETIME('1990-01-01T00:00:00z')
  AND created < DATETIME('2000-12-31T23:59:59z')

No entanto, a consulta a seguir não é válida, porque usa filtros de desigualdade em duas propriedades diferentes:

C#

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

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.GreaterThan("created", _startDate),
        Filter.GreaterThan("priority", 3))
};

Go

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

query := datastore.NewQuery("Task").
	Filter("Created >", time.Date(1990, 1, 1, 0, 0, 0, 0, time.UTC)).
	Filter("Priority >", 3)

Java

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

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(CompositeFilter.and(
        PropertyFilter.gt("created", startDate), PropertyFilter.gt("priority", 3)))
    .build();

Node.js

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

const query = datastore
  .createQuery('Task')
  .filter('priority', '>', 3)
  .filter('created', '>', new Date('1990-01-01T00:00:00z'));

PHP

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

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '>', 3)
    ->filter('created', '>', new DateTime('1990-01-01T00:00:00z'));

Python

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

start_date = datetime.datetime(1990, 1, 1)
query = client.query(kind='Task')
query.add_filter(
    'created', '>', start_date)
query.add_filter(
    'priority', '>', 3)

Ruby

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

query = datastore.query("Task")
                 .where("created", ">=", Time.utc(1990, 1, 1))
                 .where("priority", ">", 3)

GQL


# Invalid query!
SELECT * FROM Task
WHERE created > DATETIME('1990-01-01T00:00:00z')
AND priority > 3

Uma consulta pode combinar filtros de igualdade (EQUAL) em propriedades diferentes com um ou mais filtros de desigualdade em uma única propriedade. Portanto, a consulta a seguir é válida:

C#

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

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.Equal("priority", 4),
        Filter.GreaterThan("created", _startDate),
        Filter.LessThan("created", _endDate))
};

Go

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

query := datastore.NewQuery("Task").
	Filter("Priority =", 4).
	Filter("Done =", false).
	Filter("Created >", time.Date(1990, 1, 1, 0, 0, 0, 0, time.UTC)).
	Filter("Created <", time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC))

Java

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

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(CompositeFilter.and(PropertyFilter.eq("priority", 4),
        PropertyFilter.gt("created", startDate), PropertyFilter.lt("created", endDate)))
    .build();

Node.js

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

const query = datastore
  .createQuery('Task')
  .filter('priority', '=', 4)
  .filter('done', '=', false)
  .filter('created', '>', new Date('1990-01-01T00:00:00z'))
  .filter('created', '<', new Date('2000-12-31T23:59:59z'));

PHP

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

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '=', 4)
    ->filter('done', '=', false)
    ->filter('created', '>', new DateTime('1990-01-01T00:00:00z'))
    ->filter('created', '<', new DateTime('2000-12-31T23:59:59z'));

Python

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

start_date = datetime.datetime(1990, 1, 1)
end_date = datetime.datetime(2000, 12, 31, 23, 59, 59)
query = client.query(kind='Task')
query.add_filter('priority', '=', 4)
query.add_filter('done', '=', False)
query.add_filter(
    'created', '>', start_date)
query.add_filter(
    'created', '<', end_date)

Ruby

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

query = datastore.query("Task")
                 .where("done", "=", false)
                 .where("priority", "=", 4)
                 .where("created", ">=", Time.utc(1990, 1, 1))
                 .where("created", "<", Time.utc(2000, 1, 1))

GQL


SELECT * FROM Task
WHERE priority = 4
  AND done = FALSE
  AND created > DATETIME('1990-01-01T00:00:00z')
  AND created < DATETIME('2000-12-31T23:59:59z')

A ordenação dos resultados da consulta é indefinida quando nenhuma ordem de classificação é especificada

Quando uma consulta não especifica uma ordem de classificação, os resultados são retornados na ordem em que são recuperados. À medida que a implementação do modo Datastore evolui (ou os índices de um projeto sofrem alterações), essa ordem pode mudar. Portanto, se o aplicativo exigir que os resultados de consulta estejam em uma determinada ordem, certifique-se de especificar explicitamente essa ordem de classificação na consulta.

Pedidos de classificação são ignorados em propriedades com filtros de igualdade

As consultas que incluem um filtro de igualdade para uma determinada propriedade ignoram qualquer ordem de classificação especificada para essa propriedade. Essa é uma otimização simples para evitar o processamento desnecessário de propriedades de valor único, já que todos os resultados têm o mesmo valor para a propriedade e, portanto, nenhuma classificação adicional é necessária. As propriedades de valores múltiplos, no entanto, podem ter valores complementares além do correspondente ao filtro de igualdade. Como esse caso de uso é raro, e aplicar a ordem de classificação sai caro e exige índices adicionais, o planejador de consultas do modo Datastore simplesmente ignora a ordem de classificação mesmo no caso de valores múltiplos. Dessa forma, os resultados da consulta podem ser retornados em uma ordem diferente daquela que a ordem de classificação parece indicar.

Propriedades utilizadas em filtros de desigualdade devem ser classificadas primeiro

Para recuperar todos os resultados que correspondem a um filtro de desigualdade, uma consulta verifica o índice da primeira linha correspondente ao filtro e, em seguida, segue verificando até encontrar uma linha não correspondente. Para que as linhas consecutivas incluam todo o conjunto de resultados, elas devem ser ordenadas pela propriedade usada no filtro de desigualdade antes de qualquer outra propriedade. Assim, se uma consulta especifica um ou mais filtros de desigualdade juntamente com uma ou mais ordens de classificação, a primeira ordem de classificação deve se referir à mesma propriedade nomeada nos filtros de desigualdade. Veja a seguir uma consulta válida:

C#

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

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

Go

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

query := datastore.NewQuery("Task").
	Filter("Priority >", 3).
	Order("Priority").
	Order("Created")

Java

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

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

Node.js

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

const query = datastore
  .createQuery('Task')
  .filter('priority', '>', 3)
  .order('priority')
  .order('created');

PHP

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

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '>', 3)
    ->order('priority')
    ->order('created');

Python

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

query = client.query(kind='Task')
query.add_filter('priority', '>', 3)
query.order = ['priority', 'created']

Ruby

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

query = datastore.query("Task")
                 .where("priority", ">", 3)
                 .order("priority")
                 .order("created")

GQL


SELECT * FROM Task WHERE priority > 3 ORDER BY priority, created

A consulta a seguir não é válida, porque não classifica a propriedade usada no filtro de desigualdade:

C#

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

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

Go

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

query := datastore.NewQuery("Task").
	Filter("Priority >", 3).
	Order("Created")

Java

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

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

Node.js

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

const query = datastore
  .createQuery('Task')
  .filter('priority', '>', 3)
  .order('created');

PHP

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

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '>', 3)
    ->order('created');

Python

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

query = client.query(kind='Task')
query.add_filter('priority', '>', 3)
query.order = ['created']

Ruby

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

query = datastore.query("Task")
                 .where("priority", ">", 3)
                 .order("created")

GQL


# Invalid query!
SELECT * FROM Task WHERE priority > 3 ORDER BY created

Da mesma forma, a consulta a seguir não é válida porque a propriedade usada no filtro de desigualdade não é a primeira classificada:

C#

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

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

Go

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

query := datastore.NewQuery("Task").
	Filter("Priority >", 3).
	Order("Created").
	Order("Priority")

Java

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

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

Node.js

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

const query = datastore
  .createQuery('Task')
  .filter('priority', '>', 3)
  .order('created')
  .order('priority');

PHP

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

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '>', 3)
    ->order('created')
    ->order('priority');

Python

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

query = client.query(kind='Task')
query.add_filter('priority', '>', 3)
query.order = ['created', 'priority']

Ruby

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

query = datastore.query("Task")
                 .where("priority", ">", 3)
                 .order("created")
                 .order("priority")

GQL


# Invalid query!
SELECT * FROM Task WHERE priority > 3 ORDER BY created, priority

Consultas dentro de transações precisam ser consultas de ancestral

As transações do modo Datastore operam em entidades de até 25 grupos de entidades. No entanto, as consultas nas transações precisam ser de ancestrais. Todas as consultas realizadas dentro de uma transação precisam especificar um ancestral. Para mais informações, consulte Transações.

Limitações nas projeções

As consultas de projeção estão sujeitas às seguintes limitações:

  • Somente propriedades indexadas podem ser projetadas.

    A projeção não é compatível com strings com mais de 1.500 bytes, matrizes de bytes com mais de 1.500 elementos e outras propriedades explicitamente marcadas como não indexadas.

  • A mesma propriedade não pode ser projetada mais de uma vez.

  • Propriedades referenciadas em um filtro de igualdade não podem ser projetadas.

    Por exemplo,

    SELECT tag FROM Task WHERE priority = 1
    

    é uma consulta válida (a propriedade projetada não é usada no filtro de igualdade), assim como a consulta

    SELECT tag FROM Task WHERE tag > 'fun`
    

    (não é um filtro de igualdade), mas

    SELECT tag FROM Task WHERE tag = 'fun`
    

    (propriedade projetada usada no filtro de igualdade) não é.

  • Os resultados retornados por uma consulta de projeção não devem ser salvos no banco de dados do modo Datastore.

    Como a consulta retorna resultados apenas parcialmente preenchidos, não é preciso gravá-los novamente no banco de dados do modo Datastore.

    • Consultas de projeção convertem carimbos de data e hora em números inteiros.

    Nos resultados de uma consulta de projeção, o modo Datastore converte valores de carimbos de data/hora em microssegundos com números inteiros.

A seguir

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Documentação do Cloud Datastore