Method: projects.databases.documents.runAggregationQuery

Esegue una query di aggregazione.

Anziché produrre risultati Document come Firestore.RunQuery, questa API consente di eseguire un'aggregazione per produrre una serie di AggregationResult lato server.

Esempio generale:

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

Richiesta HTTP

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

L'URL utilizza la sintassi di transcodifica gRPC.

Parametri del percorso

Parametri
parent

string

obbligatorio. Il nome della risorsa padre. Nel formato: projects/{projectId}/databases/{databaseId}/documents o projects/{projectId}/databases/{databaseId}/documents/{document_path}. Ad esempio: projects/my-project/databases/my-database/documents o projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione 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.
}
Campi
explainOptions

object (ExplainOptions)

Campo facoltativo. Spiega le opzioni della query. Se impostato, verranno restituite ulteriori statistiche sulle query. In caso contrario, verranno restituiti solo i risultati della query.
Campo di unione query_type. La query da eseguire. query_type può essere solo uno dei seguenti:
structuredAggregationQuery

object (StructuredAggregationQuery)

Una query di aggregazione.
Campo di unione consistency_selector. La modalità di coerenza per la query è impostata in modo predefinito su elevata coerenza. consistency_selector può essere solo uno dei seguenti:
transaction

string (bytes format)

Eseguire l'aggregazione in una transazione già attiva.

Il valore qui è l'ID transazione opaco in cui eseguire la query.

Una stringa con codifica Base64.
newTransaction

object (TransactionOptions)

Avvia una nuova transazione come parte della query. L'impostazione predefinita è di sola lettura.

Il nuovo ID transazione verrà restituito come prima risposta nel flusso.
readTime

string (Timestamp format)

Esegue la query al timestamp specificato.

Deve essere un timestamp con precisione in microsecondi risalente all'ultima ora oppure, se il recupero point-in-time è abilitato, può essere anche un timestamp di un minuto intero compreso negli ultimi 7 giorni.

Un timestamp in formato "Zulu" RFC3339 UTC, con risoluzione in nanosecondi e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

Corpo della risposta

La risposta per Firestore.RunAggregationQuery.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string,
  "explainMetrics": {
    object (ExplainMetrics)
  }
}
Campi
result

object (AggregationResult)

Un singolo risultato dell'aggregazione.

Non presente quando segnali l'avanzamento parziale.
transaction

string (bytes format)

La transazione avviata nell'ambito di questa richiesta.

Presente solo nella prima risposta quando la richiesta ha richiesto di avviare una nuova transazione.

Una stringa con codifica Base64.
readTime

string (Timestamp format)

L'ora in cui è stato calcolato il risultato aggregato. Questo valore aumenta sempre in modo monotonico; in questo caso, i valori di AggregationResult precedente nel flusso di risultati sono garantiti che non siano cambiati tra l'elemento readTime e questo.

Se la query non restituisce risultati, verrà inviata una risposta con readTime e nessun result, che rappresenta il momento in cui è stata eseguita la query.

Un timestamp in formato "Zulu" RFC3339 UTC, con risoluzione in nanosecondi e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
explainMetrics

object (ExplainMetrics)

La query spiega le metriche. È presente solo quando viene fornito il RunAggregationQueryRequest.explain_options e viene inviato solo una volta con l'ultima risposta nello stream.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta la Panoramica dell'autenticazione.

StructuredAggregationQuery

Query Firestore per eseguire un'aggregazione su un StructuredQuery.

Rappresentazione 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.
}
Campi
aggregations[]

object (Aggregation)

Campo facoltativo. Serie di aggregazioni da applicare ai risultati di structuredQuery.

Richiede:

  • Da un minimo di una a un massimo di cinque aggregazioni per query.
Campo di unione query_type. La query di base da aggregare. query_type può essere solo uno dei seguenti:
structuredQuery

object (StructuredQuery)

Query strutturata nidificata.

Aggregazione

Definisce un'aggregazione che produce un singolo risultato.

