Cloud Spanner V1 API - Class Google::Cloud::Spanner::V1::Spanner::Client (v0.11.0)

Reference documentation and code samples for the Cloud Spanner V1 API class Google::Cloud::Spanner::V1::Spanner::Client.

Client for the Spanner service.

Cloud Spanner API

The Cloud Spanner API can be used to manage sessions and execute transactions on data stored in Cloud Spanner databases.

Inherits

  • Object

Includes

Methods

.configure

def self.configure() { |config| ... } -> Client::Configuration

Configure the Spanner Client class.

See Configuration for a description of the configuration fields.

Yields
  • (config) — Configure the Client client.
Yield Parameter
Returns
Example 
# Modify the configuration for all Spanner clients
::Google::Cloud::Spanner::V1::Spanner::Client.configure do |config|
  config.timeout = 10.0
end

#batch_create_sessions

def batch_create_sessions(request, options = nil) -> ::Google::Cloud::Spanner::V1::BatchCreateSessionsResponse
def batch_create_sessions(database: nil, session_template: nil, session_count: nil) -> ::Google::Cloud::Spanner::V1::BatchCreateSessionsResponse

Creates multiple new sessions.

This API can be used to initialize a session cache on the clients. See https://goo.gl/TgSFN2 for best practices on session cache management.

Overloads 
def batch_create_sessions(request, options = nil) -> ::Google::Cloud::Spanner::V1::BatchCreateSessionsResponse
Pass arguments to batch_create_sessions via a request object, either of type BatchCreateSessionsRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Spanner::V1::BatchCreateSessionsRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def batch_create_sessions(database: nil, session_template: nil, session_count: nil) -> ::Google::Cloud::Spanner::V1::BatchCreateSessionsResponse
Pass arguments to batch_create_sessions via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • database (::String) — Required. The database in which the new sessions are created.
  • session_template (::Google::Cloud::Spanner::V1::Session, ::Hash) — Parameters to be applied to each created session.
  • session_count (::Integer) — Required. The number of sessions to be created in this batch call. The API may return fewer than the requested number of sessions. If a specific number of sessions are desired, the client can make additional calls to BatchCreateSessions (adjusting session_count as necessary).
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/spanner/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Spanner::V1::Spanner::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Spanner::V1::BatchCreateSessionsRequest.new

# Call the batch_create_sessions method.
result = client.batch_create_sessions request

# The returned object is of type Google::Cloud::Spanner::V1::BatchCreateSessionsResponse.
p result

#begin_transaction

def begin_transaction(request, options = nil) -> ::Google::Cloud::Spanner::V1::Transaction
def begin_transaction(session: nil, options: nil, request_options: nil) -> ::Google::Cloud::Spanner::V1::Transaction

Begins a new transaction. This step can often be skipped: Read, ExecuteSql and Commit can begin a new transaction as a side-effect.

Overloads 
def begin_transaction(request, options = nil) -> ::Google::Cloud::Spanner::V1::Transaction
Pass arguments to begin_transaction via a request object, either of type BeginTransactionRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Spanner::V1::BeginTransactionRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def begin_transaction(session: nil, options: nil, request_options: nil) -> ::Google::Cloud::Spanner::V1::Transaction
Pass arguments to begin_transaction via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • session (::String) — Required. The session in which the transaction runs.
  • options (::Google::Cloud::Spanner::V1::TransactionOptions, ::Hash) — Required. Options for the new transaction.
  • request_options (::Google::Cloud::Spanner::V1::RequestOptions, ::Hash) — Common options for this request. Priority is ignored for this request. Setting the priority in this request_options struct will not do anything. To set the priority for a transaction, set it on the reads and writes that are part of this transaction instead.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/spanner/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Spanner::V1::Spanner::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Spanner::V1::BeginTransactionRequest.new

# Call the begin_transaction method.
result = client.begin_transaction request

# The returned object is of type Google::Cloud::Spanner::V1::Transaction.
p result

#commit

def commit(request, options = nil) -> ::Google::Cloud::Spanner::V1::CommitResponse
def commit(session: nil, transaction_id: nil, single_use_transaction: nil, mutations: nil, return_commit_stats: nil, request_options: nil) -> ::Google::Cloud::Spanner::V1::CommitResponse

