google-cloud-datastore 0.20.0

data/lib/google/cloud/datastore/errors.rb

@@ -0,0 +1,43 @@
+# Copyright 2014 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/errors"
+
+module Google
+  module Cloud
+    module Datastore
+      ##
+      # # KeyError
+      #
+      # Raised when a key is not correct.
+      class KeyError < Google::Cloud::Error
+      end
+
+      ##
+      # # PropertyError
+      #
+      # Raised when a property is not correct.
+      class PropertyError < Google::Cloud::Error
+      end
+
+      ##
+      # # TransactionError
+      #
+      # General error for Transaction problems.
+      class TransactionError < Google::Cloud::Error
+      end
+    end
+  end
+end

data/lib/google/cloud/datastore/gql_query.rb

@@ -0,0 +1,216 @@
+# Copyright 2016 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/datastore/entity"
+require "google/cloud/datastore/key"
+
+module Google
+  module Cloud
+    module Datastore
+      ##
+      # # GqlQuery
+      #
+      # Represents a GQL query.
+      #
+      # GQL is a SQL-like language for retrieving entities or keys from
+      # Datastore.
+      #
+      # @see https://cloud.google.com/datastore/docs/apis/gql/gql_reference GQL
+      #   Reference
+      #
+      # @example
+      #   gql_query = Google::Cloud::Datastore::GqlQuery.new
+      #   gql_query.query_string = "SELECT * FROM Task ORDER BY created ASC"
+      #   tasks = datastore.run gql_query
+      #
+      class GqlQuery
+        ##
+        # Returns a new GqlQuery instance.
+        #
+        # @example
+        #   gql_query = Google::Cloud::Datastore::GqlQuery.new
+        #
+        def initialize
+          @grpc = Google::Datastore::V1::GqlQuery.new
+        end
+
+        ##
+        # The GQL query string for the query. The string may contain named or
+        # positional argument binding sites that start with `@`. Corresponding
+        # binding values should be set with {#named_bindings=} or
+        # {#positional_bindings=}.
+        #
+        # @return [String] a GQL statement
+        #
+        def query_string
+          gql = @grpc.query_string.dup
+          gql.freeze
+          gql
+        end
+
+        ##
+        # Sets the GQL query string for the query. The string may contain named
+        # or positional argument binding sites that start with `@`.
+        # Corresponding binding values should be set with {#named_bindings=} or
+        # {#positional_bindings=}.
+        #
+        # See the [GQL
+        # Reference](https://cloud.google.com/datastore/docs/apis/gql/gql_reference).
+        #
+        # @param [String] new_query_string a valid GQL statement
+        #
+        # @example
+        #   gql_query = Google::Cloud::Datastore::GqlQuery.new
+        #   gql_query.query_string = "SELECT * FROM Task " \
+        #                            "WHERE done = @done " \
+        #                            "AND priority = @priority"
+        #   gql_query.named_bindings = {done: false, priority: 4}
+        #
+        def query_string= new_query_string
+          @grpc.query_string = new_query_string.to_s
+        end
+
+        ##
+        # Whether the query may contain literal values. When false, the query
+        # string must not contain any literals and instead must bind all values
+        # using {#named_bindings=} or {#positional_bindings=}.
+        #
+        # @return [Boolean] `true` if the query may contain literal values
+        #
+        def allow_literals
+          @grpc.allow_literals
+        end
+
+        ##
+        # Sets whether the query may contain literal values. When false, the
+        # query string must not contain any literals and instead must bind all
+        # values using {#named_bindings=} or {#positional_bindings=}.
+        #
+        # @param [Boolean] new_allow_literals `true` if the query may contain
+        #   literal values
+        #
+        # @example
+        #   gql_query = Google::Cloud::Datastore::GqlQuery.new
+        #   gql_query.query_string = "SELECT * FROM Task " \
+        #                            "WHERE completed = false AND priority = 4"
+        #   gql_query.allow_literals = true
+        #
+        def allow_literals= new_allow_literals
+          @grpc.allow_literals = new_allow_literals
+        end
+
+        ##
+        # The named binding values for a query that contains named argument
+        # binding sites that start with `@`.
+        #
+        # @return [Hash] a frozen hash that maps the binding site names in the
+        #   query string to valid GQL arguments
+        #
+        def named_bindings
+          bindings = Hash[@grpc.named_bindings.map do |name, gql_query_param|
+            if gql_query_param.parameter_type == :cursor
+              [name, Cursor.from_grpc(gql_query_param.cursor)]
+            else
+              [name, Core::GRPCUtils.from_value(gql_query_param.value)]
+            end
+          end]
+          bindings.freeze
+          bindings
+        end
+
+        ##
+        # Sets named binding values for a query that contains named argument
+        # binding sites that start with `@`.
+        #
+        # @param [Hash] new_named_bindings a hash that maps the binding site
+        #   names in the query string to valid GQL arguments
+        #
+        # @example
+        #   gql_query = Google::Cloud::Datastore::GqlQuery.new
+        #   gql_query.query_string = "SELECT * FROM Task " \
+        #                            "WHERE done = @done " \
+        #                            "AND priority = @priority"
+        #   gql_query.named_bindings = {done: false, priority: 4}
+        #
+        def named_bindings= new_named_bindings
+          @grpc.named_bindings.clear
+          new_named_bindings.map do |name, value|
+            if value.is_a? Google::Cloud::Datastore::Cursor
+              @grpc.named_bindings[name.to_s] = \
+                Google::Datastore::V1::GqlQueryParameter.new(
+                  cursor: value.to_grpc)
+            else
+              @grpc.named_bindings[name.to_s] = \
+                Google::Datastore::V1::GqlQueryParameter.new(
+                  value: Core::GRPCUtils.to_value(value))
+            end
+          end
+        end
+
+        ##
+        # The binding values for a query that contains numbered argument binding
+        # sites that start with `@`.
+        #
+        # @return [Array] a frozen array containing the query arguments in the
+        #   order of the numbered binding sites in the query string
+        #
+        def positional_bindings
+          bindings = @grpc.positional_bindings.map do |gql_query_param|
+            if gql_query_param.parameter_type == :cursor
+              Cursor.from_grpc gql_query_param.cursor
+            else
+              Core::GRPCUtils.from_value gql_query_param.value
+            end
+          end
+          bindings.freeze
+          bindings
+        end
+
+        ##
+        # Sets the binding values for a query that contains numbered argument
+        # binding sites that start with `@`.
+        #
+        # @param [Array] new_positional_bindings query arguments in the order
+        #   of the numbered binding sites in the query string
+        #
+        # @example
+        #   gql_query = Google::Cloud::Datastore::GqlQuery.new
+        #   gql_query.query_string = "SELECT * FROM Task" \
+        #                            "WHERE completed = @1 AND priority = @2"
+        #   gql_query.positional_bindings = [false, 4]
+        #
+        def positional_bindings= new_positional_bindings
+          @grpc.positional_bindings.clear
+          new_positional_bindings.map do |value|
+            if value.is_a? Google::Cloud::Datastore::Cursor
+              @grpc.positional_bindings << \
+                Google::Datastore::V1::GqlQueryParameter.new(
+                  cursor: value.to_grpc)
+            else
+              @grpc.positional_bindings << \
+                Google::Datastore::V1::GqlQueryParameter.new(
+                  value: Core::GRPCUtils.to_value(value))
+            end
+          end
+        end
+
+        # @private
+        def to_grpc
+          @grpc
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/datastore/grpc_utils.rb

