Method: projects.databases.documents.runAggregationQuery

Exécute une requête d'agrégation.

Plutôt que de produire des résultats Document comme Firestore.RunQuery, cette API permet d'exécuter une agrégation pour produire une série de résultats AggregationResult côté serveur.

Exemple général:

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

Requête HTTP

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

L'URL utilise la syntaxe de transcodage gRPC.

Paramètres de chemin d'accès

Paramètres
parent

string

Obligatoire. Nom de la ressource parente. Format à respecter: projects/{projectId}/databases/{databaseId}/documents ou projects/{projectId}/databases/{databaseId}/documents/{document_path}. Par exemple: projects/my-project/databases/my-database/documents ou projects/my-project/databases/my-database/documents/chatrooms/my-chatroom.

Corps de la requête

Le corps de la requête contient des données présentant la structure suivante :

Représentation 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.
}
Champs
explainOptions

object (ExplainOptions)

Facultatif. Expliquez les options de la requête. Si cette option est définie, des statistiques de requête supplémentaires sont renvoyées. Si ce n'est pas le cas, seuls les résultats de la requête seront renvoyés.
Champ d'union query_type. Requête à exécuter. query_type ne peut être qu'un des éléments suivants :
structuredAggregationQuery

object (StructuredAggregationQuery)

Une requête d'agrégation.
Champ d'union consistency_selector. Par défaut, le mode de cohérence de la requête est une cohérence forte. consistency_selector ne peut être qu'un des éléments suivants :
transaction

string (bytes format)

Exécutez l'agrégation dans une transaction déjà active.

La valeur ici est l'ID de transaction opaque dans lequel exécuter la requête.

Chaîne encodée en base64.
newTransaction

object (TransactionOptions)

Démarre une nouvelle transaction dans le cadre de la requête, en lecture seule par défaut.

Le nouvel ID de transaction est renvoyé en tant que première réponse dans le flux.
readTime

string (Timestamp format)

Exécute la requête à l'horodatage donné.

Il doit s'agir d'un horodatage de précision de l'ordre de la microseconde au cours de la dernière heure. Si la récupération à un moment précis est activée, il peut également s'agir d'un horodatage d'une minute entière datant des sept derniers jours.

Code temporel au format RFC3339 UTC "Zulu", avec une résolution à la nanoseconde et jusqu'à neuf chiffres après la virgule. Exemples: "2014-10-02T15:01:23Z" et "2014-10-02T15:01:23.045123456Z".

Corps de la réponse

Réponse pour Firestore.RunAggregationQuery.

Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :

Représentation JSON 
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string,
  "explainMetrics": {
    object (ExplainMetrics)
  }
}
Champs
result

object (AggregationResult)

Résultat d'agrégation unique.

Indisponible lorsque vous signalez une progression partielle.
transaction

string (bytes format)

Transaction démarrée dans le cadre de cette requête.

Présent uniquement dans la première réponse lorsque la requête a demandé le lancement d'une nouvelle transaction.

Chaîne encodée en base64.
readTime

string (Timestamp format)

Heure à laquelle le résultat agrégé a été calculé. Ce nombre augmente toujours de manière monotone. Dans ce cas, il est garanti que l'élément AggregationResult précédent dans le flux de résultats n'a pas changé entre leur readTime et celui-ci.

Si la requête ne renvoie aucun résultat, une réponse contenant readTime et aucun result sera envoyée, ce qui représente l'heure à laquelle la requête a été exécutée.

Code temporel au format RFC3339 UTC "Zulu", avec une résolution à la nanoseconde et jusqu'à neuf chiffres après la virgule. Exemples: "2014-10-02T15:01:23Z" et "2014-10-02T15:01:23.045123456Z".
explainMetrics

object (ExplainMetrics)

Métriques d'explication des requêtes. Il n'est présent que lorsque le RunAggregationQueryRequest.explain_options est fourni. Il n'est envoyé qu'une seule fois avec la dernière réponse du flux.

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

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

Pour en savoir plus, consultez la page Présentation de l'authentification.

StructuredAggregationQuery

Requête Firestore permettant d'exécuter une agrégation sur un StructuredQuery.

Représentation 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.
}
Champs
aggregations[]

object (Aggregation)

Facultatif. Série d'agrégations à appliquer aux résultats de structuredQuery.

Configuration requise:

  • Un minimum d'une et un maximum de cinq agrégations par requête.