Commits a transaction. The request includes the mutations to be applied to rows in the database.

Commit might return an ABORTED error. This can occur at any time; commonly, the cause is conflicts with concurrent transactions. However, it can also happen for a variety of other reasons. If Commit returns ABORTED, the caller should re-attempt the transaction from the beginning, re-using the same session.

On very rare occasions, Commit might return UNKNOWN. This can happen, for example, if the client job experiences a 1+ hour networking failure. At that point, Cloud Spanner has lost track of the transaction outcome and we recommend that you perform another read from the database to see the state of things as they are now.

Overloads 
def commit(request, options = nil) -> ::Google::Cloud::Spanner::V1::CommitResponse
Pass arguments to commit via a request object, either of type CommitRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Spanner::V1::CommitRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def commit(session: nil, transaction_id: nil, single_use_transaction: nil, mutations: nil, return_commit_stats: nil, request_options: nil) -> ::Google::Cloud::Spanner::V1::CommitResponse
Pass arguments to commit via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • session (::String) — Required. The session in which the transaction to be committed is running.
  • transaction_id (::String) — Commit a previously-started transaction.
  • single_use_transaction (::Google::Cloud::Spanner::V1::TransactionOptions, ::Hash) — Execute mutations in a temporary transaction. Note that unlike commit of a previously-started transaction, commit with a temporary transaction is non-idempotent. That is, if the CommitRequest is sent to Cloud Spanner more than once (for instance, due to retries in the application, or in the transport library), it is possible that the mutations are executed more than once. If this is undesirable, use BeginTransaction and Commit instead.
  • mutations (::Array<::Google::Cloud::Spanner::V1::Mutation, ::Hash>) — The mutations to be executed when this transaction commits. All mutations are applied atomically, in the order they appear in this list.
  • return_commit_stats (::Boolean) — If true, then statistics related to the transaction will be included in the CommitResponse. Default value is false.
  • request_options (::Google::Cloud::Spanner::V1::RequestOptions, ::Hash) — Common options for this request.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/spanner/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Spanner::V1::Spanner::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Spanner::V1::CommitRequest.new

# Call the commit method.
result = client.commit request

# The returned object is of type Google::Cloud::Spanner::V1::CommitResponse.
p result

#configure

def configure() { |config| ... } -> Client::Configuration

Configure the Spanner Client instance.

The configuration is set to the derived mode, meaning that values can be changed, but structural changes (adding new fields, etc.) are not allowed. Structural changes should be made on Client.configure.

See Configuration for a description of the configuration fields.

Yields
  • (config) — Configure the Client client.
Yield Parameter
Returns

#create_session

def create_session(request, options = nil) -> ::Google::Cloud::Spanner::V1::Session
def create_session(database: nil, session: nil) -> ::Google::Cloud::Spanner::V1::Session

Creates a new session. A session can be used to perform transactions that read and/or modify data in a Cloud Spanner database. Sessions are meant to be reused for many consecutive transactions.

Sessions can only execute one transaction at a time. To execute multiple concurrent read-write/write-only transactions, create multiple sessions. Note that standalone reads and queries use a transaction internally, and count toward the one transaction limit.

Active sessions use additional server resources, so it is a good idea to delete idle and unneeded sessions. Aside from explicit deletes, Cloud Spanner may delete sessions for which no operations are sent for more than an hour. If a session is deleted, requests to it return NOT_FOUND.

Idle sessions can be kept alive by sending a trivial SQL query periodically, e.g., "SELECT 1".

Overloads 
def create_session(request, options = nil) -> ::Google::Cloud::Spanner::V1::Session
Pass arguments to create_session via a request object, either of type CreateSessionRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Spanner::V1::CreateSessionRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def create_session(database: nil, session: nil) -> ::Google::Cloud::Spanner::V1::Session
Pass arguments to create_session via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/spanner/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Spanner::V1::Spanner::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Spanner::V1::CreateSessionRequest.new

# Call the create_session method.
result = client.create_session request

# The returned object is of type Google::Cloud::Spanner::V1::Session.
p result

#delete_session

def delete_session(request, options = nil) -> ::Google::Protobuf::Empty
def delete_session(name: nil) -> ::Google::Protobuf::Empty