@@ -0,0 +1,140 @@
+# Copyright 2016 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/core/grpc_utils"
+require "google/cloud/datastore/errors"
+require "stringio"
+require "base64"
+
+module Google
+  module Cloud
+    module Core
+      ##
+      # @private Conversion to/from Datastore GRPC objects.
+      # This file adds Datastore methods to Core::GRPCUtils.
+      module GRPCUtils
+        # rubocop:disable all
+
+        PROP_FILTER_OPS = { "<"            => :LESS_THAN,
+                            "lt"           => :LESS_THAN,
+                            "<="           => :LESS_THAN_OR_EQUAL,
+                            "lte"          => :LESS_THAN_OR_EQUAL,
+                            ">"            => :GREATER_THAN,
+                            "gt"           => :GREATER_THAN,
+                            ">="           => :GREATER_THAN_OR_EQUAL,
+                            "gte"          => :GREATER_THAN_OR_EQUAL,
+                            "="            => :EQUAL,
+                            "eq"           => :EQUAL,
+                            "eql"          => :EQUAL,
+                            "~"            => :HAS_ANCESTOR,
+                            "~>"           => :HAS_ANCESTOR,
+                            "ancestor"     => :HAS_ANCESTOR,
+                            "has_ancestor" => :HAS_ANCESTOR,
+                            "has ancestor" => :HAS_ANCESTOR }
+
+        ##
+        # Get a property filter operator from op
+        def self.to_prop_filter_op op
+          PROP_FILTER_OPS[op.to_s.downcase] || :EQUAL
+        end
+
+        ##
+        # Gets an object from a Google::Datastore::V1::Value.
+        def self.from_value grpc_value
+          if grpc_value.value_type == :null_value
+            return nil
+          elsif grpc_value.value_type == :key_value
+            return Google::Cloud::Datastore::Key.from_grpc(grpc_value.key_value)
+          elsif grpc_value.value_type == :entity_value
+            return Google::Cloud::Datastore::Entity.from_grpc(
+              grpc_value.entity_value)
+          elsif grpc_value.value_type == :boolean_value
+            return grpc_value.boolean_value
+          elsif grpc_value.value_type == :double_value
+            return grpc_value.double_value
+          elsif grpc_value.value_type == :integer_value
+            return grpc_value.integer_value
+          elsif grpc_value.value_type == :string_value
+            return grpc_value.string_value
+          elsif grpc_value.value_type == :array_value
+            return Array(grpc_value.array_value.values).map { |v| from_value v }
+          elsif grpc_value.value_type == :timestamp_value
+            return Time.at grpc_value.timestamp_value.seconds,
+                           grpc_value.timestamp_value.nanos/1000.0
+          elsif grpc_value.value_type == :geo_point_value
+            return grpc_value.geo_point_value.to_hash
+          elsif grpc_value.value_type == :blob_value
+            return StringIO.new(
+              grpc_value.blob_value.dup.force_encoding("ASCII-8BIT"))
+          else
+            nil
+          end
+        end
+
+        ##
+        # Stores an object into a Google::Datastore::V1::Value.
+        def self.to_value value
+          v = Google::Datastore::V1::Value.new
+          if NilClass === value
+            v.null_value = :NULL_VALUE
+          elsif TrueClass === value
+            v.boolean_value = true
+          elsif FalseClass === value
+            v.boolean_value = false
+          elsif Integer === value
+            v.integer_value = value
+          elsif Float === value
+            v.double_value = value
+          elsif defined?(BigDecimal) && BigDecimal === value
+            v.double_value = value
+          elsif Google::Cloud::Datastore::Key === value
+            v.key_value = value.to_grpc
+          elsif Google::Cloud::Datastore::Entity === value
+            value.key = nil # Embedded entities can't have keys
+            v.entity_value = value.to_grpc
+          elsif String === value
+            v.string_value = value
+          elsif Array === value
+            v.array_value = Google::Datastore::V1::ArrayValue.new(
+              values: value.map { |val| to_value val }
+            )
+          elsif value.respond_to? :to_time
+            v.timestamp_value = Google::Protobuf::Timestamp.new(
+              seconds: value.to_time.to_i, nanos: value.to_time.nsec)
+          elsif value.respond_to?(:to_hash) &&
+                value.keys.sort == [:latitude, :longitude]
+            v.geo_point_value = Google::Type::LatLng.new(value)
+          elsif value.respond_to?(:read) && value.respond_to?(:rewind)
+            value.rewind
+            v.blob_value = value.read.force_encoding("ASCII-8BIT")
+          else
+            fail Google::Cloud::Datastore::PropertyError,
+                 "A property of type #{value.class} is not supported."
+          end
+          v
+        end
+
+        def self.encode_bytes bytes
+          Base64.strict_encode64(bytes.to_s).encode("ASCII-8BIT")
+        end
+
+        def self.decode_bytes bytes
+          Base64.decode64(bytes.to_s).force_encoding Encoding::ASCII_8BIT
+        end
+        # rubocop:enable all
+      end
+    end
+  end
+end

