Skip to content
This repository has been archived by the owner on Aug 25, 2022. It is now read-only.

Commit

Permalink
Update Fields helper and documentation
Browse files Browse the repository at this point in the history 
Add #fields convenience method to appropriate classes.
Update documentation and code examples for using Fields.
  • Loading branch information
@blowmage
blowmage committed Jun 11, 2018
1 parent f728839 commit 032d5a2
Show file tree
Hide file tree
Showing 10 changed files with 881 additions and 206 deletions.
74 changes: 74 additions & 0 deletions google-cloud-spanner/lib/google/cloud/spanner/batch_client.rb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -272,6 +272,80 @@ def load_partition serialized_partition
Partition.load serialized_partition
end

##
# 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](https://cloud.google.com/spanner/docs/data-types#constructing-a-struct).
#
# @param [Array, Hash] types 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.
#
# @return [Fields] The fields of the given types.
#
# @example 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 }
# )
#
# @example 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]
#
# @example 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]
#
def fields types
Fields.new types
end

##
# Creates a Spanner Range. This can be used in place of a Ruby Range
# when needing to exclude the beginning value.
Expand Down
169 changes: 127 additions & 42 deletions google-cloud-spanner/lib/google/cloud/spanner/batch_snapshot.rb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -112,23 +112,35 @@ def timestamp
# placeholder consists of "@" followed by the parameter name.
# Parameter names consist of any combination of letters, numbers, and
# underscores.
# @param [Integer] partition_size_bytes The desired data size for each
# partition generated. This is only a hint. The actual size of each
# partition may be smaller or larger than this size request.
# @param [Integer] max_partitions The desired maximum number of
# partitions to return. For example, this may be set to the number of
# workers available. This is only a hint and may provide different
# results based on the request.
# @param [Hash] params 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](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
#
# See [Data Types - Constructing a
# STRUCT](https://cloud.google.com/spanner/docs/data-types#constructing-a-struct).
# @param [Hash] types 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.
# 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
Expand All @@ -141,13 +153,20 @@ def timestamp
# * `: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.
# * `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.
# @param [Integer] partition_size_bytes The desired data size for each
# partition generated. This is only a hint. The actual size of each
# partition may be smaller or larger than this size request.
# @param [Integer] max_partitions The desired maximum number of
# partitions to return. For example, this may be set to the number of
# workers available. This is only a hint and may provide different
# results based on the request.
#
# @return [Array<Google::Cloud::Spanner::Partition>] The partitions
# created by the query partition.
Expand Down Expand Up @@ -342,23 +361,6 @@ def close
##
# 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](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
#
# @param [String] sql The SQL query string. See [Query
# syntax](https://cloud.google.com/spanner/docs/query-syntax).
#
Expand All @@ -371,11 +373,30 @@ def close
# 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](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
#
# See [Data Types - Constructing a
# STRUCT](https://cloud.google.com/spanner/docs/data-types#constructing-a-struct).
# @param [Hash] types 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.
# 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
Expand All @@ -388,11 +409,11 @@ def close
# * `: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.
# * `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.
# @return [Google::Cloud::Spanner::Results] The results of the query
Expand All @@ -419,8 +440,72 @@ def close
# batch_snapshot = batch_client.batch_snapshot
#
# results = batch_snapshot.execute "SELECT * FROM users " \
# "WHERE active = @active",
# params: { active: true }
# "WHERE active = @active",
# params: { active: true }
#
# results.rows.each do |row|
# puts "User #{row[:id]} is #{row[:name]}"
# end
#
# @example Query with a SQL STRUCT query parameter as a Hash:
# require "google/cloud/spanner"
#
# spanner = Google::Cloud::Spanner.new
# batch_client = spanner.batch_client "my-instance", "my-database"
# batch_snapshot = batch_client.batch_snapshot
#
# user_hash = { id: 1, name: "Charlie", active: false }
#
# results = batch_snapshot.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
#
# @example Specify the SQL STRUCT type using Fields object:
# require "google/cloud/spanner"
#
# spanner = Google::Cloud::Spanner.new
# batch_client = spanner.batch_client "my-instance", "my-database"
# batch_snapshot = batch_client.batch_snapshot
#
# user_type = batch_client.fields(
# { id: :INT64, name: :STRING, active: :BOOL }
# )
# user_hash = { id: 1, name: nil, active: false }
#
# results = batch_snapshot.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
#
# @example Or, query with a SQL STRUCT as a typed Data object:
# require "google/cloud/spanner"
#
# spanner = Google::Cloud::Spanner.new
# batch_client = spanner.batch_client "my-instance", "my-database"
# batch_snapshot = batch_client.batch_snapshot
#
# user_type = batch_client.fields(
# { id: :INT64, name: :STRING, active: :BOOL }
# )
# user_data = user_type.struct id: 1, name: nil, active: false
#
# results = batch_snapshot.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]}"
Expand Down
Loading

0 comments on commit 032d5a2

Please sign in to comment.