Ends a session, releasing server resources associated with it. This will asynchronously trigger cancellation of any operations that are running with this session.

Overloads 
def delete_session(request, options = nil) -> ::Google::Protobuf::Empty
Pass arguments to delete_session via a request object, either of type DeleteSessionRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Spanner::V1::DeleteSessionRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def delete_session(name: nil) -> ::Google::Protobuf::Empty
Pass arguments to delete_session via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameter
  • name (::String) — Required. The name of the session to delete.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/spanner/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Spanner::V1::Spanner::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Spanner::V1::DeleteSessionRequest.new

# Call the delete_session method.
result = client.delete_session request

# The returned object is of type Google::Protobuf::Empty.
p result

#execute_batch_dml

def execute_batch_dml(request, options = nil) -> ::Google::Cloud::Spanner::V1::ExecuteBatchDmlResponse
def execute_batch_dml(session: nil, transaction: nil, statements: nil, seqno: nil, request_options: nil) -> ::Google::Cloud::Spanner::V1::ExecuteBatchDmlResponse

Executes a batch of SQL DML statements. This method allows many statements to be run with lower latency than submitting them sequentially with ExecuteSql.

Statements are executed in sequential order. A request can succeed even if a statement fails. The ExecuteBatchDmlResponse.status field in the response provides information about the statement that failed. Clients must inspect this field to determine whether an error occurred.

Execution stops after the first failed statement; the remaining statements are not executed.

Overloads 
def execute_batch_dml(request, options = nil) -> ::Google::Cloud::Spanner::V1::ExecuteBatchDmlResponse
Pass arguments to execute_batch_dml via a request object, either of type ExecuteBatchDmlRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Spanner::V1::ExecuteBatchDmlRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def execute_batch_dml(session: nil, transaction: nil, statements: nil, seqno: nil, request_options: nil) -> ::Google::Cloud::Spanner::V1::ExecuteBatchDmlResponse
Pass arguments to execute_batch_dml via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • session (::String) — Required. The session in which the DML statements should be performed.
  • transaction (::Google::Cloud::Spanner::V1::TransactionSelector, ::Hash) — Required. The transaction to use. Must be 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.

  • statements (::Array<::Google::Cloud::Spanner::V1::ExecuteBatchDmlRequest::Statement, ::Hash>) — Required. The list of statements to execute in this batch. Statements are executed serially, such that the effects of statement i are visible to statement i+1. Each statement must be a DML statement. Execution stops at the first failed statement; the remaining statements are not executed.

    Callers must provide at least one statement.

  • seqno (::Integer) — Required. 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 will succeed.

    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 may be aborted. Replays of previously handled requests will yield the same response as the first execution.

  • request_options (::Google::Cloud::Spanner::V1::RequestOptions, ::Hash) — Common options for this request.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/spanner/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Spanner::V1::Spanner::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Spanner::V1::ExecuteBatchDmlRequest.new

# Call the execute_batch_dml method.
result = client.execute_batch_dml request

# The returned object is of type Google::Cloud::Spanner::V1::ExecuteBatchDmlResponse.
p result

#execute_sql

def execute_sql(request, options = nil) -> ::Google::Cloud::Spanner::V1::ResultSet
def execute_sql(session: nil, transaction: nil, sql: nil, params: nil, param_types: nil, resume_token: nil, query_mode: nil, partition_token: nil, seqno: nil, query_options: nil, request_options: nil) -> ::Google::Cloud::Spanner::V1::ResultSet

Executes an SQL statement, returning all results in a single reply. This method cannot be used to return a result set larger than 10 MiB; if the query yields more data than that, the query fails with a FAILED_PRECONDITION error.

Operations inside read-write transactions might return ABORTED. If this occurs, the application should restart the transaction from the beginning. See Transaction for more details.

Larger result sets can be fetched in streaming fashion by calling ExecuteStreamingSql instead.

