gcloud 0.8.0 → 0.8.2

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    ZmFhODViYTg5Nzc4Yjg0ZDJmMGFlZjQ3MmNiYTZjYWNlOTdlMjI5Zg==
+    ZjM3ZTdhZGU0OWE0NTcxY2M0ZDAxNTY4NDAwNmI4MzNiNjlhZjBjZg==
   data.tar.gz: !binary |-
-    ZDI5YjQ0YjRlMDE1YTNmYTNmMjYyN2I0ZTIzZTQyMjllNDljMTAwZQ==
+    NTU2MWEwNzk1MjhlOWU1Mzc4MzUxNDdhZjEzNmYzZmI5NDViZjBkZA==
 SHA512:
   metadata.gz: !binary |-
-    ZTNkNDUxZTIzZWFkMjFkZmI2ODBjZDc1NWE2YjBlYmYwODUzMmU1Y2M4OTZl
-    MDBhYTI1YmI5NjI4N2QwODJmYzM4MTFkNDAwY2Y1MWFhYmJjYTlhMGQxNWE0
-    ZDQ1YzIyMjE4MTIxN2NjM2NkMTYzYzc5ZGQ5ZTQwZGQwOWVhNTM=
+    Y2JlMDZiZGFiZmZkNTQ3N2QxOTRlZjlkOTdjNDk2ZWEwNTQ5NjA1MjUxMTVk
+    NjBhNDcxZjMyOWM1ZjEzMTFjYzQzMzU1YTA2ZmQ1ZGYwMTQ3OTg3OGRhMzhm
+    YTMyNjQzODhlYTVhMThmMjkwY2Q0MjhmMmZhZGIwOTcyODU1Mjc=
   data.tar.gz: !binary |-
-    MjBlNTAxNTBkYzVmMjA0MTBjZTNjZWE2NmM4OGZmMzE0NTM3Nzg5YTdiNjE5
-    ZmE0ODVhMDQxNGUwNjg0NjViYmFhNGU3OWYxNWY3ZWY0MWExNjhhMjExOTQx
-    YjhkNDUxOTQwODliYjAxMDM5ZTZlZDhjYmFiNzE4NWVhMTc0NTc=
+    NjNmMDkzZDhjNWZjYjFlMGVkOWM4MTliOGU4ZjRlN2E4MjAxYjgzNzBiNTgx
+    ZjdiOWY2NmY1YTY0OGE4OWQ5ZTg1MDEzMDE2ZGYwNjg0M2M2ZjNhMmI3YmY2
+    MGE4MDBlNWY4YTU2NGM3Mzc1MThlZDAyMjA0YTkzZGE2NDAxMGI=

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Release History
 
+### 0.8.2 / 2016-05-04
+
+#### Changes
+
+* Datastore
+  * Fix issue with blob values being stored in base64 (bmclean)
+
+### 0.8.1 / 2016-05-03
+
+#### Changes
+
+* Datastore
+  * Add support for blob values (bmclean)
+  * Add support for Date and DateTime values
+  * Add support for setting read consistency
+  * Add support for batch operations outside of a transaction (timanovsky)
+  * Fix handling of rollback errors (timanovsky)
+  * Remove setting of project/dataset_id in query partition (toots)
+
 ### 0.8.0 / 2016-04-28
 
 #### Major changes

data/lib/gcloud/datastore/commit.rb

