Class: Google::Cloud::Spanner::BatchSnapshot

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

Overview

BatchSnapshot

Represents a read-only transaction that can be configured to read at timestamps in the past and allows for exporting arbitrarily large amounts of data from Cloud Spanner databases. This is a snapshot which additionally allows to partition a read or query request. The read/query request can then be executed independently over each partition while observing the same snapshot of the database. A BatchSnapshot can also be shared across multiple processes/machines by passing around its serialized value and then recreating the transaction using #dump.

Unlike locking read-write transactions, BatchSnapshot will never abort. They can fail if the chosen read timestamp is garbage collected; however any read or query activity within an hour on the transaction avoids garbage collection and most applications do not need to worry about this in practice.

See Google::Cloud::Spanner::BatchClient#batch_snapshot and Google::Cloud::Spanner::BatchClient#load_batch_snapshot.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

batch_client = spanner.batch_client "my-instance", "my-database"
batch_snapshot = batch_client.batch_snapshot

partitions = batch_snapshot.partition_read "users", [:id, :name]

partition = partitions.first
results = batch_snapshot.execute_partition partition

batch_snapshot.close

Instance Method Summary collapse

Instance Method Details

#closeObject

Closes the batch snapshot and releases the underlying resources.

This should only be called once the batch snapshot is no longer needed anywhere. In particular if this batch snapshot is being used across multiple machines, calling this method on any of the machines will render the batch snapshot invalid everywhere.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

batch_client = spanner.batch_client "my-instance", "my-database"
batch_snapshot = batch_client.batch_snapshot

partitions = batch_snapshot.partition_read "users", [:id, :name]

partition = partitions.first
results = batch_snapshot.execute_partition partition

batch_snapshot.close

407
408
409
410
411
# File 'lib/google/cloud/spanner/batch_snapshot.rb', line 407

def close
  ensure_session!

  session.release!
end

#dumpString Also known as: serialize

Serializes the batch snapshot object so it can be recreated on another process. See Google::Cloud::Spanner::BatchClient#load_batch_snapshot.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

batch_client = spanner.batch_client "my-instance", "my-database"

batch_snapshot = batch_client.batch_snapshot

partitions = batch_snapshot.partition_read "users", [:id, :name]

partition = partitions.first

serialized_snapshot = batch_snapshot.dump
serialized_partition = partition.dump

# In a separate process
new_batch_snapshot = batch_client.load_batch_snapshot \
  serialized_snapshot

new_partition = batch_client.load_partition \
  serialized_partition

results = new_batch_snapshot.execute_partition \
  new_partition

Returns:

  • (String)

    The serialized representation of the batch snapshot.


759
760
761
# File 'lib/google/cloud/spanner/batch_snapshot.rb', line 759

def dump
  JSON.dump to_h
end

#execute_partition(partition, call_options: nil) ⇒ Object

Execute the partition to return a Results. The result returned could be zero or more rows. The row metadata may be absent if no rows are returned.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

batch_client = spanner.batch_client "my-instance", "my-database"
batch_snapshot = batch_client.batch_snapshot

partitions = batch_snapshot.partition_read "users", [:id, :name]

partition = partitions.first
results = batch_snapshot.execute_partition partition

batch_snapshot.close

Parameters:

  • partition (Google::Cloud::Spanner::Partition)

    The partition to be executed.

  • 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.

367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
# File 'lib/google/cloud/spanner/batch_snapshot.rb', line 367

def execute_partition partition, call_options: nil
  ensure_session!

  partition = Partition.load partition unless partition.is_a? Partition
  # TODO: raise if partition.empty?

  # TODO: raise if session.path != partition.session
  # TODO: raise if grpc.transaction != partition.transaction

  opts = { call_options: call_options }
  if partition.execute?
    execute_partition_query partition, **opts
  elsif partition.read?
    execute_partition_read partition, **opts
  end
end

#execute_query(sql, params: nil, types: 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
batch_client = spanner.batch_client "my-instance", "my-database"
batch_snapshot = batch_client.batch_snapshot

results = batch_snapshot.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
batch_client = spanner.batch_client "my-instance", "my-database"
batch_snapshot = batch_client.batch_snapshot

results = batch_snapshot.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
batch_client = spanner.batch_client "my-instance", "my-database"
batch_snapshot = batch_client.batch_snapshot

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

results = batch_snapshot.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
batch_client = spanner.batch_client "my-instance", "my-database"
batch_snapshot = batch_client.batch_snapshot

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

results = batch_snapshot.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
batch_client = spanner.batch_client "my-instance", "my-database"
batch_snapshot = batch_client.batch_snapshot

user_type = batch_client.fields(
  { id: :INT64, name: :STRING, active: :BOOL }
)
user_data = user_type.struct id: 1, name: nil, active: false

results = batch_snapshot.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
batch_client = spanner.batch_client "my-instance", "my-database"
batch_snapshot = batch_client.batch_snapshot

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

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
batch_client = spanner.batch_client "my-instance", "my-database"
batch_snapshot = batch_client.batch_snapshot

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 = batch_snapshot.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.

  • 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.
    • :optimizer_statistics_package (String) Statistics package to use. Empty to use the database default.
  • 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:


639
640
641
642
643
644
645
646
647
648
649
# File 'lib/google/cloud/spanner/batch_snapshot.rb', line 639

def execute_query sql, params: nil, types: nil, query_options: nil,
                  call_options: nil
  ensure_session!

  params, types = Convert.to_input_params_and_types params, types

  session.execute_query sql, params: params, types: types,
                        transaction: tx_selector,
                        query_options: query_options,
                        call_options: call_options
