Executa uma consulta de agregação.
Em vez de produzir resultados Document
como Firestore.RunQuery
, essa API permite executar uma agregação para produzir uma série de AggregationResult
no lado do servidor.
Exemplo de alto nível:
-- Return the number of documents in table given a filter.
SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );
Solicitação HTTP
POST https://firestore.googleapis.com/v1/{parent=projects/*/databases/*/documents}:runAggregationQuery
O URL usa a sintaxe de transcodificação gRPC.
Parâmetros de caminho
Parâmetros | |
---|---|
parent |
Obrigatório. O nome do recurso pai. Use o formato: |
Corpo da solicitação
O corpo da solicitação contém dados com a seguinte estrutura:
Representação JSON |
---|
{ "explainOptions": { object ( |
Campos | |
---|---|
explainOptions |
Opcional. Explique as opções para a consulta. Se definido, outras estatísticas de consulta serão retornadas. Caso contrário, apenas os resultados da consulta serão retornados. |
Campo de união query_type . A consulta a ser executada. query_type pode ser apenas de um dos tipos a seguir: |
|
structuredAggregationQuery |
Uma consulta de agregação. |
Campo de união consistency_selector . O modo de consistência da consulta. O padrão é consistência forte. consistency_selector pode ser apenas de um dos tipos a seguir: |
|
transaction |
Execute a agregação em uma transação já ativa. O valor aqui é o ID da transação opaco em que a consulta será executada. Uma string codificada em base64. |
newTransaction |
Inicia uma nova transação como parte da consulta, assumindo o padrão somente leitura. O novo ID da transação vai ser retornado como a primeira resposta no fluxo. |
readTime |
Executa a consulta no carimbo de data/hora fornecido. Precisa ser um carimbo de data/hora com precisão de microssegundos dentro da última hora ou, se a recuperação pontual estiver ativada, também pode ser um carimbo de data/hora de um minuto inteiro nos últimos sete dias. Um carimbo de data/hora no formato UTC "Zulu" RFC3339, com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: |
Corpo da resposta
A resposta para Firestore.RunAggregationQuery
.
Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:
Representação JSON |
---|
{ "result": { object ( |
Campos | |
---|---|
result |
Um único resultado de agregação. Não está presente ao informar progresso parcial. |
transaction |
A transação que foi iniciada como parte desta solicitação. Presente apenas na primeira resposta quando a solicitação é solicitada para iniciar uma nova transação. Uma string codificada em base64. |
readTime |
A hora em que o resultado agregado foi calculado. Isso sempre aumenta monotonicamente. Nesse caso, há a garantia de que o AggregateResult anterior no fluxo de resultado não muda entre o Se a consulta não retornar resultados, uma resposta com Um carimbo de data/hora no formato UTC "Zulu" RFC3339, com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: |
explainMetrics |
Métricas de explicação de consulta. Ele só está presente quando o |
Escopos de autorização
Requer um dos seguintes escopos de OAuth:
https://www.googleapis.com/auth/datastore
https://www.googleapis.com/auth/cloud-platform
Para saber mais, consulte a Visão geral da autenticação.
StructuredAggregationQuery
Consulta do Firestore para executar uma agregação em um StructuredQuery
.
Representação JSON |
---|
{ "aggregations": [ { object ( |
Campos | |
---|---|
aggregations[] |
Opcional. Série de agregações que vão ser aplicadas aos resultados da Requer:
|
Campo de união query_type . A consulta de base para agregação. query_type pode ser apenas de um dos tipos a seguir: |
|
structuredQuery |
Consulta estruturada aninhada. |
Agregação
Define uma agregação que produz um único resultado.
Representação JSON |
---|
{ "alias": string, // Union field |
Campos | |
---|---|
alias |
Opcional. Nome opcional do campo em que o resultado da agregação é armazenado. Se não for fornecido, o Firestore escolherá um nome padrão seguindo o formato
se torna:
Requer:
|
Campo de união operator . O tipo de agregação a ser realizada, obrigatório. operator pode ser apenas de um dos tipos a seguir: |
|
count |
Agregador de contagem. |
sum |
Agregador de soma. |
avg |
Agregador médio. |
Contagem
Contagem de documentos que correspondem à consulta.
A função de agregação COUNT(*)
opera em todo o documento. Por isso, não requer uma referência de campo.
Representação JSON |
---|
{ "upTo": string } |
Campos | |
---|---|
upTo |
Opcional. Restrição opcional para o número máximo de documentos a serem contabilizados. Dessa forma, é possível definir um limite superior para o número de documentos a serem verificados, limitando a latência e o custo. Um valor não especificado é interpretado como "sem limite". Exemplo de alto nível:
Requer:
|
Sum
Soma dos valores do campo solicitado.
Somente valores numéricos serão agregados. Todos os valores não numéricos, incluindo
NULL
, são ignorados.Se os valores agregados contiverem
NaN
, retornaráNaN
. A matemática do infinito segue os padrões IEEE-754.Se o conjunto de valores agregados estiver vazio, retornará 0.
Retorna um número inteiro de 64 bits se todos os números agregados forem inteiros e o resultado da soma não estourar. Caso contrário, o resultado será retornado como double. Mesmo que todos os valores agregados sejam inteiros, o resultado será retornado como duplo se não couber em um número inteiro assinado de 64 bits. Quando isso ocorrer, o valor retornado vai perder a precisão.
Quando ocorre subfluxo, a agregação de ponto flutuante não é determinista. Isso significa que executar a mesma consulta repetidamente sem nenhuma alteração dos valores subjacentes pode produzir resultados um pouco diferentes a cada vez. Nesses casos, os valores devem ser armazenados como números inteiros sobre números de ponto flutuante.
Representação JSON |
---|
{
"field": {
object ( |
Campos | |
---|---|
field |
O campo no qual agregar. |
Méd.
Média dos valores do campo solicitado.
Somente valores numéricos serão agregados. Todos os valores não numéricos, incluindo
NULL
, são ignorados.Se os valores agregados contiverem
NaN
, retornaráNaN
. A matemática do infinito segue os padrões IEEE-754.Se o conjunto de valores agregados estiver vazio, será retornado
NULL
.Sempre retorna o resultado como double.
Representação JSON |
---|
{
"field": {
object ( |
Campos | |
---|---|
field |
O campo no qual agregar. |
AggregationResult
O resultado de um único bucket de uma consulta de agregação do Firestore.
As chaves de aggregateFields
são as mesmas para todos os resultados em uma consulta de agregação, ao contrário das consultas de documentos, que podem ter campos diferentes para cada resultado.
Representação JSON |
---|
{
"aggregateFields": {
string: {
object ( |
Campos | |
---|---|
aggregateFields |
O resultado das funções de agregação, por exemplo: A chave é a Um objeto com uma lista de pares |