Overloads 
def execute_sql(request, options = nil) -> ::Google::Cloud::Spanner::V1::ResultSet
Pass arguments to execute_sql via a request object, either of type ExecuteSqlRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Spanner::V1::ExecuteSqlRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def execute_sql(session: nil, transaction: nil, sql: nil, params: nil, param_types: nil, resume_token: nil, query_mode: nil, partition_token: nil, seqno: nil, query_options: nil, request_options: nil) -> ::Google::Cloud::Spanner::V1::ResultSet
Pass arguments to execute_sql via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • session (::String) — Required. The session in which the SQL query should be performed.
  • transaction (::Google::Cloud::Spanner::V1::TransactionSelector, ::Hash) — 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.

  • sql (::String) — Required. The SQL string.
  • params (::Google::Protobuf::Struct, ::Hash) — 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 is an error to execute a SQL statement with unbound parameters.

  • param_types (::Hash{::String => ::Google::Cloud::Spanner::V1::Type, ::Hash}) — It is not 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, param_types can be used 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.

  • resume_token (::String) — 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.
  • query_mode (::Google::Cloud::Spanner::V1::ExecuteSqlRequest::QueryMode) — 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.
  • partition_token (::String) — If present, results will be 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 (::Integer) — 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 will succeed.

    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 may be aborted. Replays of previously handled requests will yield the same response as the first execution.

    Required for DML statements. Ignored for queries.

  • query_options (::Google::Cloud::Spanner::V1::ExecuteSqlRequest::QueryOptions, ::Hash) — Query optimizer configuration to use for the given query.
  • request_options (::Google::Cloud::Spanner::V1::RequestOptions, ::Hash) — Common options for this request.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/spanner/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Spanner::V1::Spanner::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Spanner::V1::ExecuteSqlRequest.new

# Call the execute_sql method.
result = client.execute_sql request

# The returned object is of type Google::Cloud::Spanner::V1::ResultSet.
p result

#execute_streaming_sql

def execute_streaming_sql(request, options = nil) -> ::Enumerable<::Google::Cloud::Spanner::V1::PartialResultSet>
def execute_streaming_sql(session: nil, transaction: nil, sql: nil, params: nil, param_types: nil, resume_token: nil, query_mode: nil, partition_token: nil, seqno: nil, query_options: nil, request_options: nil) -> ::Enumerable<::Google::Cloud::Spanner::V1::PartialResultSet>

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.

Overloads 
def execute_streaming_sql(request, options = nil) -> ::Enumerable<::Google::Cloud::Spanner::V1::PartialResultSet>
Pass arguments to execute_streaming_sql via a request object, either of type ExecuteSqlRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Spanner::V1::ExecuteSqlRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def execute_streaming_sql(session: nil, transaction: nil, sql: nil, params: nil, param_types: nil, resume_token: nil, query_mode: nil, partition_token: nil, seqno: nil, query_options: nil, request_options: nil) -> ::Enumerable<::Google::Cloud::Spanner::V1::PartialResultSet>
Pass arguments to execute_streaming_sql via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • session (::String) — Required. The session in which the SQL query should be performed.
  • transaction (::Google::Cloud::Spanner::V1::TransactionSelector, ::Hash) — 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.

  • sql (::String) — Required. The SQL string.
  • params (::Google::Protobuf::Struct, ::Hash) — 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 is an error to execute a SQL statement with unbound parameters.

  • param_types (::Hash{::String => ::Google::Cloud::Spanner::V1::Type, ::Hash}) — It is not 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, param_types can be used 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.

  • resume_token (::String) — 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.
  • query_mode (::Google::Cloud::Spanner::V1::ExecuteSqlRequest::QueryMode) — 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.
  • partition_token (::String) — If present, results will be 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 (::Integer) — 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 will succeed.

    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 may be aborted. Replays of previously handled requests will yield the same response as the first execution.

    Required for DML statements. Ignored for queries.

  • query_options (::Google::Cloud::Spanner::V1::ExecuteSqlRequest::QueryOptions, ::Hash) — Query optimizer configuration to use for the given query.
  • request_options (::Google::Cloud::Spanner::V1::RequestOptions, ::Hash) — Common options for this request.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/spanner/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Spanner::V1::Spanner::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Spanner::V1::ExecuteSqlRequest.new

# Call the execute_streaming_sql method.
result = client.execute_streaming_sql request

# The returned object is a streamed enumerable yielding elements of
# type ::Google::Cloud::Spanner::V1::PartialResultSet.
result.each do |response|
  p response