@@ -0,0 +1,131 @@
+# 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.
+
+
+module Gcloud
+  module Datastore
+    ##
+    # # Commit
+    #
+    # Object yielded from `commit` methods to allow multiple changes to be made
+    # in a single commit.
+    #
+    # @example
+    #   dataset.commit do |c|
+    #     c.save task1, task2
+    #     c.delete entity1, entity2
+    #   end
+    #
+    # See {Gcloud::Datastore::Dataset#commit} and
+    # {Gcloud::Datastore::Transaction#commit}.
+    #
+    class Commit
+      ##
+      # @private Create a new Commit object.
+      def initialize
+        @shared_entities = []
+        @shared_auto_ids = []
+        @shared_deletes  = []
+      end
+
+      ##
+      # Saves entities to the Datastore.
+      #
+      # @param [Entity] entities One or more Entity objects to save.
+      #
+      # @example
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
+      #   dataset.commit do |c|
+      #     c.save task1, task2
+      #   end
+      #
+      def save *entities
+        entities.each do |entity|
+          shared_auto_ids << entity if entity.key.incomplete?
+          shared_entities << entity
+        end
+        # Do not save yet
+        entities
+      end
+
+      ##
+      # Remove entities from the Datastore.
+      #
+      # @param [Entity, Key] entities_or_keys One or more Entity or Key
+      #   objects to remove.
+      #
+      # @example
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
+      #   dataset.commit do |c|
+      #     c.delete entity1, entity2
+      #   end
+      #
+      def delete *entities_or_keys
+        keys = entities_or_keys.map do |e_or_k|
+          e_or_k.respond_to?(:key) ? e_or_k.key : e_or_k
+        end
+        keys.each { |k| shared_deletes << k }
+        # Do not delete yet
+        true
+      end
+
+      # @private Mutation object to be committed.
+      def mutation
+        Proto.new_mutation.tap do |m|
+          m.insert_auto_id = shared_auto_ids.map(&:to_proto)
+          m.upsert = shared_upserts.map(&:to_proto)
+          m.delete = shared_deletes.map(&:to_proto)
+        end
+      end
+
+      # @private Entities that need key ids assigned.
+      def auto_id_entities
+        shared_auto_ids
+      end
+
+      # @private All entities saved in the commit.
+      def entities
+        shared_entities
+      end
+
+      protected
+
+      ##
+      # @private List of Entity objects to be saved.
+      def shared_entities
+        @shared_entities
+      end
+
+      ##
+      # @private List of Entity objects that need auto_ids
+      def shared_auto_ids
+        @shared_auto_ids
+      end
+
+      ##
+      # @private List of Entity objects to be saved.
+      def shared_upserts
+        shared_entities - shared_auto_ids
+      end
+
+      ##
+      # @private List of Key objects to be deleted.
+      def shared_deletes
+        @shared_deletes
+      end
+    end
+  end
+end

data/lib/gcloud/datastore/connection.rb

@@ -63,19 +63,33 @@ module Gcloud
 
       ##
       # Look up entities by keys.
-      def lookup *keys
-        lookup = Proto::LookupRequest.new
-        lookup.key = keys
+      def lookup *keys, consistency: nil, transaction: nil
+        lookup = Proto::LookupRequest.new key: keys
+        if consistency == :eventual
+          lookup.read_options = Proto::ReadOptions.new(read_consistency: 2)
+        elsif consistency == :strong
+          lookup.read_options = Proto::ReadOptions.new(read_consistency: 1)
+        elsif transaction
+          lookup.read_options = Proto::ReadOptions.new(
+            transaction: transaction)
+        end
 
         Proto::LookupResponse.decode rpc("lookup", lookup)
       end
 
       # Query for entities.
-      def run_query query, partition = nil
+      def run_query query, partition = nil, consistency: nil, transaction: nil
         run_query = Proto::RunQueryRequest.new.tap do |rq|
           rq.query = query
           rq.partition_id = partition if partition
-          rq
+        end
+        if consistency == :eventual
+          run_query.read_options = Proto::ReadOptions.new(read_consistency: 2)
+        elsif consistency == :strong
+          run_query.read_options = Proto::ReadOptions.new(read_consistency: 1)
+        elsif transaction
+          run_query.read_options = Proto::ReadOptions.new(
+            transaction: transaction)
         end
 
         Proto::RunQueryResponse.decode rpc("runQuery", run_query)

data/lib/gcloud/datastore/dataset.rb

@@ -16,6 +16,7 @@
 require "gcloud/gce"
 require "gcloud/datastore/connection"
 require "gcloud/datastore/credentials"
+require "gcloud/datastore/commit"
 require "gcloud/datastore/entity"
 require "gcloud/datastore/key"
 require "gcloud/datastore/query"
@@ -114,8 +115,7 @@ module Gcloud
       ##
       # Persist one or more entities to the Datastore.
       #
-      # @param [Entity] entities One or more entity objects to be saved without
-      #   `id` or `name` set.
+      # @param [Entity] entities One or more entity objects to be saved.
       #
       # @return [Array<Gcloud::Datastore::Entity>]
       #
