Method: projects.databases.documents.runAggregationQuery

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

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

string (bytes format)

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

object (TransactionOptions)

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

string (Timestamp format)

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: "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 informar 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 é solicitada para iniciar uma nova transação.

Uma string codificada em base64.
readTime

string (Timestamp format)

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 readTime e esse.

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

Um carimbo de data/hora no formato UTC "Zulu" RFC3339, 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)

Métricas de explicação de 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.

StructuredAggregationQuery

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 que vão ser aplicadas aos resultados da structuredQuery.

Requer:

  • No mínimo uma e no máximo cinco agregações por consulta.
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

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 é 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 (
  ...
);

se torna:

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.
  • estar em conformidade com as limitações do document field name;
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

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

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

Requer:

  • Precisa ser maior que zero quando presente.

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 (FieldReference)
  }
}
Campos
field

object (FieldReference)

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 (FieldReference)
  }
}
Campos
field

object (FieldReference)

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 (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 é a alias atribuída à 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" }.