Method: projects.databases.documents.runQuery

Runs a query.

HTTP request

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

Path parameters

Parameters

Parameters
`parent`	`string` Required. The parent resource name. In the format:`projects/{projectId}/databases/{databaseId}/documents` or`projects/{projectId}/databases/{databaseId}/documents/{document_path}`. For example:`projects/my-project/databases/my-database/documents` or`projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`

parent

string

Required. The parent resource name. In the format:projects/{projectId}/databases/{databaseId}/documents orprojects/{projectId}/databases/{databaseId}/documents/{document_path}. For example:projects/my-project/databases/my-database/documents orprojects/my-project/databases/my-database/documents/chatrooms/my-chatroom

Request body

The request body contains data with the following structure:

JSON representation

JSON representation
{"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)},// Union fieldquery_type can be only one of the following:"structuredQuery":{object (StructuredQuery)}// End of list of possible types for union fieldquery_type.// Union fieldconsistency_selector can be only one of the following:"transaction":string,"newTransaction":{object (TransactionOptions)},"readTime":string// End of list of possible types for union fieldconsistency_selector.}

Fields
`explainOptions`	`object (ExplainOptions)` Optional. Explain options for the query. If set, additional query statistics will be returned. If not, only query results will be returned.
Union field`query_type`. The query to run.`query_type` can be only one of the following:
`structuredQuery`	`object (StructuredQuery)` A structured query.
Union field`consistency_selector`. The consistency mode for this transaction. If not set, defaults to strong consistency.`consistency_selector` can be only one of the following:
`transaction`	`string (bytes format)` Run the query within an already active transaction. The value here is the opaque transaction ID to execute the query in. A base64-encoded string.
`newTransaction`	`object (TransactionOptions)` Starts a new transaction and reads the documents. Defaults to a read-only transaction. The new transaction ID will be returned as the first response in the stream.
`readTime`	`string (Timestamp format)` Reads documents as they were at the given time. This must be a microsecond precision timestamp within the past one hour, or if Point-in-Time Recovery is enabled, can additionally be a whole minute timestamp within the past 7 days. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples:`"2014-10-02T15:01:23Z"`,`"2014-10-02T15:01:23.045123456Z"` or`"2014-10-02T15:01:23+05:30"`.

Response body

The response forFirestore.RunQuery.

If successful, the response body contains data with the following structure:

JSON representation

JSON representation
{"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,"document":{object (Document)},"readTime":string,"skippedResults":integer,"explainMetrics":{object (ExplainMetrics)},// Union fieldcontinuation_selector can be only one of the following:"done":boolean// End of list of possible types for union fieldcontinuation_selector.}

Fields
`transaction`	`string (bytes format)` The transaction that was started as part of this request. Can only be set in the first response, and only if`RunQueryRequest.new_transaction` was set in the request. If set, no other fields will be set in this response. A base64-encoded string.
`document`	`object (Document)` A query result, not set when reporting partial progress.
`readTime`	`string (Timestamp format)` The time at which the document was read. This may be monotonically increasing; in this case, the previous documents in the result stream are guaranteed not to have changed between their`readTime` and this one. If the query returns no results, a response with`readTime` and no`document` will be sent, and this represents the time at which the query was run. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples:`"2014-10-02T15:01:23Z"`,`"2014-10-02T15:01:23.045123456Z"` or`"2014-10-02T15:01:23+05:30"`.
`skippedResults`	`integer` The number of results that have been skipped due to an offset between the last response and the current response.
`explainMetrics`	`object (ExplainMetrics)` Query explain metrics. This is only present when the`RunQueryRequest.explain_options` is provided, and it is sent only once with the last response in the stream.
Union field`continuation_selector`. The continuation mode for the query. If present, it indicates the current query response stream has finished. This can be set with or without a`document` present, but when set, no more results are returned.`continuation_selector` can be only one of the following:
`done`	`boolean` If present, Firestore has completely finished the request and no more documents will be returned.

Authorization scopes

Requires one of the following OAuth scopes:

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

For more information, see theOAuth 2.0 Overview.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-08-26 UTC.

Movatterモバイル変換