Esta página foi traduzida pela API Cloud Translation.

Consultas do armazenamento de dados

Uma consulta obtém entidades do Firestore no modo Datastore que cumprem um conjunto especificado de condições.

A consulta opera em entidades de um determinado tipo; pode especificar filtros nos valores das propriedades, nas chaves e nos ancestrais das entidades, e pode devolver zero ou mais entidades como resultados. Uma consulta também pode especificar ordens de ordenação para sequenciar os resultados pelos respetivos valores das propriedades. Os resultados incluem todas as entidades que têm, pelo menos, um valor para cada propriedade com nome nos filtros e nas ordens de ordenação, e cujos valores das propriedades cumprem todos os critérios de filtro especificados. A consulta pode devolver entidades completas, entidades projetadas ou apenas chaves de entidades.

Uma consulta típica inclui o seguinte:

Um tipo de entidade ao qual a consulta se aplica
Zero ou mais filtros com base nos valores das propriedades das entidades, chaves e antecessores
Zero ou mais ordens de ordenação para sequenciar os resultados

Quando executada, a consulta obtém todas as entidades do tipo indicado que satisfazem todos os filtros indicados, ordenados pela ordem especificada. As consultas são executadas como só de leitura.

Nota: para conservar a memória e melhorar o desempenho, uma consulta deve, sempre que possível, especificar um limite para o número de resultados devolvidos.

Cada consulta calcula os respetivos resultados através de um ou mais índices>, que contêm chaves de entidades numa sequência especificada pelas propriedades do índice e, opcionalmente, os antecessores da entidade. Os índices são atualizados de forma incremental para refletir quaisquer alterações que a aplicação faça às respetivas entidades, de modo que os resultados corretos de todas as consultas estejam disponíveis sem necessidade de mais cálculos.

O mecanismo de consulta baseado em índice suporta uma vasta gama de consultas e é adequado para a maioria das aplicações, exceto para consultas não escaláveis, como consultas de junção. Para mais informações sobre as limitações das consultas do modo Datastore, consulte o artigo Restrições nas consultas.

Interface de consulta

Pode emitir uma consulta numa base de dados do modo Datastore. O exemplo seguinte mostra como obter todas as tarefas que ainda não foram concluídas com prioridades superiores ou iguais a 4, ordenadas por ordem descendente de prioridade:

C#

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

Para se autenticar no Cloud Datastore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

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

Go

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

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

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

PHP

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

Python

from google.cloud import datastore

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

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

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

O exemplo seguinte mostra como executar uma consulta:

C#

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

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

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

tasks = datastore.run query

GQL

Não aplicável

Estrutura da consulta

Uma consulta pode especificar um tipo de entidade, zero ou mais filtros e zero ou mais ordens de ordenação.

Filtros

Os filtros de uma consulta definem restrições nas propriedades, nas chaves e nos antecessores das entidades a serem obtidas.

Filtros de propriedades

Um filtro de propriedade especifica o seguinte:

Um nome da propriedade
Um operador de comparação
Um valor da propriedade

O exemplo seguinte devolve entidades de tarefas marcadas como não concluídas:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

GQL

SELECT * FROM Task WHERE done = FALSE

O valor da propriedade tem de ser fornecido pela aplicação. Não pode referir-se nem ser calculado em função de outras propriedades. Uma entidade satisfaz o filtro se tiver uma propriedade do nome indicado cujo valor seja comparado com o valor especificado no filtro da forma descrita pelo operador de comparação. Se a propriedade do nome indicado tiver um valor de matriz, a entidade satisfaz o filtro se algum dos valores for comparado com o valor especificado no filtro da forma descrita pelo operador de comparação.

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

Operador	Significado
`EQUAL`	Igual a
`LESS_THAN`	Inferior a
`LESS_THAN_OR_EQUAL`	Inferior ou igual a
`GREATER_THAN`	Superior a
`GREATER_THAN_OR_EQUAL`	Superior ou igual a
`NOT_EQUAL`	Diferente de
`IN`	Membro da lista especificada. Igual a qualquer um dos valores numa lista especificada.
`NOT_IN`	Não é membro da lista especificada. Não é igual a nenhum dos valores numa lista especificada.

Filtros compostos

Um filtro composto consiste em mais do que um filtro de propriedade. Pode combinar filtros com AND e OR. O exemplo seguinte devolve Task entidades marcadas como não concluídas e com uma prioridade de 4:

C#

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

Go

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

Java

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

Node.js

const query = datastore
  .createQuery('Task')
  .filter(
    and([
      new PropertyFilter('done', '=', false),
      new PropertyFilter('priority', '=', 4),
    ]),
  );

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

GQL

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

O exemplo seguinte combina filtros com um OR lógico:

C#

Fragmento não disponível.

Ir

Fragmento não disponível.

Java

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

Para autenticar no modo Datastore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

import com.google.cloud.datastore.Datastore;
import com.google.cloud.datastore.DatastoreOptions;
import com.google.cloud.datastore.Entity;
import com.google.cloud.datastore.Query;
import com.google.cloud.datastore.QueryResults;
import com.google.cloud.datastore.StructuredQuery.CompositeFilter;
import com.google.cloud.datastore.StructuredQuery.Filter;
import com.google.cloud.datastore.StructuredQuery.PropertyFilter;

public class OrFilterQuery {
  public static void invoke() throws Exception {

    // Instantiates a client
    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
    String propertyName = "description";

    // Create the two filters
    Filter orFilter =
        CompositeFilter.or(
            PropertyFilter.eq(propertyName, "Feed cats"),
            PropertyFilter.eq(propertyName, "Buy milk"));

    // Build the query
    Query<Entity> query = Query.newEntityQueryBuilder().setKind("Task").setFilter(orFilter).build();

    // Get the results back from Datastore
    QueryResults<Entity> results = datastore.run(query);

    if (!results.hasNext()) {
      throw new Exception("query yielded no results");
    }

    while (results.hasNext()) {
      Entity entity = results.next();
      System.out.printf("Entity: %s%n", entity);
    }
  }
}

Node.js

Para autenticar no modo Datastore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = "your Google Cloud project id";

// Imports the Cloud Datastore
const {Datastore, PropertyFilter, or} = require('@google-cloud/datastore');

async function queryFilterOr() {
  // Instantiate the Datastore
  const datastore = new Datastore();
  const query = datastore
    .createQuery('Task')
    .filter(
      or([
        new PropertyFilter('description', '=', 'Buy milk'),
        new PropertyFilter('description', '=', 'Feed cats'),
      ]),
    );

  const [entities] = await datastore.runQuery(query);
  for (const entity of entities) {
    console.log(`Entity found: ${entity['description']}`);
  }
}

queryFilterOr();

PHP

Fragmento não disponível.

Python

Para autenticar no modo Datastore, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

from google.cloud import datastore
from google.cloud.datastore import query


def query_filter_or(project_id: str) -> None:
    """Builds a union of two queries (OR) filter.

    Arguments:
        project_id: your Google Cloud Project ID
    """
    client = datastore.Client(project=project_id)

    or_query = client.query(kind="Task")
    or_filter = query.Or(
        [
            query.PropertyFilter("description", "=", "Buy milk"),
            query.PropertyFilter("description", "=", "Feed cats"),
        ]
    )

    or_query.add_filter(filter=or_filter)

    results = list(or_query.fetch())
    for result in results:
        print(result["description"])

Ruby

Fragmento não disponível.

GQL

Fragmento não disponível.

O Firestore no modo Datastore suporta a combinação de filtros com operadores AND e OR. O exemplo seguinte devolve entidades Task que têm uma estrela ou que estão marcadas como não concluídas e têm uma prioridade de 4:

C#

Fragmento não disponível.

Ir

Fragmento não disponível.

Java

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

Node.js

Fragmento não disponível.

PHP

Fragmento não disponível.

Python

and_or_query = client.query(kind="Task")

query_filter = query.Or(
    [
        query.PropertyFilter("starred", "=", True),
        query.And([query.PropertyFilter("done", "=", False),
                    query.PropertyFilter("priority", "=", 4,),
        ]
        )
    ]
)

and_or_query.add_filter(filter=query_filter)

results = and_or_query.fetch()
for result in results:
    print(result["description"])

Ruby

Fragmento não disponível.

GQL

Fragmento não disponível.

Filtros principais

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

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

GQL

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

Quando faz a comparação para verificar a desigualdade, as chaves são ordenadas pelos seguintes critérios, por ordem:

Caminho do antepassado
Tipo de entidade
Identificador (nome da chave ou ID numérico)

Os elementos do caminho de antepassados são comparados de forma semelhante: por tipo (string) e, em seguida, por nome da chave ou ID numérico. Os tipos e os nomes das chaves são strings e são ordenados por valor de byte; os IDs numéricos são números inteiros e são ordenados numericamente. Se as entidades com o mesmo elemento principal e tipo usarem uma combinação de strings de nomes de chaves e IDs numéricos, as entidades com IDs numéricos precedem as entidades com nomes de chaves.

As consultas em chaves usam índices tal como as consultas em propriedades e requerem índices personalizados nos mesmos casos. As seguintes exceções não requerem um índice personalizado:

Filtros de desigualdade
Ordem de ordenação ascendente na chave

Uma ordem de ordenação descendente na chave requer um índice personalizado. Tal como acontece com todas as consultas, o servidor de desenvolvimento cria entradas adequadas no ficheiro de configuração do índice quando é usada uma consulta que precisa de um índice personalizado no ambiente de desenvolvimento.

Ordene encomendas

Uma ordem de ordenação de consulta especifica o seguinte:

Um nome da propriedade.
Uma direção de ordenação (ascendente ou descendente). Por predefinição, a ordem de ordenação é ascendente.

Este exemplo ordena as entidades de tarefas por hora de criação por ordem ascendente:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

GQL

SELECT * FROM Task ORDER BY created ASC

Este exemplo ordena as entidades Task por hora de criação por ordem descendente:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

GQL

SELECT * FROM Task ORDER BY created DESC

Se uma consulta incluir várias ordens de ordenação, estas são aplicadas na sequência especificada. O exemplo seguinte ordena primeiro por prioridade descendente e, em seguida, por hora de criação ascendente:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

GQL

SELECT * FROM Task ORDER BY priority DESC, created ASC

Se não forem especificadas ordens de ordenação, os resultados são devolvidos na ordem em que são obtidos do modo Datastore.

Restrições

As ordenações têm as seguintes restrições:

Devido à forma como o modo Datastore executa as consultas, se uma consulta especificar filtros de desigualdade numa propriedade e ordens de ordenação noutras propriedades, a propriedade usada nos filtros de desigualdade tem de ser ordenada antes das outras propriedades.
Se a ordenação for especificada, o conjunto de propriedades especificado na cláusula distinct on tem de aparecer antes de quaisquer propriedades não distinct on nas ordens de ordenação . Para mais informações, consulte o artigo sobre agrupar consultas.
As ordens de ordenação em propriedades com filtros de igualdade são todas ignoradas.

Tipos de consultas especiais

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

`!= Not equal`

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

C#

Não aplicável

Go

package datastore_snippets

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/datastore"
	"google.golang.org/api/iterator"
)

func queryNotEquals(w io.Writer, projectId string) error {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectId)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	q := datastore.NewQuery("TaskList")
	q.FilterField("Task", "!=", []string{"notASimpleTask"})

	it := client.Run(ctx, q)
	for {
		var dst struct {
			Task string
		}
		key, err := it.Next(&dst)
		if err == iterator.Done {
			break
		}

		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Key retrieved: %v\n", key)
	}

	return nil
}

Java

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

Node.js

Não aplicável

PHP

Não aplicável

Python

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

Ruby

Não aplicável

GQL

SELECT * FROM Task WHERE category != 'work'

Esta consulta devolve todas as entidades Task em que a propriedade category existe e está definida para qualquer valor que não seja Work.

Esta consulta não devolve entidades onde a propriedade category não existe. As consultas não iguais (!=) e NOT_IN excluem entidades onde a propriedade especificada não existe ou onde a propriedade é excluída da indexação. Uma propriedade existe quando está definida para qualquer valor, incluindo uma string vazia ou null.

Limitações

Tenha em atenção as seguintes limitações para consultas !=:

Só as entidades em que a propriedade especificada existe podem corresponder à consulta.
Só é permitido um único NOT_IN ou != por consulta.

`IN`

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

C#

Não aplicável

Go

package datastore_snippets

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/datastore"
	"google.golang.org/api/iterator"
)

func queryIn(w io.Writer, projectId string) error {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectId)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	q := datastore.NewQuery("TaskList")
	q.FilterField("Task", "in", []string{"simpleTask", "easyTask"})

	it := client.Run(ctx, q)
	for {
		var dst struct {
			Task string
		}
		key, err := it.Next(&dst)
		if err == iterator.Done {
			break
		}

		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Key retrieved: %v\n", key)
	}

	return nil
}

Java

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

Node.js

Não aplicável

PHP

Não aplicável

Python

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

Ruby

Não aplicável

GQL

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

