Method: projects.databases.documents.partitionQuery

Partitions a query by returning partition cursors that can be used to run the query in parallel. The returned partition cursors are split points that can be used by documents.runQuery as starting/end points for the query results.

HTTP request

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

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
parent

string

Required. The parent resource name. In the format: projects/{projectId}/databases/{databaseId}/documents. Document resource names are not supported; only database resource names can be specified.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "partitionCount": string,
  "pageToken": string,
  "pageSize": integer,

  // 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:
  "readTime": string
  // End of list of possible types for union field consistency_selector.
}
Fields
partitionCount

string (int64 format)

The desired maximum number of partition points. The partitions may be returned across multiple pages of results. The number must be positive. The actual number of partitions returned may be fewer.

For example, this may be set to one fewer than the number of parallel queries to be run, or in running a data pipeline job, one fewer than the number of workers or compute instances available.
pageToken

string

The nextPageToken value returned from a previous call to documents.partitionQuery that may be used to get an additional set of results. There are no ordering guarantees between sets of results. Thus, using multiple sets of results will require merging the different result sets.

For example, two subsequent calls using a pageToken may return:

  • cursor B, cursor M, cursor Q
  • cursor A, cursor U, cursor W

To obtain a complete result set ordered with respect to the results of the query supplied to documents.partitionQuery, the results sets should be merged: cursor A, cursor B, cursor M, cursor Q, cursor U, cursor W
pageSize

integer

The maximum number of partitions to return in this call, subject to partitionCount.

For example, if partitionCount = 10 and pageSize = 8, the first call to documents.partitionQuery will return up to 8 partitions and a nextPageToken if more results exist. A second call to documents.partitionQuery will return up to 2 partitions, to complete the total of 10 specified in partitionCount.
Union field query_type. The query to partition. query_type can be only one of the following:
structuredQuery

object (StructuredQuery)

A structured query. Query must specify collection with all descendants and be ordered by name ascending. Other filters, order bys, limits, offsets, and start/end cursors are not supported.
Union field consistency_selector. The consistency mode for this request. If not set, defaults to strong consistency. consistency_selector can be only one of the following:
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.PartitionQuery.

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

JSON representation 
{
  "partitions": [
    {
      object (Cursor)
    }
  ],
  "nextPageToken": string
}
Fields
partitions[]

object (Cursor)

Partition results. Each partition is a split point that can be used by documents.runQuery as a starting or end point for the query results. The documents.runQuery requests must be made with the same query supplied to this documents.partitionQuery request. The partition cursors will be ordered according to same ordering as the results of the query supplied to documents.partitionQuery.

For example, if a documents.partitionQuery request returns partition cursors A and B, running the following three queries will return the entire result set of the original query:

  • query, endAt A
  • query, startAt A, endAt B
  • query, startAt B

An empty result may indicate that the query has too few results to be partitioned, or that the query is not yet supported for partitioning.
nextPageToken

string

A page token that may be used to request an additional set of results, up to the number specified by partitionCount in the documents.partitionQuery request. If blank, there are no more results.

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.