@@ -123,11 +123,51 @@ module Gcloud
       #   dataset.save task1, task2
       #
       def save *entities
-        mutation = Proto.new_mutation
-        save_entities_to_mutation entities, mutation
-        response = connection.commit mutation
-        auto_id_assign_ids response.mutation_result.insert_auto_id_key
+        commit { |c| c.save(*entities) }
+      end
+
+      ##
+      # Remove entities from the Datastore.
+      #
+      # @param [Entity, Key] entities_or_keys One or more Entity or Key objects
+      #   to remove.
+      #
+      # @return [Boolean] Returns `true` if successful
+      #
+      # @example
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
+      #   dataset.delete entity1, entity2
+      #
+      def delete *entities_or_keys
+        commit { |c| c.delete(*entities_or_keys) }
+        true
+      end
+
+      ##
+      # Make multiple changes in a single commit.
+      #
+      # @yield [commit] a block for making changes
+      # @yieldparam [Commit] commit The object that changes are made on
+      #
+      # @return [Array<Gcloud::Datastore::Entity>] The entities that were
+      #   persisted.
+      #
+      # @example
+      #   dataset.commit do |c|
+      #     c.save task1, task2
+      #     c.delete entity1, entity2
+      #   end
+      #
+      def commit
+        return unless block_given?
+        c = Commit.new
+        yield c
+        response = connection.commit c.mutation
+        auto_id_assign_ids c.auto_id_entities,
+                           response.mutation_result.insert_auto_id_key
         # Make sure all entity keys are frozen so all show as persisted
+        entities = c.entities
         entities.each { |e| e.key.freeze unless e.persisted? }
         entities
       end
@@ -138,6 +178,14 @@ module Gcloud
       # @param [Key, String] key_or_kind A Key object or `kind` string value.
       # @param [Integer, String, nil] id_or_name The Key's `id` or `name` value
       #   if a `kind` was provided in the first parameter.
+      # @param [Symbol] consistency The non-transactional read consistency to
+      #   use. Cannot be set to `:strong` for global queries. Accepted values
+      #   are `:eventual` and `:strong`.
+      #
+      #   The default consistency depends on the type of lookup used. See
+      #   [Eventual Consistency in Google Cloud
+      #   Datastore](https://cloud.google.com/datastore/docs/articles/balancing-strong-and-eventual-consistency-with-google-cloud-datastore/#h.tf76fya5nqk8)
+      #   for more information.
       #
       # @return [Gcloud::Datastore::Entity, nil]
       #
@@ -148,12 +196,12 @@ module Gcloud
       # @example Finding an entity with a `kind` and `id`/`name`:
       #   task = dataset.find "Task", 123456
       #
-      def find key_or_kind, id_or_name = nil
+      def find key_or_kind, id_or_name = nil, consistency: nil
         key = key_or_kind
         unless key.is_a? Gcloud::Datastore::Key
           key = Key.new key_or_kind, id_or_name
         end
-        find_all(key).first
+        find_all(key, consistency: consistency).first
       end
       alias_method :get, :find
 
@@ -161,6 +209,14 @@ module Gcloud
       # Retrieve the entities for the provided keys.
       #
       # @param [Key] keys One or more Key objects to find records for.
+      # @param [Symbol] consistency The non-transactional read consistency to
+      #   use. Cannot be set to `:strong` for global queries. Accepted values
+      #   are `:eventual` and `:strong`.
+      #
+      #   The default consistency depends on the type of lookup used. See
+      #   [Eventual Consistency in Google Cloud
+      #   Datastore](https://cloud.google.com/datastore/docs/articles/balancing-strong-and-eventual-consistency-with-google-cloud-datastore/#h.tf76fya5nqk8)
+      #   for more information.
       #
       # @return [Gcloud::Datastore::Dataset::LookupResults]
       #
@@ -171,8 +227,10 @@ module Gcloud
       #   key2 = dataset.key "Task", 987654
       #   tasks = dataset.find_all key1, key2
       #
-      def find_all *keys
-        response = connection.lookup(*keys.map(&:to_proto))
+      def find_all *keys, consistency: nil
+        check_consistency! consistency
+        response = connection.lookup(*keys.map(&:to_proto),
+                                     consistency: consistency)
         entities = to_gcloud_entities response.found
         deferred = to_gcloud_keys response.deferred
         missing  = to_gcloud_entities response.missing