Esta consulta devolve todas as entidades Task em que a propriedade tag está definida como learn ou study. Isto inclui entidades Task em que a propriedade tag inclui um destes valores, mas não o outro.

`NOT_IN`

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

C#

Não aplicável

Go

package datastore_snippets

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/datastore"
	"google.golang.org/api/iterator"
)

func queryNotIn(w io.Writer, projectId string) error {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectId)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	q := datastore.NewQuery("TaskList")
	q.FilterField("Task", "not-in", []string{"notASimpleTask", "notAnEasyTask"})

	it := client.Run(ctx, q)
	for {
		var dst struct {
			Task string
		}
		key, err := it.Next(&dst)
		if err == iterator.Done {
			break
		}

		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Key retrieved: %v\n", key)
	}

	return nil
}

Java

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

Node.js

Não aplicável

PHP

Não aplicável

Python

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

Ruby

Não aplicável

GQL

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

Esta consulta não devolve entidades onde a entidade category não existe. As consultas de não igual (!=) e NOT_IN excluem entidades onde a propriedade especificada não existe. Uma propriedade existe quando está definida para qualquer valor, incluindo uma string vazia ou null.

Limitações

Tenha em atenção as seguintes limitações para consultas NOT_IN:

Só as entidades em que a propriedade especificada existe podem corresponder à consulta.
Só é permitido um único NOT_IN ou != por consulta.

Consultas de antepassados

Uma consulta predecessora limita os respetivos resultados à entidade especificada e aos respetivos descendentes. Este exemplo devolve todas as entidades Task que têm a entidade TaskList especificada como antepassado:

C#

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

Go

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

Java

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

Node.js

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

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

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

GQL

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

Limitações nas consultas de antepassados

Tenha em atenção as seguintes limitações para consultas Ancestor:

Todas as disjunções avaliadas têm de ter o mesmo filtro de antepassados.

Consultas sem tipo

Uma consulta sem tipo nem antepassado obtém todas as entidades de uma aplicação do modo Datastore. Essas consultas sem tipo não podem incluir filtros nem ordens de ordenação em valores de propriedades. No entanto, podem filtrar por chaves de entidades e usar filtros de antecessores. Pode usar filtros de chaves especificando __key__ como o nome da propriedade:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

GQL

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

Consultas de projeção

A maioria das consultas devolve entidades inteiras como resultados, mas, muitas vezes, uma aplicação está realmente interessada apenas em algumas das propriedades da entidade. As consultas de projeção permitem-lhe consultar apenas as propriedades específicas de uma entidade de que realmente precisa, com uma latência e um custo inferiores aos da obtenção da entidade completa.

As consultas de projeção requerem que as propriedades especificadas sejam indexadas.

Consultas apenas de chaves

Uma consulta apenas com chaves (que é um tipo de consulta de projeção) devolve apenas as chaves das entidades de resultado em vez das próprias entidades, com uma latência e um custo inferiores aos da obtenção de entidades inteiras.

Geralmente, é mais económico fazer primeiro uma consulta apenas de chaves e, em seguida, obter um subconjunto de entidades dos resultados, em vez de executar uma consulta geral que pode obter mais entidades do que as que realmente precisa.

Veja como criar uma consulta apenas com chaves:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

GQL

SELECT __key__ FROM Task

Uma consulta apenas com chaves é uma operação pequena e conta como apenas uma leitura de entidade para a própria consulta.

Projeções

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

SELECT priority, percent_complete FROM Task

Pode usar todas as funcionalidades de filtragem e ordenação disponíveis para consultas de entidades padrão, mas tenha em atenção estas limitações.

A consulta SQL de exemplo devolve resultados abreviados com apenas as propriedades especificadas, priority e percent_complete, preenchidas com valores. Todas as outras propriedades não são preenchidas. Veja como construir esta consulta como uma consulta de projeção:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

GQL

SELECT priority, percent_complete FROM Task

Veja como executar a consulta de projeção:

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

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

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

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

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

Python

priorities = []
percent_completes = []

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

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 e conta apenas como uma leitura de entidade única para a própria consulta.

Agrupamento

As consultas de projeção podem usar a cláusula distinct on para garantir que apenas é devolvido o primeiro resultado para cada combinação distinta de valores para as propriedades especificadas. Isto devolve apenas o primeiro resultado para entidades que têm os mesmos valores para as propriedades que estão a ser projetadas.

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

O conjunto de propriedades especificado na cláusula distinct on tem de aparecer antes de quaisquer propriedades não distinct on na cláusula order by, se order by for especificado.

