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 Method Summary collapse

Instance Method Details

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

Executes a SQL query.

Arguments can be passed using params, 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.

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

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) —

    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.

  • types (Hash) —

    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

    Arrays are specified by providing the type code in an array. For example, an array of integers are specified as [:INT64].

    Structs are not yet supported in query parameters.

    Types are optional.

Returns:



152
153
154
155
156
157
158
159
 
# File 'lib/google/cloud/spanner/snapshot.rb', line 152

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

#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) —

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

  • exclude_end (Boolean) —

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

Returns:



235
236
237
238
239
 
# File 'lib/google/cloud/spanner/snapshot.rb', line 235

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>) —

    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) —

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

  • limit (Integer) —

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

Returns:



196
197
198
199
200
201
202
203
204
 
# File 'lib/google/cloud/spanner/snapshot.rb', line 196

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