Champ d'union query_type. Requête de base sur laquelle effectuer l'agrégation. query_type ne peut être qu'un des éléments suivants :
structuredQuery

object (StructuredQuery)

Requête structurée imbriquée.

Agrégation

Définit une agrégation qui produit un seul résultat.

Représentation 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.
}
Champs
alias

string

Facultatif. Nom facultatif du champ dans lequel stocker le résultat de l'agrégation.

Si ce champ n'est pas fourni, Firestore choisit un nom par défaut au format field_<incremental_id++>. Exemple :

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

devient:

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

Configuration requise:

  • Doit être unique pour tous les alias d'agrégation.
  • Respecter les limites de document field name.
Champ d'union operator. Type d'agrégation à effectuer (obligatoire). operator ne peut être qu'un des éléments suivants :
count

object (Count)

Agrégateur de nombres.
sum

object (Sum)

Agrégateur de somme.
avg

object (Avg)

Agrégateur moyen.

Nombre

Nombre de documents correspondant à la requête.

La fonction d'agrégation COUNT(*) opère sur l'ensemble du document. Elle ne nécessite donc pas de référence de champ.

Représentation JSON 
{
  "upTo": string
}
Champs
upTo

string (Int64Value format)

Facultatif. Contrainte facultative sur le nombre maximal de documents à compter.

Vous pouvez ainsi limiter le nombre de documents à analyser, et limiter la latence et les coûts.

"Non spécifié" est interprété comme étant sans limite.

Exemple général:

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

Configuration requise:

  • La valeur doit être supérieure à zéro lorsqu'elle est présente.

pondérée

Somme des valeurs du champ demandé.

  • Seules les valeurs numériques seront agrégées. Toutes les valeurs non numériques, y compris NULL, sont ignorées.

  • Si les valeurs agrégées contiennent NaN, renvoie NaN. Les calculs de l'infinité sont conformes aux normes IEEE-754.

  • Si l'ensemble de valeurs agrégées est vide, renvoie 0.

  • Renvoie un entier de 64 bits si tous les nombres agrégés sont des entiers et que la somme ne déborde pas. Sinon, le résultat est renvoyé sous forme de double. Notez que même si toutes les valeurs agrégées sont des entiers, le résultat est renvoyé en tant que double s'il ne peut pas tenir dans un entier signé de 64 bits. Dans ce cas, la valeur renvoyée perd la précision.

  • En cas de dépassement de capacité négatif, l'agrégation à virgule flottante est non déterministe. Cela signifie que l'exécution répétée d'une même requête sans modifier les valeurs sous-jacentes peut produire des résultats légèrement différents à chaque fois. Dans ce cas, les valeurs doivent être stockées sous forme d'entiers et de nombres à virgule flottante.

Représentation JSON 
{
  "field": {
    object (FieldReference)
  }
}
Champs
field

object (FieldReference)

Champ à utiliser pour l'agrégation.

Moy

Moyenne des valeurs du champ demandé.

  • Seules les valeurs numériques seront agrégées. Toutes les valeurs non numériques, y compris NULL, sont ignorées.

  • Si les valeurs agrégées contiennent NaN, renvoie NaN. Les calculs de l'infinité sont conformes aux normes IEEE-754.

  • Si l'ensemble de valeurs agrégées est vide, renvoie NULL.

  • Renvoie toujours le résultat sous la forme d'un double.

Représentation JSON 
{
  "field": {
    object (FieldReference)
  }
}
Champs
field

object (FieldReference)

Champ à utiliser pour l'agrégation.

AggregationResult

Résultat d'un seul bucket à partir d'une requête d'agrégation Firestore.

Les clés de aggregateFields sont les mêmes pour tous les résultats d'une requête d'agrégation, contrairement aux requêtes de document, qui peuvent comporter des champs différents pour chaque résultat.

Représentation JSON 
{
  "aggregateFields": {
    string: {
      object (Value)
    },
    ...
  }
}
Champs
aggregateFields

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

Résultat des fonctions d'agrégation, par exemple: COUNT(*) AS total_docs.

La clé est la alias attribuée à la fonction d'agrégation en entrée. La taille de ce mappage est égale au nombre de fonctions d'agrégation dans la requête.

Objet contenant une liste de paires "key": value. Exemple : { "name": "wrench", "mass": "1.3kg", "count": "3" }.