Consultas de agregação

O Firestore no modo Datastore suporta a count() consulta de agregação. Consulte a secção Consultas de agregação.

Filtros de intervalo e desigualdade em várias propriedades

O Firestore no modo Datastore suporta vários filtros de desigualdade numa consulta composta. Consulte o artigo Consultar usando filtros de intervalo e de desigualdade em várias propriedades.

Valores de matriz

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

Tenha em atenção o seguinte quando a sua consulta inclui propriedades com valores de matriz.

Filtros de desigualdade

Devido à forma como são indexadas, as entidades com vários valores para a mesma propriedade podem, por vezes, interagir com filtros de consulta e ordens de ordenação de formas inesperadas e surpreendentes.

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

C#

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

Go

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

Java

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

Node.js

const query = datastore
  .createQuery('Task')
  .filter(
    and([
      new PropertyFilter('tag', '>', 'learn'),
      new PropertyFilter('tag', '<', 'math'),
    ]),
  );

PHP

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

Python

from google.cloud import datastore

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

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

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 tag da entidade satisfaz um dos filtros, mas nenhum valor único satisfaz ambos.

Vários filtros de igualdade

É possível usar vários filtros de igualdade para consultar entidades que contêm um conjunto de valores. Por exemplo, uma entidade do tipo Task com os valores fun e programming para a propriedade tag satisfaz a consulta

C#

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

Go

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

Java

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

Node.js

const query = datastore
  .createQuery('Task')
  .filter(
    and([
      new PropertyFilter('tag', '=', 'fun'),
      new PropertyFilter('tag', '=', 'programming'),
    ]),
  );

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

GQL

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

Embora nenhum dos valores tag individuais da entidade satisfaça ambas as condições de filtro.

Disposição da Ordenação

Da mesma forma, a ordem de ordenação das propriedades com vários valores é invulgar. Uma vez que estas propriedades aparecem uma vez no índice para cada valor único, o primeiro valor apresentado no índice determina a ordem de ordenação de uma entidade.

Se uma propriedade com vários valores não for usada em nenhum filtro:

e os resultados da consulta são ordenados por ordem ascendente pela propriedade, o valor mais pequeno da propriedade é usado para a ordenação.
e os resultados da consulta são ordenados por ordem descendente pela propriedade, o maior valor é usado para a ordenação.
Os outros valores não afetam a ordem de ordenação, nem o número de valores.

Isto tem a consequência invulgar de que uma entidade com os valores das propriedades 1 e 9 precede uma entidade com os valores 4, 5, 6 e 7 por ordem ascendente e descendente.

Se uma propriedade com vários valores for usada num filtro de igualdade, qualquer ordem de classificação nessa propriedade é ignorada.

Se for usada uma propriedade com vários valores numa desigualdade ou num filtro NOT_IN:

e os resultados da consulta são ordenados por ordem ascendente pela propriedade, o valor mais pequeno que satisfaz todos os filtros de desigualdade da consulta é usado para a ordenação.
e os resultados da consulta são ordenados por ordem descendente pela propriedade, o maior valor que satisfaz todos os filtros de desigualdade da consulta é usado para a ordenação.

Tenha em atenção que, se um conjunto de filtros de desigualdade numa propriedade se traduzir num filtro de igualdade, como

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

Qualquer ordem de ordenação nessa propriedade é ignorada, uma vez que os filtros são avaliados da mesma forma que o filtro de igualdade

WHERE tag = 'math'

Projeções e propriedades com valores de matriz

A projeção de uma propriedade com valores de matriz não preenche todos os valores dessa propriedade. Em alternativa, é devolvida uma entidade separada para cada combinação única de valores projetados que corresponda à consulta. Por exemplo, suponhamos que tem uma entidade do tipo Task com duas propriedades de vários valores, tag e collaborators:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

GQL

Não aplicável

Em seguida, a consulta de projeção

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

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

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

Cursores, limites e desvios

Pode especificar um limite para a sua consulta de modo a controlar o número máximo de resultados devolvidos num lote. O exemplo seguinte obtém, no máximo, cinco entidades Task:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

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

Ruby

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

GQL

SELECT * FROM Task LIMIT 5

