google-cloud-spanner 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e9faf33e2e5945db9c82ec262ec12b68c703cdfa42413d1c2da9605bcacca88
-  data.tar.gz: dabf39029f6106cc4f3a6d126e32a46e77cf06120f41a4ecf7c0ab4460cfb6c5
+  metadata.gz: ab2f6de02b2dc38f872be9ecf0b9a538353c23457d7d82277bab5e636420b2a4
+  data.tar.gz: 31e72548e11120e24de11bf932fc5c575478ba5732e21b4610ac42fa3af695ad
 SHA512:
-  metadata.gz: a0e446f217517f5feeb2f342694d57a83981e782a6d2586ba4182b18d06c536aa24c2a2527a064d76af5e317d57ce313b6ad689422a92f2a138ade9410ef5571
-  data.tar.gz: a3ee7508a48f04a77e4b42ee809a6bdcd3134e7b25fb27349283e27e61754ae34d05d7c9a98b0fc6c66bed1deda69dd828e0fd4626c120ba9d95500b145cd1cf
+  metadata.gz: ef87329e6ccc9269a894aafaa179016269ed61a9ebcf338a51faa9a43027fdda825d05b534bda2946a101f9896dc5d98b861e714fc24aa64e5585423c0489548
+  data.tar.gz: 5d7e360cf9678935eb7d295bca0f808c942a217310d5bfb81dbc0eb3357020f2f32e8d40ef2ffa838c8faf56b882592b5d373e4261bb6ec67ec5acdb867920d4

data/lib/google/cloud/spanner.rb

@@ -40,6 +40,39 @@ module Google
     # [Authentication
     # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
     #
+    # ## Enabling Logging
+    #
+    # To enable logging for this library, set the logger for the underlying
+    # [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The
+    # logger that you set may be a Ruby stdlib
+    # [`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html)
+    # as shown below, or a
+    # [`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/cloud/logging/logger)
+    # that will write logs to [Stackdriver
+    # Logging](https://cloud.google.com/logging/). See
+    # [grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb)
+    # and the gRPC
+    # [spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb)
+    # for additional information.
+    #
+    # Configuring a Ruby stdlib logger:
+    #
+    # ```ruby
+    # require "logger"
+    #
+    # module MyLogger
+    #   LOGGER = Logger.new $stderr, level: Logger::WARN
+    #   def logger
+    #     LOGGER
+    #   end
+    # end
+    #
+    # # Define a gRPC module-level logger method before grpc/logconfig.rb loads.
+    # module GRPC
+    #   extend MyLogger
+    # end
+    # ```
+    #
     # ## Creating instances
     #
     # When you first use Cloud Spanner, you must create an instance, which is an

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

@@ -272,6 +272,80 @@ module Google
           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.

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

@@ -112,23 +112,35 @@ module Google
         #   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
@@ -141,13 +153,20 @@ 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 [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.
@@ -342,23 +361,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).
         #
@@ -371,11 +373,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
@@ -388,11 +409,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
@@ -419,8 +440,72 @@ module Google
         #   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]}"

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

@@ -98,23 +98,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).
         #
@@ -127,11 +110,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
@@ -144,11 +146,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 [Hash] single_use Perform the read with a single-use snapshot
@@ -234,6 +236,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_data }
+        #
+        #   results.rows.each do |row|
+        #     puts "User #{row[:id]} is #{row[:name]}"
+        #   end
+        #
         def execute sql, params: nil, types: nil, single_use: nil
           validate_single_use_args! single_use
           ensure_service!
@@ -855,24 +917,72 @@ module Google
         end
 
         ##
-        # @private
-        # Creates fields object from types.
+        # 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 of types, array of type
-        #   pairs, hash of positional types, hash of named types.
+        # @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
+        # @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"
+        #
+        #   named_type = db.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
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   anon_type = db.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
         #
         #   db = spanner.client "my-instance", "my-database"
-        #   user_fields = db.fields id: :INT64, name: :STRING, active: :BOOL
         #
-        #   db.update "users", [user_fields.data(1, "Charlie", false),
-        #                       user_fields.data(2, "Harvey", true)]
+        #   dup_type = db.fields [[:x, :INT64], [:x, :STRING], [:x, :BOOL]]
+        #   dup_data = dup_type.struct [42, nil, false]
         #
         def fields types
           Fields.new types