Rappresentazione 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.
}
Campi
alias

string

Campo facoltativo. Nome facoltativo del campo in cui archiviare il risultato dell'aggregazione.

Se non viene specificato, Firestore sceglierà un nome predefinito nel formato field_<incremental_id++>. Ad esempio:

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

diventa:

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

Richiede:

  • Deve essere univoco in tutti gli alias di aggregazione.
  • Rispetta le limitazioni di document field name.
Campo di unione operator. Il tipo di aggregazione da eseguire, obbligatorio. operator può essere solo uno dei seguenti:
count

object (Count)

Conteggio aggregatore.
sum

object (Sum)

Somma aggregatore.
avg

object (Avg)

Aggregatore medio.

Conteggio

Numero di documenti che corrispondono alla query.

La funzione di aggregazione COUNT(*) opera sull'intero documento, quindi non richiede un riferimento di campo.

Rappresentazione JSON 
{
  "upTo": string
}
Campi
upTo

string (Int64Value format)

Campo facoltativo. Vincolo facoltativo al numero massimo di documenti da conteggiare.

Ciò fornisce un modo per impostare un limite superiore per il numero di documenti da scansionare, limitando la latenza e il costo.

Un valore non specificato viene interpretato come nessun limite.

Esempio generale:

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

Richiede:

  • Deve essere maggiore di zero se presente.

Somma

Somma dei valori del campo richiesto.

  • Verranno aggregati solo valori numerici. Tutti i valori non numerici, incluso NULL, vengono ignorati.

  • Se i valori aggregati contengono NaN, restituisce NaN. I calcoli matematici Infinity seguono gli standard IEEE-754.

  • Se il set di valori aggregati è vuoto, restituisce 0.

  • Restituisce un numero intero a 64 bit se tutti i numeri aggregati sono numeri interi e il risultato della somma non ha un overflow. In caso contrario, il risultato viene restituito come doppio. Tieni presente che anche se tutti i valori aggregati sono numeri interi, il risultato viene restituito come doppio se non può rientrare in un valore Integer a 64 bit con segno. In questo caso, il valore restituito perderà precisione.

  • Quando si verifica un underflow, l'aggregazione in virgola mobile non è deterministica. Ciò significa che l'esecuzione della stessa query più volte senza modifiche ai valori sottostanti potrebbe produrre risultati leggermente diversi ogni volta. In questi casi, i valori devono essere archiviati come numeri interi anziché in virgola mobile.

Rappresentazione JSON 
{
  "field": {
    object (FieldReference)
  }
}
Campi
field

object (FieldReference)

Il campo in base al quale aggregare.

Med

Media dei valori del campo richiesto.

  • Verranno aggregati solo valori numerici. Tutti i valori non numerici, incluso NULL, vengono ignorati.

  • Se i valori aggregati contengono NaN, restituisce NaN. I calcoli matematici Infinity seguono gli standard IEEE-754.

  • Se il set di valori aggregati è vuoto, restituisce NULL.

  • Restituisce sempre il risultato come doppio.

Rappresentazione JSON 
{
  "field": {
    object (FieldReference)
  }
}
Campi
field

object (FieldReference)

Il campo in base al quale aggregare.

AggregationResult

Il risultato di un singolo bucket da una query di aggregazione Firestore.

Le chiavi di aggregateFields sono le stesse per tutti i risultati in una query di aggregazione, a differenza delle query sui documenti che possono avere campi diversi per ogni risultato.

Rappresentazione JSON 
{
  "aggregateFields": {
    string: {
      object (Value)
    },
    ...
  }
}
Campi
aggregateFields

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

Il risultato delle funzioni di aggregazione, ad esempio COUNT(*) AS total_docs.

La chiave è la chiave alias assegnata alla funzione di aggregazione al momento dell'input e le dimensioni di questa mappa corrispondono al numero di funzioni di aggregazione nella query.

Un oggetto contenente un elenco di "key": value coppie. Esempio: { "name": "wrench", "mass": "1.3kg", "count": "3" }.