PartitionQueryRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/google-cloud-firestore/json-schema/google-cloud-firestore-partition-query-request-schema.json",
  "title": "PartitionQueryRequest",
  "description": "The request for Firestore.PartitionQuery.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/google-cloud-firestore-projects-api-openapi.yml#/components/schemas/PartitionQueryRequest",
  "properties": {
    "requestOptions": {
      "$ref": "#/$defs/RequestOptions",
      "description": "Optional. The request options for the request."
    },
    "structuredQuery": {
      "$ref": "#/$defs/StructuredQuery",
      "description": "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."
    },
    "partitionCount": {
      "type": "string",
      "format": "int64",
      "description": "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."
    },
    "pageSize": {
      "type": "integer",
      "format": "int32",
      "description": "The maximum number of partitions to return in this call, subject to `partition_count`. For example, if `partition_count` = 10 and `page_size` = 8, the first call to PartitionQuery will return up to 8 partitions and a `next_page_token` if more results exist. A second call to PartitionQuery will return up to 2 partitions, to complete the total of 10 specified in `partition_count`."
    },
    "readTime": {
      "description": "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.",
      "format": "google-datetime",
      "type": "string"
    },
    "pageToken": {
      "description": "The `next_page_token` value returned from a previous call to 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 page_token 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 PartitionQuery, the results sets should be merged: cursor A, cursor B, cursor M, cursor Q, cursor U, cursor W",
      "type": "string"
    }
  },
  "type": "object",
  "$defs": {
    "ArrayValue": {
      "type": "object",
      "description": "An array value.",
      "properties": {
        "values": {
          "items": {
            "$ref": "#/$defs/Value"
          },
          "type": "array",
          "description": "Values in the array."
        }
      }
    },
    "CollectionSelector": {
      "description": "A selection of a collection, such as `messages as m1`.",
      "type": "object",
      "properties": {
        "collectionId": {
          "description": "The collection ID. When set, selects only collections with this ID.",
          "type": "string"
        },
        "allDescendants": {
          "description": "When false, selects only collections that are immediate children of the `parent` specified in the containing `RunQueryRequest`. When true, selects all descendant collections.",
          "type": "boolean"
        }
      }
    },
    "CompositeFilter": {
      "type": "object",
      "description": "A filter that merges multiple other filters using the given operator.",
      "properties": {
        "op": {
          "type": "string",
          "enum": [
            "OPERATOR_UNSPECIFIED",
            "AND",
            "OR"
          ],
          "description": "The operator for combining multiple filters."
        },
        "filters": {
          "description": "The list of filters to combine. Requires: * At least one filter is present.",
          "items": {
            "$ref": "#/$defs/Filter"
          },
          "type": "array"
        }
      }
    },
    "Cursor": {
      "type": "object",
      "properties": {
        "values": {
          "description": "The values that represent a position, in the order they appear in the order by clause of a query. Can contain fewer values than specified in the order by clause.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/Value"
          }
        },
        "before": {
          "type": "boolean",
          "description": "If the position is just before or just after the given values, relative to the sort order defined by the query."
        }
      },
      "description": "A position in a query result set."
    },
    "FieldFilter": {
      "description": "A filter on a specific field.",
      "properties": {
        "op": {
          "description": "The operator to filter by.",
          "type": "string",
          "enum": [
            "OPERATOR_UNSPECIFIED",
            "LESS_THAN",
            "LESS_THAN_OR_EQUAL",
            "GREATER_THAN",
            "GREATER_THAN_OR_EQUAL",
            "EQUAL",
            "NOT_EQUAL",
            "ARRAY_CONTAINS",
            "IN",
            "ARRAY_CONTAINS_ANY",
            "NOT_IN"
          ]
        },
        "field": {
          "$ref": "#/$defs/FieldReference",
          "description": "The field to filter by."
        },
        "value": {
          "$ref": "#/$defs/Value",
          "description": "The value to compare to."
        }
      },
      "type": "object"
    },
    "FieldReference": {
      "type": "object",
      "description": "A reference to a field in a document, ex: `stats.operations`.",
      "properties": {
        "fieldPath": {
          "type": "string",
          "description": "A reference to a field in a document. Requires: * MUST be a dot-delimited (`.`) string of segments, where each segment conforms to document field name limitations."
        }
      }
    },
    "Filter": {
      "properties": {
        "fieldFilter": {
          "$ref": "#/$defs/FieldFilter",
          "description": "A filter on a document field."
        },
        "unaryFilter": {
          "$ref": "#/$defs/UnaryFilter",
          "description": "A filter that takes exactly one argument."
        },
        "compositeFilter": {
          "$ref": "#/$defs/CompositeFilter",
          "description": "A composite filter."
        }
      },
      "description": "A filter.",
      "type": "object"
    },
    "FindNearest": {
      "description": "Nearest Neighbors search config. The ordering provided by FindNearest supersedes the order_by stage. If multiple documents have the same vector distance, the returned document order is not guaranteed to be stable between queries.",
      "type": "object",
      "properties": {
        "vectorField": {
          "$ref": "#/$defs/FieldReference",
          "description": "Required. An indexed vector field to search upon. Only documents which contain vectors whose dimensionality match the query_vector can be returned."
        },
        "queryVector": {
          "$ref": "#/$defs/Value",
          "description": "Required. The query vector that we are searching on. Must be a vector of no more than 2048 dimensions."
        },
        "limit": {
          "format": "int32",
          "description": "Required. The number of nearest neighbors to return. Must be a positive integer of no more than 1000.",
          "type": "integer"
        },
        "distanceMeasure": {
          "type": "string",
          "enum": [
            "DISTANCE_MEASURE_UNSPECIFIED",
            "EUCLIDEAN",
            "COSINE",
            "DOT_PRODUCT"
          ],
          "description": "Required. The distance measure to use, required."
        },
        "distanceThreshold": {
          "description": "Optional. Option to specify a threshold for which no less similar documents will be returned. The behavior of the specified `distance_measure` will affect the meaning of the distance threshold. Since DOT_PRODUCT distances increase when the vectors are more similar, the comparison is inverted. * For EUCLIDEAN, COSINE: `WHERE distance <= distance_threshold` * For DOT_PRODUCT: `WHERE distance >= distance_threshold`",
          "type": "number",
          "format": "double"
        },
        "distanceResultField": {
          "description": "Optional. Optional name of the field to output the result of the vector distance calculation. Must conform to document field name limitations.",
          "type": "string"
        }
      }
    },
    "Function": {
      "description": "Represents an unevaluated scalar expression. For example, the expression `like(user_name, \"%alice%\")` is represented as: ``` name: \"like\" args { field_reference: \"user_name\" } args { string_value: \"%alice%\" } ```",
      "type": "object",
      "properties": {
        "args": {
          "description": "Optional. Ordered list of arguments the given function expects.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/Value"
          }
        },
        "options": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/Value"
          },
          "description": "Optional. Optional named arguments that certain functions may support."
        },
        "name": {
          "type": "string",
          "description": "Required. The name of the function to evaluate. **Requires:** * must be in snake case (lower case with underscore separator)."
        }
      }
    },
    "LatLng": {
      "description": "An object that represents a latitude/longitude pair. This is expressed as a pair of doubles to represent degrees latitude and degrees longitude. Unless specified otherwise, this object must conform to the WGS84 standard. Values must be within normalized ranges.",
      "type": "object",
      "properties": {
        "latitude": {
          "description": "The latitude in degrees. It must be in the range [-90.0, +90.0].",
          "type": "number",
          "format": "double"
        },
        "longitude": {
          "format": "double",
          "type": "number",
          "description": "The longitude in degrees. It must be in the range [-180.0, +180.0]."
        }
      }
    },
    "MapValue": {
      "description": "A map value.",
      "type": "object",
      "properties": {
        "fields": {
          "description": "The map's fields. The map keys represent field names. Field names matching the regular expression `__.*__` are reserved. Reserved field names are forbidden except in certain documented contexts. The map keys, represented as UTF-8, must not exceed 1,500 bytes and cannot be empty.",
          "additionalProperties": {
            "$ref": "#/$defs/Value"
          },
          "type": "object"
        }
      }
    },
    "Order": {
      "type": "object",
      "description": "An order on a field.",
      "properties": {
        "direction": {
          "type": "string",
          "enum": [
            "DIRECTION_UNSPECIFIED",
            "ASCENDING",
            "DESCENDING"
          ],
          "description": "The direction to order by. Defaults to `ASCENDING`."
        },
        "field": {
          "$ref": "#/$defs/FieldReference",
          "description": "The field to order by."
        }
      }
    },
    "Pipeline": {
      "description": "A Firestore query represented as an ordered list of operations / stages.",
      "properties": {
        "stages": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Stage"
          },
          "description": "Required. Ordered list of stages to evaluate."
        }
      },
      "type": "object"
    },
    "Projection": {
      "type": "object",
      "description": "The projection of document's fields to return.",
      "properties": {
        "fields": {
          "description": "The fields to return. If empty, all fields are returned. To only return the name of the document, use `['__name__']`.",
          "items": {
            "$ref": "#/$defs/FieldReference"
          },
          "type": "array"
        }
      }
    },
    "RequestOptions": {
      "description": "Options for a request.",
      "type": "object",
      "properties": {
        "requestTags": {
          "description": "Optional. The request tags for the request. Request tags are user-provided strings used for usage monitoring, cost management, and observability. Callers can associate custom application context (such as component, microservice, feature name, or operation type) with database requests. These tags are collected and aggregated in usage and monitoring reports, allowing billable operations and usage metrics to be sliced and analyzed by tag. These tags *only* show up in monitoring and are visible in administrative operations (such as usage reports). They do not affect data storage, query semantics, or request execution. Cardinality and Best Practices: - Request tags are most effective when using a bounded set of distinct values (e.g., fewer than 100 distinct tags across an entire database). Using a large number of distinct tags may result in tags being omitted from top usage dashboards. - Use structured identifiers (for example: `app=cart`, `env=prod`, `service=checkout`) and avoid high-cardinality values such as UUIDs, request IDs, timestamps, user IDs, or document keys. - Do not include sensitive data or personally identifiable information (PII) in request tags, as they show up in administrative monitoring. The tags are processed as follows: - Leading and trailing whitespace is trimmed. - Empty tags (after trimming) are filtered out. - Truncated to a maximum of 510 characters. - Deduplicated within the same request. - Limited to a maximum of 50 tags per request (excess tags are silently discarded).",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "Stage": {
      "description": "A single operation within a pipeline. A stage is made up of a unique name, and a list of arguments. The exact number of arguments & types is dependent on the stage type. To give an example, the stage `filter(state = \"MD\")` would be encoded as: ``` name: \"filter\" args { function_value { name: \"eq\" args { field_reference_value: \"state\" } args { string_value: \"MD\" } } } ``` See public documentation for the full list.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Required. The name of the stage to evaluate. **Requires:** * must be in snake case (lower case with underscore separator)."
        },
        "options": {
          "description": "Optional. Optional named arguments that certain functions may support.",
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/Value"
          }
        },
        "args": {
          "description": "Optional. Ordered list of arguments the given stage expects.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/Value"
          }
        }
      },
      "type": "object"
    },
    "StructuredQuery": {
      "properties": {
        "startAt": {
          "$ref": "#/$defs/Cursor",
          "description": "A potential prefix of a position in the result set to start the query at. The ordering of the result set is based on the `ORDER BY` clause of the original query. ``` SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC; ``` This query's results are ordered by `(b ASC, __name__ ASC)`. Cursors can reference either the full ordering or a prefix of the location, though it cannot reference more fields than what are in the provided `ORDER BY`. Continuing off the example above, attaching the following start cursors will have varying impact: - `START BEFORE (2, /k/123)`: start the query right before `a = 1 AND b > 2 AND __name__ > /k/123`. - `START AFTER (10)`: start the query right after `a = 1 AND b > 10`. Unlike `OFFSET` which requires scanning over the first N results to skip, a start cursor allows the query to begin at a logical position. This position is not required to match an actual result, it will scan forward from this position to find the next document. Requires: * The number of values cannot be greater than the number of fields specified in the `ORDER BY` clause."
        },
        "findNearest": {
          "$ref": "#/$defs/FindNearest",
          "description": "Optional. A potential nearest neighbors search. Applies after all other filters and ordering. Finds the closest vector embeddings to the given query vector."
        },
        "where": {
          "$ref": "#/$defs/Filter",
          "description": "The filter to apply."
        },
        "orderBy": {
          "type": "array",
          "description": "The order to apply to the query results. Callers can provide a full ordering, a partial ordering, or no ordering at all. While Firestore will always respect the provided order, the behavior for queries without a full ordering is different per database edition: In Standard edition, Firestore guarantees a stable ordering through the following rules: * The `order_by` is required to reference all fields used with an inequality filter. * All fields that are required to be in the `order_by` but are not already present are appended in lexicographical ordering of the field name. * If an order on `__name__` is not specified, it is appended by default. Fields are appended with the same sort direction as the last order specified, or 'ASCENDING' if no order was specified. For example: * `ORDER BY a` becomes `ORDER BY a ASC, __name__ ASC` * `ORDER BY a DESC` becomes `ORDER BY a DESC, __name__ DESC` * `WHERE a > 1` becomes `WHERE a > 1 ORDER BY a ASC, __name__ ASC` * `WHERE __name__ > ... AND a > 1` becomes `WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC` In Enterprise edition, Firestore does not guarantee a stable ordering. Instead it will pick the most efficient ordering based on the indexes available at the time of query execution. This will result in a different ordering for queries that are otherwise identical. To ensure a stable ordering, always include a unique field in the `order_by` clause, such as `__name__`.",
          "items": {
            "$ref": "#/$defs/Order"
          }
        },
        "offset": {
          "description": "The number of documents to skip before returning the first result. This applies after the constraints specified by the `WHERE`, `START AT`, & `END AT` but before the `LIMIT` clause. Requires: * The value must be greater than or equal to zero if specified.",
          "format": "int32",
          "type": "integer"
        },
        "limit": {
          "type": "integer",
          "description": "The maximum number of results to return. Applies after all other constraints. Requires: * The value must be greater than or equal to zero if specified.",
          "format": "int32"
        },
        "from": {
          "description": "The collections to query.",
          "items": {
            "$ref": "#/$defs/CollectionSelector"
          },
          "type": "array"
        },
        "select": {
          "$ref": "#/$defs/Projection",
          "description": "Optional sub-set of the fields to return. This acts as a DocumentMask over the documents returned from a query. When not set, assumes that the caller wants all fields returned."
        },
        "endAt": {
          "$ref": "#/$defs/Cursor",
          "description": "A potential prefix of a position in the result set to end the query at. This is similar to `START_AT` but with it controlling the end position rather than the start position. Requires: * The number of values cannot be greater than the number of fields specified in the `ORDER BY` clause."
        }
      },
      "type": "object",
      "description": "A Firestore query. The query stages are executed in the following order: 1. from 2. where 3. select 4. order_by + start_at + end_at 5. offset 6. limit 7. find_nearest"
    },
    "UnaryFilter": {
      "description": "A filter with a single operand.",
      "type": "object",
      "properties": {
        "op": {
          "description": "The unary operator to apply.",
          "type": "string",
          "enum": [
            "OPERATOR_UNSPECIFIED",
            "IS_NAN",
            "IS_NULL",
            "IS_NOT_NAN",
            "IS_NOT_NULL"
          ]
        },
        "field": {
          "$ref": "#/$defs/FieldReference",
          "description": "The field to which to apply the operator."
        }
      }
    },
    "Value": {
      "description": "A message that can hold any of the supported value types.",
      "properties": {
        "booleanValue": {
          "description": "A boolean value.",
          "type": "boolean"
        },
        "stringValue": {
          "type": "string",
          "description": "A string value. In Standard edition databases: * The string, represented as UTF-8, must not exceed 1 MiB - 89 bytes. * Only the first 1,500 bytes of the UTF-8 representation are considered by queries. In Enterprise edition databases, there is no limit on the size of the value. However, it is still subject to document and index entry size limits."
        },
        "mapValue": {
          "$ref": "#/$defs/MapValue",
          "description": "A map value."
        },
        "bytesValue": {
          "description": "A bytes value. In Standard edition databases: * The value must not exceed 1 MiB - 89 bytes. * Only the first 1,500 bytes are considered by queries. In Enterprise edition databases, there is no limit on the size of the value. However, it is still subject to document and index entry size limits.",
          "format": "byte",
          "type": "string"
        },
        "geoPointValue": {
          "$ref": "#/$defs/LatLng",
          "description": "A geo point value representing a point on the surface of Earth."
        },
        "nullValue": {
          "type": "string",
          "enum": [
            "NULL_VALUE"
          ],
          "description": "A null value."
        },
        "pipelineValue": {
          "$ref": "#/$defs/Pipeline",
          "description": "A value that represents an unevaluated pipeline. **Requires:** * Not allowed to be used when writing documents."
        },
        "referenceValue": {
          "description": "A reference to a document. For example: `projects/{project_id}/databases/{database_id}/documents/{document_path}`.",
          "type": "string"
        },
        "functionValue": {
          "$ref": "#/$defs/Function",
          "description": "A value that represents an unevaluated expression. **Requires:** * Not allowed to be used when writing documents."
        },
        "fieldReferenceValue": {
          "description": "Value which references a field. This is considered relative (vs absolute) since it only refers to a field and not a field within a particular document. **Requires:** * Must follow field reference limitations. * Not allowed to be used when writing documents.",
          "type": "string"
        },
        "arrayValue": {
          "$ref": "#/$defs/ArrayValue",
          "description": "An array value. In Standard edition databases, an array value cannot directly contain another array value, though it can contain a map which contains another array. In Enterprise edition databases, an array value can contain another array value."
        },
        "doubleValue": {
          "format": "double",
          "type": "number",
          "description": "A double value."
        },
        "timestampValue": {
          "description": "A timestamp value. Precise only to microseconds. When stored, any additional precision is rounded down.",
          "type": "string",
          "format": "google-datetime"
        },
        "integerValue": {
          "type": "string",
          "format": "int64",
          "description": "An integer value."
        },
        "variableReferenceValue": {
          "type": "string",
          "description": "Pointer to a variable defined elsewhere in a pipeline. Unlike `field_reference_value` which references a field within a document, this refers to a variable, defined in a separate namespace than the fields of a document."
        }
      },
      "type": "object"
    }
  }
}