Method: projects.databases.documents.runAggregationQuery

Ejecuta una consulta de agregación.

En lugar de producir resultados Document como Firestore.RunQuery , esta API permite ejecutar una agregación para producir una serie de AggregationResult en el lado 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/v1/{parent=projects/*/databases/*/documents}:runAggregationQuery

La URL utiliza la sintaxis de transcodificación gRPC .

Parámetros de ruta

Parámetros
parent

string

Requerido. El nombre del recurso principal. 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
{

  // 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ón query_type . La consulta a ejecutar. query_type puede ser solo uno de los siguientes:
structuredAggregationQuery

object ( StructuredAggregationQuery )

Una consulta de agregación.

consistency_selector del campo de unión. El modo de coherencia para la consulta tiene por defecto una coherencia fuerte. consistency_selector puede ser sólo uno de los siguientes:
transaction

string ( bytes format)

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

El valor aquí es el ID de transacción opaco para ejecutar la consulta.

Una cadena codificada en base64.

newTransaction

object ( TransactionOptions )

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

El nuevo ID de transacción se devolverá como primera respuesta en la secuencia.

readTime

string ( Timestamp format)

Ejecuta la consulta en la marca de tiempo dada.

Debe ser una marca de tiempo con precisión de microsegundos dentro de la última hora o, si la recuperación de un punto en el tiempo está habilitada, 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 "Zulu", 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 respuesta

La respuesta para Firestore.RunAggregationQuery .

Si tiene éxito, el cuerpo de la respuesta contiene datos con la siguiente estructura:

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

object ( AggregationResult )

Un único resultado de agregación.

No presente al informar el progreso parcial.

transaction

string ( bytes format)

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

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

Una cadena codificada en base64.

readTime

string ( Timestamp format)

La hora a la que se calculó el resultado agregado. Esto siempre aumenta monótonamente; en este caso, se garantiza que el AggregationResult anterior en la secuencia de resultados no habrá cambiado entre su readTime y este.

Si la consulta no arroja resultados, se enviará una respuesta con readTime y sin result , y esto representa el momento en que se ejecutó la consulta.

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

Ámbitos de autorización

Requiere uno de los siguientes ámbitos de OAuth:

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

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

Consulta de agregación estructurada

Consulta de Firestore para ejecutar una agregación a través de 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 a aplicar sobre los resultados de la structuredQuery .

Requiere:

  • Un mínimo de una y un máximo de cinco agregaciones por consulta.
Campo de unión query_type . La consulta base para 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 único 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 almacenar el resultado de la agregación.

Si no se proporciona, Firestore elegirá un nombre predeterminado siguiendo 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:

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

Requiere:

  • Debe ser único en todos los alias de agregación.
  • Cumplir con las limitaciones document field name .
operator de campo sindical. El tipo de agregación a realizar, requerido. operator sólo puede ser uno de los siguientes:
count

object ( Count )

Agregador de conteo.

sum

object ( Sum )

Agregador de sumas.

avg

object ( Avg )

Agregador promedio.

Contar

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 el número máximo de documentos a contar.

Esto proporciona una manera de establecer un límite superior en la cantidad de documentos a escanear, limitando la latencia y el costo.

No especificado se interpreta como sin límite.

Ejemplo de alto nivel:

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

Requiere:

  • Debe ser mayor que cero cuando esté presente.

Suma

Suma de los valores del campo solicitado.

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

  • Si los valores agregados contienen NaN , devuelve NaN . Infinity Math sigue los estándares IEEE-754.

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

  • Devuelve un entero de 64 bits si todos los números agregados son enteros y el resultado de la suma no se desborda. De lo contrario, el resultado se devuelve como doble. Tenga en cuenta que incluso si todos los valores agregados son números enteros, el resultado se devuelve como doble si no cabe dentro de un entero de 64 bits con signo. Cuando esto ocurre, el valor devuelto perderá precisión.

  • Cuando se produce un desbordamiento insuficiente, 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 deben almacenarse como números enteros sobre números de punto flotante.

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

object ( FieldReference )

El campo para agregar.

promedio

Promedio de los valores del campo solicitado.

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

  • Si los valores agregados contienen NaN , devuelve NaN . Infinity Math sigue los estándares IEEE-754.

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

  • Siempre devuelve el resultado como doble.

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

object ( FieldReference )

El campo para agregar.

Resultado de agregación

El resultado de un único depósito 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, por ejemplo: 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 al número 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" } .