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)

按指定时间读取文档。

此时间戳必须是过去一小时内的微秒级精确时间戳;如果启用了时间点恢复,也可以是过去 7 天内的整分钟时间戳。

采用 RFC3339 世界协调时间 (UTC)(即“祖鲁时”)格式的时间戳,采用纳秒级精度,最多包含九个小数位。示例:"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 和当前文档之间不会发生变化。

如果查询未返回任何结果,则不会发送包含 readTime 但不包含 document 的响应,这表示查询的运行时间。

采用 RFC3339 世界协调时间 (UTC)(即“祖鲁时”)格式的时间戳,采用纳秒级精度,最多包含九个小数位。示例:"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

如需了解详情,请参阅身份验证概览