Class: Google::Cloud::Spanner::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/spanner/client.rb

Overview

Client

A client is used to read and/or modify data in a Cloud Spanner database.

See Project#client.

Examples:

require "google/cloud"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

db.transaction do |tx|
  results = tx.execute_query "SELECT * FROM users"

  results.rows.each do |row|
    puts "User #{row[:id]} is #{row[:name]}"
  end
end

Instance Method Summary collapse

Instance Method Details

#close ⇒ Object

Closes the client connection and releases resources.



1481
1482
1483
 
# File 'lib/google/cloud/spanner/client.rb', line 1481

def close
  @pool.close
end

#commit(call_options: nil) {|commit| ... } ⇒ Time

Creates and commits a transaction for writes that execute atomically at a single logical point in time across columns, rows, and tables in a database.

All changes are accumulated in memory until the block completes. Unlike #transaction, which can also perform reads, this operation accepts only mutations and makes a single API request.

Note: This method does not feature replay protection present in #transaction. This method makes a single RPC, whereas #transaction requires two RPCs (one of which may be performed in advance), and so this method may be appropriate for latency sensitive and/or high throughput blind changes.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

db.commit do |c|
  c.update "users", [{ id: 1, name: "Charlie", active: false }]
  c.insert "users", [{ id: 2, name: "Harvey",  active: true }]
end

Parameters:

  • call_options (Hash) (defaults to: nil) —

    A hash of values to specify the custom call options, e.g., timeout, retries, etc. Call options are optional. The following settings can be provided:

    • :timeout (Numeric) A numeric value of custom timeout in seconds that overrides the default setting.
    • :retry_policy (Hash) A hash of values that overrides the default setting of retry policy with the following keys:
      • :initial_delay (Numeric) - The initial delay in seconds.
      • :max_delay (Numeric) - The max delay in seconds.
      • :multiplier (Numeric) - The incremental backoff multiplier.
      • :retry_codes (Array<String>) - The error codes that should trigger a retry.

Yields:

  • (commit) —

    The block for mutating the data.

Yield Parameters:

Returns:

  • (Time) —

    The timestamp at which the operation committed.

Raises:

  • (ArgumentError) 


1095
1096
1097
1098
1099
1100
1101
 
# File 'lib/google/cloud/spanner/client.rb', line 1095

def commit call_options: nil, &block
  raise ArgumentError, "Must provide a block" unless block_given?

  @pool.with_session do |session|
    session.commit(call_options: call_options, &block)
  end
end

#commit_timestamp ⇒ ColumnValue

Creates a column value object representing setting a field's value to the timestamp of the commit. (See Google::Cloud::Spanner::ColumnValue.commit_timestamp)

This placeholder value can only be used for timestamp columns that have set the option "(allow_commit_timestamp=true)" in the schema.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

# create column value object
commit_timestamp = db.commit_timestamp

db.commit do |c|
  c.insert "users", [
    { id: 5, name: "Murphy", updated_at: commit_timestamp }
  ]
end

Returns:

  • (ColumnValue) —

    The commit timestamp column value object.



1474
1475
1476
 
# File 'lib/google/cloud/spanner/client.rb', line 1474

def commit_timestamp
  ColumnValue.commit_timestamp
end

#database ⇒ Database

The Spanner database connected to.

Returns:



97
98
99
 
# File 'lib/google/cloud/spanner/client.rb', line 97

def database
  @project.database instance_id, database_id
end

#database_id ⇒ String

The unique identifier for the database.

Returns:

  • (String) 


79
80
81
 
# File 'lib/google/cloud/spanner/client.rb', line 79

def database_id
  @database_id
end

#delete(table, keys = [], call_options: nil) ⇒ Time

Deletes rows from a table. Succeeds whether or not the specified rows were present.

Changes are made immediately upon calling this method using a single-use transaction. To make multiple changes in the same single-use transaction use #commit. To make changes in a transaction that supports reads and automatic retry protection use #transaction.

Note: This method does not feature replay protection present in Transaction#delete (See #transaction). This method makes a single RPC, whereas Transaction#delete requires two RPCs (one of which may be performed in advance), and so this method may be appropriate for latency sensitive and/or high throughput blind deletions.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

db.delete "users", [1, 2, 3]

Parameters:

  • table (String) —

    The name of the table in the database to be modified.

  • keys (Object, Array<Object>) (defaults to: []) —

    A single, or list of keys or key ranges to match returned data to. Values should have exactly as many elements as there are columns in the primary key.

  • call_options (Hash) (defaults to: nil) —

    A hash of values to specify the custom call options, e.g., timeout, retries, etc. Call options are optional. The following settings can be provided:

    • :timeout (Numeric) A numeric value of custom timeout in seconds that overrides the default setting.
    • :retry_policy (Hash) A hash of values that overrides the default setting of retry policy with the following keys:
      • :initial_delay (Numeric) - The initial delay in seconds.
      • :max_delay (Numeric) - The max delay in seconds.
      • :multiplier (Numeric) - The incremental backoff multiplier.
      • :retry_codes (Array<String>) - The error codes that should trigger a retry.

