Method: projects.databases.documents.runQuery

執行查詢。

HTTP 要求

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

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

路徑參數

參數
parent

string

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

要求主體

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

JSON 表示法
{
  "explainOptions": {
    object (ExplainOptions)
  },

  // 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:
  "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 只能是下列其中一項:
structuredQuery

object (StructuredQuery)

結構化查詢。

聯集欄位 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.RunQuery 的回應。

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

JSON 表示法
{
  "transaction": string,
  "document": {
    object (Document)
  },
  "readTime": string,
  "skippedResults": integer,
  "explainMetrics": {
    object (ExplainMetrics)
  },

  // Union field continuation_selector can be only one of the following:
  "done": boolean
  // End of list of possible types for union field continuation_selector.
}
欄位
transaction

string (bytes format)

在這個要求中啟動的交易。只能在第一個回應中設定,且要求中必須設有 RunQueryRequest.new_transaction。如果設定,就不會在這個回應中設定任何其他欄位。

Base64 編碼的字串。

document

object (Document)

查詢結果,回報部分進度時未設定。

readTime

string (Timestamp format)

讀取文件的時間。這可能單純增加;在這種情況下,結果串流中的舊文件在其 readTime 和此檔案之間不會進行變更。

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

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

skippedResults

integer

因上次回應與目前回應之間偏移而略過的結果數。

explainMetrics

object (ExplainMetrics)

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

聯集欄位 continuation_selector。查詢的接續模式。如有顯示,表示目前的查詢回應串流已完成。無論是否包含 document,都可以進行設定,但設定完畢後,系統就不會傳回其他結果。continuation_selector 只能採用下列其中一種設定:
done

boolean

如果存在,Firestore 就會完成要求,不會再傳回其他文件。

授權範圍

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

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

詳情請參閱驗證總覽