Method: projects.databases.documents.runAggregationQuery

Führt eine Aggregationsabfrage aus.

Anstatt Document-Ergebnisse wie Firestore.RunQuery zu erzeugen, ermöglicht diese API das Ausführen einer Aggregation, um serverseitig eine Reihe von AggregationResult zu erzeugen.

Allgemeines Beispiel:

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

HTTP-Anfrage

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

Die URL verwendet die Syntax der gRPC-Transcodierung.

Pfadparameter

Parameter
parent

string

Erforderlich. Der Name der übergeordneten Ressource. Im Format: projects/{projectId}/databases/{databaseId}/documents oder projects/{projectId}/databases/{databaseId}/documents/{document_path}. Beispiel: projects/my-project/databases/my-database/documents oder projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

Anfragetext

Der Anfragetext enthält Daten mit folgender Struktur:

JSON-Darstellung 
{
  "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.
}
Felder
explainOptions

object (ExplainOptions)

Optional. Erläutern Sie Optionen für die Abfrage. Wenn festgelegt, werden zusätzliche Abfragestatistiken zurückgegeben. Andernfalls werden nur Abfrageergebnisse zurückgegeben.
Union-Feld query_type. Die auszuführende Abfrage. Für query_type ist nur einer der folgenden Werte zulässig:
structuredAggregationQuery

object (StructuredAggregationQuery)

Eine Aggregationsabfrage.
Union-Feld consistency_selector. Als Konsistenzmodus für die Abfrage wird standardmäßig „Strong Consistency“ verwendet. Für consistency_selector ist nur einer der folgenden Werte zulässig:
transaction

string (bytes format)

Führen Sie die Aggregation innerhalb einer bereits aktiven Transaktion aus.

Der Wert hier ist die intransparente Transaktions-ID, in der die Abfrage ausgeführt wird.

Ein base64-codierter String.
newTransaction

object (TransactionOptions)

Startet im Rahmen der Abfrage eine neue Transaktion und ist standardmäßig schreibgeschützt.

Die neue Transaktions-ID wird als erste Antwort im Stream zurückgegeben.
readTime

string (Timestamp format)

Führt die Abfrage zum angegebenen Zeitstempel aus.

Dabei muss es sich um einen Zeitstempel mit einer Genauigkeit von Mikrosekunden innerhalb der letzten Stunde handeln. Wenn die Wiederherstellung zu einem bestimmten Zeitpunkt aktiviert ist, kann zusätzlich ein Zeitstempel einer ganzen Minute innerhalb der letzten 7 Tage angegeben werden.

Ein Zeitstempel im Format RFC3339 UTC „Zulu“ mit Nanosekundenauflösung und bis zu neun Nachkommastellen. Beispiele: "2014-10-02T15:01:23Z" und "2014-10-02T15:01:23.045123456Z".

Antworttext

Die Antwort für Firestore.RunAggregationQuery.

Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:

JSON-Darstellung 
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string,
  "explainMetrics": {
    object (ExplainMetrics)
  }
}
Felder
result

object (AggregationResult)

Ein einzelnes Aggregationsergebnis.

Nicht vorhanden, wenn ein teilweiser Fortschritt gemeldet wird.
transaction

string (bytes format)

Die Transaktion, die im Rahmen dieser Anfrage gestartet wurde.

Ist nur in der ersten Antwort vorhanden, wenn die Anfrage den Start einer neuen Transaktion angefordert hat.

Ein base64-codierter String.
readTime

string (Timestamp format)

Der Zeitpunkt, zu dem das aggregierte Ergebnis berechnet wurde. Dieser Wert erhöht sich immer kontinuierlich. In diesem Fall hat sich das vorherige Aggregationsergebnis im Ergebnisstream garantiert zwischen readTime und diesem nicht geändert.

Wenn die Abfrage keine Ergebnisse zurückgibt, wird eine Antwort mit readTime und ohne result gesendet. Dies gibt den Zeitpunkt an, zu dem die Abfrage ausgeführt wurde.

Ein Zeitstempel im Format RFC3339 UTC „Zulu“ mit Nanosekundenauflösung und bis zu neun Nachkommastellen. Beispiele: "2014-10-02T15:01:23Z" und "2014-10-02T15:01:23.045123456Z".
explainMetrics

object (ExplainMetrics)

Messwerte zur Abfrage erklären. Es ist nur vorhanden, wenn RunAggregationQueryRequest.explain_options angegeben ist, und wird nur einmal mit der letzten Antwort im Stream gesendet.

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

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

Weitere Informationen finden Sie in der Authentifizierungsübersicht.

StructuredAggregationQuery

Firestore-Abfrage zum Ausführen einer Aggregation über einen StructuredQuery

JSON-Darstellung 
{
  "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.
}
Felder
aggregations[]

object (Aggregation)

Optional. Reihe von Aggregationen, die auf die Ergebnisse von structuredQuery angewendet werden sollen.

Benötigt:

  • Mindestens eine und maximal fünf Aggregationen pro Abfrage.
