Method: projects.databases.documents.runAggregationQuery

Ejecuta una consulta de agregación.

En lugar de producir resultados de Document como Firestore.RunQuery, esta API permite ejecutar una agregación para producir una serie de AggregationResult del servidor.

Ejemplo de alto nivel:

-- Return the number of documents in table given a filter.
SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );

Solicitud HTTP

POST https://firestore.googleapis.com/v1beta1/{parent=projects/*/databases/*/documents}:runAggregationQuery

La URL usa la sintaxis de la transcodificación gRPC.

Parámetros de ruta de acceso

Parámetros
parent

string

Obligatorio. El nombre del recurso superior. En el formato: projects/{projectId}/databases/{databaseId}/documents o projects/{projectId}/databases/{databaseId}/documents/{document_path}. Por ejemplo, projects/my-project/databases/my-database/documents o projects/my-project/databases/my-database/documents/chatrooms/my-chatroom.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene datos con la siguiente estructura:

Representación 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. Explica las opciones para la consulta. Si se configura, se mostrarán estadísticas de consulta adicionales. De lo contrario, solo se mostrarán los resultados de la consulta.
Campo de unión query_type. La consulta que se ejecutará. Las direcciones (query_type) solo pueden ser una de las siguientes opciones:
structuredAggregationQuery

object (StructuredAggregationQuery)

Una consulta de agregación.
Campo de unión consistency_selector. El modo de coherencia para la consulta se establece de forma predeterminada en la coherencia sólida. Las direcciones (consistency_selector) solo pueden ser una de las siguientes opciones:
transaction

string (bytes format)

Ejecuta la agregación dentro de una transacción ya activa.

El valor aquí es el ID de transacción opaco en el que se ejecutará la consulta.

String codificada en base64.
newTransaction

object (TransactionOptions)

Inicia una transacción nueva como parte de la consulta y, de forma predeterminada, es de solo lectura.

El nuevo ID de transacción se mostrará como la primera respuesta en la transmisión.
readTime

string (Timestamp format)

Ejecuta la consulta en la marca de tiempo indicada.

Debe ser una marca de tiempo con precisión de microsegundos dentro de la última hora o, si está habilitada la recuperación de un momento determinado, también puede ser una marca de tiempo de un minuto completo dentro de los últimos 7 días.

Una marca de tiempo en formato RFC3339 UTC “Zulú”, con resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z" y "2014-10-02T15:01:23.045123456Z".

Cuerpo de la respuesta

La respuesta para Firestore.RunAggregationQuery.

Si se ejecuta correctamente, el cuerpo de la respuesta contendrá datos con la siguiente estructura:

Representación JSON 
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string,
  "explainMetrics": {
    object (ExplainMetrics)
  }
}
Campos
result

object (AggregationResult)

Un solo resultado de agregación.

No está presente cuando se informa un progreso parcial.
transaction

string (bytes format)

Indica la transacción que se inició como parte de esta solicitud.

Solo está presente en la primera respuesta cuando la solicitud solicitó iniciar una transacción nueva.

String codificada en base64.
readTime

string (Timestamp format)

El momento en el que se calculó el resultado agregado. Esto siempre aumenta de forma monótona; en este caso, se garantiza que el AggregationResult anterior en el flujo de resultados no haya cambiado entre su readTime y este.

Si la consulta no muestra resultados, se enviará una respuesta con readTime y sin result, que representa la hora en la que se ejecutó la consulta.

Una marca de tiempo en formato RFC3339 UTC “Zulú”, con resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z" y "2014-10-02T15:01:23.045123456Z".
explainMetrics

object (ExplainMetrics)

Métricas de explicación de consultas Esto solo está presente cuando se proporciona el RunAggregationQueryRequest.explain_options y se envía solo una vez con la última respuesta del flujo.

Permisos de autorización

Se necesita uno de los siguientes alcances de OAuth:

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

Para obtener más información, consulta Descripción general de la autenticación.

StructuredAggregationQuery

Consulta de Firestore para ejecutar una agregación en una StructuredQuery.

Representación 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. Es la serie de agregaciones que se aplicarán a los resultados de structuredQuery.

