Class: Google::Cloud::Spanner::Snapshot

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

Overview

# Snapshot

A snapshot in Cloud Spanner is a set of reads that execute atomically at a single logical point in time across columns, rows, and tables in a database.

Examples:

require "google/cloud/spanner"

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

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

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#session ⇒ Object 



45
46
47
 
# File 'lib/google/cloud/spanner/snapshot.rb', line 45

def session
  @session
end

Class Method Details

.from_grpc(grpc, session) ⇒ Object

Google::Spanner::V1::Transaction.



387
388
389
390
391
392
 
# File 'lib/google/cloud/spanner/snapshot.rb', line 387

def self.from_grpc grpc, session
  new.tap do |s|
    s.instance_variable_set :@grpc,    grpc
    s.instance_variable_set :@session, session
  end
end

Instance Method Details

#execute(sql, params: nil, types: nil) ⇒ Google::Cloud::Spanner::Results Also known as: query

Executes a SQL query.

Examples:

require "google/cloud/spanner"

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

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

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

Query using query parameters:

require "google/cloud/spanner"

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

db.snapshot do |snp|
  results = snp.execute "SELECT * FROM users " \
                        "WHERE active = @active",
                        params: { active: true }

  results.rows.each do |row|
    puts "User #{row[:id]} is #{row[:name]}"
  end
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"

db.snapshot do |snp|
   user_hash = { id: 1, name: "Charlie", active: false }

  results = snp.execute "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
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"

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

  results = snp.execute "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
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"

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

  results = snp.execute "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
end

Parameters:

  • sql (String) —

    The SQL query string. See [Query syntax](cloud.google.com/spanner/docs/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](cloud.google.com/spanner/docs/data-definition-language#data_types).

    See [Data Types - Constructing a STRUCT](cloud.google.com/spanner/docs/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.

Returns:



217
218
219
220
221
222
223
224
 
# File 'lib/google/cloud/spanner/snapshot.rb', line 217

def execute sql, params: nil, types: nil
  ensure_session!

  params, types = Convert.to_input_params_and_types params, types

  session.execute sql, params: params, types: types,
                       transaction: tx_selector
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 Client#execute and/or Fields#struct.

For more information, see [Data Types - Constructing a STRUCT](cloud.google.com/spanner/docs/data-types#constructing-a-struct).

See [Data Types - Constructing a STRUCT](cloud.google.com/spanner/docs/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"

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

Create a STRUCT value with anonymous field names:

require "google/cloud/spanner"

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

db.snapshot do |snp|
  anon_type = snp.fields [:INT64, :STRING, :BOOL]
  anon_data = anon_type.struct [42, nil, false]
end

Create a STRUCT value with duplicate field names:

require "google/cloud/spanner"

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

db.snapshot do |snp|
  dup_type = snp.fields [[:x, :INT64], [:x, :STRING], [:x, :BOOL]]
  dup_data = dup_type.struct [42, nil, false]
end

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.



345
346
347
 
# File 'lib/google/cloud/spanner/snapshot.rb', line 345

def fields types
  Fields.new types
end

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

Creates a Cloud 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"

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

  results.rows.each do |row|
    puts "User #{row[:id]} is #{row[:name]}"
  end
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:



378
379
380
381
382
 
# File 'lib/google/cloud/spanner/snapshot.rb', line 378

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) ⇒ Google::Cloud::Spanner::Results

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

Examples:

require "google/cloud/spanner"

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

db.snapshot do |snp|
  results = snp.read "users", [:id, :name]

  results.rows.each do |row|
    puts "User #{row[:id]} is #{row[:name]}"
  end
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.

Returns:



261
262
263
264
265
266
267
268
269
 
# File 'lib/google/cloud/spanner/snapshot.rb', line 261

def read table, columns, keys: nil, index: nil, limit: 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
end

#timestamp ⇒ Time

The read timestamp chosen for snapshots.

Returns:

  • (Time) —

    The chosen timestamp.



58
59
60
61
 
# File 'lib/google/cloud/spanner/snapshot.rb', line 58

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

#transaction_id ⇒ String

Identifier of the transaction results were run in.

Returns:

  • (String) —

    The transaction id.



50
51
52
53
 
# File 'lib/google/cloud/spanner/snapshot.rb', line 50

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