google-cloud-spanner 1.4.0 → 1.5.0

data/lib/google/cloud/spanner/results.rb

@@ -37,7 +37,7 @@ module Google
       #   results = db.execute "SELECT * FROM users"
       #
       #   results.fields.pairs.each do |name, type|
-      #     puts "Column #{name} is type {type}"
+      #     puts "Column #{name} is type #{type}"
       #   end
       #
       class Results
@@ -51,7 +51,8 @@ module Google
         end
 
         ##
-        # Returns the field names and types for the rows in the returned data.
+        # Returns the configuration object ({Fields}) of the names and types of
+        # the rows in the returned data.
         #
         # @return [Fields] The fields of the returned data.
         #
@@ -65,7 +66,7 @@ module Google
         #   results = db.execute "SELECT * FROM users"
         #
         #   results.fields.pairs.each do |name, type|
-        #     puts "Column #{name} is type {type}"
+        #     puts "Column #{name} is type #{type}"
         #   end
         #
         def fields

data/lib/google/cloud/spanner/session.rb

@@ -93,23 +93,6 @@ module Google
         ##
         # 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).
         #
@@ -122,11 +105,30 @@ module Google
         #   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
@@ -139,11 +141,11 @@ module Google
         #   * `: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 [Google::Spanner::V1::TransactionSelector] transaction The
@@ -180,6 +182,66 @@ module Google
         #     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
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   user_hash = { id: 1, name: "Charlie", active: false }
+        #
+        #   results = db.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
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   user_type = db.fields id: :INT64, name: :STRING, active: :BOOL
+        #   user_hash = { id: 1, name: nil, active: false }
+        #
+        #   results = db.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
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   user_type = db.fields id: :INT64, name: :STRING, active: :BOOL
+        #   user_data = user_type.struct id: 1, name: nil, active: false
+        #
+        #   results = db.execute "SELECT * FROM users WHERE " \
+        #                        "ID = @user_struct.id " \
+        #                        "AND name = @user_struct.name " \
+        #                        "AND active = @user_struct.active",
+        #                        params: { user_struct: user_struct }
+        #
+        #   results.rows.each do |row|
+        #     puts "User #{row[:id]} is #{row[:name]}"
+        #   end
+        #
         def execute sql, params: nil, types: nil, transaction: nil,
                     partition_token: nil
           ensure_service!

data/lib/google/cloud/spanner/snapshot.rb

@@ -63,23 +63,6 @@ module Google
         ##
         # 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).
         #
@@ -92,11 +75,30 @@ module Google
         #   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
@@ -109,11 +111,11 @@ module Google
         #   * `: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
@@ -149,6 +151,69 @@ module Google
         #     end
         #   end
         #
+        # @example Query with a SQL STRUCT query parameter as a Hash:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.snapshot do |snp|
+        #      user_hash = { id: 1, name: "Charlie", active: false }
+        #
+        #     results = snp.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
+        #   end
+        #
+        # @example Specify the SQL STRUCT type using Fields object:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.snapshot do |snp|
+        #      user_type = snp.fields id: :INT64, name: :STRING, active: :BOOL
+        #      user_hash = { id: 1, name: nil, active: false }
+        #
+        #     results = snp.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
+        #   end
+        #
+        # @example Or, query with a SQL STRUCT as a typed Data object:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.snapshot do |snp|
+        #      user_type = snp.fields id: :INT64, name: :STRING, active: :BOOL
+        #   user_data = user_type.struct id: 1, name: nil, active: false
+        #
+        #     results = snp.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]}"
+        #     end
+        #   end
+        #
         def execute sql, params: nil, types: nil
           ensure_session!
 
@@ -203,6 +268,84 @@ module Google
                                        transaction: tx_selector
         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).
+        #
+        # 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
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.snapshot do |snp|
+        #     named_type = snp.fields(
+        #       { id: :INT64, name: :STRING, active: :BOOL }
+        #     )
+        #     named_data = named_type.struct(
+        #       { id: 42, name: nil, active: false }
+        #     )
+        #   end
+        #
+        # @example Create a STRUCT value with anonymous field names:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.snapshot do |snp|
+        #     anon_type = snp.fields [:INT64, :STRING, :BOOL]
+        #     anon_data = anon_type.struct [42, nil, false]
+        #   end
+        #
+        # @example Create a STRUCT value with duplicate field names:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.snapshot do |snp|
+        #     dup_type = snp.fields [[:x, :INT64], [:x, :STRING], [:x, :BOOL]]
+        #     dup_data = dup_type.struct [42, nil, false]
+        #   end
+        #
+        def fields types
+          Fields.new types
+        end
+
         ##
         # Creates a Cloud Spanner Range. This can be used in place of a Ruby
         # Range when needing to exclude the beginning value.

data/lib/google/cloud/spanner/transaction.rb

@@ -92,23 +92,6 @@ module Google
         ##
         # 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).
         #
@@ -121,11 +104,30 @@ module Google
         #   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
@@ -138,11 +140,11 @@ module Google
         #   * `: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
@@ -177,6 +179,69 @@ module Google
         #     end
         #   end
         #
+        # @example Query with a SQL STRUCT query parameter as a Hash:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.transaction do |tx|
+        #     user_hash = { id: 1, name: "Charlie", active: false }
+        #
+        #     results = tx.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
+        #   end
+        #
+        # @example Specify the SQL STRUCT type using Fields object:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.transaction do |tx|
+        #     user_type = tx.fields id: :INT64, name: :STRING, active: :BOOL
+        #     user_hash = { id: 1, name: nil, active: false }
+        #
+        #     results = tx.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
+        #   end
+        #
+        # @example Or, query with a SQL STRUCT as a typed Data object:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.transaction do |tx|
+        #     user_type = tx.fields id: :INT64, name: :STRING, active: :BOOL
+        #     user_data = user_type.struct id: 1, name: nil, active: false
+        #
+        #     results = tx.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]}"
+        #     end
+        #   end
+        #
         def execute sql, params: nil, types: nil
           ensure_session!
 
@@ -468,6 +533,81 @@ module Google
           execute("SELECT * FROM #{table} WHERE 1 = 0").fields
         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
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.transaction do |tx|
+        #     named_type = tx.fields(
+        #       { id: :INT64, name: :STRING, active: :BOOL }
+        #     )
+        #     named_data = named_type.struct(
+        #       { id: 42, name: nil, active: false }
+        #     )
+        #   end
+        #
+        # @example Create a STRUCT value with anonymous field names:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.transaction do |tx|
+        #     anon_type = tx.fields [:INT64, :STRING, :BOOL]
+        #     anon_data = anon_type.struct [42, nil, false]
+        #   end
+        #
+        # @example Create a STRUCT value with duplicate field names:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.transaction do |tx|
+        #     dup_type = tx.fields [[:x, :INT64], [:x, :STRING], [:x, :BOOL]]
+        #     dup_data = dup_type.struct [42, nil, false]
+        #   end
+        #
+        def fields types
+          Fields.new types
+        end
+
         ##
         # Creates a Cloud Spanner Range. This can be used in place of a Ruby
         # Range when needing to exclude the beginning value.