PartialResultSet

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/google-cloud-spanner/json-schema/google-cloud-spanner-partial-result-set-schema.json",
  "title": "PartialResultSet",
  "description": "Partial results from a streaming read or SQL query. Streaming reads and SQL queries better tolerate large result sets, large rows, and large values, but are a little trickier to consume.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/google-cloud-spanner-projects-api-openapi.yml#/components/schemas/PartialResultSet",
  "properties": {
    "precommitToken": {
      "$ref": "#/$defs/MultiplexedSessionPrecommitToken",
      "description": "Optional. A precommit token is included if the read-write transaction has multiplexed sessions enabled. Pass the precommit token with the highest sequence number from this transaction attempt to the Commit request for this transaction."
    },
    "metadata": {
      "$ref": "#/$defs/ResultSetMetadata",
      "description": "Metadata about the result set, such as row type information. Only present in the first response."
    },
    "stats": {
      "$ref": "#/$defs/ResultSetStats",
      "description": "Query plan and execution statistics for the statement that produced this streaming result set. These can be requested by setting ExecuteSqlRequest.query_mode and are sent only once with the last response in the stream. This field is also present in the last response for DML statements."
    },
    "resumeToken": {
      "type": "string",
      "format": "byte",
      "description": "Streaming calls might be interrupted for a variety of reasons, such as TCP connection loss. If this occurs, the stream of results can be resumed by re-sending the original request and including `resume_token`. Note that executing any other transaction in the same session invalidates the token."
    },
    "last": {
      "type": "boolean",
      "description": "Optional. Indicates whether this is the last `PartialResultSet` in the stream. The server might optionally set this field. Clients shouldn't rely on this field being set in all cases."
    },
    "chunkedValue": {
      "description": "If true, then the final value in values is chunked, and must be combined with more values from subsequent `PartialResultSet`s to obtain a complete field value.",
      "type": "boolean"
    },
    "values": {
      "items": {},
      "type": "array",
      "description": "A streamed result set consists of a stream of values, which might be split into many `PartialResultSet` messages to accommodate large rows and/or large values. Every N complete values defines a row, where N is equal to the number of entries in metadata.row_type.fields. Most values are encoded based on type as described here. It's possible that the last value in values is \"chunked\", meaning that the rest of the value is sent in subsequent `PartialResultSet`(s). This is denoted by the chunked_value field. Two or more chunked values can be merged to form a complete value as follows: * `bool/number/null`: can't be chunked * `string`: concatenate the strings * `list`: concatenate the lists. If the last element in a list is a `string`, `list`, or `object`, merge it with the first element in the next list by applying these rules recursively. * `object`: concatenate the (field name, field value) pairs. If a field name is duplicated, then apply these rules recursively to merge the field values. Some examples of merging: Strings are concatenated. \"foo\", \"bar\" => \"foobar\" Lists of non-strings are concatenated. [2, 3], [4] => [2, 3, 4] Lists are concatenated, but the last and first elements are merged because they are strings. [\"a\", \"b\"], [\"c\", \"d\"] => [\"a\", \"bc\", \"d\"] Lists are concatenated, but the last and first elements are merged because they are lists. Recursively, the last and first elements of the inner lists are merged because they are strings. [\"a\", [\"b\", \"c\"]], [[\"d\"], \"e\"] => [\"a\", [\"b\", \"cd\"], \"e\"] Non-overlapping object fields are combined. {\"a\": \"1\"}, {\"b\": \"2\"} => {\"a\": \"1\", \"b\": 2\"} Overlapping object fields are merged. {\"a\": \"1\"}, {\"a\": \"2\"} => {\"a\": \"12\"} Examples of merging objects containing lists of strings. {\"a\": [\"1\"]}, {\"a\": [\"2\"]} => {\"a\": [\"12\"]} For a more complete example, suppose a streaming SQL query is yielding a result set whose rows contain a single string field. The following `PartialResultSet`s might be yielded: { \"metadata\": { ... } \"values\": [\"Hello\", \"W\"] \"chunked_value\": true \"resume_token\": \"Af65...\" } { \"values\": [\"orl\"] \"chunked_value\": true } { \"values\": [\"d\"] \"resume_token\": \"Zx1B...\" } This sequence of `PartialResultSet`s encodes two rows, one containing the field value `\"Hello\"`, and a second containing the field value `\"World\" = \"W\" + \"orl\" + \"d\"`. Not all `PartialResultSet`s contain a `resume_token`. Execution can only be resumed from a previously yielded `resume_token`. For the above sequence of `PartialResultSet`s, resuming the query with `\"resume_token\": \"Af65...\"` yields results from the `PartialResultSet` with value \"orl\"."
    }
  },
  "type": "object",
  "$defs": {
    "ChildLink": {
      "properties": {
        "childIndex": {
          "format": "int32",
          "description": "The node to which the link points.",
          "type": "integer"
        },
        "type": {
          "type": "string",
          "description": "The type of the link. For example, in Hash Joins this could be used to distinguish between the build child and the probe child, or in the case of the child being an output variable, to represent the tag associated with the output variable."
        },
        "variable": {
          "type": "string",
          "description": "Only present if the child node is SCALAR and corresponds to an output variable of the parent node. The field carries the name of the output variable. For example, a `TableScan` operator that reads rows from a table will have child links to the `SCALAR` nodes representing the output variables created for each column that is read by the operator. The corresponding `variable` fields will be set to the variable names assigned to the columns."
        }
      },
      "description": "Metadata associated with a parent-child relationship appearing in a PlanNode.",
      "type": "object"
    },
    "Field": {
      "type": "object",
      "properties": {
        "name": {
          "description": "The name of the field. For reads, this is the column name. For SQL queries, it is the column alias (e.g., `\"Word\"` in the query `\"SELECT 'hello' AS Word\"`), or the column name (e.g., `\"ColName\"` in the query `\"SELECT ColName FROM Table\"`). Some columns might have an empty name (e.g., `\"SELECT UPPER(ColName)\"`). Note that a query result can contain multiple fields with the same name.",
          "type": "string"
        },
        "type": {
          "$ref": "#/$defs/Type",
          "description": "The type of the field."
        }
      },
      "description": "Message representing a single field of a struct."
    },
    "IndexAdvice": {
      "type": "object",
      "description": "Recommendation to add new indexes to run queries more efficiently.",
      "properties": {
        "ddl": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "description": "Optional. DDL statements to add new indexes that will improve the query."
        },
        "improvementFactor": {
          "type": "number",
          "description": "Optional. Estimated latency improvement factor. For example if the query currently takes 500 ms to run and the estimated latency with new indexes is 100 ms this field will be 5.",
          "format": "double"
        }
      }
    },
    "MultiplexedSessionPrecommitToken": {
      "description": "When a read-write transaction is executed on a multiplexed session, this precommit token is sent back to the client as a part of the Transaction message in the BeginTransaction response and also as a part of the ResultSet and PartialResultSet responses.",
      "type": "object",
      "properties": {
        "precommitToken": {
          "type": "string",
          "format": "byte",
          "description": "Opaque precommit token."
        },
        "seqNum": {
          "type": "integer",
          "description": "An incrementing seq number is generated on every precommit token that is returned. Clients should remember the precommit token with the highest sequence number from the current transaction attempt.",
          "format": "int32"
        }
      }
    },
    "PlanNode": {
      "properties": {
        "metadata": {
          "type": "object",
          "additionalProperties": {
            "description": "Properties of the object."
          },
          "description": "Attributes relevant to the node contained in a group of key-value pairs. For example, a Parameter Reference node could have the following information in its metadata: { \"parameter_reference\": \"param1\", \"parameter_type\": \"array\" }"
        },
        "kind": {
          "type": "string",
          "description": "Used to determine the type of node. May be needed for visualizing different kinds of nodes differently. For example, If the node is a SCALAR node, it will have a condensed representation which can be used to directly embed a description of the node in its parent.",
          "enum": [
            "KIND_UNSPECIFIED",
            "RELATIONAL",
            "SCALAR"
          ]
        },
        "shortRepresentation": {
          "$ref": "#/$defs/ShortRepresentation",
          "description": "Condensed representation for SCALAR nodes."
        },
        "displayName": {
          "description": "The display name for the node.",
          "type": "string"
        },
        "executionStats": {
          "additionalProperties": {
            "description": "Properties of the object."
          },
          "description": "The execution statistics associated with the node, contained in a group of key-value pairs. Only present if the plan was returned as a result of a profile query. For example, number of executions, number of rows/time per execution etc.",
          "type": "object"
        },
        "index": {
          "description": "The `PlanNode`'s index in node list.",
          "type": "integer",
          "format": "int32"
        },
        "childLinks": {
          "items": {
            "$ref": "#/$defs/ChildLink"
          },
          "type": "array",
          "description": "List of child node `index`es and their relationship to this parent."
        }
      },
      "description": "Node information for nodes appearing in a QueryPlan.plan_nodes.",
      "type": "object"
    },
    "QueryAdvisorResult": {
      "type": "object",
      "properties": {
        "indexAdvice": {
          "items": {
            "$ref": "#/$defs/IndexAdvice"
          },
          "description": "Optional. Index Recommendation for a query. This is an optional field and the recommendation will only be available when the recommendation guarantees significant improvement in query performance.",
          "type": "array"
        }
      },
      "description": "Output of query advisor analysis."
    },
    "QueryPlan": {
      "description": "Contains an ordered list of nodes appearing in the query plan.",
      "properties": {
        "queryAdvice": {
          "$ref": "#/$defs/QueryAdvisorResult",
          "description": "Optional. The advise/recommendations for a query. Currently this field will be serving index recommendations for a query."
        },
        "planNodes": {
          "description": "The nodes in the query plan. Plan nodes are returned in pre-order starting with the plan root. Each PlanNode's `id` corresponds to its index in `plan_nodes`.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/PlanNode"
          }
        }
      },
      "type": "object"
    },
    "ResultSetMetadata": {
      "description": "Metadata about a ResultSet or PartialResultSet.",
      "type": "object",
      "properties": {
        "undeclaredParameters": {
          "$ref": "#/$defs/StructType",
          "description": "A SQL query can be parameterized. In PLAN mode, these parameters can be undeclared. This indicates the field names and types for those undeclared parameters in the SQL query. For example, a SQL query like `\"SELECT * FROM Users where UserId = @userId and UserName = @userName \"` could return a `undeclared_parameters` value like: \"fields\": [ { \"name\": \"UserId\", \"type\": { \"code\": \"INT64\" } }, { \"name\": \"UserName\", \"type\": { \"code\": \"STRING\" } }, ]"
        },
        "rowType": {
          "$ref": "#/$defs/StructType",
          "description": "Indicates the field names and types for the rows in the result set. For example, a SQL query like `\"SELECT UserId, UserName FROM Users\"` could return a `row_type` value like: \"fields\": [ { \"name\": \"UserId\", \"type\": { \"code\": \"INT64\" } }, { \"name\": \"UserName\", \"type\": { \"code\": \"STRING\" } }, ]"
        },
        "transaction": {
          "$ref": "#/$defs/Transaction",
          "description": "If the read or SQL query began a transaction as a side-effect, the information about the new transaction is yielded here."
        }
      }
    },
    "ResultSetStats": {
      "description": "Additional statistics about a ResultSet or PartialResultSet.",
      "type": "object",
      "properties": {
        "queryPlan": {
          "$ref": "#/$defs/QueryPlan",
          "description": "QueryPlan for the query associated with this result."
        },
        "rowCountLowerBound": {
          "type": "string",
          "description": "Partitioned DML doesn't offer exactly-once semantics, so it returns a lower bound of the rows modified.",
          "format": "int64"
        },
        "queryStats": {
          "type": "object",
          "description": "Aggregated statistics from the execution of the query. Only present when the query is profiled. For example, a query could return the statistics as follows: { \"rows_returned\": \"3\", \"elapsed_time\": \"1.22 secs\", \"cpu_time\": \"1.19 secs\" }",
          "additionalProperties": {
            "description": "Properties of the object."
          }
        },
        "rowCountExact": {
          "format": "int64",
          "description": "Standard DML returns an exact count of rows that were modified.",
          "type": "string"
        }
      }
    },
    "ShortRepresentation": {
      "description": "Condensed representation of a node and its subtree. Only present for `SCALAR` PlanNode(s).",
      "type": "object",
      "properties": {
        "subqueries": {
          "type": "object",
          "description": "A mapping of (subquery variable name) -> (subquery node id) for cases where the `description` string of this node references a `SCALAR` subquery contained in the expression subtree rooted at this node. The referenced `SCALAR` subquery may not necessarily be a direct child of this node.",
          "additionalProperties": {
            "type": "integer",
            "format": "int32"
          }
        },
        "description": {
          "type": "string",
          "description": "A string representation of the expression subtree rooted at this node."
        }
      }
    },
    "StructType": {
      "description": "`StructType` defines the fields of a STRUCT type.",
      "properties": {
        "fields": {
          "items": {
            "$ref": "#/$defs/Field"
          },
          "description": "The list of fields that make up this struct. Order is significant, because values of this struct type are represented as lists, where the order of field values matches the order of fields in the StructType. In turn, the order of fields matches the order of columns in a read request, or the order of fields in the `SELECT` clause of a query.",
          "type": "array"
        }
      },
      "type": "object"
    },
    "Transaction": {
      "properties": {
        "readTimestamp": {
          "format": "google-datetime",
          "type": "string",
          "description": "For snapshot read-only transactions, the read timestamp chosen for the transaction. Not returned by default: see TransactionOptions.ReadOnly.return_read_timestamp. A timestamp in RFC3339 UTC \\\"Zulu\\\" format, accurate to nanoseconds. Example: `\"2014-10-02T15:01:23.045123456Z\"`."
        },
        "id": {
          "type": "string",
          "description": "`id` may be used to identify the transaction in subsequent Read, ExecuteSql, Commit, or Rollback calls. Single-use read-only transactions do not have IDs, because single-use transactions do not support multiple requests.",
          "format": "byte"
        },
        "precommitToken": {
          "$ref": "#/$defs/MultiplexedSessionPrecommitToken",
          "description": "A precommit token is included in the response of a BeginTransaction request if the read-write transaction is on a multiplexed session and a mutation_key was specified in the BeginTransaction. The precommit token with the highest sequence number from this transaction attempt should be passed to the Commit request for this transaction."
        }
      },
      "type": "object",
      "description": "A transaction."
    },
    "Type": {
      "description": "`Type` indicates the type of a Cloud Spanner value, as might be stored in a table cell or returned from an SQL query.",
      "properties": {
        "structType": {
          "$ref": "#/$defs/StructType",
          "description": "If code == STRUCT, then `struct_type` provides type information for the struct's fields."
        },
        "arrayElementType": {
          "$ref": "#/$defs/Type",
          "description": "If code == ARRAY, then `array_element_type` is the type of the array elements."
        },
        "protoTypeFqn": {
          "type": "string",
          "description": "If code == PROTO or code == ENUM, then `proto_type_fqn` is the fully qualified name of the proto type representing the proto/enum definition."
        },
        "typeAnnotation": {
          "type": "string",
          "description": "The TypeAnnotationCode that disambiguates SQL type that Spanner will use to represent values of this type during query processing. This is necessary for some type codes because a single TypeCode can be mapped to different SQL types depending on the SQL dialect. type_annotation typically is not needed to process the content of a value (it doesn't affect serialization) and clients can ignore it on the read path.",
          "enum": [
            "TYPE_ANNOTATION_CODE_UNSPECIFIED",
            "PG_NUMERIC",
            "PG_JSONB",
            "PG_OID"
          ]
        },
        "code": {
          "type": "string",
          "enum": [
            "TYPE_CODE_UNSPECIFIED",
            "BOOL",
            "INT64",
            "FLOAT64",
            "FLOAT32",
            "TIMESTAMP",
            "DATE",
            "STRING",
            "BYTES",
            "ARRAY",
            "STRUCT",
            "NUMERIC",
            "JSON",
            "PROTO",
            "ENUM",
            "INTERVAL",
            "UUID"
          ],
          "description": "Required. The TypeCode for this type."
        }
      },
      "type": "object"
    }
  }
}