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. Tiene 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. Explicar las opciones de la consulta. Si se establece, se mostrarán estadísticas adicionales de las consultas. De lo contrario, solo se devolverán los resultados de la consulta.
Campo de unión query_type. La consulta que se ejecutará. query_type puede ser solo uno de los siguientes:
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. consistency_selector puede ser solo uno de los siguientes:
transaction

string (bytes format)

Ejecutar 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 nueva transacción como parte de la consulta y cambia la configuración predeterminada a 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 especificada.

Debe ser una marca de tiempo con precisión de microsegundos dentro de la última hora o, si se habilitó 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 una 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 contiene 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 el progreso parcial.
transaction

string (bytes format)

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

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

String codificada en base64.
readTime

string (Timestamp format)

El momento en que se calculó el resultado agregado. Esto siempre aumenta monótonamente; En este caso, se garantiza que el AggregationResult anterior en la transmisión 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 a la que se ejecutó la consulta.

Una marca de tiempo en formato RFC3339 UTC “Zulú”, con una 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 de la transmisión.

Alcances de autorización

Se necesita uno de los siguientes permisos 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 un 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. 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 va a agregar. query_type puede ser solo uno de los siguientes:
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. Es el nombre opcional del campo en el que se almacenará el resultado de la agregación.

Si no se proporciona, Firestore elegirá un nombre predeterminado según 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 (
  ...
);

se convierte en lo siguiente:

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á (obligatorio). operator puede ser solo uno de los siguientes:
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 en la cantidad de documentos que se analizarán, lo que limita la latencia y el costo.

Si no se especifica, 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.

Suma

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. La matemática de Infinity cumple con 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 se desborda. De lo contrario, el resultado se muestra como un doble. Ten en cuenta que, aunque todos los valores agregados sean números enteros, el resultado se muestra como un doble si no cabe dentro de un número entero firmado de 64 bits. Cuando esto ocurre, el valor devuelto perderá precisión.

  • Cuando se produce un subdesbordamiento, la agregación de punto flotante no es determinista. Esto significa que ejecutar la misma consulta varias veces sin ningún cambio en los valores subyacentes podría producir resultados ligeramente diferentes cada vez. En esos casos, los valores deben almacenarse 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 realizará 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. La matemática de Infinity cumple con 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 realizará la agregación.

AggregationResult (Resultado de agregación)

El resultado de un solo bucket 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.

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