@@ -180,35 +238,19 @@ module Gcloud
       end
       alias_method :lookup, :find_all
 
-      ##
-      # Remove entities from the Datastore.
-      #
-      # @param [Entity, Key] entities_or_keys One or more Entity or Key objects
-      #   to remove.
-      #
-      # @return [Boolean] Returns `true` if successful
-      #
-      # @example
-      #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
-      #   dataset.delete entity1, entity2
-      #
-      def delete *entities_or_keys
-        keys = entities_or_keys.map do |e_or_k|
-          e_or_k.respond_to?(:key) ? e_or_k.key.to_proto : e_or_k.to_proto
-        end
-        mutation = Proto.new_mutation.tap do |m|
-          m.delete = keys
-        end
-        connection.commit mutation
-        true
-      end
-
       ##
       # Retrieve entities specified by a Query.
       #
       # @param [Query] query The Query object with the search criteria.
       # @param [String] namespace The namespace the query is to run within.
+      # @param [Symbol] consistency The non-transactional read consistency to
+      #   use. Cannot be set to `:strong` for global queries. Accepted values
+      #   are `:eventual` and `:strong`.
+      #
+      #   The default consistency depends on the type of query used. See
+      #   [Eventual Consistency in Google Cloud
+      #   Datastore](https://cloud.google.com/datastore/docs/articles/balancing-strong-and-eventual-consistency-with-google-cloud-datastore/#h.tf76fya5nqk8)
+      #   for more information.
       #
       # @return [Gcloud::Datastore::Dataset::QueryResults]
       #
@@ -222,9 +264,11 @@ module Gcloud
       #     where("completed", "=", true)
       #   tasks = dataset.run query, namespace: "ns~todo-project"
       #
-      def run query, namespace: nil
+      def run query, namespace: nil, consistency: nil
         partition = optional_partition_id namespace
-        response = connection.run_query query.to_proto, partition
+        check_consistency! consistency
+        response = connection.run_query query.to_proto, partition,
+                                        consistency: consistency
         entities = to_gcloud_entities response.batch.entity_result
         cursor = Proto.encode_cursor response.batch.end_cursor
         more_results = Proto.to_more_results_string response.batch.more_results
@@ -284,8 +328,14 @@ module Gcloud
           yield tx
           tx.commit
         rescue => e
-          tx.rollback
-          raise TransactionError.new("Transaction failed to commit.", e)
+          begin
+            tx.rollback
+          rescue => re
+            msg = "Transaction failed to commit and rollback."
+            raise TransactionError.new(msg, commit_error: e, rollback_error: re)
+          end
+          raise TransactionError.new("Transaction failed to commit.",
+                                     commit_error: e)
         end
       end
 
@@ -411,45 +461,28 @@ module Gcloud
         end
       end
 
-      ##
-      # @private Save a key to be given an ID when comitted.
-      def auto_id_register entity
-        @_auto_id_entities ||= []
-        @_auto_id_entities << entity
-      end
-
       ##
       # @private Update saved keys with new IDs post-commit.
-      def auto_id_assign_ids auto_ids
-        @_auto_id_entities ||= []
+      def auto_id_assign_ids entities, auto_ids
         Array(auto_ids).each_with_index do |key, index|
-          entity = @_auto_id_entities[index]
+          entity = entities[index]
           entity.key = Key.from_proto key
         end
-        @_auto_id_entities = []
-      end
-
-      ##
-      # @private Add entities to a Mutation, and register they key to be
-      # updated with an auto ID if needed.
-      def save_entities_to_mutation entities, mutation
-        entities.each do |entity|
-          if entity.key.id.nil? && entity.key.name.nil?
-            mutation.insert_auto_id << entity.to_proto
-            auto_id_register entity
-          else
-            mutation.upsert << entity.to_proto
-          end
-        end
       end
 
       def optional_partition_id namespace = nil
         return nil if namespace.nil?
         Proto::PartitionId.new.tap do |p|
           p.namespace = namespace
-          p.dataset_id = project
         end
       end