Returns:

  • (Time) —

    The timestamp at which the operation committed.



1043
1044
1045
1046
1047
 
# File 'lib/google/cloud/spanner/client.rb', line 1043

def delete table, keys = [], call_options: nil
  @pool.with_session do |session|
    session.delete table, keys, call_options: call_options
  end
end

#execute_partition_update(sql, params: nil, types: nil, query_options: nil, call_options: nil) ⇒ Integer Also known as: execute_pdml

Executes a Partitioned DML SQL statement.

Partitioned DML is an alternate implementation with looser semantics to enable large-scale changes without running into transaction size limits or (accidentally) locking the entire table in one large transaction. At a high level, it partitions the keyspace and executes the statement on each partition in separate internal transactions.

Partitioned DML does not guarantee database-wide atomicity of the statement - it guarantees row-based atomicity, which includes updates to any indices. Additionally, it does not guarantee that it will execute exactly one time against each row - it guarantees "at least once" semantics.

Where DML statements must be executed using Transaction (see Transaction#execute_update), Paritioned DML statements are executed outside of a read/write transaction.

Not all DML statements can be executed in the Partitioned DML mode and the backend will return an error for the statements which are not supported.

DML statements must be fully-partitionable. Specifically, the statement must be expressible as the union of many statements which each access only a single row of the table. InvalidArgumentError is raised if the statement does not qualify.

The method will block until the update is complete. Running a DML statement with this method does not offer exactly once semantics, and therefore the DML statement should be idempotent. The DML statement must be fully-partitionable. Specifically, the statement must be expressible as the union of many statements which each access only a single row of the table. This is a Partitioned DML transaction in which a single Partitioned DML statement is executed. Partitioned DML partitions the and runs the DML statement over each partition in parallel using separate, internal transactions that commit independently. Partitioned DML transactions do not need to be committed.

Partitioned DML updates are used to execute a single DML statement with a different execution strategy that provides different, and often better, scalability properties for large, table-wide operations than DML in a Transaction#execute_update transaction. Smaller scoped statements, such as an OLTP workload, should prefer using Transaction#execute_update.

That said, Partitioned DML is not a drop-in replacement for standard DML used in Transaction#execute_update.

  • The DML statement must be fully-partitionable. Specifically, the statement must be expressible as the union of many statements which each access only a single row of the table.
  • The statement is not applied atomically to all rows of the table. Rather, the statement is applied atomically to partitions of the table, in independent internal transactions. Secondary index rows are updated atomically with the base table rows.
  • Partitioned DML does not guarantee exactly-once execution semantics against a partition. The statement will be applied at least once to each partition. It is strongly recommended that the DML statement should be idempotent to avoid unexpected results. For instance, it is potentially dangerous to run a statement such as UPDATE table SET column = column + 1 as it could be run multiple times against some rows.
  • The partitions are committed automatically - there is no support for Commit or Rollback. If the call returns an error, or if the client issuing the DML statement dies, it is possible that some rows had the statement executed on them successfully. It is also possible that statement was never executed against other rows.
  • If any error is encountered during the execution of the partitioned DML operation (for instance, a UNIQUE INDEX violation, division by zero, or a value that cannot be stored due to schema constraints), then the operation is stopped at that point and an error is returned. It is possible that at this point, some partitions have been committed (or even committed multiple times), and other partitions have not been run at all.

Given the above, Partitioned DML is good fit for large, database-wide, operations that are idempotent, such as deleting old rows from a very large table.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

row_count = db.execute_partition_update \
 "UPDATE users SET friends = NULL WHERE active = false"

Query using query parameters:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

row_count = db.execute_partition_update \
 "UPDATE users SET friends = NULL WHERE active = @active",
 params: { active: false }

Query using query options:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

row_count = db.execute_partition_update \
 "UPDATE users SET friends = NULL WHERE active = false",
 query_options: { optimizer_version: "1" }

Query using custom timeout and retry policy:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

timeout = 30.0
retry_policy = {
  initial_delay: 0.25,
  max_delay:     32.0,
  multiplier:    1.3,
  retry_codes:   ["UNAVAILABLE"]
}
call_options = { timeout: timeout, retry_policy: retry_policy }

row_count = db.execute_partition_update \
 "UPDATE users SET friends = NULL WHERE active = false",
 call_options: call_options

Parameters:

  • sql (String) —

    The Partitioned DML statement string. See Query syntax.

    The Partitioned DML statement string can contain parameter placeholders. A parameter placeholder consists of "@" followed by the parameter name. Parameter names consist of any combination of letters, numbers, and underscores.

  • params (Hash) (defaults to: nil) —

    Parameters for the Partitioned DML statement string. The parameter placeholders, minus the "@", are the the hash keys, and the literal values are the hash values. If the query string contains something like "WHERE id > @msg_id", then the params must contain something like :msg_id => 1.

    Ruby types are mapped to Spanner types as follows:

    Spanner Ruby Notes
    BOOL true/false
    INT64 Integer
    FLOAT64 Float
    STRING String
    DATE Date
    TIMESTAMP Time, DateTime
    BYTES File, IO, StringIO, or similar
    ARRAY Array Nested arrays are not supported.
    STRUCT Hash, Data

    See Data types.

    See Data Types - Constructing a STRUCT.

  • types (Hash) (defaults to: nil) —

    Types of the SQL parameters in params. It is not always possible for Cloud Spanner to infer the right SQL type from a value in params. In these cases, the types hash can be used to specify the exact SQL type for some or all of the SQL query parameters.

    The keys of the hash should be query string parameter placeholders, minus the "@". The values of the hash should be Cloud Spanner type codes from the following list:

    • :BOOL
    • :BYTES
    • :DATE
    • :FLOAT64
    • :INT64
    • :STRING
    • :TIMESTAMP
    • Array - Lists are specified by providing the type code in an array. For example, an array of integers are specified as [:INT64].
    • Fields - Nested Structs are specified by providing a Fields object.
  • query_options (Hash) (defaults to: nil) —

    A hash of values to specify the custom query options for executing SQL query. Query options are optional. The following settings can be provided:

    • :optimizer_version (String) The version of optimizer to use. Empty to use database default. "latest" to use the latest available optimizer version.
  • call_options (Hash) (defaults to: nil) —

    A hash of values to specify the custom call options, e.g., timeout, retries, etc. Call options are optional. The following settings can be provided:

    • :timeout (Numeric) A numeric value of custom timeout in seconds that overrides the default setting.
    • :retry_policy (Hash) A hash of values that overrides the default setting of retry policy with the following keys:
      • :initial_delay (Numeric) - The initial delay in seconds.
      • :max_delay (Numeric) - The max delay in seconds.
      • :multiplier (Numeric) - The incremental backoff multiplier.
      • :retry_codes (Array<String>) - The error codes that should trigger a retry.

Returns:

  • (Integer) —

    The lower bound number of rows that were modified.



600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
 
# File 'lib/google/cloud/spanner/client.rb', line 600

def execute_partition_update sql, params: nil, types: nil,
                             query_options: nil, call_options: nil
  ensure_service!

  params, types = Convert.to_input_params_and_types params, types
  results = nil
  @pool.with_session do |session|
    results = session.execute_query \
      sql, params: params, types: types,
      transaction: pdml_transaction(session),
      query_options: query_options, call_options: call_options
  end
  # Stream all PartialResultSet to get ResultSetStats
  results.rows.to_a
  # Raise an error if there is not a row count returned
  if results.row_count.nil?
    raise Google::Cloud::InvalidArgumentError,
          "Partitioned DML statement is invalid."
  end
  results.row_count
end

#execute_query(sql, params: nil, types: nil, single_use: nil, query_options: nil, call_options: nil) ⇒ Google::Cloud::Spanner::Results Also known as: execute, query, execute_sql

Executes a SQL query.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

results = db.execute_query "SELECT * FROM users"

results.rows.each do |row|
  puts "User #{row[:id]} is #{row[:name]}"
end

Query using query parameters:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

results = db.execute_query(
  "SELECT * FROM users WHERE active = @active",
  params: { active: true }
)

results.rows.each do |row|
  puts "User #{row[:id]} is #{row[:name]}"
end

Query with a SQL STRUCT query parameter as a Hash:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

user_hash = { id: 1, name: "Charlie", active: false }

results = db.execute_query(
  "SELECT * FROM users WHERE " \
  "ID = @user_struct.id " \
  "AND name = @user_struct.name " \
  "AND active = @user_struct.active",
  params: { user_struct: user_hash }
)

results.rows.each do |row|
  puts "User #{row[:id]} is #{row[:name]}"
end

Specify the SQL STRUCT type using Fields object:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

user_type = db.fields id: :INT64, name: :STRING, active: :BOOL
user_hash = { id: 1, name: nil, active: false }

results = db.execute_query(
  "SELECT * FROM users WHERE " \
  "ID = @user_struct.id " \
  "AND name = @user_struct.name " \
  "AND active = @user_struct.active",
  params: { user_struct: user_hash },
  types: { user_struct: user_type }
)

results.rows.each do |row|
  puts "User #{row[:id]} is #{row[:name]}"
end

Or, query with a SQL STRUCT as a typed Data object:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

user_type = db.fields id: :INT64, name: :STRING, active: :BOOL
user_data = user_type.struct id: 1, name: nil, active: false

results = db.execute_query(
  "SELECT * FROM users WHERE " \
  "ID = @user_struct.id " \
  "AND name = @user_struct.name " \
  "AND active = @user_struct.active",
  params: { user_struct: user_data }
)

results.rows.each do |row|
  puts "User #{row[:id]} is #{row[:name]}"
end

Query using query options:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

results = db.execute_query \
  "SELECT * FROM users", query_options: { optimizer_version: "1" }

results.rows.each do |row|
  puts "User #{row[:id]} is #{row[:name]}"
end

Query using custom timeout and retry policy:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

timeout = 30.0
retry_policy = {
  initial_delay: 0.25,
  max_delay:     32.0,
  multiplier:    1.3,
  retry_codes:   ["UNAVAILABLE"]
}
call_options = { timeout: timeout, retry_policy: retry_policy }

results = db.execute_query \
  "SELECT * FROM users", call_options: call_options

results.rows.each do |row|
  puts "User #{row[:id]} is #{row[:name]}"
end

Parameters:

  • sql (String) —

    The SQL query string. See Query syntax.

    The SQL query string can contain parameter placeholders. A parameter placeholder consists of "@" followed by the parameter name. Parameter names consist of any combination of letters, numbers, and underscores.

  • params (Hash) (defaults to: nil) —

    SQL parameters for the query string. The parameter placeholders, minus the "@", are the the hash keys, and the literal values are the hash values. If the query string contains something like "WHERE id > @msg_id", then the params must contain something like :msg_id => 1.

    Ruby types are mapped to Spanner types as follows:

    Spanner Ruby Notes
    BOOL true/false
    INT64 Integer
    FLOAT64 Float
    STRING String
    DATE Date
    TIMESTAMP Time, DateTime
    BYTES File, IO, StringIO, or similar
    ARRAY Array Nested arrays are not supported.
    STRUCT Hash, Data

    See Data types.

    See Data Types - Constructing a STRUCT.

  • types (Hash) (defaults to: nil) —

    Types of the SQL parameters in params. It is not always possible for Cloud Spanner to infer the right SQL type from a value in params. In these cases, the types hash must be used to specify the SQL type for these values.

    The keys of the hash should be query string parameter placeholders, minus the "@". The values of the hash should be Cloud Spanner type codes from the following list:

    • :BOOL
    • :BYTES
    • :DATE
    • :FLOAT64
    • :INT64
    • :STRING
    • :TIMESTAMP
    • Array - Lists are specified by providing the type code in an array. For example, an array of integers are specified as [:INT64].
    • Fields - Types for STRUCT values (Hash/Data objects) are specified using a Fields object.

    Types are optional.

  • single_use (Hash) (defaults to: nil) —

    Perform the read with a single-use snapshot (read-only transaction). (See TransactionOptions.) The snapshot can be created by providing exactly one of the following options in the hash:

    • Strong
      • :strong (true, false) Read at a timestamp where all previously committed transactions are visible.

    • Exact

      • :timestamp/:read_timestamp (Time, 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 will block 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.

      • :staleness/:exact_staleness (Numeric) Executes all reads at a timestamp that is exactly the number of seconds provided 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 single-use bounded_staleness.

    • Bounded

      • :bounded_timestamp/:min_read_timestamp (Time, DateTime) Executes all reads at a timestamp greater than the value provided.

      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.

      • :bounded_staleness/:max_staleness (Numeric) Read data at a timestamp greater than or equal to the number of seconds provided. 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.

  • query_options (Hash) (defaults to: nil) —

    A hash of values to specify the custom query options for executing SQL query. Query options are optional. The following settings can be provided:

    • :optimizer_version (String) The version of optimizer to use. Empty to use database default. "latest" to use the latest available optimizer version.
  • call_options (Hash) (defaults to: nil) —

    A hash of values to specify the custom call options, e.g., timeout, retries, etc. Call options are optional. The following settings can be provided:

    • :timeout (Numeric) A numeric value of custom timeout in seconds that overrides the default setting.
    • :retry_policy (Hash) A hash of values that overrides the default setting of retry policy with the following keys:
      • :initial_delay (Numeric) - The initial delay in seconds.
      • :max_delay (Numeric) - The max delay in seconds.
      • :multiplier (Numeric) - The incremental backoff multiplier.
      • :retry_codes (Array<String>) - The error codes that should trigger a retry.

Returns:



374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
 
# File 'lib/google/cloud/spanner/client.rb', line 374

def execute_query sql, params: nil, types: nil, single_use: nil,
                  query_options: nil, call_options: nil
  validate_single_use_args! single_use
  ensure_service!

  params, types = Convert.to_input_params_and_types params, types

  single_use_tx = single_use_transaction single_use
  results = nil
  @pool.with_session do |session|
    results = session.execute_query \
      sql, params: params, types: types, transaction: single_use_tx,
      query_options: query_options, call_options: call_options
  end
  results
end

#fields(types) ⇒ Fields

Creates a configuration object (Fields) that may be provided to queries or used to create STRUCT objects. (The STRUCT will be represented by the Data class.) See #execute and/or Fields#struct.

For more information, see Data Types - Constructing a STRUCT.

Examples:

Create a STRUCT value with named fields using Fields object:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

named_type = db.fields(
  { id: :INT64, name: :STRING, active: :BOOL }
)
named_data = named_type.struct(
  { id: 42, name: nil, active: false }
)

Create a STRUCT value with anonymous field names:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

anon_type = db.fields [:INT64, :STRING, :BOOL]
anon_data = anon_type.struct [42, nil, false]

Create a STRUCT value with duplicate field names:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

dup_type = db.fields [[:x, :INT64], [:x, :STRING], [:x, :BOOL]]
dup_data = dup_type.struct [42, nil, false]

Parameters:

  • types (Array, Hash) —

    Accepts an array or hash types.

    Arrays can contain just the type value, or a sub-array of the field's name and type value. Hash keys must contain the field name as a Symbol or String, or the field position as an Integer. Hash values must contain the type value. If a Hash is used the fields will be created using the same order as the Hash keys.

    Supported type values incude:

    • :BOOL
    • :BYTES
    • :DATE
    • :FLOAT64
    • :INT64
    • :STRING
    • :TIMESTAMP
    • Array - Lists are specified by providing the type code in an array. For example, an array of integers are specified as [:INT64].
    • Fields - Nested Structs are specified by providing a Fields object.

Returns:

  • (Fields) —

    The fields of the given types.



1386
1387
1388
 
# File 'lib/google/cloud/spanner/client.rb', line 1386

def fields types
  Fields.new types
end

#insert(table, *rows) ⇒ Time

Inserts new rows in a table. If any of the rows already exist, the write or request fails with AlreadyExistsError.

Changes are made immediately upon calling this method using a single-use transaction. To make multiple changes in the same single-use transaction use #commit. To make changes in a transaction that supports reads and automatic retry protection use #transaction.

Note: This method does not feature replay protection present in Transaction#insert (See #transaction). This method makes a single RPC, whereas Transaction#insert requires two RPCs (one of which may be performed in advance), and so this method may be appropriate for latency sensitive and/or high throughput blind inserts.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

db.insert "users", [{ id: 1, name: "Charlie", active: false },
                    { id: 2, name: "Harvey",  active: true }]

Parameters:

  • table (String) —

    The name of the table in the database to be modified.

  • rows (Array<Hash>) —

    One or more hash objects with the hash keys matching the table's columns, and the hash values matching the table's values.

    Ruby types are mapped to Spanner types as follows:

    Spanner Ruby Notes
    BOOL true/false
    INT64 Integer
    FLOAT64 Float
    STRING String
    DATE Date
    TIMESTAMP Time, DateTime
    BYTES File, IO, StringIO, or similar
    ARRAY Array Nested arrays are not supported.

    See Data types.

Returns:

  • (Time) —

    The timestamp at which the operation committed.



880
881
882
883
884
 
# File 'lib/google/cloud/spanner/client.rb', line 880

def insert table, *rows
  @pool.with_session do |session|
    session.insert table, rows
  end
end

#instance ⇒ Instance

The Spanner instance connected to.

Returns:



91
92
93
 
# File 'lib/google/cloud/spanner/client.rb', line 91

def instance
  @project.instance instance_id
end

#instance_id ⇒ String

The unique identifier for the instance.

Returns:

  • (String) 


73
74
75
 
# File 'lib/google/cloud/spanner/client.rb', line 73

def instance_id
  @instance_id
end

#project ⇒ Project

The Spanner project connected to.

Returns:



85
86
87
 
# File 'lib/google/cloud/spanner/client.rb', line 85

def project
  @project
end

#project_id ⇒ String

The unique identifier for the project.

Returns:

  • (String) 


67
68
69
 
# File 'lib/google/cloud/spanner/client.rb', line 67

def project_id
  @project.service.project
end

#query_options ⇒ Hash

A hash of values to specify the custom query options for executing SQL query.

Returns:

  • (Hash) 


104
105
106
 
# File 'lib/google/cloud/spanner/client.rb', line 104

def query_options
  @query_options
end

#range(beginning, ending, exclude_begin: false, exclude_end: false) ⇒ Google::Cloud::Spanner::Range

Creates a Spanner Range. This can be used in place of a Ruby Range when needing to exclude the beginning value.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

key_range = db.range 1, 100
results = db.read "users", [:id, :name], keys: key_range

results.rows.each do |row|
  puts "User #{row[:id]} is #{row[:name]}"
end

Parameters:

  • beginning (Object) —

    The object that defines the beginning of the range.

  • ending (Object) —

    The object that defines the end of the range.

  • exclude_begin (Boolean) (defaults to: false) —

    Determines if the range excludes its beginning value. Default is false.

  • exclude_end (Boolean) (defaults to: false) —

    Determines if the range excludes its ending value. Default is false.

Returns:



1443
1444
1445
1446
1447
 
# File 'lib/google/cloud/spanner/client.rb', line 1443

def range beginning, ending, exclude_begin: false, exclude_end: false
  Range.new beginning, ending,
            exclude_begin: exclude_begin,
            exclude_end: exclude_end
end

#read(table, columns, keys: nil, index: nil, limit: nil, single_use: nil, call_options: nil) ⇒ Google::Cloud::Spanner::Results

Read rows from a database table, as a simple alternative to #execute_query.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

results = db.read "users", [:id, :name]

results.rows.each do |row|
  puts "User #{row[:id]} is #{row[:name]}"
end

Use the keys option to pass keys and/or key ranges to read.

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

results = db.read "users", [:id, :name], keys: 1..5

results.rows.each do |row|
  puts "User #{row[:id]} is #{row[:name]}"
end

Read using custom timeout and retry.

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

timeout = 30.0
retry_policy = {
  initial_delay: 0.25,
  max_delay:     32.0,
  multiplier:    1.3,
  retry_codes:   ["UNAVAILABLE"]
}
call_options = { timeout: timeout, retry_policy: retry_policy }

results = db.read "users", [:id, :name], call_options: call_options

results.rows.each do |row|
  puts "User #{row[:id]} is #{row[:name]}"
end

Parameters:

  • table (String) —

    The name of the table in the database to be read.

  • columns (Array<String, Symbol>) —

    The columns of table to be returned for each row matching this request.

  • keys (Object, Array<Object>) (defaults to: nil) —

    A single, or list of keys or key ranges to match returned data to. Values should have exactly as many elements as there are columns in the primary key.

  • index (String) (defaults to: nil) —

    The name of an index to use instead of the table's primary key when interpreting id and sorting result rows. Optional.

  • limit (Integer) (defaults to: nil) —

    If greater than zero, no more than this number of rows will be returned. The default is no limit.

  • single_use (Hash) (defaults to: nil) —

    Perform the read with a single-use snapshot (read-only transaction). (See TransactionOptions.) The snapshot can be created by providing exactly one of the following options in the hash:

    • Strong
      • :strong (true, false) Read at a timestamp where all previously committed transactions are visible.

    • Exact

      • :timestamp/:read_timestamp (Time, 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 will block 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.

      • :staleness/:exact_staleness (Numeric) Executes all reads at a timestamp that is exactly the number of seconds provided 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 single-use bounded_staleness.

    • Bounded

      • :bounded_timestamp/:min_read_timestamp (Time, DateTime) Executes all reads at a timestamp greater than the value provided.

      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.

      • :bounded_staleness/:max_staleness (Numeric) Read data at a timestamp greater than or equal to the number of seconds provided. 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.

  • call_options (Hash) (defaults to: nil) —

    A hash of values to specify the custom call options, e.g., timeout, retries, etc. Call options are optional. The following settings can be provided:

    • :timeout (Numeric) A numeric value of custom timeout in seconds that overrides the default setting.
    • :retry_policy (Hash) A hash of values that overrides the default setting of retry policy with the following keys:
      • :initial_delay (Numeric) - The initial delay in seconds.
      • :max_delay (Numeric) - The max delay in seconds.
      • :multiplier (Numeric) - The incremental backoff multiplier.
      • :retry_codes (Array<String>) - The error codes that should trigger a retry.

Returns:



755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
 
# File 'lib/google/cloud/spanner/client.rb', line 755

def read table, columns, keys: nil, index: nil, limit: nil,
         single_use: nil, call_options: nil
  validate_single_use_args! single_use
  ensure_service!

  columns = Array(columns).map(&:to_s)
  keys = Convert.to_key_set keys

  single_use_tx = single_use_transaction single_use
  results = nil
  @pool.with_session do |session|
    results = session.read \
      table, columns, keys: keys, index: index, limit: limit,
                      transaction: single_use_tx,
                      call_options: call_options
  end
  results
end

#replace(table, *rows) ⇒ Time

Inserts or replaces rows in a table. If any of the rows already exist, it is deleted, and the column values provided are inserted instead. Unlike #upsert, this means any values not explicitly written become NULL.

Changes are made immediately upon calling this method using a single-use transaction. To make multiple changes in the same single-use transaction use #commit. To make changes in a transaction that supports reads and automatic retry protection use #transaction.

Note: This method does not feature replay protection present in Transaction#replace (See #transaction). This method makes a single RPC, whereas Transaction#replace requires two RPCs (one of which may be performed in advance), and so this method may be appropriate for latency sensitive and/or high throughput blind replaces.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

db.replace "users", [{ id: 1, name: "Charlie", active: false },
                     { id: 2, name: "Harvey",  active: true }]

Parameters:

  • table (String) —

    The name of the table in the database to be modified.

  • rows (Array<Hash>) —

    One or more hash objects with the hash keys matching the table's columns, and the hash values matching the table's values.

    Ruby types are mapped to Spanner types as follows:

    Spanner Ruby Notes
    BOOL true/false
    INT64 Integer
    FLOAT64 Float
    STRING String
    DATE Date
    TIMESTAMP Time, DateTime
    BYTES File, IO, StringIO, or similar
    ARRAY Array Nested arrays are not supported.

    See Data types.

Returns:

  • (Time) —

    The timestamp at which the operation committed.



992
993
994
995
996
 
# File 'lib/google/cloud/spanner/client.rb', line 992

def replace table, *rows
  @pool.with_session do |session|
    session.replace table, rows
  end
end

#reset ⇒ Object

Reset the client sessions.



1488
1489
1490
 
# File 'lib/google/cloud/spanner/client.rb', line 1488

def reset
  @pool.reset
end

#snapshot(strong: nil, timestamp: nil, read_timestamp: nil, staleness: nil, exact_staleness: nil, call_options: nil) {|snapshot| ... } ⇒ Object

Creates a snapshot read-only transaction for reads that execute atomically at a single logical point in time across columns, rows, and tables in a database. For transactions that only read, snapshot read-only transactions provide simpler semantics and are almost always faster than read-write transactions.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

db.snapshot do |snp|
  results = snp.execute_query "SELECT * FROM users"

  results.rows.each do |row|
    puts "User #{row[:id]} is #{row[:name]}"
  end
end

Parameters:

  • strong (true, false) (defaults to: nil) —

    Read at a timestamp where all previously committed transactions are visible.

  • timestamp (Time, DateTime) (defaults to: nil) —

    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 will block 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. (See TransactionOptions.)

  • read_timestamp (Time, DateTime) (defaults to: nil) —

    Same as timestamp.

  • staleness (Numeric) (defaults to: nil) —

    Executes all reads at a timestamp that is staleness seconds old. For example, the number 10.1 is translated to 10 seconds and 100 milliseconds.

    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 single-use staleness. (See TransactionOptions.)

  • exact_staleness (Numeric) (defaults to: nil) —

    Same as staleness.

  • call_options (Hash) (defaults to: nil) —

    A hash of values to specify the custom call options, e.g., timeout, retries, etc. Call options are optional. The following settings can be provided:

    • :timeout (Numeric) A numeric value of custom timeout in seconds that overrides the default setting.
    • :retry_policy (Hash) A hash of values that overrides the default setting of retry policy with the following keys:
      • :initial_delay (Numeric) - The initial delay in seconds.
      • :max_delay (Numeric) - The max delay in seconds.
      • :multiplier (Numeric) - The incremental backoff multiplier.
      • :retry_codes (Array<String>) - The error codes that should trigger a retry.

Yields:

  • (snapshot) —

    The block for reading and writing data.

Yield Parameters:



1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
 
# File 'lib/google/cloud/spanner/client.rb', line 1289

def snapshot strong: nil, timestamp: nil, read_timestamp: nil,
             staleness: nil, exact_staleness: nil, call_options: nil
  validate_snapshot_args! strong: strong, timestamp: timestamp,
                          read_timestamp: read_timestamp,
                          staleness: staleness,
                          exact_staleness: exact_staleness

  ensure_service!
  unless Thread.current[:transaction_id].nil?
    raise "Nested snapshots are not allowed"
  end

  @pool.with_session do |session|
    begin
      snp_grpc = @project.service.create_snapshot \
        session.path, strong: strong,
                      timestamp: (timestamp || read_timestamp),
                      staleness: (staleness || exact_staleness),
                      call_options: call_options
      Thread.current[:transaction_id] = snp_grpc.id
      snp = Snapshot.from_grpc snp_grpc, session
      yield snp if block_given?
    ensure
      Thread.current[:transaction_id] = nil
    end
  end
  nil
end

#transaction(deadline: 120, call_options: nil) {|transaction| ... } ⇒ Time

Creates a transaction for reads and writes that execute atomically at a single logical point in time across columns, rows, and tables in a database.

The transaction will always commit unless an error is raised. If the error raised is Rollback the transaction method will return without passing on the error. All other errors will be passed on.

All changes are accumulated in memory until the block completes. Transactions will be automatically retried when possible, until deadline is reached. This operation makes separate API requests to begin and commit the transaction.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

db.transaction do |tx|
  results = tx.execute_query "SELECT * FROM users"

  results.rows.each do |row|
    puts "User #{row[:id]} is #{row[:name]}"
  end

  tx.update "users", [{ id: 1, name: "Charlie", active: false }]
  tx.insert "users", [{ id: 2, name: "Harvey",  active: true }]
end

Manually rollback the transaction using Rollback:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
db = spanner.client "my-instance", "my-database"

db.transaction do |tx|
  tx.update "users", [{ id: 1, name: "Charlie", active: false }]
  tx.insert "users", [{ id: 2, name: "Harvey",  active: true }]

  if something_wrong?
    # Rollback the transaction without passing on the error
    # outside of the transaction method.
    raise Google::Cloud::Spanner::Rollback
  end
end

Parameters:

  • deadline (Numeric) (defaults to: 120) —

    The total amount of time in seconds the transaction has to succeed. The default is 120.

  • call_options (Hash) (defaults to: nil) —

    A hash of values to specify the custom call options, e.g., timeout, retries, etc. Call options are optional. The following settings can be provided:

    • :timeout (Numeric) A numeric value of custom timeout in seconds that overrides the default setting.
    • :retry_policy (Hash) A hash of values that overrides the default setting of retry policy with the following keys:
      • :initial_delay (Numeric) - The initial delay in seconds.
      • :max_delay (Numeric) - The max delay in seconds.
      • :multiplier (Numeric) - The incremental backoff multiplier.
      • :retry_codes (Array<String>) - The error codes that should trigger a retry.

Yields:

  • (transaction) —

    The block for reading and writing data.

Yield Parameters:

Returns:

  • (Time) —

    The timestamp at which the transaction committed.



1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
 
# File 'lib/google/cloud/spanner/client.rb', line 1176

def transaction deadline: 120, call_options: nil
  ensure_service!
  unless Thread.current[:transaction_id].nil?
    raise "Nested transactions are not allowed"
  end

  deadline = validate_deadline deadline
  backoff = 1.0
  start_time = current_time

  @pool.with_transaction do |tx|
    begin
      Thread.current[:transaction_id] = tx.transaction_id
      yield tx
      commit_resp = @project.service.commit \
        tx.session.path, tx.mutations,
        transaction_id: tx.transaction_id, call_options: call_options
      return Convert.timestamp_to_time commit_resp.commit_timestamp
    rescue GRPC::Aborted, Google::Cloud::AbortedError => err
      # Re-raise if deadline has passed
      if current_time - start_time > deadline
        if err.is_a? GRPC::BadStatus
          err = Google::Cloud::Error.from_error err
        end
        raise err
      end
      # Sleep the amount from RetryDelay, or incremental backoff
      sleep(delay_from_aborted(err) || backoff *= 1.3)
      # Create new transaction on the session and retry the block
      tx = tx.session.create_transaction
      retry
    rescue StandardError => err
      # Rollback transaction when handling unexpected error
      tx.session.rollback tx.transaction_id
      # Return nil if raised with rollback.
      return nil if err.is_a? Rollback
      # Re-raise error.
      raise err
    ensure
      Thread.current[:transaction_id] = nil
    end
  end
end

#update(table, *rows) ⇒ Time

Updates existing rows in a table. If any of the rows does not already exist, the request fails with NotFoundError.

Changes are made immediately upon calling this method using a single-use transaction. To make multiple changes in the same single-use transaction use #commit. To make changes in a transaction that supports reads and automatic retry protection use #transaction.

Note: This method does not feature replay protection present in Transaction#update (See #transaction). This method makes a single RPC, whereas Transaction#update requires two RPCs (one of which may be performed in advance), and so this method may be appropriate for latency sensitive and/or high throughput blind updates.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

db.update "users", [{ id: 1, name: "Charlie", active: false },
                    { id: 2, name: "Harvey",  active: true }]

Parameters:

  • table (String) —

    The name of the table in the database to be modified.

  • rows (Array<Hash>) —

    One or more hash objects with the hash keys matching the table's columns, and the hash values matching the table's values.

    Ruby types are mapped to Spanner types as follows:

    Spanner Ruby Notes
    BOOL true/false
    INT64 Integer
    FLOAT64 Float
    STRING String
    DATE Date
    TIMESTAMP Time, DateTime
    BYTES File, IO, StringIO, or similar
    ARRAY Array Nested arrays are not supported.

    See Data types.

Returns:

  • (Time) —

    The timestamp at which the operation committed.



935
936
937
938
939
 
# File 'lib/google/cloud/spanner/client.rb', line 935

def update table, *rows
  @pool.with_session do |session|
    session.update table, rows
  end
end

#upsert(table, *rows) ⇒ Time Also known as: save

Inserts or updates rows in a table. If any of the rows already exist, then its column values are overwritten with the ones provided. Any column values not explicitly written are preserved.

Changes are made immediately upon calling this method using a single-use transaction. To make multiple changes in the same single-use transaction use #commit. To make changes in a transaction that supports reads and automatic retry protection use #transaction.

Note: This method does not feature replay protection present in Transaction#upsert (See #transaction). This method makes a single RPC, whereas Transaction#upsert requires two RPCs (one of which may be performed in advance), and so this method may be appropriate for latency sensitive and/or high throughput blind upserts.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

db.upsert "users", [{ id: 1, name: "Charlie", active: false },
                    { id: 2, name: "Harvey",  active: true }]

Parameters:

  • table (String) —

    The name of the table in the database to be modified.

  • rows (Array<Hash>) —

    One or more hash objects with the hash keys matching the table's columns, and the hash values matching the table's values.

    Ruby types are mapped to Spanner types as follows:

    Spanner Ruby Notes
    BOOL true/false
    INT64 Integer
    FLOAT64 Float
    STRING String
    DATE Date
    TIMESTAMP Time, DateTime
    BYTES File, IO, StringIO, or similar
    ARRAY Array Nested arrays are not supported.

    See Data types.

Returns:

  • (Time) —

    The timestamp at which the operation committed.



824
825
826
827
828
 
# File 'lib/google/cloud/spanner/client.rb', line 824

def upsert table, *rows
  @pool.with_session do |session|
    session.upsert table, rows
  end
end