end

#get_session

def get_session(request, options = nil) -> ::Google::Cloud::Spanner::V1::Session
def get_session(name: nil) -> ::Google::Cloud::Spanner::V1::Session

Gets a session. Returns NOT_FOUND if the session does not exist. This is mainly useful for determining whether a session is still alive.

Overloads 
def get_session(request, options = nil) -> ::Google::Cloud::Spanner::V1::Session
Pass arguments to get_session via a request object, either of type GetSessionRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Spanner::V1::GetSessionRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def get_session(name: nil) -> ::Google::Cloud::Spanner::V1::Session
Pass arguments to get_session via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameter
  • name (::String) — Required. The name of the session to retrieve.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/spanner/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Spanner::V1::Spanner::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Spanner::V1::GetSessionRequest.new

# Call the get_session method.
result = client.get_session request

# The returned object is of type Google::Cloud::Spanner::V1::Session.
p result

#initialize

def initialize() { |config| ... } -> Client

Create a new Spanner client object.

Yields
  • (config) — Configure the Spanner client.
Yield Parameter
Returns
  • (Client) — a new instance of Client
Example 
# Create a client using the default configuration
client = ::Google::Cloud::Spanner::V1::Spanner::Client.new

# Create a client using a custom configuration
client = ::Google::Cloud::Spanner::V1::Spanner::Client.new do |config|
  config.timeout = 10.0
end

#list_sessions

def list_sessions(request, options = nil) -> ::Gapic::PagedEnumerable<::Google::Cloud::Spanner::V1::Session>
def list_sessions(database: nil, page_size: nil, page_token: nil, filter: nil) -> ::Gapic::PagedEnumerable<::Google::Cloud::Spanner::V1::Session>

Lists all sessions in a given database.

Overloads 
def list_sessions(request, options = nil) -> ::Gapic::PagedEnumerable<::Google::Cloud::Spanner::V1::Session>
Pass arguments to list_sessions via a request object, either of type ListSessionsRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Spanner::V1::ListSessionsRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def list_sessions(database: nil, page_size: nil, page_token: nil, filter: nil) -> ::Gapic::PagedEnumerable<::Google::Cloud::Spanner::V1::Session>
Pass arguments to list_sessions via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • database (::String) — Required. The database in which to list sessions.
  • page_size (::Integer) — Number of sessions to be returned in the response. If 0 or less, defaults to the server's maximum allowed page size.
  • page_token (::String) — If non-empty, page_token should contain a next_page_token from a previous ListSessionsResponse.
  • filter (::String) —

    An expression for filtering the results of the request. Filter rules are case insensitive. The fields eligible for filtering are:

    • labels.key where key is the name of a label

    Some examples of using filters are:

    • labels.env:* --> The session has the label "env".
    • labels.env:dev --> The session has the label "env" and the value of the label contains the string "dev".
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/spanner/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Spanner::V1::Spanner::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Spanner::V1::ListSessionsRequest.new

# Call the list_sessions method.
result = client.list_sessions request

# The returned object is of type Gapic::PagedEnumerable. You can
# iterate over all elements by calling #each, and the enumerable
# will lazily make API calls to fetch subsequent pages. Other
# methods are also available for managing paging directly.
result.each do |response|
  # Each element is of type ::Google::Cloud::Spanner::V1::Session.
  p response
end

#partition_query

def partition_query(request, options = nil) -> ::Google::Cloud::Spanner::V1::PartitionResponse
def partition_query(session: nil, transaction: nil, sql: nil, params: nil, param_types: nil, partition_options: nil) -> ::Google::Cloud::Spanner::V1::PartitionResponse

Creates a set of partition tokens that can be used to execute a query operation in parallel. Each of the returned partition tokens can be used by ExecuteStreamingSql to specify a subset of the query result to read. The same session and read-only transaction must be used by the PartitionQueryRequest used to create the partition tokens and the ExecuteSqlRequests that use the partition tokens.

Partition tokens become invalid when the session used to create them is deleted, is idle for too long, begins a new transaction, or becomes too old. When any of these happen, it is not possible to resume the query, and the whole operation must be restarted from the beginning.

Overloads 
def partition_query(request, options = nil) -> ::Google::Cloud::Spanner::V1::PartitionResponse
Pass arguments to partition_query via a request object, either of type PartitionQueryRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Spanner::V1::PartitionQueryRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def partition_query(session: nil, transaction: nil, sql: nil, params: nil, param_types: nil, partition_options: nil) -> ::Google::Cloud::Spanner::V1::PartitionResponse
Pass arguments to partition_query via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • session (::String) — Required. The session used to create the partitions.
  • transaction (::Google::Cloud::Spanner::V1::TransactionSelector, ::Hash) — Read only snapshot transactions are supported, read/write and single use transactions are not.
  • sql (::String) — Required. The query request to generate partitions for. The request will fail if the query is not root partitionable. The query plan of a root partitionable query has a single distributed union operator. A distributed union operator conceptually divides one or more tables into multiple splits, remotely evaluates a subquery independently on each split, and then unions all results.

    This must not contain DML commands, such as INSERT, UPDATE, or DELETE. Use ExecuteStreamingSql with a PartitionedDml transaction for large, partition-friendly DML operations.

  • params (::Google::Protobuf::Struct, ::Hash) — 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 can contain letters, numbers, and underscores.

    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 is an error to execute a SQL statement with unbound parameters.

  • param_types (::Hash{::String => ::Google::Cloud::Spanner::V1::Type, ::Hash}) — It is not 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, param_types can be used to specify the exact SQL type for some or all of the SQL query parameters. See the definition of Type for more information about SQL types.

  • partition_options (::Google::Cloud::Spanner::V1::PartitionOptions, ::Hash) — Additional options that affect how many partitions are created.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/spanner/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Spanner::V1::Spanner::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Spanner::V1::PartitionQueryRequest.new

# Call the partition_query method.
result = client.partition_query request

# The returned object is of type Google::Cloud::Spanner::V1::PartitionResponse.
p result

#partition_read

def partition_read(request, options = nil) -> ::Google::Cloud::Spanner::V1::PartitionResponse
def partition_read(session: nil, transaction: nil, table: nil, index: nil, columns: nil, key_set: nil, partition_options: nil) -> ::Google::Cloud::Spanner::V1::PartitionResponse

Creates a set of partition tokens that can be used to execute a read operation in parallel. Each of the returned partition tokens can be used by StreamingRead to specify a subset of the read result to read. The same session and read-only transaction must be used by the PartitionReadRequest used to create the partition tokens and the ReadRequests that use the partition tokens. There are no ordering guarantees on rows returned among the returned partition tokens, or even within each individual StreamingRead call issued with a partition_token.

Partition tokens become invalid when the session used to create them is deleted, is idle for too long, begins a new transaction, or becomes too old. When any of these happen, it is not possible to resume the read, and the whole operation must be restarted from the beginning.

Overloads 
def partition_read(request, options = nil) -> ::Google::Cloud::Spanner::V1::PartitionResponse
Pass arguments to partition_read via a request object, either of type PartitionReadRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Spanner::V1::PartitionReadRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def partition_read(session: nil, transaction: nil, table: nil, index: nil, columns: nil, key_set: nil, partition_options: nil) -> ::Google::Cloud::Spanner::V1::PartitionResponse
Pass arguments to partition_read via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • session (::String) — Required. The session used to create the partitions.
  • transaction (::Google::Cloud::Spanner::V1::TransactionSelector, ::Hash) — Read only snapshot transactions are supported, read/write and single use transactions are not.
  • table (::String) — Required. The name of the table in the database to be read.
  • index (::String) — If non-empty, the name of an index on table. This index is used instead of the table primary key when interpreting key_set and sorting result rows. See key_set for further information.
  • columns (::Array<::String>) — The columns of table to be returned for each row matching this request.
  • key_set (::Google::Cloud::Spanner::V1::KeySet, ::Hash) — Required. key_set identifies the rows to be yielded. key_set names the primary keys of the rows in table to be yielded, unless index is present. If index is present, then key_set instead names index keys in index.

    It is not an error for the key_set to name rows that do not exist in the database. Read yields nothing for nonexistent rows.

  • partition_options (::Google::Cloud::Spanner::V1::PartitionOptions, ::Hash) — Additional options that affect how many partitions are created.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/spanner/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Spanner::V1::Spanner::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Spanner::V1::PartitionReadRequest.new

