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

Yields:

  • (snapshot) —

    The block for reading and writing data.

Yield Parameters:



212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 212

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, directed_read_options: @directed_read_options
end

#database ⇒ ::Google::Cloud::Spanner::Database

Deprecated.

Use Admin::Database#database_admin instead.

The Spanner database connected to.



134
135
136
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 134

def database
  @project.database instance_id, database_id
end

#database_id ⇒ String

The unique identifier for the database.



114
115
116
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 114

def database_id
  @database_id
end

#directed_read_options ⇒ Hash

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



141
142
143
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 141

def directed_read_options
  @directed_read_options
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]



382
383
384
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 382

def fields types
  Fields.new types
end

#instance ⇒ ::Google::Cloud::Spanner::Instance

Deprecated.

Use Admin::Instance#instance_admin instead.

The Spanner instance connected to.



127
128
129
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 127

def instance
  @project.instance instance_id
end

#instance_id ⇒ String

The unique identifier for the instance.



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

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



265
266
267
268
269
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 265

def load_batch_snapshot serialized_snapshot
  ensure_service!

  BatchSnapshot.load serialized_snapshot, service: @project.service, query_options: @query_options
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



306
307
308
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 306

def load_partition serialized_partition
  Partition.load serialized_partition
end

#project ⇒ Project

The Spanner project connected to.



120
121
122
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 120

def project
  @project
end

#project_id ⇒ String

The unique identifier for the project.



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

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



413
414
415
416
417
 
# File 'lib/google/cloud/spanner/batch_client.rb', line 413

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