執行匯總查詢。
這個 API 不會產生 Firestore.RunQuery
之類的 Document
結果,而是允許執行匯總作業,在伺服器端產生一系列 AggregationResult
。
高階範例:
-- Return the number of documents in table given a filter.
SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );
HTTP 要求
POST https://firestore.googleapis.com/v1/{parent=projects/*/databases/*/documents}:runAggregationQuery
這個網址使用 gRPC 轉碼語法。
路徑參數
參數 | |
---|---|
parent |
必要欄位。父項資源名稱。格式為: |
要求主體
要求主體的資料會採用以下結構:
JSON 表示法 |
---|
{ "explainOptions": { object ( |
欄位 | |
---|---|
explainOptions |
選用設定。說明查詢的選項。如果有設定,系統就會傳回額外的查詢統計資料。否則,系統只會傳回查詢結果。 |
聯集欄位 query_type 。要執行的查詢。query_type 只能是下列其中一項: |
|
structuredAggregationQuery |
匯總查詢。 |
聯集欄位 consistency_selector 。查詢的一致性模式預設為同步一致性。consistency_selector 只能是下列其中一項: |
|
transaction |
在既有交易中執行匯總作業。 這裡的值是執行查詢的不透明交易 ID。 Base64 編碼的字串。 |
newTransaction |
在查詢中開始新交易,預設為唯讀。 新的交易 ID 將傳回,做為串流中的第一個回應。 |
readTime |
按照指定的時間戳記執行查詢。 這個值必須是過去 1 小時內的微秒精確度,如果已啟用「時間點復原」功能,則可以是過去 7 天內的整分鐘時間戳記。 採用 RFC3339 世界標準時間「Zulu」格式的時間戳記,採用奈秒解析度和最多九個小數位數。範例: |
回應主體
Firestore.RunAggregationQuery
的回應。
如果成功,回應主體即會包含具有以下結構的資料:
JSON 表示法 |
---|
{ "result": { object ( |
欄位 | |
---|---|
result |
單一匯總結果。 回報部分進度時不會顯示。 |
transaction |
在這個要求中啟動的交易。 只有在要求展開新交易時,才會出現在第一個回應中。 Base64 編碼的字串。 |
readTime |
計算匯總結果的時間。該數值一律會單調增加;在這種情況下,結果串流中先前的 AggregationResult 不保證在其 如果查詢未傳回任何結果,則會收到含有 採用 RFC3339 世界標準時間「Zulu」格式的時間戳記,採用奈秒解析度和最多九個小數位數。範例: |
explainMetrics |
查詢說明指標。只有在提供 |
授權範圍
需要下列其中一種 OAuth 範圍:
https://www.googleapis.com/auth/datastore
https://www.googleapis.com/auth/cloud-platform
詳情請參閱驗證總覽。
StructuredAggregationQuery
用於執行 StructuredQuery
匯總的 Firestore 查詢。
JSON 表示法 |
---|
{ "aggregations": [ { object ( |
欄位 | |
---|---|
aggregations[] |
選用設定。要套用至 需求:
|
聯集欄位 query_type 。要匯總的基本查詢。query_type 只能是下列其中一項: |
|
structuredQuery |
巢狀結構化查詢。 |
匯總
定義產生單一結果的匯總。
JSON 表示法 |
---|
{ "alias": string, // Union field |
欄位 | |
---|---|
alias |
選用設定。選填的欄位名稱,用於儲存匯總結果。 如未提供,Firestore 會按照
會變成:
需求:
|
聯集欄位 operator 。要執行的匯總類型 (必要)。operator 只能是下列其中一項: |
|
count |
計數集結網站。 |
sum |
加總資料集結網站。 |
avg |
平均集結網站。 |
數量
符合查詢的文件數量。
COUNT(*)
匯總函式適用於整份文件,因此不需要欄位參照。
JSON 表示法 |
---|
{ "upTo": string } |
欄位 | |
---|---|
upTo |
選用設定。視需要設定文件數量上限。 這個方式可用來設定要掃描的文件數上限,進而限制延遲時間和費用。 未指定為未繫結。 高階範例:
需求:
|
總和
要求欄位值的總和。
只會匯總數字值。系統會略過包括
NULL
在內的所有非數值。如果匯總值包含
NaN
,就會傳回NaN
。Infinity 數學符合 IEEE-754 標準。如果匯總值為空白,就會傳回 0。
如果所有匯總數字都是整數,且總和結果未溢位,會傳回 64 位元整數。否則,結果會以雙精度浮點值傳回。請注意,即使所有匯總值都是整數,如果結果超出 64 位元帶正負號整數,系統仍會將結果傳回為雙精度浮點值。發生這種情況時,傳回的值會失去精確度。
發生反向溢位時,浮點匯總不具確定性,也就是說,重複執行相同的查詢時,如果基礎值沒有變更,每次產生的結果可能略有不同。在這種情況下,值應以整數形式儲存在浮點數上。
JSON 表示法 |
---|
{
"field": {
object ( |
欄位 | |
---|---|
field |
要匯總依據的欄位。 |
Avg
所要求欄位值的平均值。
只會匯總數字值。系統會略過包括
NULL
在內的所有非數值。如果匯總值包含
NaN
,就會傳回NaN
。Infinity 數學符合 IEEE-754 標準。如果匯總值為空白,就會傳回
NULL
。一律以雙精度浮點值傳回結果。
JSON 表示法 |
---|
{
"field": {
object ( |
欄位 | |
---|---|
field |
要匯總依據的欄位。 |
AggregationResult
Firestore 匯總查詢中單一值區的結果。
匯總查詢中所有結果的 aggregateFields
金鑰都相同,這一點與在每份結果中可能會有不同欄位的文件查詢不同。
JSON 表示法 |
---|
{
"aggregateFields": {
string: {
object ( |
欄位 | |
---|---|
aggregateFields |
匯總函式的結果,例如: 索引鍵是在輸入時指派給匯總函式的 這個物件中包含 |