Requisitos:

  • Un mínimo de una y un máximo de cinco agregaciones por consulta.
Campo de unión query_type. La consulta base sobre la que se agregará. Las direcciones (query_type) solo pueden ser una de las siguientes opciones:
structuredQuery

object (StructuredQuery)

Consulta estructurada anidada.

Agregación

Define una agregación que produce un solo resultado.

Representación 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. Nombre opcional del campo en el que se almacenará el resultado de la agregación.

Si no se proporciona, Firestore elegirá un nombre predeterminado con el formato field_<incremental_id++>. Por ejemplo:

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

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

Requisitos:

  • Debe ser único en todos los alias de agregación.
  • Cumple con las limitaciones de document field name.
Campo de unión operator. El tipo de agregación que se realizará, obligatoria. Las direcciones (operator) solo pueden ser una de las siguientes opciones:
count

object (Count)

Agregador de recuento.
sum

object (Sum)

Agregador de suma.
avg

object (Avg)

Agregador promedio.

Recuento

Recuento de documentos que coinciden con la consulta.

La función de agregación COUNT(*) opera en todo el documento, por lo que no requiere una referencia de campo.

Representación JSON 
{
  "upTo": string
}
Campos
upTo

string (Int64Value format)

Opcional. Restricción opcional sobre la cantidad máxima de documentos que se deben contar.

Esto proporciona una forma de establecer un límite superior para la cantidad de documentos que se deben analizar, lo que limita la latencia y el costo.

Sin especificar se interpreta como sin límite.

Ejemplo de alto nivel:

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

Requisitos:

  • Debe ser mayor que cero cuando esté presente.

Sum

Suma de los valores del campo solicitado.

  • Solo se agregarán valores numéricos. Se omiten todos los valores no numéricos, incluido NULL.

  • Si los valores agregados contienen NaN, muestra NaN. Las matemáticas de Infinity siguen los estándares IEEE-754.

  • Si el conjunto de valores agregados está vacío, muestra 0.

  • Muestra un número entero de 64 bits si todos los números agregados son números enteros y el resultado de la suma no desborda. De lo contrario, el resultado se muestra como un doble. Ten en cuenta que, incluso si todos los valores agregados son números enteros, el resultado se muestra como un doble si no puede caber dentro de un número entero de 64 bits firmado. Cuando esto ocurre, el valor que se muestra perderá precisión.

  • Cuando se produce un subdesbordamiento, la agregación de punto flotante no es determinista. Esto significa que ejecutar la misma consulta repetidamente sin ningún cambio en los valores subyacentes podría producir resultados ligeramente diferentes cada vez. En esos casos, los valores se deben almacenar como números enteros sobre números de punto flotante.

Representación JSON 
{
  "field": {
    object (FieldReference)
  }
}
Campos
field

object (FieldReference)

El campo en el que se realiza la agregación.

Prom

Promedio de los valores del campo solicitado.

  • Solo se agregarán valores numéricos. Se omiten todos los valores no numéricos, incluido NULL.

  • Si los valores agregados contienen NaN, muestra NaN. Las matemáticas de Infinity siguen los estándares IEEE-754.

  • Si el conjunto de valores agregados está vacío, muestra NULL.

  • Siempre muestra el resultado como un doble.

Representación JSON 
{
  "field": {
    object (FieldReference)
  }
}
Campos
field

object (FieldReference)

El campo en el que se realiza la agregación.

AggregationResult

El resultado de un solo bucket a partir de una consulta de agregación de Firestore.

Las claves de aggregateFields son las mismas para todos los resultados de una consulta de agregación, a diferencia de las consultas de documentos que pueden tener diferentes campos presentes para cada resultado.

Representación JSON 
{
  "aggregateFields": {
    string: {
      object (Value)
    },
    ...
  }
}
Campos
aggregateFields

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

El resultado de las funciones de agregación, p. ej.: COUNT(*) AS total_docs.

La clave es el alias asignado a la función de agregación en la entrada, y el tamaño de este mapa es igual a la cantidad de funciones de agregación en la consulta.

Es un objeto que contiene una lista de pares "key": value. Ejemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.