Console
    Contact Us Start free

    Method: projects.databases.documents.runQuery

    Runs a query.

    HTTP request

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

    The URL uses gRPC Transcoding syntax.

    Path 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

    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 
. 
 }
    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 for Firestore.RunQuery .

    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 
. 
 }
    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 the Authentication Overview .
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: