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

Para saber como instalar e usar a biblioteca cliente do Cloud Datastore, consulte as

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`