Method: projects.databases.documents.runAggregationQuery

Executa uma consulta de agregação.

Em vez de produzir resultados Document como Firestore.RunQuery , esta 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/v1beta1/{parent=projects/*/databases/*/documents}:runAggregationQuery

A URL usa sintaxe de transcodificação gRPC .

Parâmetros de caminho

Parâmetros
parent

string

Obrigatório. O nome do recurso pai. No 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

Solicitar corpo

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

Representação JSON
{

  // 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
Campo de união query_type . A consulta a ser executada. query_type pode ser apenas um dos seguintes:
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 consistência forte. consistency_selector pode ser apenas um dos seguintes:
transaction

string ( bytes format)

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

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

Uma string codificada em base64.

newTransaction

object ( TransactionOptions )

Inicia uma nova transação como parte da consulta, padronizando como somente leitura.

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

readTime

string ( Timestamp format)

Executa a consulta no carimbo de data/hora fornecido.

Deve ser um carimbo de data/hora com precisão de microssegundos da última hora ou, se a recuperação pontual estiver ativada, também pode ser um carimbo de hora de um minuto inteiro dos últimos 7 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 de resposta

A resposta para Firestore.RunAggregationQuery .

Se for bem-sucedido, o corpo da resposta conterá dados com a seguinte estrutura:

Representação JSON
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string
}
Campos
result

object ( AggregationResult )

Um único resultado de agregação.

Não presente ao relatar progresso parcial.

transaction

string ( bytes format)

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

Presente apenas na primeira resposta quando a solicitação solicitou o início de uma nova transação.

Uma string codificada em base64.

readTime

string ( Timestamp format)

A hora em que o resultado agregado foi calculado. Isto está sempre aumentando monotonicamente; nesse caso, é garantido que o AggregationResult anterior no fluxo de resultados não mudou entre seu readTime e este.

Se a consulta não retornar nenhum resultado, será enviada uma resposta com readTime e nenhum result , e isso 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" .

Escopos de autorização

Requer um dos seguintes escopos OAuth:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

Para obter mais informações, consulte Visão geral da autenticação .

Consulta de agregaçã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 sobre os resultados do structuredQuery .

Requer:

  • Um mínimo de uma e um máximo de cinco agregações por consulta.
Campo de união query_type . A consulta base a ser agregada. query_type pode ser apenas um dos seguintes:
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 no qual armazenar o resultado da agregação.

Se não for fornecido, o Firestore escolherá um nome padrão seguindo o formato field_<incremental_id++> . Por 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 (
  ...
);

torna-se:

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:

  • Deve ser exclusivo em todos os aliases de agregação.
  • Em conformidade com as limitações document field name .
operator de campo união. O tipo de agregação a ser executada, obrigatório. operator pode ser apenas um dos seguintes:
count

object ( Count )

Agregador de contagem.

sum

object ( Sum )

Agregador de soma.

avg

object ( Avg )

Agregador médio.

Contar

Contagem de documentos que correspondem à consulta.

A função de agregação COUNT(*) opera em todo o documento, portanto não requer uma referência de campo.

Representação JSON
{
  "upTo": string
}
Campos
upTo

string ( Int64Value format)

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

Isso fornece uma maneira de definir um limite máximo para o número de documentos a serem digitalizados, 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:

  • Deve 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 infinita 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 exceder. Caso contrário, o resultado será retornado como duplo. Observe que mesmo que todos os valores agregados sejam inteiros, o resultado será retornado como um duplo se não couber em um inteiro assinado de 64 bits. Quando isso ocorrer, o valor retornado perderá precisão.

  • Quando ocorre underflow, a agregação de ponto flutuante não é determinística. Isso significa que executar a mesma consulta repetidamente sem quaisquer alterações nos valores subjacentes poderá produzir resultados ligeiramente 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 (FieldReference)
  }
}
Campos
field

object ( FieldReference )

O campo no qual agregar.

Média

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 infinita segue os padrões IEEE-754.

  • Se o conjunto de valores agregados estiver vazio, retornará NULL .

  • Sempre retorna o resultado como duplo.

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

object ( FieldReference )

O campo no qual agregar.

Resultado de agregação

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, diferentemente das consultas de documentos que podem ter campos diferentes presentes 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, ex: COUNT(*) AS total_docs .

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

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