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」格式的時間戳記，解析度以奈秒為單位，小數點後最多 9 位。範例："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」格式的時間戳記，解析度以奈秒為單位，小數點後最多 9 位。範例："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 );

需求條件：

  • 存在時必須大於零。

Sum

所要求欄位值的總和。

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

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

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

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

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

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

object (FieldReference)

要匯總的欄位。

平均

所要求欄位值的平均值。

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

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

  • 如果設定的匯總值空白，則會傳回 NULL。

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

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

object (FieldReference)

要匯總的欄位。

匯總結果

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" }。