# Call the partition_read method.
result = client.partition_read request

# The returned object is of type Google::Cloud::Spanner::V1::PartitionResponse.
p result

#read

def read(request, options = nil) -> ::Google::Cloud::Spanner::V1::ResultSet
def read(session: nil, transaction: nil, table: nil, index: nil, columns: nil, key_set: nil, limit: nil, resume_token: nil, partition_token: nil, request_options: nil) -> ::Google::Cloud::Spanner::V1::ResultSet

Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteSql. This method cannot be used to return a result set larger than 10 MiB; if the read matches more data than that, the read fails with a FAILED_PRECONDITION error.

Reads inside read-write transactions might return ABORTED. If this occurs, the application should restart the transaction from the beginning. See Transaction for more details.

Larger result sets can be yielded in streaming fashion by calling StreamingRead instead.

Overloads 
def read(request, options = nil) -> ::Google::Cloud::Spanner::V1::ResultSet
Pass arguments to read via a request object, either of type ReadRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Spanner::V1::ReadRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def read(session: nil, transaction: nil, table: nil, index: nil, columns: nil, key_set: nil, limit: nil, resume_token: nil, partition_token: nil, request_options: nil) -> ::Google::Cloud::Spanner::V1::ResultSet
Pass arguments to read via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • session (::String) — Required. The session in which the read should be performed.
  • transaction (::Google::Cloud::Spanner::V1::TransactionSelector, ::Hash) — The transaction to use. If none is provided, the default is a temporary read-only transaction with strong concurrency.
  • table (::String) — Required. The name of the table in the database to be read.
  • index (::String) — If non-empty, the name of an index on table. This index is used instead of the table primary key when interpreting key_set and sorting result rows. See key_set for further information.
  • columns (::Array<::String>) — Required. The columns of table to be returned for each row matching this request.
  • key_set (::Google::Cloud::Spanner::V1::KeySet, ::Hash) — Required. key_set identifies the rows to be yielded. key_set names the primary keys of the rows in table to be yielded, unless index is present. If index is present, then key_set instead names index keys in index.

    If the partition_token field is empty, rows are yielded in table primary key order (if index is empty) or index key order (if index is non-empty). If the partition_token field is not empty, rows will be yielded in an unspecified order.

    It is not an error for the key_set to name rows that do not exist in the database. Read yields nothing for nonexistent rows.

  • limit (::Integer) — If greater than zero, only the first limit rows are yielded. If limit is zero, the default is no limit. A limit cannot be specified if partition_token is set.
  • resume_token (::String) — If this request is resuming a previously interrupted read, resume_token should be copied from the last PartialResultSet yielded before the interruption. Doing this enables the new read to resume where the last read left off. The rest of the request parameters must exactly match the request that yielded this token.
  • partition_token (::String) — If present, results will be restricted to the specified partition previously created using PartitionRead(). There must be an exact match for the values of fields common to this message and the PartitionReadRequest message used to create this partition_token.
  • request_options (::Google::Cloud::Spanner::V1::RequestOptions, ::Hash) — Common options for this request.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/spanner/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Spanner::V1::Spanner::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Spanner::V1::ReadRequest.new

# Call the read method.
result = client.read request

# The returned object is of type Google::Cloud::Spanner::V1::ResultSet.
p result

#rollback

def rollback(request, options = nil) -> ::Google::Protobuf::Empty
def rollback(session: nil, transaction_id: nil) -> ::Google::Protobuf::Empty

Rolls back a transaction, releasing any locks it holds. It is a good idea to call this for any transaction that includes one or more Read or ExecuteSql requests and ultimately decides not to commit.

Rollback returns OK if it successfully aborts the transaction, the transaction was already aborted, or the transaction is not found. Rollback never returns ABORTED.

Overloads 
def rollback(request, options = nil) -> ::Google::Protobuf::Empty
Pass arguments to rollback via a request object, either of type RollbackRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Spanner::V1::RollbackRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def rollback(session: nil, transaction_id: nil) -> ::Google::Protobuf::Empty
Pass arguments to rollback via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • session (::String) — Required. The session in which the transaction to roll back is running.
  • transaction_id (::String) — Required. The transaction to roll back.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/spanner/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Spanner::V1::Spanner::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Spanner::V1::RollbackRequest.new

