--- title: "POST /v1/{+session}:executeStreamingSql" method: POST path: "/v1/{+session}:executeStreamingSql" tags: ["projects"] --- # POST /v1/{+session}:executeStreamingSql `POST /v1/{+session}:executeStreamingSql` Like ExecuteSql, except returns the result set as a stream. Unlike ExecuteSql, there is no limit on the size of the returned result set. However, no individual row in the result set can exceed 100 MiB, and no column value can exceed 10 MiB. The query string can be SQL or [Graph Query Language (GQL)](https://cloud.google.com/spanner/docs/reference/standard-sql/graph-intro). ## Path parameters - `session` string, required ## Request body - ExecuteSqlRequest — The request for ExecuteSql and ExecuteStreamingSql. - `transaction` TransactionSelector — This message is used to select the transaction in which a Read or ExecuteSql call runs. See TransactionOptions for more information about transactions. - `singleUse` TransactionOptions — Options to use for transactions. - `readWrite` ReadWrite — Message type to initiate a read-write transaction. Currently this transaction type has no options. - `readLockMode` 'READ_LOCK_MODE_UNSPECIFIED' | 'PESSIMISTIC' | 'OPTIMISTIC' — The read lock mode for the transaction. - `multiplexedSessionPreviousTransactionId` string, byte — 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. - `partitionedDml` PartitionedDml — Message type to initiate a Partitioned DML transaction. - `readOnly` ReadOnly — Message type to initiate a read-only transaction. - `strong` boolean — Read at a timestamp where all previously committed transactions are visible. - `minReadTimestamp` string, google-datetime — 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"`. - `maxStaleness` string, google-duration — 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. - `readTimestamp` string, google-datetime — 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"`. - `exactStaleness` string, google-duration — 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`. - `returnReadTimestamp` boolean — If true, the Cloud Spanner-selected read timestamp is included in the Transaction message that describes the transaction. - `excludeTxnFromChangeStreams` boolean — 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. - `isolationLevel` 'ISOLATION_LEVEL_UNSPECIFIED' | 'SERIALIZABLE' | 'REPEATABLE_READ' — Isolation level for the transaction. - `id` string, byte — Execute the read or SQL query in a previously-started transaction. - `begin` TransactionOptions — Options to use for transactions. - `readWrite` ReadWrite — Message type to initiate a read-write transaction. Currently this transaction type has no options. - `readLockMode` 'READ_LOCK_MODE_UNSPECIFIED' | 'PESSIMISTIC' | 'OPTIMISTIC' — The read lock mode for the transaction. - `multiplexedSessionPreviousTransactionId` string, byte — 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. - `partitionedDml` PartitionedDml — Message type to initiate a Partitioned DML transaction. - `readOnly` ReadOnly — Message type to initiate a read-only transaction. - `strong` boolean — Read at a timestamp where all previously committed transactions are visible. - `minReadTimestamp` string, google-datetime — 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"`. - `maxStaleness` string, google-duration — 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. - `readTimestamp` string, google-datetime — 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"`. - `exactStaleness` string, google-duration — 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`. - `returnReadTimestamp` boolean — If true, the Cloud Spanner-selected read timestamp is included in the Transaction message that describes the transaction. - `excludeTxnFromChangeStreams` boolean — 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. - `isolationLevel` 'ISOLATION_LEVEL_UNSPECIFIED' | 'SERIALIZABLE' | 'REPEATABLE_READ' — Isolation level for the transaction. - `sql` string — Required. The SQL string. - `params` object — 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. - `paramTypes` object — 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. - `resumeToken` string, byte — 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. - `queryMode` 'NORMAL' | 'PLAN' | 'PROFILE' | 'WITH_STATS' | 'WITH_PLAN_AND_STATS' — 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. - `partitionToken` string, byte — 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`. - `seqno` string, int64 — 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. - `queryOptions` QueryOptions — Query optimizer configuration. - `optimizerVersion` string — 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` string — 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. - `requestOptions` RequestOptions — Common request options for various APIs. - `priority` 'PRIORITY_UNSPECIFIED' | 'PRIORITY_LOW' | 'PRIORITY_MEDIUM' | 'PRIORITY_HIGH' — Priority for the request. - `requestTag` string — 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. - `transactionTag` string — 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. - `clientContext` ClientContext — Container for various pieces of client-owned context attached to a request. - `secureContext` object — 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` DirectedReadOptions — 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. - `includeReplicas` IncludeReplicas — An `IncludeReplicas` contains a repeated set of `ReplicaSelection` which indicates the order in which replicas should be considered. - `replicaSelections` ReplicaSelection[] — The directed read replica selector. - `location` string — The location or region of the serving requests, for example, "us-east1". - `type` 'TYPE_UNSPECIFIED' | 'READ_WRITE' | 'READ_ONLY' — The type of replica. - `autoFailoverDisabled` boolean — 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`. - `excludeReplicas` ExcludeReplicas — An ExcludeReplicas contains a repeated set of ReplicaSelection that should be excluded from serving requests. - `replicaSelections` ReplicaSelection[] — The directed read replica selector. - `location` string — The location or region of the serving requests, for example, "us-east1". - `type` 'TYPE_UNSPECIFIED' | 'READ_WRITE' | 'READ_ONLY' — The type of replica. - `dataBoostEnabled` boolean — 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. - `lastStatement` boolean — 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. ## Response `200` Successful response --- [API](https://skmtc.net/google/apis/spanner.md) · [All operations](https://skmtc.net/google/apis/spanner/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/google/spanner/versions/4b66067d2622/schema)