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
Request body
The request body contains data with the following structure:
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.}
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:
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.
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".
If successful, the response body contains data with the following structure:
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.}
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.
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.
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-26 UTC."],[[["\u003cp\u003eThis webpage documents how to run a query against Firestore databases using an HTTP POST request to a specific URL with required path parameters for the parent resource.\u003c/p\u003e\n"],["\u003cp\u003eThe request body can include \u003ccode\u003eexplainOptions\u003c/code\u003e for query statistics, the \u003ccode\u003equery_type\u003c/code\u003e which can be a \u003ccode\u003estructuredQuery\u003c/code\u003e, and the \u003ccode\u003econsistency_selector\u003c/code\u003e for managing the transaction's consistency mode.\u003c/p\u003e\n"],["\u003cp\u003eThe consistency mode for the transaction can be set to use an existing \u003ccode\u003etransaction\u003c/code\u003e, a \u003ccode\u003enewTransaction\u003c/code\u003e, or read documents at a specific \u003ccode\u003ereadTime\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eThe response body includes fields such as \u003ccode\u003etransaction\u003c/code\u003e, \u003ccode\u003edocument\u003c/code\u003e, \u003ccode\u003ereadTime\u003c/code\u003e, \u003ccode\u003eskippedResults\u003c/code\u003e, and \u003ccode\u003eexplainMetrics\u003c/code\u003e, with \u003ccode\u003edone\u003c/code\u003e signaling the end of the response stream.\u003c/p\u003e\n"],["\u003cp\u003eAuthorization for running queries requires either the \u003ccode\u003ehttps://www.googleapis.com/auth/datastore\u003c/code\u003e or \u003ccode\u003ehttps://www.googleapis.com/auth/cloud-platform\u003c/code\u003e OAuth scopes.\u003c/p\u003e\n"]]],[],null,["# Method: projects.databases.documents.runQuery\n\nRuns a query.\n\n### HTTP request\n\n`POST https://firestore.googleapis.com/v1beta1/{parent=projects/*/databases/*/documents}:runQuery`\n\nThe URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.\n\n### Path parameters\n\n### Request body\n\nThe request body contains data with the following structure:\n\n### Response body\n\nThe response for [Firestore.RunQuery](/firestore/docs/reference/rest/v1beta1/projects.databases.documents/runQuery#google.firestore.v1beta1.Firestore.RunQuery).\n\nIf successful, the response body contains data with the following structure:\n\n### Authorization scopes\n\nRequires one of the following OAuth scopes:\n\n- `https://www.googleapis.com/auth/datastore`\n- `https://www.googleapis.com/auth/cloud-platform`\n\nFor more information, see the [Authentication Overview](/docs/authentication#authorization-gcp)."]]