data/lib/google/cloud/datastore/key.rb

@@ -0,0 +1,289 @@
+# Copyright 2014 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.
+
+
+module Google
+  module Cloud
+    module Datastore
+      ##
+      # # Key
+      #
+      # Every Datastore record has an identifying key, which includes the
+      # record's entity kind and a unique identifier. The identifier may be
+      # either a key name string, assigned explicitly by the application, or an
+      # integer numeric ID, assigned automatically by Datastore.
+      #
+      # @example
+      #   task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
+      #
+      class Key
+        ##
+        # The kind of the Key.
+        #
+        # @return [String]
+        #
+        # @example
+        #   key = Google::Cloud::Datastore::Key.new "TaskList"
+        #   key.kind #=> "TaskList"
+        #   key.kind = "Task"
+        #
+        attr_accessor :kind
+
+        ##
+        # The project of the Key.
+        #
+        # @return [String]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new "my-todo-project",
+        #                       "/path/to/keyfile.json"
+        #
+        #   datastore = gcloud.datastore
+        #   task = datastore.find "Task", "sampleTask"
+        #   task.key.project #=> "my-todo-project"
+        #
+        attr_accessor :project
+        alias_method :dataset_id,  :project
+        alias_method :dataset_id=, :project=
+
+        ##
+        # The namespace of the Key.
+        #
+        # @return [String, nil]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new "my-todo-project",
+        #                       "/path/to/keyfile.json"
+        #
+        #   datastore = gcloud.datastore
+        #   task = datastore.find "Task", "sampleTask"
+        #   task.key.namespace #=> "ns~todo-project"
+        #
+        attr_accessor :namespace
+
+        ##
+        # Create a new Key instance.
+        #
+        # @param [String] kind The kind of the Key. This is optional.
+        # @param [Integer, String] id_or_name The id or name of the Key. This is
+        #   optional.
+        #
+        # @return [Google::Cloud::Datastore::Dataset::Key]
+        #
+        # @example
+        #   task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
+        #
+        def initialize kind = nil, id_or_name = nil
+          @kind = kind
+          if id_or_name.is_a? Integer
+            @id = id_or_name
+          else
+            @name = id_or_name
+          end
+        end
+
+        ##
+        # @private Set the id of the Key.
+        # If a name is already present it will be removed.
+        #
+        # @return [Integer, nil]
+        #
+        # @example
+        #   task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
+        #   task_key.id #=> nil
+        #   task_key.name #=> "sampleTask"
+        #   task_key.id = 654321
+        #   task_key.id #=> 654321
+        #   task_key.name #=> nil
+        #
+        def id= new_id
+          @name = nil if new_id
+          @id = new_id
+        end
+
+        ##
+        # The id of the Key.
+        #
+        # @return [Integer, nil]
+        #
+        # @example
+        #   task_key = Google::Cloud::Datastore::Key.new "Task", 123456
+        #   task_key.id #=> 123456
+        #
+        attr_reader :id
+
+        ##
+        # @private Set the name of the Key.
+        # If an id is already present it will be removed.
+        #
+        # @return [String, nil]
+        #
+        # @example
+        #   task_key = Google::Cloud::Datastore::Key.new "Task", 123456
+        #   task_key.id #=> 123456
+        #   task_key.name #=> nil
+        #   task_key.name = "sampleTask"
+        #   task_key.id #=> nil
+        #   task_key.name #=> "sampleTask"
+        #
+        def name= new_name
+          @id = nil if new_name
+          @name = new_name
+        end
+
+        ##
+        # The name of the Key.
+        #
+        # @return [String, nil]
+        #
+        # @example
+        #   task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
+        #   task_key.name #=> "sampleTask"
+        #
+        attr_reader :name
+
+        ##
+        # Set the parent of the Key.
+        #
+        # @return [Key, nil]
+        #
+        # @example
+        #   parent_key = Google::Cloud::Datastore::Key.new "TaskList", "default"
+        #   task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
+        #   task_key.parent = parent_key
+        #
+        # @example With multiple levels:
+        #   user_key = Google::Cloud::Datastore::Key.new "User", "alice"
+        #   list_key = Google::Cloud::Datastore::Key.new "TaskList", "default"
+        #   task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
+        #   list_key.parent = user_key
+        #   task_key.parent = list_key
+        #
+        def parent= new_parent
+          # store key if given an entity
+          new_parent = new_parent.key if new_parent.respond_to? :key
+          @parent = new_parent
+        end
+
+        ##
+        # The parent of the Key.
+        #
+        # @return [Key, nil]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   datastore = gcloud.datastore
+        #
+        #   task_list = datastore.find "TaskList", "default"
+        #   query = datastore.query("Task").
+        #     ancestor(task_list)
+        #   lists = datastore.run query
+        #   lists.first.key.parent #=> Key("TaskList", "default")
+        #
+        attr_reader :parent
+
+        ##
+        # Represent the Key's path (including parent) as an array of arrays.
+        # Each inner array contains two values, the kind and the id or name.
+        # If neither an id or name exist then nil will be returned.
+        #
+        # @return [Array<Array<(String, String)>>]
+        #
+        # @example
+        #   parent_key = Google::Cloud::Datastore::Key.new "TaskList", "default"
+        #   task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
+        #   task_key.parent = parent_key
+        #   task_key.path #=> [["TaskList", "default"], ["Task", "sampleTask"]]
+        #
+        def path
+          new_path = parent ? parent.path : []
+          new_path << [kind, (id || name)]
+        end
+
+        ##
+        # Determine if the key is complete.
+        # A complete key has either an id or a name.
+        #
+        # Inverse of {#incomplete?}
+        def complete?
+          !incomplete?
+        end
+
+        ##
+        # Determine if the key is incomplete.
+        # An incomplete key has neither an id nor a name.
+        #
+        # Inverse of {#complete?}
+        def incomplete?
+          kind.nil? || (id.nil? && (name.nil? || name.empty?))
+        end
+
+        ##
+        # The number of bytes the Key will take to serialize during API calls.
+        def serialized_size
+          to_grpc.to_proto.length
+        end
+
+        ##
+        # @private Convert the Key to a Google::Datastore::V1::Key object.
+        def to_grpc
+          grpc_path = path.map do |pe_kind, pe_id_or_name|
+            path_args = { kind: pe_kind }
+            if pe_id_or_name.is_a? Integer
+              path_args[:id] = pe_id_or_name
+            elsif pe_id_or_name.is_a? String
+              path_args[:name] = pe_id_or_name unless pe_id_or_name.empty?
+            end
+            Google::Datastore::V1::Key::PathElement.new(path_args)
+          end
+          grpc = Google::Datastore::V1::Key.new(path: grpc_path)
+          if project || namespace
+            grpc.partition_id = Google::Datastore::V1::PartitionId.new(
+              project_id: project.to_s, namespace_id: namespace.to_s)
+          end
+          grpc
+        end
+
+        ##
+        # @private Create a new Key from a Google::Datastore::V1::Key
+        # object.
+        def self.from_grpc grpc
+          return nil if grpc.nil?
+          key_grpc = grpc.dup
+          key = Key.new
+          path_grpc = key_grpc.path.pop
+          if path_grpc
+            id_or_name =
+              (path_grpc.id_type == :id ? path_grpc.id : path_grpc.name)
+            key = Key.new path_grpc.kind, id_or_name
+          end
+          if key_grpc.partition_id
+            key.project = key_grpc.partition_id.project_id
+            key.namespace = key_grpc.partition_id.namespace_id
+          end
+          key.parent = Key.from_grpc(key_grpc) if key_grpc.path.count > 0
+          # Freeze the key to make it immutable.
+          key.freeze
+          key
+        end
+      end
+    end
+  end
+end