end

#partition_query(sql, params: nil, types: nil, partition_size_bytes: nil, max_partitions: nil, query_options: nil, call_options: nil) ⇒ Array<Google::Cloud::Spanner::Partition>

Returns a list of Partition objects to execute a batch query against a database.

These partitions can be executed across multiple processes, even across different machines. The partition size and count can be configured, although the values given may not necessarily be honored depending on the query and options in the request.

The query must have a single distributed union operator at the root of the query plan. Such queries are root-partitionable. If a query cannot be partitioned at the root, Cloud Spanner cannot achieve the parallelism and in this case partition generation will fail.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

batch_client = spanner.batch_client "my-instance", "my-database"
batch_snapshot = batch_client.batch_snapshot

sql = "SELECT u.id, u.active FROM users AS u \
       WHERE u.id < 2000 AND u.active = false"
partitions = batch_snapshot.partition_query sql

partition = partitions.first
results = batch_snapshot.execute_partition partition

batch_snapshot.close

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.

  • partition_size_bytes (Integer) (defaults to: nil)

    The desired data size for each partition generated. This is only a hint. The actual size of each partition may be smaller or larger than this size request.

  • max_partitions (Integer) (defaults to: nil)

    The desired maximum number of partitions to return. For example, this may be set to the number of workers available. This is only a hint and may provide different results based on the request.

  • 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.
    • :optimizer_statistics_package (String) Statistics package to use. Empty to use the database default.
  • 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:


212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
# File 'lib/google/cloud/spanner/batch_snapshot.rb', line 212

def partition_query sql, params: nil, types: nil,
                    partition_size_bytes: nil, max_partitions: nil,
                    query_options: nil, call_options: nil
  ensure_session!

  params, types = Convert.to_input_params_and_types params, types

  results = session.partition_query \
    sql, tx_selector, params: params, types: types,
                      partition_size_bytes: partition_size_bytes,
                      max_partitions: max_partitions,
                      call_options: call_options
  results.partitions.map do |grpc|
    # Convert partition protos to execute sql request protos
    execute_sql_grpc = V1::ExecuteSqlRequest.new(
      {
        session: session.path,
        sql: sql,
        params: params,
        param_types: types,
        transaction: tx_selector,
        partition_token: grpc.partition_token,
        query_options: query_options
      }.delete_if { |_, v| v.nil? }
    )
    Partition.from_execute_sql_grpc execute_sql_grpc
  end
end

#partition_read(table, columns, keys: nil, index: nil, partition_size_bytes: nil, max_partitions: nil, call_options: nil) ⇒ Array<Google::Cloud::Spanner::Partition>

Returns a list of Partition objects to read zero or more rows from a database.

These partitions can be executed across multiple processes, even across different machines. The partition size and count can be configured, although the values given may not necessarily be honored depending on the query and options in the request.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

batch_client = spanner.batch_client "my-instance", "my-database"
batch_snapshot = batch_client.batch_snapshot

partitions = batch_snapshot.partition_read "users", [:id, :name]

partition = partitions.first
results = batch_snapshot.execute_partition partition

batch_snapshot.close

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.

  • partition_size_bytes (Integer) (defaults to: nil)

    The desired data size for each partition generated. This is only a hint. The actual size of each partition may be smaller or larger than this size request.

  • max_partitions (Integer) (defaults to: nil)

    The desired maximum number of partitions to return. For example, this may be set to the number of workers available. This is only a hint and may provide different results based on the request.

  • 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:


299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
# File 'lib/google/cloud/spanner/batch_snapshot.rb', line 299

def partition_read table, columns, keys: nil, index: nil,
                   partition_size_bytes: nil, max_partitions: nil,
                   call_options: nil
  ensure_session!

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

  results = session.partition_read \
    table, columns, tx_selector,
    keys: keys, index: index,
    partition_size_bytes: partition_size_bytes,
    max_partitions: max_partitions,
    call_options: call_options

  results.partitions.map do |grpc|
    # Convert partition protos to read request protos
    read_grpc = V1::ReadRequest.new(
      {
        session: session.path,
        table: table,
        columns: columns,
        key_set: keys,
        index: index,
        transaction: tx_selector,
        partition_token: grpc.partition_token
      }.delete_if { |_, v| v.nil? }
    )
    Partition.from_read_grpc read_grpc
  end
end

#read(table, columns, keys: nil, index: nil, limit: 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
batch_client = spanner.batch_client "my-instance", "my-database"
batch_snapshot = batch_client.batch_snapshot

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

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.

  • 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:


700
701
702
703
704
705
706
707
708
709
710
# File 'lib/google/cloud/spanner/batch_snapshot.rb', line 700

def read table, columns, keys: nil, index: nil, limit: nil,
         call_options: nil
  ensure_session!

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

  session.read table, columns, keys: keys, index: index, limit: limit,
                               transaction: tx_selector,
                               call_options: call_options
end

#timestampTime

The read timestamp chosen for batch snapshot.

Returns:

  • (Time)

    The chosen timestamp.


86
87
88
89
# File 'lib/google/cloud/spanner/batch_snapshot.rb', line 86

def timestamp
  return nil if grpc.nil?
  Convert.timestamp_to_time grpc.read_timestamp
end

#transaction_idString

Identifier of the batch snapshot transaction.

Returns:

  • (String)

    The transaction id.


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

def transaction_id
  return nil if grpc.nil?
  grpc.id
end