Class: Google::Cloud::Spanner::BatchClient

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

Overview

BatchClient

Provides a batch client that can be used to read data from a Cloud Spanner database. An instance of this class is tied to a specific database.

BatchClient is useful when one wants to read or query a large amount of data from Cloud Spanner across multiple processes, even across different machines. It allows to create partitions of Cloud Spanner database and then read or query over each partition independently yet at the same snapshot.

See Project#batch_client.

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

Instance Method Summary collapse

Instance Method Details

#batch_snapshot(strong: nil, timestamp: nil, read_timestamp: nil, staleness: nil, exact_staleness: nil) {|snapshot| ... } ⇒ Google::Cloud::Spanner::BatchSnapshot

Returns a Google::Cloud::Spanner::BatchSnapshot context in which multiple reads and/or queries can be performed. All reads/queries will use the same timestamp, and the timestamp can be inspected after this transaction is created successfully. This is a blocking method since it waits to finish the RPCs.

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

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.

Yields:

  • (snapshot) —

    The block for reading and writing data.

Yield Parameters:

Returns:



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 178

def batch_snapshot strong: nil, timestamp: nil, read_timestamp: nil,
                   staleness: nil, exact_staleness: nil
  validate_snapshot_args! strong: strong, timestamp: timestamp,
                          read_timestamp: read_timestamp,
                          staleness: staleness,
                          exact_staleness: exact_staleness

  ensure_service!
  snp_session = session
  snp_grpc = @project.service.create_snapshot \
    snp_session.path, strong: strong,
                      timestamp: (timestamp || read_timestamp),
                      staleness: (staleness || exact_staleness)
  BatchSnapshot.from_grpc snp_grpc, snp_session
end

#database ⇒ Database

The Spanner database connected to.

Returns:



107
108
109
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 107

def database
  @project.database instance_id, database_id
end

#database_id ⇒ String

The unique identifier for the database.

Returns:

  • (String) 


89
90
91
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 89

def database_id
  @database_id
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.

Examples:

Create a STRUCT value with named fields using Fields object:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

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

named_type = batch_client.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

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

anon_type = batch_client.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

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

dup_type = batch_client.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.



346
347
348
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 346

def fields types
  Fields.new types
end

#instance ⇒ Instance

The Spanner instance connected to.

Returns:



101
102
103
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 101

def instance
  @project.instance instance_id
end

#instance_id ⇒ String

The unique identifier for the instance.

Returns:

  • (String) 


83
84
85
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 83

def instance_id
  @instance_id
end

#load_batch_snapshot(serialized_snapshot) ⇒ Google::Cloud::Spanner::BatchSnapshot

Returns a Google::Cloud::Spanner::BatchSnapshot context in which multiple reads and/or queries can be performed. All reads/queries will use the same timestamp, and the timestamp can be inspected after this transaction is created successfully. This method does not perform an RPC.

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

Parameters:

Returns:



231
232
233
234
235
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 231

def load_batch_snapshot serialized_snapshot
  ensure_service!

  BatchSnapshot.load serialized_snapshot, service: @project.service
end

#load_partition(serialized_partition) ⇒ Google::Cloud::Spanner::Partition

Returns a Partition from a serialized representation. See Partition.load.

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

Parameters:

  • serialized_partition (String) —

    The serialized representation of an existing batch partition. See Partition#dump.

Returns:



272
273
274
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 272

def load_partition serialized_partition
  Partition.load serialized_partition
end

#project ⇒ Project

The Spanner project connected to.

Returns:



95
96
97
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 95

def project
  @project
end

#project_id ⇒ String

The unique identifier for the project.

Returns:

  • (String) 


77
78
79
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 77

def project_id
  @project.service.project
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

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

key_range = batch_client.range 1, 100

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

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:



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

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