# Call the rollback method.
result = client.rollback request

# The returned object is of type Google::Protobuf::Empty.
p result

#streaming_read

def streaming_read(request, options = nil) -> ::Enumerable<::Google::Cloud::Spanner::V1::PartialResultSet>
def streaming_read(session: nil, transaction: nil, table: nil, index: nil, columns: nil, key_set: nil, limit: nil, resume_token: nil, partition_token: nil, request_options: nil) -> ::Enumerable<::Google::Cloud::Spanner::V1::PartialResultSet>

Like Read, except returns the result set as a stream. Unlike Read, 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.

Overloads 
def streaming_read(request, options = nil) -> ::Enumerable<::Google::Cloud::Spanner::V1::PartialResultSet>
Pass arguments to streaming_read via a request object, either of type ReadRequest or an equivalent Hash.
Parameters
  • request (::Google::Cloud::Spanner::V1::ReadRequest, ::Hash) — A request object representing the call parameters. Required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash.
  • options (::Gapic::CallOptions, ::Hash) — Overrides the default settings for this call, e.g, timeout, retries, etc. Optional. 
def streaming_read(session: nil, transaction: nil, table: nil, index: nil, columns: nil, key_set: nil, limit: nil, resume_token: nil, partition_token: nil, request_options: nil) -> ::Enumerable<::Google::Cloud::Spanner::V1::PartialResultSet>
Pass arguments to streaming_read via keyword arguments. Note that at least one keyword argument is required. To specify no parameters, or to keep all the default parameter values, pass an empty Hash as a request object (see above).
Parameters
  • session (::String) — Required. The session in which the read should be performed.
  • transaction (::Google::Cloud::Spanner::V1::TransactionSelector, ::Hash) — The transaction to use. If none is provided, the default is a temporary read-only transaction with strong concurrency.
  • table (::String) — Required. The name of the table in the database to be read.
  • index (::String) — If non-empty, the name of an index on table. This index is used instead of the table primary key when interpreting key_set and sorting result rows. See key_set for further information.
  • columns (::Array<::String>) — Required. The columns of table to be returned for each row matching this request.
  • key_set (::Google::Cloud::Spanner::V1::KeySet, ::Hash) — Required. key_set identifies the rows to be yielded. key_set names the primary keys of the rows in table to be yielded, unless index is present. If index is present, then key_set instead names index keys in index.

    If the partition_token field is empty, rows are yielded in table primary key order (if index is empty) or index key order (if index is non-empty). If the partition_token field is not empty, rows will be yielded in an unspecified order.

    It is not an error for the key_set to name rows that do not exist in the database. Read yields nothing for nonexistent rows.

  • limit (::Integer) — If greater than zero, only the first limit rows are yielded. If limit is zero, the default is no limit. A limit cannot be specified if partition_token is set.
  • resume_token (::String) — If this request is resuming a previously interrupted read, resume_token should be copied from the last PartialResultSet yielded before the interruption. Doing this enables the new read to resume where the last read left off. The rest of the request parameters must exactly match the request that yielded this token.
  • partition_token (::String) — If present, results will be restricted to the specified partition previously created using PartitionRead(). There must be an exact match for the values of fields common to this message and the PartitionReadRequest message used to create this partition_token.
  • request_options (::Google::Cloud::Spanner::V1::RequestOptions, ::Hash) — Common options for this request.
Yields
  • (response, operation) — Access the result along with the RPC operation
Yield Parameters
Returns
Raises
  • (::Google::Cloud::Error) — if the RPC is aborted.
Example

Basic example

require "google/cloud/spanner/v1"

# Create a client object. The client can be reused for multiple calls.
client = Google::Cloud::Spanner::V1::Spanner::Client.new

# Create a request. To set request fields, pass in keyword arguments.
request = Google::Cloud::Spanner::V1::ReadRequest.new

# Call the streaming_read method.
result = client.streaming_read request

# The returned object is a streamed enumerable yielding elements of
# type ::Google::Cloud::Spanner::V1::PartialResultSet.
result.each do |response|
  p response
end