Union-Feld query_type. Die zu aggregierende Basisabfrage. Für query_type ist nur einer der folgenden Werte zulässig:
structuredQuery

object (StructuredQuery)

Verschachtelte strukturierte Abfrage.

Aggregation

Definiert eine Aggregation, die ein einzelnes Ergebnis generiert.

JSON-Darstellung 
{
  "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.
}
Felder
alias

string

Optional. Optionaler Name des Felds, in dem das Ergebnis der Aggregation gespeichert werden soll.

Wenn nicht angegeben, wählt Firestore einen Standardnamen im Format field_<incremental_id++> aus. Beispiel:

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

wird zu:

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

Benötigt:

  • Muss für alle Aggregationsaliasse eindeutig sein.
  • Die Einschränkungen von document field name einhalten.
Union-Feld operator. Der durchzuführende Aggregationstyp (erforderlich). Für operator ist nur einer der folgenden Werte zulässig:
count

object (Count)

Anzahl-Aggregator.
sum

object (Sum)

Summen-Aggregator.
avg

object (Avg)

Durchschnittlicher Aggregator.

Anzahl

Anzahl der Dokumente, die der Abfrage entsprechen.

Die Aggregatfunktion COUNT(*) gilt für das gesamte Dokument, daher ist kein Feldverweis erforderlich.

JSON-Darstellung 
{
  "upTo": string
}
Felder
upTo

string (Int64Value format)

Optional. Optionale Einschränkung der maximalen Anzahl von zu zählenden Dokumenten.

Dies bietet eine Möglichkeit, eine Obergrenze für die Anzahl der zu scannenden Dokumente festzulegen, um Latenz und Kosten zu begrenzen.

„Nicht angegeben“ wird als keine Grenze interpretiert.

Allgemeines Beispiel:

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

Benötigt:

  • Muss größer als null sein, sofern vorhanden.

Summe

Summe der Werte des angeforderten Felds.

  • Nur numerische Werte werden aggregiert. Alle nicht numerischen Werte, einschließlich NULL, werden übersprungen.

  • Wenn die aggregierten Werte NaN enthalten, wird NaN zurückgegeben. Die Unendlichkeitsberechnung entspricht den IEEE-754-Standards.

  • Wenn der aggregierte Wert leer ist, wird 0 zurückgegeben.

  • Gibt eine 64-Bit-Ganzzahl zurück, wenn alle aggregierten Zahlen Ganzzahlen sind und das Summenergebnis nicht überläuft. Andernfalls wird das Ergebnis als Double zurückgegeben. Auch wenn alle aggregierten Werte Ganzzahlen sind, wird das Ergebnis als Double zurückgegeben, wenn es nicht in eine vorzeichenbehaftete 64-Bit-Ganzzahl passt. In diesem Fall geht die Genauigkeit des zurückgegebenen Werts verloren.

  • Bei einem Unterlauf ist die Gleitkommaaggregation nicht deterministisch. Wenn also dieselbe Abfrage wiederholt ohne Änderungen an den zugrunde liegenden Werten ausgeführt wird, kann dies jedes Mal zu leicht unterschiedlichen Ergebnissen führen. In diesen Fällen sollten die Werte als Ganzzahlen anstelle von Gleitkommazahlen gespeichert werden.

JSON-Darstellung 
{
  "field": {
    object (FieldReference)
  }
}
Felder
field

object (FieldReference)

Das Feld, für das die Daten aggregiert werden sollen.

Durchschn.

Durchschnitt der Werte im angeforderten Feld.

  • Nur numerische Werte werden aggregiert. Alle nicht numerischen Werte, einschließlich NULL, werden übersprungen.

  • Wenn die aggregierten Werte NaN enthalten, wird NaN zurückgegeben. Die Unendlichkeitsberechnung entspricht den IEEE-754-Standards.

  • Wenn der aggregierte Wertesatz leer ist, wird NULL zurückgegeben.

  • Gibt das Ergebnis immer als Double zurück.

JSON-Darstellung 
{
  "field": {
    object (FieldReference)
  }
}
Felder
field

object (FieldReference)

Das Feld, für das die Daten aggregiert werden sollen.

AggregationResult

Das Ergebnis eines einzelnen Buckets aus einer Firestore-Aggregationsabfrage.

Im Gegensatz zu Dokumentabfragen, bei denen für jedes Ergebnis unterschiedliche Felder vorhanden sein können, sind die Schlüssel von aggregateFields für alle Ergebnisse einer Aggregationsabfrage gleich.

JSON-Darstellung 
{
  "aggregateFields": {
    string: {
      object (Value)
    },
    ...
  }
}
Felder
aggregateFields

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

Das Ergebnis der Aggregatfunktionen, z. B. COUNT(*) AS total_docs.

Der Schlüssel ist die alias, die der Aggregationsfunktion bei der Eingabe zugewiesen wird. Die Größe dieser Zuordnung entspricht der Anzahl der Aggregationsfunktionen in der Abfrage.

Ein Objekt, das eine Liste von "key": value-Paaren enthält. Beispiel: { "name": "wrench", "mass": "1.3kg", "count": "3" }.