Method: projects.databases.documents.runAggregationQuery

Executa uma consulta de agregação.

Em vez de produzir resultados de Document como Firestore.RunQuery, essa API permite executar uma agregação para produzir uma série de AggregationResult do 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

string

Obrigatório. O nome do recurso pai. Use o formato projects/{projectId}/databases/{databaseId}/documents ou projects/{projectId}/databases/{databaseId}/documents/{document_path}. Por exemplo: projects/my-project/databases/my-database/documents ou projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação JSON 
{
  "explainOptions": {
    object (ExplainOptions)
  },

  // Union field query_type can be only one of the following:
  "structuredAggregationQuery": {
    object (StructuredAggregationQuery)
  }
  // End of list of possible types for union field query_type.

  // Union field consistency_selector can be only one of the following:
  "transaction": string,
  "newTransaction": {
    object (TransactionOptions)
  },
  "readTime": string
  // End of list of possible types for union field consistency_selector.
}
Campos
explainOptions

object (ExplainOptions)

Opcional. Explique as opções da consulta. Se definido, serão retornadas estatísticas de consulta adicionais. 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

object (StructuredAggregationQuery)

Uma consulta de agregação.
Campo de união consistency_selector. O modo de consistência da consulta tem como padrão a consistência forte. consistency_selector pode ser apenas de um dos tipos a seguir:
transaction

string (bytes format)

Execute a agregação em uma transação já ativa.

O valor aqui é o ID da transação opaco para executar a consulta.

Uma string codificada em base64.
newTransaction

object (TransactionOptions)

Inicia uma nova transação como parte da consulta, com o padrão somente para leitura.

O novo ID da transação será retornado como a primeira resposta no fluxo.
readTime

string (Timestamp format)

Executa a consulta no carimbo de data/hora determinado.

Precisa ser um carimbo de data/hora com precisão de microssegundos na última hora ou, se a recuperação pontual estiver ativada, também poderá ser um carimbo de data/hora de um minuto inteiro nos últimos sete dias.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

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 (AggregationResult)
  },
  "transaction": string,
  "readTime": string,
  "explainMetrics": {
    object (ExplainMetrics)
  }
}
Campos
result

object (AggregationResult)

Um único resultado de agregação.

Não está presente ao relatar progresso parcial.
transaction

string (bytes format)

A transação que foi iniciada como parte da solicitação.

Presente apenas na primeira resposta quando a solicitação pede para iniciar uma nova transação.

Uma string codificada em base64.
readTime

string (Timestamp format)

A hora em que o resultado agregado foi calculado. Ela está sempre aumentando monotonicamente. nesse caso, o AggregateResult anterior no stream de resultados não vai ter sido alterado entre o readTime e este.

Se a consulta não retornar resultados, uma resposta com readTime e nenhum result será enviada, o que representa o horário em que a consulta foi executada.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
explainMetrics

object (ExplainMetrics)

Explicar as métricas da consulta. Ele só está presente quando o RunAggregationQueryRequest.explain_options é fornecido e é enviado apenas uma vez com a última resposta no stream.

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.

ConsultadeAgregação Estruturada

Consulta do Firestore para executar uma agregação em um StructuredQuery.

Representação JSON 
{
  "aggregations": [
    {
      object (Aggregation)
    }
  ],

  // Union field query_type can be only one of the following:
  "structuredQuery": {
    object (StructuredQuery)
  }
  // End of list of possible types for union field query_type.
}
Campos
aggregations[]

object (Aggregation)

Opcional. Série de agregações a serem aplicadas aos resultados do structuredQuery.

Requer:

  • Mínimo de uma e máximo de cinco agregações por consulta.
Campo de união query_type. A consulta base sobre a qual a agregação será feita. query_type pode ser apenas de um dos tipos a seguir:
structuredQuery

object (StructuredQuery)

Consulta estruturada aninhada.

Agregação

Define uma agregação que produz um único resultado.

Representação JSON 
{
  "alias": string,

  // Union field operator can be only one of the following:
  "count": {
    object (Count)
  },
  "sum": {
    object (Sum)
  },
  "avg": {
    object (Avg)
  }
  // End of list of possible types for union field operator.
}
Campos
alias

string

Opcional. Nome opcional do campo em que o resultado da agregação será armazenado.

Se não for fornecido, o Firestore escolherá um nome padrão seguindo o formato field_<incremental_id++>. Exemplo:

AGGREGATE
  COUNT_UP_TO(1) AS count_up_to_1,
  COUNT_UP_TO(2),
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT(*)
OVER (
  ...
);

passa a ser:

AGGREGATE
  COUNT_UP_TO(1) AS count_up_to_1,
  COUNT_UP_TO(2) AS field_1,
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT(*) AS field_2
OVER (
  ...
);

Requer:

  • Precisa ser exclusivo entre todos os aliases de agregação.
  • Seguir as limitações de document field name.
Campo de união operator. O tipo de agregação a ser executada (obrigatório). operator pode ser apenas de um dos tipos a seguir:
count

object (Count)

Agregador de contagem.
sum

object (Sum)

Agregador de soma.
avg

object (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

string (Int64Value format)

Opcional. Restrição opcional sobre o número máximo de documentos a serem contados.

Isso oferece uma maneira de definir um limite superior para o número de documentos a serem verificados, limitando a latência e o custo.

"Não especificado" é interpretado como sem limite.

Exemplo de alto nível:

AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );

Requer:

  • Precisa ser maior que zero quando presente.

Soma

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 é retornado como um valor double. Mesmo que todos os valores agregados sejam números inteiros, o resultado será retornado como "double" se não couber em um número inteiro assinado de 64 bits. Quando isso ocorre, o valor retornado perde a precisão.

  • Quando ocorre um subfluxo, a agregação de ponto flutuante não é determinista. Isso significa que executar a mesma consulta repetidamente sem alterações nos valores subjacentes pode produzir resultados um pouco diferentes a cada vez. Nesses casos, os valores precisam ser armazenados como números inteiros sobre números de ponto flutuante.

Representação JSON 
{
  "field": {
    object (FieldReference)
  }
}
Campos
field

object (FieldReference)

O campo de agregação.

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, retornará NULL.

  • Sempre retorna o resultado como um valor duplo.

Representação JSON 
{
  "field": {
    object (FieldReference)
  }
}
Campos
field

object (FieldReference)

O campo de agregação.

AggregateResult

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 (Value)
    },
    ...
  }
}
Campos
aggregateFields

map (key: string, value: object (Value))

O resultado das funções de agregação, por exemplo: COUNT(*) AS total_docs.

A chave é o alias atribuído à função de agregação na entrada, e o tamanho desse mapa é igual ao número de funções de agregação na consulta.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.