Method: projects.databases.documents.batchGet

Gets multiple documents.

Documents returned by this method are not guaranteed to be returned in the same order that they were requested.

HTTP request

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

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
database

string

The database name. In the format: projects/{project_id}/databases/{database_id}.

Request body

The request body contains data with the following structure:

JSON representation
{
  "documents": [
    string
  ],
  "mask": {
    object(DocumentMask)
  },

  // 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
documents[]

string

The names of the documents to retrieve. In the format: projects/{project_id}/databases/{database_id}/documents/{document_path}. The request will fail if any of the document is not a child resource of the given database. Duplicate names will be elided.

mask

object(DocumentMask)

The fields to return. If not set, returns all fields.

If a document has a field that is not present in this mask, that field will not be returned in the response.

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)

Reads documents in a transaction.

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 may not be older than 60 seconds.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

Response body

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

The streamed response for Firestore.BatchGetDocuments.

JSON representation
{
  "transaction": string,
  "readTime": string,

  // Union field result can be only one of the following:
  "found": {
    object(Document)
  },
  "missing": string
  // End of list of possible types for union field result.
}
Fields
transaction

string (bytes format)

The transaction that was started as part of this request. Will only be set in the first response, and only if BatchGetDocumentsRequest.new_transaction was set in the request.

A base64-encoded string.

readTime

string (Timestamp format)

The time at which the document was read. This may be monotically increasing, in this case the previous documents in the result stream are guaranteed not to have changed between their readTime and this one.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

Union field result. A single result. This can be empty if the server is just returning a transaction. result can be only one of the following:
found

object(Document)

A document that was requested.

missing

string

A document name that was requested but does not exist. In the format: projects/{project_id}/databases/{database_id}/documents/{document_path}.

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.

Try it!

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Firestore