Os cursores de consulta permitem que uma aplicação obtenha os resultados de uma consulta em lotes convenientes sem incorrer na sobrecarga de uma compensação de consulta. Após realizar uma operação de obtenção, a aplicação pode obter um cursor, que é uma string de bytes opaca que marca a posição do índice do último resultado obtido. A aplicação pode guardar esta string (por exemplo, na sua base de dados do modo Datastore, numa cache ou incorporada numa página Web como um parâmetro HTTP GET ou POST codificado em base 64) e, em seguida, pode usar o cursor como ponto de partida para uma operação de obtenção subsequente para obter o lote seguinte de resultados a partir do ponto em que a obtenção anterior terminou. Uma obtenção também pode especificar um cursor final para limitar a extensão do conjunto de resultados devolvido.

O exemplo seguinte demonstra a utilização de cursores para paginação:

C#

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

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

Go

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

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

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

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

Java

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

// 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

/**
 * Fetch a query cursor.
 *
 * @param int $pageSize
 * @param string $pageCursor
 * @param string $namespaceId
 */
function cursor_paging(int $pageSize, string $pageCursor = '', string $namespaceId = null)
{
    $datastore = new DatastoreClient(['namespaceId' => $namespaceId]);
    $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;
    }

    printf('Found %s entities', count($entities));

    $entities = [];
    if (!empty($nextPageCursor)) {
        $query = $datastore->query()
          ->kind('Task')
          ->limit($pageSize)
          ->start($nextPageCursor);
        $result = $datastore->runQuery($query);

        foreach ($result as $entity) {
            $entities[] = $entity;
        }

        printf('Found %s entities with next page cursor', count($entities));
    }
}

Python

from google.cloud import datastore

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


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

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

Embora as bases de dados do modo Datastore suportem deslocamentos de números inteiros, deve evitar usá-los. Em alternativa, use cursores. A utilização de um deslocamento apenas evita devolver as entidades ignoradas à sua aplicação, mas estas entidades continuam a ser obtidas internamente. As entidades ignoradas afetam a latência da consulta e a sua aplicação é faturada pelas operações de leitura necessárias para as obter. A utilização de cursores em vez de deslocamentos permite-lhe evitar todos estes custos.

Limitações dos cursores

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

Um cursor só pode ser usado pelo mesmo projeto que executou a consulta original e apenas para continuar a mesma consulta. Não é possível obter resultados através de um cursor sem configurar a mesma consulta a partir da qual foi originalmente gerado.
Se algum dos seguintes itens for alterado, ainda pode usar um cursor para obtenções subsequentes.
- cursor de início
- cursor final
- compensação
- limite
Se algum dos seguintes itens for alterado, não é possível usar um cursor para obtenções subsequentes.
- projeção
- gentil
- predecessor
- filtrar
- distinta em
- Ordem de ordenação Uma exceção é se a ordem de ordenação final da consulta original foi em __key__. Nesse caso, pode usar o cursor numa consulta inversa, que é a consulta original com cada ordem de ordenação invertida. A consulta inversa pode modificar o cursor inicial, o cursor final, o desvio e o limite.
Os cursores nem sempre funcionam como esperado com uma consulta que usa um filtro de desigualdade ou uma ordem de ordenação numa propriedade com vários valores. A lógica de remoção de duplicados para essas propriedades com vários valores não persiste entre as obtenções, o que pode fazer com que o mesmo resultado seja devolvido mais do que uma vez.
Os novos lançamentos do modo Datastore podem alterar os detalhes de implementação internos, invalidando os cursores que dependem deles. Se uma aplicação tentar usar um cursor que já não é válido, o Firestore no modo Datastore gera uma exceção.

Cursores e atualizações de dados

O cursor representa a localização na lista de resultados após o último resultado devolvido. Um cursor não é uma posição relativa na lista (não é um desvio); é um marcador para o qual uma base de dados do modo Datastore pode saltar quando inicia uma análise de índice para resultados. Se os resultados de uma consulta mudarem entre as utilizações de um cursor, a consulta apenas nota as alterações que ocorrem nos resultados após o cursor. Se aparecer um novo resultado antes da posição do cursor para a consulta, este não é devolvido quando os resultados após o cursor são obtidos. Da mesma forma, se uma entidade deixar de ser um resultado para uma consulta, mas tiver aparecido antes do cursor, os resultados que aparecem depois do cursor não mudam. Se o último resultado devolvido for removido do conjunto de resultados, o cursor continua a saber como localizar o resultado seguinte.

