google-cloud-spanner 0.21.0

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

@@ -0,0 +1,351 @@
+# Copyright 2017 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google/cloud/spanner/data"
+require "google/cloud/spanner/convert"
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # # Commit
+      #
+      # Accepts mutations for execution within a transaction. All writes will
+      # execute atomically at a single logical point in time across columns,
+      # rows, and tables in a database.
+      #
+      # All changes are accumulated in memory until the block passed to
+      # {Client#commit} completes.
+      #
+      # @example
+      #   require "google/cloud/spanner"
+      #
+      #   spanner = Google::Cloud::Spanner.new
+      #
+      #   db = spanner.client "my-instance", "my-database"
+      #
+      #   db.commit do |c|
+      #     c.update "users", [{ id: 1, name: "Charlie", active: false }]
+      #     c.insert "users", [{ id: 2, name: "Harvey",  active: true }]
+      #   end
+      #
+      class Commit
+        ##
+        # @private
+        def initialize
+          @mutations = []
+        end
+
+        ##
+        # Inserts or updates rows in a table. If any of the rows already exist,
+        # then its column values are overwritten with the ones provided. Any
+        # column values not explicitly written are preserved.
+        #
+        # All changes are accumulated in memory until the block passed to
+        # {Client#commit} completes.
+        #
+        # @param [String] table The name of the table in the database to be
+        #   modified.
+        # @param [Array<Hash>] rows One or more hash objects with the hash keys
+        #   matching the table's columns, and the hash values matching the
+        #   table's values.
+        #
+        #   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).
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.commit do |c|
+        #     c.upsert "users", [{ id: 1, name: "Charlie", active: false },
+        #                        { id: 2, name: "Harvey",  active: true }]
+        #   end
+        #
+        def upsert table, *rows
+          rows = Array(rows).flatten
+          return rows if rows.empty?
+          rows.delete_if(&:nil?)
+          rows.delete_if(&:empty?)
+          @mutations += rows.map do |row|
+            Google::Spanner::V1::Mutation.new(
+              insert_or_update: Google::Spanner::V1::Mutation::Write.new(
+                table: table, columns: row.keys.map(&:to_s),
+                values: [Convert.raw_to_value(row.values).list_value]
+              )
+            )
+          end
+          rows
+        end
+        alias_method :save, :upsert
+
+        ##
+        # Inserts new rows in a table. If any of the rows already exist, the
+        # write or request fails with error {Google::Cloud::AlreadyExistsError}.
+        #
+        # All changes are accumulated in memory until the block passed to
+        # {Client#commit} completes.
+        #
+        # @param [String] table The name of the table in the database to be
+        #   modified.
+        # @param [Array<Hash>] rows One or more hash objects with the hash keys
+        #   matching the table's columns, and the hash values matching the
+        #   table's values.
+        #
+        #   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).
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.commit do |c|
+        #     c.insert "users", [{ id: 1, name: "Charlie", active: false },
+        #                        { id: 2, name: "Harvey",  active: true }]
+        #   end
+        #
+        def insert table, *rows
+          rows = Array(rows).flatten
+          return rows if rows.empty?
+          rows.delete_if(&:nil?)
+          rows.delete_if(&:empty?)
+          @mutations += rows.map do |row|
+            Google::Spanner::V1::Mutation.new(
+              insert: Google::Spanner::V1::Mutation::Write.new(
+                table: table, columns: row.keys.map(&:to_s),
+                values: [Convert.raw_to_value(row.values).list_value]
+              )
+            )
+          end
+          rows
+        end
+
+        ##
+        # Updates existing rows in a table. If any of the rows does not already
+        # exist, the request fails with error {Google::Cloud::NotFoundError}.
+        #
+        # All changes are accumulated in memory until the block passed to
+        # {Client#commit} completes.
+        #
+        # @param [String] table The name of the table in the database to be
+        #   modified.
+        # @param [Array<Hash>] rows One or more hash objects with the hash keys
+        #   matching the table's columns, and the hash values matching the
+        #   table's values.
+        #
+        #   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).
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.commit do |c|
+        #     c.update "users", [{ id: 1, name: "Charlie", active: false },
+        #                        { id: 2, name: "Harvey",  active: true }]
+        #   end
+        #
+        def update table, *rows
+          rows = Array(rows).flatten
+          return rows if rows.empty?
+          rows.delete_if(&:nil?)
+          rows.delete_if(&:empty?)
+          @mutations += rows.map do |row|
+            Google::Spanner::V1::Mutation.new(
+              update: Google::Spanner::V1::Mutation::Write.new(
+                table: table, columns: row.keys.map(&:to_s),
+                values: [Convert.raw_to_value(row.values).list_value]
+              )
+            )
+          end
+          rows
+        end
+
+        ##
+        # Inserts or replaces rows in a table. If any of the rows already exist,
+        # it is deleted, and the column values provided are inserted instead.
+        # Unlike #upsert, this means any values not explicitly written become
+        # `NULL`.
+        #
+        # All changes are accumulated in memory until the block passed to
+        # {Client#commit} completes.
+        #
+        # @param [String] table The name of the table in the database to be
+        #   modified.
+        # @param [Array<Hash>] rows One or more hash objects with the hash keys
+        #   matching the table's columns, and the hash values matching the
+        #   table's values.
+        #
+        #   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).
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.commit do |c|
+        #     c.replace "users", [{ id: 1, name: "Charlie", active: false },
+        #                        { id: 2, name: "Harvey",  active: true }]
+        #   end
+        #
+        def replace table, *rows
+          rows = Array(rows).flatten
+          return rows if rows.empty?
+          rows.delete_if(&:nil?)
+          rows.delete_if(&:empty?)
+          @mutations += rows.map do |row|
+            Google::Spanner::V1::Mutation.new(
+              replace: Google::Spanner::V1::Mutation::Write.new(
+                table: table, columns: row.keys.map(&:to_s),
+                values: [Convert.raw_to_value(row.values).list_value]
+              )
+            )
+          end
+          rows
+        end
+
+        ##
+        # Deletes rows from a table. Succeeds whether or not the specified rows
+        # were present.
+        #
+        # All changes are accumulated in memory until the block passed to
+        # {Client#commit} completes.
+        #
+        # @param [String] table The name of the table in the database to be
+        #   modified.
+        # @param [Object, Array<Object>] keys 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.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   db.commit do |c|
+        #     c.delete "users", [1, 2, 3]
+        #   end
+        #
+        def delete table, keys = []
+          @mutations += [
+            Google::Spanner::V1::Mutation.new(
+              delete: Google::Spanner::V1::Mutation::Delete.new(
+                table: table, key_set: key_set(keys))
+            )
+          ]
+          keys
+        end
+
+        # @private
+        def mutations
+          @mutations
+        end
+
+        protected
+
+        def key_set keys
+          return Google::Spanner::V1::KeySet.new(all: true) if keys.nil?
+          keys = [keys] unless keys.is_a? Array
+          return Google::Spanner::V1::KeySet.new(all: true) if keys.empty?
+          if keys_are_ranges? keys
+            keys = [keys] unless keys.is_a? Array
+            key_ranges = keys.map do |r|
+              Convert.to_key_range(r)
+            end
+            return Google::Spanner::V1::KeySet.new(ranges: key_ranges)
+          end
+          key_list = Array(keys).map do |i|
+            Convert.raw_to_value(Array(i)).list_value
+          end
+          Google::Spanner::V1::KeySet.new keys: key_list
+        end
+
+        def keys_are_ranges? keys
+          keys.each do |key|
+            return true if key.is_a? ::Range
+            return true if key.is_a? Google::Cloud::Spanner::Range
+          end
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,311 @@
+# Copyright 2017 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "time"
+require "date"
+require "stringio"
+require "base64"
+require "google/cloud/spanner/data"
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # @private Helper module for converting Spanner values.
+      module Convert
+        # rubocop:disable all
+
+        module ClassMethods
+          def to_query_params params, types = nil
+            types ||= {}
+            formatted_params = params.map do |key, obj|
+              [String(key), raw_to_value_and_type(obj, types[key])]
+            end
+            Hash[formatted_params]
+          end
+
+          def raw_to_value_and_type obj, type = nil
+            if NilClass === obj
+              if type
+                if type.is_a?(Array) && type.count == 1
+                  [Google::Protobuf::Value.new(null_value: :NULL_VALUE),
+                   Google::Spanner::V1::Type.new(
+                     code: :ARRAY, array_element_type:
+                      Google::Spanner::V1::Type.new(code: type.first))]
+                # elsif type.is_a? Fields
+                else
+                  [Google::Protobuf::Value.new(null_value: :NULL_VALUE),
+                   Google::Spanner::V1::Type.new(code: type)]
+                end
+              else
+                raise ArgumentError, "Must provide type for nil values."
+              end
+            elsif String === obj
+              [raw_to_value(obj), Google::Spanner::V1::Type.new(code: :STRING)]
+            elsif Symbol === obj
+              [raw_to_value(obj.to_s),
+               Google::Spanner::V1::Type.new(code: :STRING)]
+            elsif TrueClass === obj
+              [raw_to_value(obj), Google::Spanner::V1::Type.new(code: :BOOL)]
+            elsif FalseClass === obj
+              [raw_to_value(obj), Google::Spanner::V1::Type.new(code: :BOOL)]
+            elsif Integer === obj
+              [raw_to_value(obj.to_s),
+               Google::Spanner::V1::Type.new(code: :INT64)]
+            elsif Numeric === obj # Any number not an integer gets to be a float
+              [raw_to_value(obj),
+               Google::Spanner::V1::Type.new(code: :FLOAT64)]
+            elsif Time === obj || DateTime === obj
+              [raw_to_value(obj),
+               Google::Spanner::V1::Type.new(code: :TIMESTAMP)]
+            elsif Date === obj
+              [raw_to_value(obj.to_s),
+               Google::Spanner::V1::Type.new(code: :DATE)]
+            elsif Array === obj
+              if type && !type.is_a?(Array)
+                raise ArgumentError, "Array values must have an Array type."
+              end
+              type ||= begin
+                # Find the param type for the first non-nil item the list
+                nested_param_value = obj.detect { |x| !x.nil? }
+                if nested_param_value.nil?
+                  raise ArgumentError, "Array values must have an Array type."
+                end
+                [raw_to_value_and_type(nested_param_value).last.code]
+              end
+              [raw_to_value(obj),
+               Google::Spanner::V1::Type.new(
+                code: :ARRAY, array_element_type:
+                  Google::Spanner::V1::Type.new(code: type.first))]
+            elsif Hash === obj
+              field_pairs = obj.map do |key, value|
+                [key, raw_to_value_and_type(value).last]
+              end
+              formatted_fields = field_pairs.map do |name, param_type|
+                Google::Spanner::V1::StructType::Field.new(
+                  name: String(name), type: param_type
+                )
+              end
+              [raw_to_value(obj),
+               Google::Spanner::V1::Type.new(
+                code: :STRUCT,
+                struct_type: Google::Spanner::V1::StructType.new(
+                  fields: formatted_fields
+                ))]
+            elsif obj.respond_to?(:read) && obj.respond_to?(:rewind)
+              obj.rewind
+              [raw_to_value(obj),
+               Google::Spanner::V1::Type.new(code: :BYTES)]
+            else
+              raise ArgumentError,
+                    "A parameter of type #{obj.class} is not supported."
+            end
+          end
+
+          def raw_to_value obj
+            if NilClass === obj
+              Google::Protobuf::Value.new null_value: :NULL_VALUE
+            elsif String === obj
+              Google::Protobuf::Value.new string_value: obj
+            elsif Symbol === obj
+              Google::Protobuf::Value.new string_value: obj.to_s
+            elsif TrueClass === obj
+              Google::Protobuf::Value.new bool_value: true
+            elsif FalseClass === obj
+              Google::Protobuf::Value.new bool_value: false
+            elsif Integer === obj
+              Google::Protobuf::Value.new string_value: obj.to_s
+            elsif Numeric === obj # Any number not an integer gets to be a float
+              if obj == Float::INFINITY
+                Google::Protobuf::Value.new string_value: "Infinity"
+              elsif obj == -Float::INFINITY
+                Google::Protobuf::Value.new string_value: "-Infinity"
+              elsif obj.respond_to?(:nan?) && obj.nan?
+                Google::Protobuf::Value.new string_value: "NaN"
+              else
+                Google::Protobuf::Value.new number_value: obj.to_f
+              end
+            elsif Time === obj || DateTime === obj
+              Google::Protobuf::Value.new(string_value:
+                obj.to_time.utc.strftime("%FT%T.%NZ"))
+            elsif Date === obj
+              Google::Protobuf::Value.new string_value: obj.to_s
+            elsif Array === obj
+              Google::Protobuf::Value.new list_value:
+                Google::Protobuf::ListValue.new(values:
+                  obj.map { |o| raw_to_value(o) })
+            elsif Hash === obj
+              Google::Protobuf::Value.new struct_value:
+                Google::Protobuf::Struct.new(fields:
+                  Hash[obj.map { |k, v| [String(k), raw_to_value(v)] }])
+            elsif obj.respond_to?(:read) && obj.respond_to?(:rewind)
+              obj.rewind
+              content = obj.read.force_encoding("ASCII-8BIT")
+              encoded_content = Base64.strict_encode64(content)
+              Google::Protobuf::Value.new(string_value: encoded_content)
+            else
+              raise ArgumentError,
+                    "A value of type #{obj.class} is not supported."
+            end
+          end
+
+          def row_to_pairs row_types, row
+            row_types.zip(row).map do |field, value|
+              [field.name.to_sym, value_to_raw(value, field.type)]
+            end
+          end
+
+          def row_to_raw row_types, row
+            Hash[row_to_pairs(row_types, row)]
+          end
+
+          def value_to_raw value, type
+            return nil if value.kind == :null_value
+            case type.code
+            when :BOOL
+              value.bool_value
+            when :INT64
+              Integer value.string_value
+            when :FLOAT64
+              if value.kind == :string_value
+                if value.string_value == "Infinity"
+                  Float::INFINITY
+                elsif value.string_value == "-Infinity"
+                  -Float::INFINITY
+                elsif value.string_value == "NaN"
+                  Float::NAN
+                else
+                  Float value.string_value
+                end
+              else
+                value.number_value
+              end
+            when :TIMESTAMP
+              Time.parse value.string_value
+            when :DATE
+              Date.parse value.string_value
+            when :STRING
+              value.string_value
+            when :BYTES
+              StringIO.new Base64.decode64 value.string_value
+            when :ARRAY
+              value.list_value.values.map do |v|
+                value_to_raw v, type.array_element_type
+              end
+            when :STRUCT
+              Data.from_grpc value.list_value.values, type.struct_type.fields
+            end
+          end
+
+          ##
+          # @private Convert an Object to a Google::Protobuf::Value.
+          def object_to_value obj
+            case obj
+            when NilClass then Google::Protobuf::Value.new null_value:
+              :NULL_VALUE
+            when Numeric then Google::Protobuf::Value.new number_value: obj
+            when String then Google::Protobuf::Value.new string_value: obj
+            when TrueClass then Google::Protobuf::Value.new bool_value: true
+            when FalseClass then Google::Protobuf::Value.new bool_value: false
+            when Hash then Google::Protobuf::Value.new struct_value:
+              hash_to_struct(obj)
+            when Array then Google::Protobuf::Value.new list_value:
+              Google::Protobuf::ListValue.new(values:
+                obj.map { |o| object_to_value(o) })
+            else
+              # TODO: Could raise ArgumentError here, or convert to a string
+              Google::Protobuf::Value.new string_value: obj.to_s
+            end
+          end
+
+          ##
+          # @private Convert a Google::Protobuf::Value to an Object.
+          def value_to_object value
+            # TODO: ArgumentError if struct is not a Google::Protobuf::Value
+            if value.kind == :null_value
+              nil
+            elsif value.kind == :number_value
+              value.number_value
+            elsif value.kind == :string_value
+              value.string_value
+            elsif value.kind == :bool_value
+              value.bool_value
+            elsif value.kind == :struct_value
+              struct_to_hash value.struct_value
+            elsif value.kind == :list_value
+              value.list_value.values.map { |v| value_to_object(v) }
+            else
+              nil # just in case
+            end
+          end
+
+          def number_to_duration number
+            return nil if number.nil?
+
+            Google::Protobuf::Duration.new \
+              seconds: number.to_i,
+              nanos: (number.remainder(1) * 1000000000).round
+          end
+
+          def duration_to_number duration
+            return nil if duration.nil?
+
+            return duration.seconds if duration.nanos == 0
+
+            duration.seconds + (duration.nanos / 1000000000.0)
+          end
+
+          def time_to_timestamp time
+            return nil if time.nil?
+
+            # Force the object to be a Time object.
+            time = time.to_time
+
+            Google::Protobuf::Timestamp.new \
+              seconds: time.to_i,
+              nanos: time.nsec
+          end
+
+          def timestamp_to_time timestamp
+            return nil if timestamp.nil?
+
+            Time.at timestamp.seconds, Rational(timestamp.nanos, 1000)
+          end
+
+          def to_key_range range
+            range_opts = {
+              start_closed: raw_to_value(Array(range.begin)).list_value,
+              end_closed: raw_to_value(Array(range.end)).list_value }
+
+            if range.respond_to?(:exclude_begin?) && range.exclude_begin?
+              range_opts[:start_open] = range_opts[:start_closed]
+              range_opts.delete :start_closed
+            end
+            if range.exclude_end?
+              range_opts[:end_open] = range_opts[:end_closed]
+              range_opts.delete :end_closed
+            end
+
+            Google::Spanner::V1::KeyRange.new range_opts
+          end
+        end
+
+        # rubocop:enable all
+
+        extend ClassMethods
+      end
+    end
+  end
+end