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 |
Obligatorio. El nombre del recurso superior. En el formato: |
Cuerpo de la solicitud
El cuerpo de la solicitud contiene datos con la siguiente estructura:
Representación JSON |
---|
{ "explainOptions": { object ( |
Campos | |
---|---|
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 |
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 |
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 |
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 |
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: |
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 ( |
Campos | |
---|---|
result |
Un solo resultado de agregación. No está presente cuando se informa un progreso parcial. |
transaction |
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 |
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 Si la consulta no muestra resultados, se enviará una respuesta con Una marca de tiempo en formato RFC3339 UTC “Zulú”, con resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: |
explainMetrics |
Métricas de explicación de consultas Esto solo está presente cuando se proporciona el |
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 ( |
Campos | |
---|---|
aggregations[] |
Opcional. Es la serie de agregaciones que se aplicarán a los resultados de Requisitos:
|
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 |
Consulta estructurada anidada. |
Agregación
Define una agregación que produce un solo resultado.
Representación JSON |
---|
{ "alias": string, // Union field |
Campos | |
---|---|
alias |
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
pasa a ser:
Requisitos:
|
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 |
Agregador de recuento. |
sum |
Agregador de suma. |
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 |
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:
Requisitos:
|
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
, muestraNaN
. 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 ( |
Campos | |
---|---|
field |
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
, muestraNaN
. 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 ( |
Campos | |
---|---|
field |
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 ( |
Campos | |
---|---|
aggregateFields |
El resultado de las funciones de agregación, p. ej.: La clave es el Es un objeto que contiene una lista de pares |