+
+      def check_consistency! consistency
+        fail(ArgumentError,
+             format("Consistency must be :eventual or :strong, not %s.",
+                    consistency.inspect)
+            ) unless [:eventual, :strong, nil].include? consistency
+      end
     end
   end
 end

data/lib/gcloud/datastore/entity.rb

@@ -46,6 +46,9 @@ module Gcloud
       ##
       # Retrieve a property value by providing the name.
       #
+      # Property values are converted from the Datastore value type
+      # automatically. Blob properties are returned as StringIO objects.
+      #
       # @param [String, Symbol] prop_name The name of the property.
       #
       # @return [Object, nil] Returns `nil` if the property doesn't exist
@@ -66,6 +69,14 @@ module Gcloud
       #   user = dataset.find "User", "heidi@example.com"
       #   user[:name] #=> "Heidi Henderson"
       #
+      # @example Getting a blob value returns a StringIO object:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
+      #   user = dataset.find "User", "heidi@example.com"
+      #   user["avatar"] #=> StringIO("\x89PNG\r\n\x1A...")
+      #
       def [] prop_name
         @properties[prop_name]
       end
@@ -73,6 +84,12 @@ module Gcloud
       ##
       # Set a property value by name.
       #
+      # Property values are converted to use the proper Datastore value type
+      # automatically. Use an IO-compatible object (File, StringIO, Tempfile) to
+      # indicate the property value should be stored as a Datastore `blob`.
+      # IO-compatible objects are converted to StringIO objects when they are
+      # set.
+      #
       # @param [String, Symbol] prop_name The name of the property.
       # @param [Object] prop_value The value of the property.
       #
@@ -92,6 +109,15 @@ module Gcloud
       #   user = dataset.find "User", "heidi@example.com"
       #   user[:name] = "Heidi H. Henderson"
       #
+      # @example Setting a blob value using an IO:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
+      #   user = dataset.find "User", "heidi@example.com"
+      #   user["avatar"] = File.open "/avatars/heidi.png"
+      #   user["avatar"] #=> StringIO("\x89PNG\r\n\x1A...")
+      #
       def []= prop_name, prop_value
         @properties[prop_name] = prop_value
       end

data/lib/gcloud/datastore/errors.rb

@@ -66,12 +66,18 @@ module Gcloud
     class TransactionError < Gcloud::Datastore::Error
       ##
       # An error that occurred within the transaction. (optional)
-      attr_reader :inner
+      attr_reader :commit_error
+      alias_method :inner, :commit_error # backwards compatibility
+
+      ##
+      # An error that occurred within the transaction. (optional)
+      attr_reader :rollback_error
 
       # @private
-      def initialize message, inner = nil
+      def initialize message, commit_error: nil, rollback_error: nil
         super(message)
-        @inner = inner
+        @commit_error   = commit_error
+        @rollback_error = rollback_error
       end
     end
   end

data/lib/gcloud/datastore/properties.rb

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 
+require "stringio"
+
 module Gcloud
   module Datastore
     ##
@@ -86,8 +88,7 @@ module Gcloud
       # Ensures the value is a type that can be persisted,
       # otherwise a PropertyError is raised.
       def ensure_value_type value
-        if Time                      === value ||
-           Gcloud::Datastore::Key    === value ||
+        if Gcloud::Datastore::Key    === value ||
            Gcloud::Datastore::Entity === value ||
            NilClass                  === value ||
            TrueClass                 === value ||
@@ -97,6 +98,12 @@ module Gcloud
            String                    === value ||
            Array                     === value
           return value
+        elsif value.respond_to?(:to_time)
+          return value
+        elsif value.respond_to?(:read) && value.respond_to?(:rewind)
+          # Always convert an IO object to a StringIO when storing.
+          value.rewind
+          return StringIO.new(value.read.force_encoding("ASCII-8BIT"))
         elsif defined?(BigDecimal) && BigDecimal === value
           return value
         end

data/lib/gcloud/datastore/proto.rb

@@ -15,6 +15,7 @@
 
 require "gcloud/proto/datastore_v1.pb"
 require "gcloud/datastore/errors"
+require "stringio"
 
 module Gcloud
   module Datastore
@@ -53,6 +54,8 @@ module Gcloud
           return Array(proto_value.list_value).map do |item|
             from_proto_value item
           end
