Method: projects.databases.documents.partitionQuery

傳回可平行執行查詢的分區遊標，將查詢分區。傳回的分區遊標是分割點，可供 document.runQuery 使用為查詢結果的起點/終點。

HTTP 要求

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

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

路徑參數

參數
parent

string

執行個體類型，父項資源名稱。請採用下列格式：projects/{projectId}/databases/{databaseId}/documents。不支援文件資源名稱；只能指定資料庫資源名稱。

要求主體

要求主體包含下列結構的資料：

JSON 表示法 
{
  "partitionCount": string,
  "pageToken": string,
  "pageSize": integer,

  // 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.

  // Union field consistency_selector can be only one of the following:
  "readTime": string
  // End of list of possible types for union field consistency_selector.
}
欄位
partitionCount

string (int64 format)

所需的分區點數量上限。多個結果頁面可能會傳回分區。數字必須是正數。實際傳回的分區數量可能較少。

舉例來說，設定可以設為只執行平行查詢數量的一個，或是執行資料管道工作中的數量少於可用的工作站或運算執行個體數量。
pageToken

string

先前呼叫 document.partitionQuery 的 nextPageToken 值，可用於取得另一組結果。結果組合之間沒有排序保證。因此，使用多組結果時，就需要合併不同的結果集。

舉例來說，使用 pageToken 的後續兩次呼叫可能會傳回：

  • 遊標 B、遊標 M、遊標 Q
  • 遊標 A，遊標 U，遊標 W

如要依提供給 document.partitionQuery 的查詢結果取得完整的結果集，結果集必須合併：遊標 A、遊標 B、遊標 M、遊標 Q、遊標 U、遊標 W。
pageSize

integer

此呼叫中要傳回的分區數量上限，以 partitionCount 為準。

舉例來說，如果 partitionCount = 10 且 pageSize = 8，第一次呼叫 document.partitionQuery 會傳回最多 8 個分區，如果還有更多結果，則傳回 nextPageToken。第二次呼叫 document.partitionQuery 最多會傳回 2 個分區，以完成 partitionCount 中指定的 10 個分區。
聯集欄位 query_type。要分區的查詢。query_type 只能採用下列其中一種設定：
structuredQuery

object (StructuredQuery)

結構化查詢。查詢必須指定所有子系的集合，並依照名稱遞增排序。不支援其他篩選器、排序依據、限制、偏移和開始/結束遊標。
聯集欄位 consistency_selector。這項要求的一致性模式。如果未設定，則會預設為同步一致性。consistency_selector 只能採用下列其中一種設定：
readTime

string (Timestamp format)

讀取特定時間的文件。

這個時間戳記須為過去 1 小時內的微秒精確度，或者如果已啟用時間點復原，也可以是過去 7 天內的整分鐘時間戳記。

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

回應主體

Firestore.PartitionQuery 的回應。

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

JSON 表示法 
{
  "partitions": [
    {
      object (Cursor)
    }
  ],
  "nextPageToken": string
}
欄位
partitions[]

object (Cursor)

分區結果。每個分區都是分割點，可供 document.runQuery 用來做為查詢結果的起點或終點。必須透過提供給這個 document.partitionQuery 要求的相同查詢，提出 document.runQuery 要求。分區遊標的順序與針對文件.partitionQuery 的查詢結果順序相同。

例如，如果 document.partitionQuery 要求傳回分區遊標 A 和 B，則執行以下三個查詢將會傳回原始查詢的完整結果集：

  • 查詢結尾
  • 查詢, startAt A、endAt B
  • 查詢, startAt B

空白結果可能表示該查詢沒有可分區的結果，或是查詢尚未支援分區。
nextPageToken

string

網頁權杖，可用於要求其他一組結果，上限為 document.partitionQuery 要求中的 partitionCount 指定數。如果留空，表示沒有其他結果。

授權範圍

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

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

詳情請參閱驗證總覽一文。