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/v1beta1/{parent=projects/*/databases/*/documents}:runAggregationQuery
Die URL verwendet die Syntax der gRPC-Transcodierung.
Pfadparameter
Parameter | |
---|---|
parent |
Erforderlich. Der Name der übergeordneten Ressource. Im Format: |
Anfragetext
Der Anfragetext enthält Daten mit folgender Struktur:
JSON-Darstellung |
---|
{ "explainOptions": { object ( |
Felder | |
---|---|
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 |
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 |
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 |
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 |
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: |
Antworttext
Die Antwort für Firestore.RunAggregationQuery
.
Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:
JSON-Darstellung |
---|
{ "result": { object ( |
Felder | |
---|---|
result |
Ein einzelnes Aggregationsergebnis. Nicht vorhanden, wenn ein teilweiser Fortschritt gemeldet wird. |
transaction |
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 |
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 Wenn die Abfrage keine Ergebnisse zurückgibt, wird eine Antwort mit Ein Zeitstempel im Format RFC3339 UTC „Zulu“ mit Nanosekundenauflösung und bis zu neun Nachkommastellen. Beispiele: |
explainMetrics |
Messwerte zur Abfrage erklären. Es ist nur vorhanden, wenn |
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 ( |
Felder | |
---|---|
aggregations[] |
Optional. Reihe von Aggregationen, die auf die Ergebnisse von Benötigt:
|
Union-Feld query_type . Die zu aggregierende Basisabfrage. Für query_type ist nur einer der folgenden Werte zulässig: |
|
structuredQuery |
Verschachtelte strukturierte Abfrage. |
Aggregation
Definiert eine Aggregation, die ein einzelnes Ergebnis generiert.
JSON-Darstellung |
---|
{ "alias": string, // Union field |
Felder | |
---|---|
alias |
Optional. Optionaler Name des Felds, in dem das Ergebnis der Aggregation gespeichert werden soll. Wenn nicht angegeben, wählt Firestore einen Standardnamen im Format
wird zu:
Benötigt:
|
Union-Feld operator . Der durchzuführende Aggregationstyp (erforderlich). Für operator ist nur einer der folgenden Werte zulässig: |
|
count |
Anzahl-Aggregator. |
sum |
Summen-Aggregator. |
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 |
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:
Benötigt:
|
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, wirdNaN
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 ( |
Felder | |
---|---|
field |
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, wirdNaN
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 ( |
Felder | |
---|---|
field |
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 ( |
Felder | |
---|---|
aggregateFields |
Das Ergebnis der Aggregatfunktionen, z. B. Der Schlüssel ist die Ein Objekt, das eine Liste von |