Method: projects.databases.documents.runAggregationQuery

執行匯總查詢。

這個 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/v1beta1/{parent=projects/*/databases/*/documents}:runAggregationQuery

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
parent

string

必要欄位。父項資源名稱。格式為：projects/{projectId}/databases/{databaseId}/documents 或 projects/{projectId}/databases/{databaseId}/documents/{document_path}。例如 projects/my-project/databases/my-database/documents 或 projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

要求主體

要求主體的資料會採用以下結構：

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.
}
欄位
explainOptions

object (ExplainOptions)

選用設定。說明查詢的選項。如果有設定，系統就會傳回額外的查詢統計資料。否則，系統只會傳回查詢結果。
聯集欄位 query_type。要執行的查詢。query_type 只能是下列其中一項：
structuredAggregationQuery

object (StructuredAggregationQuery)

匯總查詢。
聯集欄位 consistency_selector。查詢的一致性模式預設為同步一致性。consistency_selector 只能是下列其中一項：
transaction

string (bytes format)

在既有交易中執行匯總作業。

這裡的值是執行查詢的不透明交易 ID。

Base64 編碼的字串。
newTransaction

object (TransactionOptions)

在查詢中開始新交易，預設為唯讀。

新的交易 ID 將傳回，做為串流中的第一個回應。
readTime

string (Timestamp format)

按照指定的時間戳記執行查詢。

這個值必須是過去 1 小時內的微秒精確度，如果已啟用「時間點復原」功能，則可以是過去 7 天內的整分鐘時間戳記。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

回應主體

Firestore.RunAggregationQuery 的回應。

如果成功，回應主體即會包含具有以下結構的資料：

JSON 表示法 
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string,
  "explainMetrics": {
    object (ExplainMetrics)
  }
}
欄位
result

object (AggregationResult)

單一匯總結果。

回報部分進度時不會顯示。
transaction

string (bytes format)

在這個要求中啟動的交易。

只有在要求展開新交易時，才會出現在第一個回應中。

Base64 編碼的字串。
readTime

string (Timestamp format)

計算匯總結果的時間。該數值一律會單調增加；在這種情況下，結果串流中先前的 AggregationResult 不保證在其 readTime 和此值之間不會有任何變化。

如果查詢未傳回任何結果，則會收到含有 readTime 和 result 的回應，且這代表查詢的執行時間。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
explainMetrics

object (ExplainMetrics)

查詢說明指標。只有在提供 RunAggregationQueryRequest.explain_options 時，才會出現此屬性，且在串流中只與串流中的最後一個回應一起傳送一次。

授權範圍

需要下列其中一種 OAuth 範圍：

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

詳情請參閱驗證總覽。

StructuredAggregationQuery

用於執行 StructuredQuery 匯總的 Firestore 查詢。

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.
}
欄位
aggregations[]

object (Aggregation)

選用設定。要套用至 structuredQuery 結果的一系列匯總。

需求：

  • 每個查詢最少一項或最多五個匯總。
聯集欄位 query_type。要匯總的基本查詢。query_type 只能是下列其中一項：
structuredQuery

object (StructuredQuery)

巢狀結構化查詢。

匯總

定義產生單一結果的匯總。

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.
}
欄位
alias

string

選用設定。選填的欄位名稱，用於儲存匯總結果。

如未提供，Firestore 會按照 field_<incremental_id++> 格式選擇預設名稱。例如：

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

會變成：

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

需求：
聯集欄位 operator。要執行的匯總類型 (必要)。operator 只能是下列其中一項：
count

object (Count)

計數集結網站。
sum

object (Sum)

加總資料集結網站。
avg

object (Avg)

平均集結網站。

數量

符合查詢的文件數量。

COUNT(*) 匯總函式適用於整份文件，因此不需要欄位參照。

JSON 表示法 
{
  "upTo": string
}
欄位
upTo

string (Int64Value format)

選用設定。視需要設定文件數量上限。

這個方式可用來設定要掃描的文件數上限，進而限制延遲時間和費用。

未指定為未繫結。

高階範例：

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

需求：

  • 使用時必須大於零。

總和

要求欄位值的總和。

  • 只會匯總數字值。系統會略過包括 NULL 在內的所有非數值。

  • 如果匯總值包含 NaN，就會傳回 NaN。Infinity 數學符合 IEEE-754 標準。

  • 如果匯總值為空白，就會傳回 0。

  • 如果所有匯總數字都是整數，且總和結果未溢位，會傳回 64 位元整數。否則，結果會以雙精度浮點值傳回。請注意，即使所有匯總值都是整數，如果結果超出 64 位元帶正負號整數，系統仍會將結果傳回為雙精度浮點值。發生這種情況時，傳回的值會失去精確度。

  • 發生反向溢位時，浮點匯總不具確定性，也就是說，重複執行相同的查詢時，如果基礎值沒有變更，每次產生的結果可能略有不同。在這種情況下，值應以整數形式儲存在浮點數上。

JSON 表示法 
{
  "field": {
    object (FieldReference)
  }
}
欄位
field

object (FieldReference)

要匯總依據的欄位。

Avg

所要求欄位值的平均值。

  • 只會匯總數字值。系統會略過包括 NULL 在內的所有非數值。

  • 如果匯總值包含 NaN，就會傳回 NaN。Infinity 數學符合 IEEE-754 標準。

  • 如果匯總值為空白，就會傳回 NULL。

  • 一律以雙精度浮點值傳回結果。

JSON 表示法 
{
  "field": {
    object (FieldReference)
  }
}
欄位
field

object (FieldReference)

要匯總依據的欄位。

AggregationResult

Firestore 匯總查詢中單一值區的結果。

匯總查詢中所有結果的 aggregateFields 金鑰都相同，這一點與在每份結果中可能會有不同欄位的文件查詢不同。

JSON 表示法 
{
  "aggregateFields": {
    string: {
      object (Value)
    },
    ...
  }
}
欄位
aggregateFields

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

匯總函式的結果，例如：COUNT(*) AS total_docs。

索引鍵是在輸入時指派給匯總函式的 alias，且這張地圖的大小等於查詢中的匯總函式數量。

這個物件中包含 "key": value 組合的清單，例如：{ "name": "wrench", "mass": "1.3kg", "count": "3" }.