Ao obter resultados de consultas, pode usar um cursor inicial e um cursor final para devolver um grupo contínuo de resultados. Quando usa um cursor de início e fim para obter os resultados, não tem a garantia de que o tamanho dos resultados seja o mesmo que quando gerou os cursores. As entidades podem ser adicionadas ou eliminadas da base de dados entre o momento em que os cursores são gerados e o momento em que são usados numa consulta.

Restrições relativas a consultas

A natureza do mecanismo de consulta de índice impõe determinadas restrições ao que uma consulta pode fazer. As consultas do modo Datastore não suportam correspondências de subcadeias de carateres, correspondências não sensíveis a maiúsculas e minúsculas nem pesquisa de texto completo. Além disso, aplicam-se as seguintes restrições:

As entidades que não têm uma propriedade com o nome especificado na consulta são ignoradas

As entidades do mesmo tipo não têm de ter as mesmas propriedades. Para ser elegível como resultado de uma consulta, uma entidade tem de ter um valor (possivelmente nulo) para cada propriedade com nome nos filtros e nas ordens de ordenação da consulta. Caso contrário, a entidade é omitida dos índices usados para executar a consulta e, consequentemente, não é incluída nos resultados da consulta.

A filtragem em propriedades não indexadas não devolve resultados

Uma consulta não consegue encontrar valores de propriedades que não estejam indexados, nem consegue ordenar por essas propriedades. Para mais informações, consulte o artigo Propriedades não indexadas.

Limites nos filtros de desigualdade

Para evitar que as consultas se tornem demasiado caras de executar, o Firestore no modo Datastore limita o número de propriedades de intervalo ou de desigualdade a 10. Para mais informações sobre consultas com filtros de desigualdade, consulte o artigo Consultar usando filtros de intervalo e de desigualdade em várias propriedades.

Não pode usar os parâmetros `NOT_EQUAL` e `NOT_IN` ao mesmo tempo

Se usar a cláusula NOT_IN, também não pode adicionar uma cláusula NOT_EQUAL.

A ordenação dos resultados da consulta não está definida quando não é especificada nenhuma ordem de ordenação

Quando uma consulta não especifica uma ordem de ordenação, os resultados são devolvidos na ordem em que são obtidos. À medida que a implementação do modo Datastore evolui (ou se os índices de um projeto mudarem), esta ordem pode mudar. Por conseguinte, se a sua aplicação precisar dos resultados da consulta numa ordem específica, certifique-se de que especifica explicitamente essa ordem de ordenação na consulta.

As ordens de ordenação são ignoradas 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. Esta é uma otimização para poupar processamento desnecessário para propriedades de valor único. Uma vez que todos os resultados têm o mesmo valor para a propriedade, não é necessária qualquer ordenação adicional. No entanto, as propriedades com vários valores podem ter valores adicionais além do valor correspondente ao filtro de igualdade. Uma vez que este exemplo de utilização é raro e a aplicação da ordem de ordenação seria dispendiosa e exigiria índices adicionais, o planeador de consultas do modo Datastore ignora a ordem de ordenação, mesmo no caso de vários valores. Isto pode fazer com que os resultados da consulta sejam devolvidos numa ordem diferente da ordem de ordenação que parece estar implícita. Por exemplo, a ordem de ordenação é ignorada na seguinte consulta:

C#

Não aplicável

Go

Não aplicável

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.eq("tag", "learn"))
        .setOrderBy(OrderBy.asc("tag"))
        .build();

Node.js

Não aplicável

PHP

Não aplicável

Python

Não aplicável

Ruby

Não aplicável

GQL

# Sort order on an equality filter is ignored
SELECT * FROM Task WHERE tag = 'learn' ORDER BY tag ASC

Isto não se aplica a consultas que incluem um filtro IN. Use o operador IN para combinar até 10 cláusulas de igualdade (==) na mesma propriedade com um OR lógico. Se adicionar uma ordem de classificação para essa propriedade, esta é aplicada ao conjunto de resultados.

C#

Não aplicável

Go

Não aplicável

Java

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

Node.js

Não aplicável

PHP

Não aplicável

Python

Não aplicável

Ruby

Não aplicável

GQL

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

Para a ordem ascendente, o valor mais pequeno que satisfaz o filtro é usado para a ordenação.
Para a ordem descendente, é usado o maior valor que satisfaz o filtro para a ordenação.
Outros valores não afetam a ordem de ordenação, nem o número de valores na propriedade.

As propriedades usadas em filtros de desigualdade têm de ser ordenadas primeiro

Para obter todos os resultados que correspondem a um filtro de desigualdade, uma consulta analisa o índice para encontrar a primeira linha que corresponde ao filtro e, em seguida, analisa para a frente até encontrar uma linha que não corresponde. Para que as linhas consecutivas abranjam o conjunto de resultados completo, têm de ser ordenadas pela propriedade usada no filtro de desigualdade antes de quaisquer outras propriedades. Assim, se uma consulta especificar um ou mais filtros de desigualdade juntamente com uma ou mais ordens de ordenação, a primeira ordem de ordenação tem de fazer referência à mesma propriedade mencionada nos filtros de desigualdade. Segue-se uma consulta válida:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

query = client.query(kind="Task")
query.add_filter(filter=datastore.query.PropertyFilter("priority", ">", 3))
query.order = ["priority", "created"]

Ruby

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

GQL

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

Esta consulta não é válida porque não ordena pela propriedade usada no filtro de desigualdade:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

    query = client.query(kind="Task")
    query.add_filter(filter=datastore.query.PropertyFilter("priority", ">", 3))
    query.order = ["created"]

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, esta consulta não é válida porque a propriedade usada no filtro de desigualdade não é a primeira a ser ordenada:

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

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

    query = client.query(kind="Task")
    query.add_filter(filter=datastore.query.PropertyFilter("priority", ">", 3))
    query.order = ["created", "priority"]

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

`OrderBy` e existência

Quando ordena uma consulta por uma determinada propriedade, a consulta só pode devolver as entidades onde a propriedade de ordenação existe.

Por exemplo, a seguinte consulta não devolve nenhuma entidade em que a propriedade priority não esteja definida, mesmo que, de resto, cumpra os filtros de consulta.

Java

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

Um efeito relacionado aplica-se a desigualdades. Uma consulta com um filtro de desigualdade numa propriedade também implica a ordenação por essa propriedade. A seguinte consulta não devolve entidades sem uma propriedade priority, mesmo que starred = true nessa entidade. Como solução alternativa, pode executar consultas separadas para cada ordenação ou pode atribuir um valor a todas as propriedades pelas quais ordena.

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(CompositeFilter.or(
            PropertyFilter.eq("starred", true)),
            PropertyFilter.ge("priority", 4))
        .build();

A consulta anterior inclui uma ordenação implícita na desigualdade, como a seguinte. A direção da ordenação implícita depende dos índices disponíveis:

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(CompositeFilter.or(
            PropertyFilter.eq("starred", true)),
            PropertyFilter.ge("priority", 4)
        )
        .setOrderBy(OrderBy.asc("priority"))
        .build();

Limitações nas projeções

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

Só é possível projetar propriedades indexadas.

Isto significa que todas as propriedades usadas numa consulta (projetadas ou filtros) têm de existir no mesmo índice. Assim, select tag from Task where priority = 1 requer um índice composto na prioridade e, em seguida, na etiqueta.

A projeção não é suportada para strings com mais de 1500 bytes, matrizes de bytes com mais de 1500 elementos e outras propriedades explicitamente marcadas como não indexadas.
Não é possível projetar a mesma propriedade mais do que uma vez.
Não é possível projetar propriedades referenciadas num filtro de igualdade.

Por exemplo,
```
SELECT tag FROM Task WHERE priority = 1
```
É válido (a propriedade projetada não é usada no filtro de igualdade), tal como
```
SELECT tag FROM Task WHERE tag > 'fun`
```
(não é um filtro de igualdade), mas
```
SELECT tag FROM Task WHERE tag = 'fun`
```
(projected property used in equality filter) is not.
Os resultados devolvidos por uma consulta de projeção não devem ser guardados novamente na base de dados do modo Datastore.

Uma vez que a consulta devolve resultados que estão apenas parcialmente preenchidos, não deve escrevê-los novamente na base de dados do modo Datastore.
As consultas de projeção convertem as datas/horas em números inteiros.

Nos resultados de uma consulta de projeção, o modo Datastore converte os valores de data/hora em valores inteiros de microssegundos.

O que se segue?

Saiba mais sobre as Transações.

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

Interface de consulta

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Estrutura da consulta

Filtros

Filtros de propriedades

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Filtros compostos

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

C#

Ir

Java

Node.js

PHP

Python

Ruby

GQL

C#

Ir

Java

Node.js

PHP

Python

Ruby

GQL

Filtros principais

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Ordene encomendas

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

Consultas do armazenamento de dados

`!= Not equal`

`IN`

`NOT_IN`