+        elsif !proto_value.blob_value.nil?
+          return StringIO.new(proto_value.blob_value.force_encoding("ASCII-8BIT"))
         else
           nil
         end
@@ -60,9 +63,7 @@ module Gcloud
 
       def self.to_proto_value value
         v = Gcloud::Datastore::Proto::Value.new
-        if Time === value
-          v.timestamp_microseconds_value = self.microseconds_from_time value
-        elsif Gcloud::Datastore::Key === value
+        if Gcloud::Datastore::Key === value
           v.key_value = value.to_proto
         elsif Gcloud::Datastore::Entity === value
           v.entity_value = value.to_proto
@@ -82,6 +83,11 @@ module Gcloud
           v.string_value = value
         elsif Array === value
           v.list_value = value.map { |item| to_proto_value item }
+        elsif value.respond_to?(:to_time)
+          v.timestamp_microseconds_value = self.microseconds_from_time value.to_time
+        elsif value.respond_to?(:read) && value.respond_to?(:rewind)
+          value.rewind
+          v.blob_value = value.read.force_encoding("ASCII-8BIT")
         else
           fail PropertyError, "A property of type #{value.class} is not supported."
         end

data/lib/gcloud/datastore/transaction.rb

@@ -44,8 +44,7 @@ module Gcloud
       #   end
       #
       def save *entities
-        save_entities_to_mutation entities, shared_mutation
-        @_saved_entities += entities
+        @commit.save(*entities)
         # Do not save or assign auto_ids yet
         entities
       end
@@ -61,16 +60,94 @@ module Gcloud
       #   end
       #
       def delete *entities_or_keys
-        keys = entities_or_keys.map do |e_or_k|
-          e_or_k.respond_to?(:key) ? e_or_k.key.to_proto : e_or_k.to_proto
-        end
-        shared_mutation.tap do |m|
-          m.delete = keys
-        end
+        @commit.delete(*entities_or_keys)
         # Do not delete yet
         true
       end
 
+      ##
+      # Retrieve an entity by providing key information. The lookup is run
+      # within the transaction.
+      #
+      # @param [Key, String] key_or_kind A Key object or `kind` string value.
+      #
+      # @return [Gcloud::Datastore::Entity, nil]
+      #
+      # @example Finding an entity with a key:
+      #   key = dataset.key "Task", 123456
+      #   task = dataset.find key
+      #
+      # @example Finding an entity with a `kind` and `id`/`name`:
+      #   task = dataset.find "Task", 123456
+      #
+      def find key_or_kind, id_or_name = nil
+        key = key_or_kind
+        unless key.is_a? Gcloud::Datastore::Key
+          key = Key.new key_or_kind, id_or_name
+        end
+        find_all(key).first
+      end
+      alias_method :get, :find
+
+      ##
+      # Retrieve the entities for the provided keys. The lookup is run within
+      # the transaction.
+      #
+      # @param [Key] keys One or more Key objects to find records for.
+      #
+      # @return [Gcloud::Datastore::Dataset::LookupResults]
+      #
+      # @example
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
+      #   key1 = dataset.key "Task", 123456
+      #   key2 = dataset.key "Task", 987654
+      #   tasks = dataset.find_all key1, key2
+      #
+      def find_all *keys
+        response = connection.lookup(*keys.map(&:to_proto),
+                                     transaction: @id)
+        entities = to_gcloud_entities response.found
+        deferred = to_gcloud_keys response.deferred
+        missing  = to_gcloud_entities response.missing
+        LookupResults.new entities, deferred, missing
+      end
+      alias_method :lookup, :find_all
+
+      ##
+      # Retrieve entities specified by a Query. The query is run within the
+      # transaction.
+      #
+      # @param [Query] query The Query object with the search criteria.
+      # @param [String] namespace The namespace the query is to run within.
+      #
+      # @return [Gcloud::Datastore::Dataset::QueryResults]
+      #
+      # @example
+      #   query = dataset.query("Task").
+      #     where("completed", "=", true)
+      #   dataset.transaction do |tx|
+      #     tasks = tx.run query
+      #   end
+      #
+      # @example Run the query within a namespace with the `namespace` option:
+      #   query = Gcloud::Datastore::Query.new.kind("Task").
+      #     where("completed", "=", true)
+      #   dataset.transaction do |tx|
+      #     tasks = tx.run query, namespace: "ns~todo-project"
+      #   end
+      #
+      def run query, namespace: nil
+        partition = optional_partition_id namespace
+        response = connection.run_query query.to_proto, partition,
+                                        transaction: @id
+        entities = to_gcloud_entities response.batch.entity_result
+        cursor = Proto.encode_cursor response.batch.end_cursor
+        more_results = Proto.to_more_results_string response.batch.more_results
+        QueryResults.new entities, cursor, more_results
+      end
+      alias_method :run_query, :run
+
       ##
       # Begins a transaction.
       # This method is run when a new Transaction is created.
@@ -84,20 +161,84 @@ module Gcloud
 
       ##
       # Commits a transaction.
+      #
+      # @yield [commit] an optional block for making changes
+      # @yieldparam [Commit] commit The object that changes are made on
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
+      #
+      #   user = dataset.entity "User", "heidi" do |u|
+      #     u["name"] = "Heidi Henderson"
+      #     u["email"] = "heidi@example.net"
+      #   end
+      #
+      #   tx = dataset.transaction
+      #   begin
+      #     if tx.find(user.key).nil?
+      #       tx.save user
+      #     end
+      #     tx.commit
+      #   rescue
+      #     tx.rollback
+      #   end
+      #
+      # @example Commit can be passed a block, same as {Dataset#commit}:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
+      #
+      #   tx = dataset.transaction
+      #   begin
+      #     tx.commit do |c|
+      #       c.save task1, task2
+      #       c.delete entity1, entity2
+      #     end
+      #   rescue
+      #     tx.rollback
+      #   end
+      #
       def commit
         if @id.nil?
           fail TransactionError, "Cannot commit when not in a transaction."
         end
 
-        response = connection.commit shared_mutation, @id
-        auto_id_assign_ids response.mutation_result.insert_auto_id_key
+        yield @commit if block_given?
+        response = connection.commit @commit.mutation, @id
+        auto_id_assign_ids @commit.auto_id_entities,
+                           response.mutation_result.insert_auto_id_key
         # Make sure all entity keys are frozen so all show as persisted
-        @_saved_entities.each { |e| e.key.freeze unless e.persisted? }
+        @commit.entities.each { |e| e.key.freeze unless e.persisted? }
         true
       end
 
       ##
       # Rolls a transaction back.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
+      #
+      #   user = dataset.entity "User", "heidi" do |u|
+      #     u["name"] = "Heidi Henderson"
+      #     u["email"] = "heidi@example.net"
+      #   end
+      #
+      #   tx = dataset.transaction
+      #   begin
+      #     if tx.find(user.key).nil?
+      #       tx.save user
+      #     end
+      #     tx.commit
+      #   rescue
+      #     tx.rollback
+      #   end
       def rollback
         if @id.nil?
           fail TransactionError, "Cannot rollback when not in a transaction."
@@ -111,19 +252,8 @@ module Gcloud
       # Reset the transaction.
       # {Transaction#start} must be called afterwards.
       def reset!
-        @shared_mutation = nil
         @id = nil
-        @_auto_id_entities = []
-        @_saved_entities = []
-      end
-
-      protected
-
-      ##
-      # @private Mutation to be shared across save, delete, and commit calls.
-      # This enables updates to happen when commit is called.
-      def shared_mutation
-        @shared_mutation ||= Proto.new_mutation
+        @commit = Commit.new
       end
     end
   end

data/lib/gcloud/version.rb

@@ -14,5 +14,5 @@
 
 
 module Gcloud
-  VERSION = "0.8.0"
+  VERSION = "0.8.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gcloud
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.2
 platform: ruby
 authors:
 - Silvano Luciani
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-28 00:00:00.000000000 Z
+date: 2016-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grpc
@@ -290,6 +290,7 @@ files:
 - lib/gcloud/bigquery/view.rb
 - lib/gcloud/credentials.rb
 - lib/gcloud/datastore.rb
+- lib/gcloud/datastore/commit.rb
 - lib/gcloud/datastore/connection.rb
 - lib/gcloud/datastore/credentials.rb
 - lib/gcloud/datastore/dataset.rb