Method: Google::Cloud::Spanner::Client#read

Defined in:

lib/google/cloud/spanner/client.rb

#read(table, columns, keys: nil, index: nil, limit: nil, single_use: nil, request_options: nil, call_options: nil, directed_read_options: nil, order_by: nil, lock_hint: nil) ⇒ Google::Cloud::Spanner::Results

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

The following settings can be provided:

• :exclude_replicas (Hash) Exclude_replicas indicates what replicas should be excluded from serving requests. Spanner will not route requests to the replicas in this list.
• :include_replicas (Hash) Include_replicas indicates the order of replicas to process the request. If auto_failover_disabled is set to true and all replicas are exhausted without finding a healthy replica, Spanner will wait for a replica in the list to become available, requests may fail due to DEADLINE_EXCEEDED errors.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

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

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

Use the keys option to pass keys and/or key ranges to read.

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

results = db.read "users", [:id, :name], keys: 1..5

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

Read using custom timeout and retry.

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

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 = db.read "users", [:id, :name], call_options: call_options

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

Using request options.

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

request_options = { priority: :PRIORITY_MEDIUM }
results = db.read "users", [:id, :name],
                  request_options: request_options

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

Read using tag for read statistics collection.

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

request_options = { tag: "Read-Users-All" }
results = db.read "users", [:id, :name],
                  request_options: request_options

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.

• single_use (Hash) (defaults to: nil) —

  Perform the read with a single-use snapshot (read-only transaction). (See TransactionOptions.) If no value is specified for this parameter, Cloud Spanner will use a single use read-only transaction with strong timestamp bound as default. The snapshot can be created by providing exactly one of the following options in the hash:

  • Strong
    • :strong (true, false) Read at a timestamp where all previously committed transactions are visible.

  • Exact

    • :timestamp/:read_timestamp (Time, DateTime) 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.

    • :staleness/:exact_staleness (Numeric) Executes all reads at a timestamp that is exactly the number of seconds provided old. The timestamp is chosen soon after the read is started.

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

  • Bounded

    • :bounded_timestamp/:min_read_timestamp (Time, DateTime) Executes all reads at a timestamp greater than the value provided.

    This is useful for requesting fresher data than some previous read, or data that is fresh enough to observe the effects of some previously committed transaction whose timestamp is known.

    • :bounded_staleness/:max_staleness (Numeric) Read data at a timestamp greater than or equal to the number of seconds provided. 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 the freshest data available at a nearby replica, while bounding the possible staleness if the local replica has fallen behind.

• request_options (Hash) (defaults to: nil) —

  Common request options.

  • :priority (Symbol) The relative priority for requests. The priority acts as a hint to the Cloud Spanner scheduler and does not guarantee priority or order of execution. Valid values are :PRIORITY_LOW, :PRIORITY_MEDIUM, :PRIORITY_HIGH. If priority not set then default is PRIORITY_UNSPECIFIED is equivalent to :PRIORITY_HIGH.
  • :tag (String) A per-request tag which can be applied to queries or reads, used for statistics collection. Tag must be a valid identifier of the form: [a-zA-Z][a-zA-Z0-9_\-] between 2 and 64 characters in length.
• 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.
• directed_read_options (Hash) (defaults to: nil) —

  Client options used to set the directed_read_options for all ReadRequests and ExecuteSqlRequests that indicates which replicas or regions should be used for non-transactional reads or queries. Will represent Google::Cloud::Spanner::V1::DirectedReadOptions

• order_by (::Google::Cloud::Spanner::V1::ReadRequest::OrderBy) (defaults to: nil) —

  An option to control the order in which rows are returned from a read. To see the available options refer to Google::Cloud::Spanner::V1::ReadRequest::OrderBy

• lock_hint (::Google::Cloud::Spanner::V1::ReadRequest::LockHint) (defaults to: nil) —

  A lock hint mechanism for reads done within a transaction. To see the available options refer to Google::Cloud::Spanner::V1::ReadRequest::LockHint

Returns:

• (Google::Cloud::Spanner::Results) —

  The results of the read.

# File 'lib/google/cloud/spanner/client.rb', line 985

def read table, columns, keys: nil, index: nil, limit: nil,
         single_use: nil, request_options: nil, call_options: nil,
         directed_read_options: nil, order_by: nil, lock_hint: nil
  validate_single_use_args! single_use
  ensure_service!

  columns = Array(columns).map(&:to_s)
  keys = Convert.to_key_set keys
  single_use_tx = single_use_transaction single_use
  route_to_leader = LARHeaders.read false
  request_options = Convert.to_request_options request_options,
                                               tag_type: :request_tag

  results = nil
  @pool.with_session do |session|
    results = session.read \
      table, columns, keys: keys, index: index, limit: limit,
                      transaction: single_use_tx,
                      request_options: request_options,
                      call_options: call_options,
                      directed_read_options: directed_read_options || @directed_read_options,
                      route_to_leader: route_to_leader,
                      order_by: order_by,
                      lock_hint: lock_hint
  end
  results
end