ExecuteSqlRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/google-cloud-spanner/json-schema/google-cloud-spanner-execute-sql-request-schema.json",
  "title": "ExecuteSqlRequest",
  "description": "The request for ExecuteSql and ExecuteStreamingSql.",
  "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/ExecuteSqlRequest",
  "properties": {
    "dataBoostEnabled": {
      "description": "If this is for a partitioned query and this field is set to `true`, the request is executed with Spanner Data Boost independent compute resources. If the field is set to `true` but the request doesn't set `partition_token`, the API returns an `INVALID_ARGUMENT` error.",
      "type": "boolean"
    },
    "requestOptions": {
      "$ref": "#/$defs/RequestOptions",
      "description": "Common options for this request."
    },
    "params": {
      "additionalProperties": {
        "description": "Properties of the object."
      },
      "type": "object",
      "description": "Parameter names and values that bind to placeholders in the SQL string. A parameter placeholder consists of the `@` character followed by the parameter name (for example, `@firstName`). Parameter names must conform to the naming requirements of identifiers as specified at https://cloud.google.com/spanner/docs/lexical#identifiers. Parameters can appear anywhere that a literal value is expected. The same parameter name can be used more than once, for example: `\"WHERE id > @msg_id AND id < @msg_id + 100\"` It's an error to execute a SQL statement with unbound parameters."
    },
    "queryOptions": {
      "$ref": "#/$defs/QueryOptions",
      "description": "Query optimizer configuration to use for the given query."
    },
    "partitionToken": {
      "format": "byte",
      "type": "string",
      "description": "If present, results are restricted to the specified partition previously created using `PartitionQuery`. There must be an exact match for the values of fields common to this message and the `PartitionQueryRequest` message used to create this `partition_token`."
    },
    "directedReadOptions": {
      "$ref": "#/$defs/DirectedReadOptions",
      "description": "Directed read options for this request."
    },
    "sql": {
      "type": "string",
      "description": "Required. The SQL string."
    },
    "paramTypes": {
      "type": "object",
      "description": "It isn't always possible for Cloud Spanner to infer the right SQL type from a JSON value. For example, values of type `BYTES` and values of type `STRING` both appear in params as JSON strings. In these cases, you can use `param_types` to specify the exact SQL type for some or all of the SQL statement parameters. See the definition of Type for more information about SQL types.",
      "additionalProperties": {
        "$ref": "#/$defs/Type"
      }
    },
    "seqno": {
      "type": "string",
      "format": "int64",
      "description": "A per-transaction sequence number used to identify this request. This field makes each request idempotent such that if the request is received multiple times, at most one succeeds. The sequence number must be monotonically increasing within the transaction. If a request arrives for the first time with an out-of-order sequence number, the transaction can be aborted. Replays of previously handled requests yield the same response as the first execution. Required for DML statements. Ignored for queries."
    },
    "queryMode": {
      "description": "Used to control the amount of debugging information returned in ResultSetStats. If partition_token is set, query_mode can only be set to QueryMode.NORMAL.",
      "enum": [
        "NORMAL",
        "PLAN",
        "PROFILE",
        "WITH_STATS",
        "WITH_PLAN_AND_STATS"
      ],
      "type": "string"
    },
    "transaction": {
      "$ref": "#/$defs/TransactionSelector",
      "description": "The transaction to use. For queries, if none is provided, the default is a temporary read-only transaction with strong concurrency. Standard DML statements require a read-write transaction. To protect against replays, single-use transactions are not supported. The caller must either supply an existing transaction ID or begin a new transaction. Partitioned DML requires an existing Partitioned DML transaction ID."
    },
    "resumeToken": {
      "description": "If this request is resuming a previously interrupted SQL statement execution, `resume_token` should be copied from the last PartialResultSet yielded before the interruption. Doing this enables the new SQL statement execution to resume where the last one left off. The rest of the request parameters must exactly match the request that yielded this token.",
      "format": "byte",
      "type": "string"
    },
    "lastStatement": {
      "description": "Optional. If set to `true`, this statement marks the end of the transaction. After this statement executes, you must commit or abort the transaction. Attempts to execute any other requests against this transaction (including reads and queries) are rejected. For DML statements, setting this option might cause some error reporting to be deferred until commit time (for example, validation of unique constraints). Given this, successful execution of a DML statement shouldn't be assumed until a subsequent `Commit` call completes successfully.",
      "type": "boolean"
    }
  },
  "type": "object",
  "$defs": {
    "ClientContext": {
      "type": "object",
      "description": "Container for various pieces of client-owned context attached to a request.",
      "properties": {
        "secureContext": {
          "additionalProperties": {},
          "type": "object",
          "description": "Optional. Map of parameter name to value for this request. These values will be returned by any SECURE_CONTEXT() calls invoked by this request (e.g., by queries against Parameterized Secure Views)."
        }
      }
    },
    "DirectedReadOptions": {
      "type": "object",
      "properties": {
        "includeReplicas": {
          "$ref": "#/$defs/IncludeReplicas",
          "description": "`Include_replicas` indicates the order of replicas (as they appear in this list) to process the request. If `auto_failover_disabled` is set to `true` and all replicas are exhausted without finding a healthy replica, Spanner waits for a replica in the list to become available, requests might fail due to `DEADLINE_EXCEEDED` errors."
        },
        "excludeReplicas": {
          "$ref": "#/$defs/ExcludeReplicas",
          "description": "`Exclude_replicas` indicates that specified replicas should be excluded from serving requests. Spanner doesn't route requests to the replicas in this list."
        }
      },
      "description": "The `DirectedReadOptions` can be used to indicate which replicas or regions should be used for non-transactional reads or queries. `DirectedReadOptions` can only be specified for a read-only transaction, otherwise the API returns an `INVALID_ARGUMENT` error."
    },
    "ExcludeReplicas": {
      "type": "object",
      "properties": {
        "replicaSelections": {
          "type": "array",
          "description": "The directed read replica selector.",
          "items": {
            "$ref": "#/$defs/ReplicaSelection"
          }
        }
      },
      "description": "An ExcludeReplicas contains a repeated set of ReplicaSelection that should be excluded from serving requests."
    },
    "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."
    },
    "IncludeReplicas": {
      "type": "object",
      "properties": {
        "replicaSelections": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ReplicaSelection"
          },
          "description": "The directed read replica selector."
        },
        "autoFailoverDisabled": {
          "description": "If `true`, Spanner doesn't route requests to a replica outside the <`include_replicas` list when all of the specified replicas are unavailable or unhealthy. Default value is `false`.",
          "type": "boolean"
        }
      },
      "description": "An `IncludeReplicas` contains a repeated set of `ReplicaSelection` which indicates the order in which replicas should be considered."
    },
    "PartitionedDml": {
      "type": "object",
      "properties": {},
      "description": "Message type to initiate a Partitioned DML transaction."
    },
    "QueryOptions": {
      "description": "Query optimizer configuration.",
      "properties": {
        "optimizerVersion": {
          "type": "string",
          "description": "An option to control the selection of optimizer version. This parameter allows individual queries to pick different query optimizer versions. Specifying `latest` as a value instructs Cloud Spanner to use the latest supported query optimizer version. If not specified, Cloud Spanner uses the optimizer version set at the database level options. Any other positive integer (from the list of supported optimizer versions) overrides the default optimizer version for query execution. The list of supported optimizer versions can be queried from `SPANNER_SYS.SUPPORTED_OPTIMIZER_VERSIONS`. Executing a SQL statement with an invalid optimizer version fails with an `INVALID_ARGUMENT` error. See https://cloud.google.com/spanner/docs/query-optimizer/manage-query-optimizer for more information on managing the query optimizer. The `optimizer_version` statement hint has precedence over this setting."
        },
        "optimizerStatisticsPackage": {
          "description": "An option to control the selection of optimizer statistics package. This parameter allows individual queries to use a different query optimizer statistics package. Specifying `latest` as a value instructs Cloud Spanner to use the latest generated statistics package. If not specified, Cloud Spanner uses the statistics package set at the database level options, or the latest package if the database option isn't set. The statistics package requested by the query has to be exempt from garbage collection. This can be achieved with the following DDL statement: ```sql ALTER STATISTICS SET OPTIONS (allow_gc=false) ``` The list of available statistics packages can be queried from `INFORMATION_SCHEMA.SPANNER_STATISTICS`. Executing a SQL statement with an invalid optimizer statistics package or with a statistics package that allows garbage collection fails with an `INVALID_ARGUMENT` error.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "ReadOnly": {
      "properties": {
        "exactStaleness": {
          "format": "google-duration",
          "description": "Executes all reads at a timestamp that is `exact_staleness` old. The timestamp is chosen soon after the read is started. Guarantees that all writes that have committed more than the specified number of seconds ago are visible. Because Cloud Spanner chooses the exact timestamp, this mode works even if the client's local clock is substantially skewed from Cloud Spanner commit timestamps. Useful for reading at nearby replicas without the distributed timestamp negotiation overhead of `max_staleness`.",
          "type": "string"
        },
        "minReadTimestamp": {
          "description": "Executes all reads at a timestamp >= `min_read_timestamp`. This is useful for requesting fresher data than some previous read, or data that is fresh enough to observe the effects of some previously committed transaction whose timestamp is known. Note that this option can only be used in single-use transactions. A timestamp in RFC3339 UTC \\\"Zulu\\\" format, accurate to nanoseconds. Example: `\"2014-10-02T15:01:23.045123456Z\"`.",
          "type": "string",
          "format": "google-datetime"
        },
        "strong": {
          "description": "Read at a timestamp where all previously committed transactions are visible.",
          "type": "boolean"
        },
        "maxStaleness": {
          "type": "string",
          "format": "google-duration",
          "description": "Read data at a timestamp >= `NOW - max_staleness` seconds. Guarantees that all writes that have committed more than the specified number of seconds ago are visible. Because Cloud Spanner chooses the exact timestamp, this mode works even if the client's local clock is substantially skewed from Cloud Spanner commit timestamps. Useful for reading the freshest data available at a nearby replica, while bounding the possible staleness if the local replica has fallen behind. Note that this option can only be used in single-use transactions."
        },
        "returnReadTimestamp": {
          "description": "If true, the Cloud Spanner-selected read timestamp is included in the Transaction message that describes the transaction.",
          "type": "boolean"
        },
        "readTimestamp": {
          "format": "google-datetime",
          "type": "string",
          "description": "Executes all reads at the given timestamp. Unlike other modes, reads at a specific timestamp are repeatable; the same read at the same timestamp always returns the same data. If the timestamp is in the future, the read is blocked until the specified timestamp, modulo the read's deadline. Useful for large scale consistent reads such as mapreduces, or for coordinating many reads against a consistent snapshot of the data. A timestamp in RFC3339 UTC \\\"Zulu\\\" format, accurate to nanoseconds. Example: `\"2014-10-02T15:01:23.045123456Z\"`."
        }
      },
      "type": "object",
      "description": "Message type to initiate a read-only transaction."
    },
    "ReadWrite": {
      "properties": {
        "multiplexedSessionPreviousTransactionId": {
          "type": "string",
          "format": "byte",
          "description": "Optional. Clients should pass the transaction ID of the previous transaction attempt that was aborted if this transaction is being executed on a multiplexed session."
        },
        "readLockMode": {
          "type": "string",
          "enum": [
            "READ_LOCK_MODE_UNSPECIFIED",
            "PESSIMISTIC",
            "OPTIMISTIC"
          ],
          "description": "The read lock mode for the transaction."
        }
      },
      "description": "Message type to initiate a read-write transaction. Currently this transaction type has no options.",
      "type": "object"
    },
    "ReplicaSelection": {
      "type": "object",
      "description": "The directed read replica selector. Callers must provide one or more of the following fields for replica selection: * `location` - The location must be one of the regions within the multi-region configuration of your database. * `type` - The type of the replica. Some examples of using replica_selectors are: * `location:us-east1` --> The \"us-east1\" replica(s) of any available type is used to process the request. * `type:READ_ONLY` --> The \"READ_ONLY\" type replica(s) in the nearest available location are used to process the request. * `location:us-east1 type:READ_ONLY` --> The \"READ_ONLY\" type replica(s) in location \"us-east1\" is used to process the request.",
      "properties": {
        "location": {
          "description": "The location or region of the serving requests, for example, \"us-east1\".",
          "type": "string"
        },
        "type": {
          "enum": [
            "TYPE_UNSPECIFIED",
            "READ_WRITE",
            "READ_ONLY"
          ],
          "type": "string",
          "description": "The type of replica."
        }
      }
    },
    "RequestOptions": {
      "description": "Common request options for various APIs.",
      "properties": {
        "clientContext": {
          "$ref": "#/$defs/ClientContext",
          "description": "Optional. Optional context that may be needed for some requests."
        },
        "requestTag": {
          "description": "A per-request tag which can be applied to queries or reads, used for statistics collection. Both `request_tag` and `transaction_tag` can be specified for a read or query that belongs to a transaction. This field is ignored for requests where it's not applicable (for example, `CommitRequest`). Legal characters for `request_tag` values are all printable characters (ASCII 32 - 126) and the length of a request_tag is limited to 50 characters. Values that exceed this limit are truncated. Any leading underscore (_) characters are removed from the string.",
          "type": "string"
        },
        "priority": {
          "enum": [
            "PRIORITY_UNSPECIFIED",
            "PRIORITY_LOW",
            "PRIORITY_MEDIUM",
            "PRIORITY_HIGH"
          ],
          "description": "Priority for the request.",
          "type": "string"
        },
        "transactionTag": {
          "type": "string",
          "description": "A tag used for statistics collection about this transaction. Both `request_tag` and `transaction_tag` can be specified for a read or query that belongs to a transaction. To enable tagging on a transaction, `transaction_tag` must be set to the same value for all requests belonging to the same transaction, including BeginTransaction. If this request doesn't belong to any transaction, `transaction_tag` is ignored. Legal characters for `transaction_tag` values are all printable characters (ASCII 32 - 126) and the length of a `transaction_tag` is limited to 50 characters. Values that exceed this limit are truncated. Any leading underscore (_) characters are removed from the string."
        }
      },
      "type": "object"
    },
    "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"
    },
    "TransactionOptions": {
      "description": "Options to use for transactions.",
      "properties": {
        "isolationLevel": {
          "description": "Isolation level for the transaction.",
          "type": "string",
          "enum": [
            "ISOLATION_LEVEL_UNSPECIFIED",
            "SERIALIZABLE",
            "REPEATABLE_READ"
          ]
        },
        "readOnly": {
          "$ref": "#/$defs/ReadOnly",
          "description": "Transaction does not write. Authorization to begin a read-only transaction requires `spanner.databases.beginReadOnlyTransaction` permission on the `session` resource."
        },
        "readWrite": {
          "$ref": "#/$defs/ReadWrite",
          "description": "Transaction may write. Authorization to begin a read-write transaction requires `spanner.databases.beginOrRollbackReadWriteTransaction` permission on the `session` resource."
        },
        "excludeTxnFromChangeStreams": {
          "type": "boolean",
          "description": "When `exclude_txn_from_change_streams` is set to `true`, it prevents read or write transactions from being tracked in change streams. * If the DDL option `allow_txn_exclusion` is set to `true`, then the updates made within this transaction aren't recorded in the change stream. * If you don't set the DDL option `allow_txn_exclusion` or if it's set to `false`, then the updates made within this transaction are recorded in the change stream. When `exclude_txn_from_change_streams` is set to `false` or not set, modifications from this transaction are recorded in all change streams that are tracking columns modified by these transactions. The `exclude_txn_from_change_streams` option can only be specified for read-write or partitioned DML transactions, otherwise the API returns an `INVALID_ARGUMENT` error."
        },
        "partitionedDml": {
          "$ref": "#/$defs/PartitionedDml",
          "description": "Partitioned DML transaction. Authorization to begin a Partitioned DML transaction requires `spanner.databases.beginPartitionedDmlTransaction` permission on the `session` resource."
        }
      },
      "type": "object"
    },
    "TransactionSelector": {
      "description": "This message is used to select the transaction in which a Read or ExecuteSql call runs. See TransactionOptions for more information about transactions.",
      "properties": {
        "begin": {
          "$ref": "#/$defs/TransactionOptions",
          "description": "Begin a new transaction and execute this read or SQL query in it. The transaction ID of the new transaction is returned in ResultSetMetadata.transaction, which is a Transaction."
        },
        "singleUse": {
          "$ref": "#/$defs/TransactionOptions",
          "description": "Execute the read or SQL query in a temporary transaction. This is the most efficient way to execute a transaction that consists of a single SQL query."
        },
        "id": {
          "type": "string",
          "format": "byte",
          "description": "Execute the read or SQL query in a previously-started transaction."
        }
      },
      "type": "object"
    },
    "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"
    }
  }
}