gcloud 0.8.2 → 0.9.0

data/lib/gcloud/datastore/commit.rb

@@ -22,21 +22,23 @@ module Gcloud
     # in a single commit.
     #
     # @example
-    #   dataset.commit do |c|
+    #   gcloud = Gcloud.new
+    #   datastore = gcloud.datastore
+    #   datastore.commit do |c|
     #     c.save task1, task2
     #     c.delete entity1, entity2
     #   end
     #
-    # See {Gcloud::Datastore::Dataset#commit} and
-    # {Gcloud::Datastore::Transaction#commit}.
-    #
+    # @see {Gcloud::Datastore::Dataset#commit}
+    # @see {Gcloud::Datastore::Transaction#commit}
     class Commit
       ##
       # @private Create a new Commit object.
       def initialize
-        @shared_entities = []
-        @shared_auto_ids = []
-        @shared_deletes  = []
+        @shared_upserts = []
+        @shared_inserts = []
+        @shared_updates = []
+        @shared_deletes = []
       end
 
       ##
@@ -46,19 +48,56 @@ module Gcloud
       #
       # @example
       #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
-      #   dataset.commit do |c|
+      #   datastore = gcloud.datastore
+      #   datastore.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
+        entities = Array(entities).flatten
+        @shared_upserts += entities unless entities.empty?
         # Do not save yet
         entities
       end
+      alias_method :upsert, :save
+
+      ##
+      # Inserts entities to the Datastore.
+      #
+      # @param [Entity] entities One or more Entity objects to insert.
+      #
+      # @example
+      #   gcloud = Gcloud.new
+      #   datastore = gcloud.datastore
+      #   datastore.commit do |c|
+      #     c.insert task1, task2
+      #   end
+      #
+      def insert *entities
+        entities = Array(entities).flatten
+        @shared_inserts += entities unless entities.empty?
+        # Do not insert yet
+        entities
+      end
+
+      ##
+      # Updates entities to the Datastore.
+      #
+      # @param [Entity] entities One or more Entity objects to update.
+      #
+      # @example
+      #   gcloud = Gcloud.new
+      #   datastore = gcloud.datastore
+      #   datastore.commit do |c|
+      #     c.update task1, task2
+      #   end
+      #
+      def update *entities
+        entities = Array(entities).flatten
+        @shared_updates += entities unless entities.empty?
+        # Do not update yet
+        entities
+      end
 
       ##
       # Remove entities from the Datastore.
@@ -68,63 +107,41 @@ module Gcloud
       #
       # @example
       #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
-      #   dataset.commit do |c|
-      #     c.delete entity1, entity2
+      #   datastore = gcloud.datastore
+      #   datastore.commit do |c|
+      #     c.delete task1, task2
       #   end
       #
       def delete *entities_or_keys
-        keys = entities_or_keys.map do |e_or_k|
+        keys = Array(entities_or_keys).flatten.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 }
+        @shared_deletes += keys unless keys.empty?
         # 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)
+      # @private Mutations object to be committed.
+      def mutations
+        mutations = []
+        mutations += @shared_upserts.map do |entity|
+          Google::Datastore::V1beta3::Mutation.new upsert: entity.to_grpc
         end
-      end
-
-      # @private Entities that need key ids assigned.
-      def auto_id_entities
-        shared_auto_ids
+        mutations += @shared_inserts.map do |entity|
+          Google::Datastore::V1beta3::Mutation.new insert: entity.to_grpc
+        end
+        mutations += @shared_updates.map do |entity|
+          Google::Datastore::V1beta3::Mutation.new update: entity.to_grpc
+        end
+        mutations += @shared_deletes.map do |key|
+          Google::Datastore::V1beta3::Mutation.new delete: key.to_grpc
+        end
+        mutations
       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
+        @shared_upserts + @shared_inserts + @shared_updates
       end
     end
   end

data/lib/gcloud/datastore/credentials.rb

@@ -26,21 +26,10 @@ module Gcloud
     #
     # @see https://developers.google.com/accounts/docs/application-default-credentials
     class Credentials < Gcloud::Credentials
-      SCOPE = ["https://www.googleapis.com/auth/datastore",
-               "https://www.googleapis.com/auth/userinfo.email"]
+      SCOPE = ["https://www.googleapis.com/auth/datastore"]
       PATH_ENV_VARS = %w(DATASTORE_KEYFILE GCLOUD_KEYFILE GOOGLE_CLOUD_KEYFILE)
       JSON_ENV_VARS = %w(DATASTORE_KEYFILE_JSON GCLOUD_KEYFILE_JSON
                          GOOGLE_CLOUD_KEYFILE_JSON)
-
-      ##
-      # Sign OAuth 2.0 API calls.
-      def sign_http_request request
-        if @client
-          @client.fetch_access_token! if @client.expires_within? 30
-          @client.generate_authenticated_request request: request
-        end
-        request
-      end
     end
   end
 end

data/lib/gcloud/datastore/cursor.rb

@@ -0,0 +1,76 @@
+# 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
+    ##
+    # # Cursor
+    #
+    # Cursor is a point in query results. Cursors are returned in QueryResults.
+    #
+    # @example
+    #   require "gcloud"
+    #
+    #   gcloud = Gcloud.new
+    #   datastore = gcloud.datastore
+    #
+    #   query = datastore.query("Task").
+    #     where("done", "=", false)
+    #
+    #   tasks = datastore.run query
+    #   tasks.cursor #=> Cursor
+    #
+    class Cursor
+      # Base64 encoded array of bytes
+      def initialize cursor
+        @cursor = cursor
+      end
+
+      # Base64 encoded array of bytes
+      def to_s
+        @cursor
+      end
+
+      # @private
+      def inspect
+        "#{self.class}(#{@cursor})"
+      end
+
+      # @private
+      def == other
+        return false unless other.is_a? Cursor
+        @cursor == other.to_s
+      end
+
+      # @private
+      def <=> other
+        return -1 unless other.is_a? Cursor
+        @cursor <=> other.to_s
+      end
+
+      # @private byte array as a string
+      def to_grpc
+        GRPCUtils.decode_bytes(@cursor)
+      end
+
+      # @private byte array as a string
+      def self.from_grpc grpc
+        grpc = String grpc
+        return nil if grpc.empty?
+        new GRPCUtils.encode_bytes(grpc)
+      end
+    end
+  end
+end

data/lib/gcloud/datastore/dataset.rb

@@ -14,12 +14,15 @@
 
 
 require "gcloud/gce"
-require "gcloud/datastore/connection"
+require "gcloud/datastore/grpc_utils"
 require "gcloud/datastore/credentials"
+require "gcloud/datastore/service"
 require "gcloud/datastore/commit"
 require "gcloud/datastore/entity"
 require "gcloud/datastore/key"
 require "gcloud/datastore/query"
+require "gcloud/datastore/gql_query"
+require "gcloud/datastore/cursor"
 require "gcloud/datastore/dataset/lookup_results"
 require "gcloud/datastore/dataset/query_results"
 
@@ -41,16 +44,17 @@ module Gcloud
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
-    #   dataset = gcloud.datastore
+    #   datastore = gcloud.datastore
     #
-    #   query = dataset.query("Task").
-    #     where("completed", "=", true)
+    #   query = datastore.query("Task").
+    #     where("done", "=", false)
     #
-    #   tasks = dataset.run query
+    #   tasks = datastore.run query
     #
     class Dataset
-      # @private
-      attr_accessor :connection
+      ##
+      # @private The gRPC Service object.
+      attr_accessor :service
 
       ##
       # @private Creates a new Dataset instance.
@@ -59,7 +63,7 @@ module Gcloud
       def initialize project, credentials
         project = project.to_s # Always cast to a string
         fail ArgumentError, "project is missing" if project.empty?
-        @connection = Connection.new project, credentials
+        @service = Service.new project, credentials
       end
 
       ##
@@ -71,11 +75,11 @@ module Gcloud
       #   gcloud = Gcloud.new "my-todo-project",
       #                       "/path/to/keyfile.json"
       #
-      #   dataset = gcloud.datastore
-      #   dataset.project #=> "my-todo-project"
+      #   datastore = gcloud.datastore
+      #   datastore.project #=> "my-todo-project"
       #
       def project
-        connection.dataset_id
+        service.project
       end
 
       ##
@@ -97,19 +101,20 @@ module Gcloud
       # @return [Array<Gcloud::Datastore::Key>]
       #
       # @example
-      #   empty_key = dataset.key "Task"
-      #   task_keys = dataset.allocate_ids empty_key, 5
+      #   task_key = datastore.key "Task"
+      #   task_keys = datastore.allocate_ids task_key, 5
       #
       def allocate_ids incomplete_key, count = 1
         if incomplete_key.complete?
           fail Gcloud::Datastore::Error, "An incomplete key must be provided."
         end
 
-        incomplete_keys = count.times.map { incomplete_key.to_proto }
-        response = connection.allocate_ids(*incomplete_keys)
-        Array(response.key).map do |key|
-          Key.from_proto key
-        end
+        ensure_service!
+        incomplete_keys = count.times.map { incomplete_key.to_grpc }
+        allocate_res = service.allocate_ids(*incomplete_keys)
+        allocate_res.keys.map { |key| Key.from_grpc key }
+      rescue GRPC::BadStatus => e
+        raise Gcloud::Error.from_error(e)
       end
 
       ##
@@ -119,12 +124,106 @@ module Gcloud
       #
       # @return [Array<Gcloud::Datastore::Entity>]
       #
-      # @example
-      #   dataset.save task1, task2
+      # @example Insert a new entity:
+      #   task = datastore.entity "Task" do |t|
+      #     t["type"] = "Personal"
+      #     t["done"] = false
+      #     t["priority"] = 4
+      #     t["description"] = "Learn Cloud Datastore"
+      #   end
+      #   task.key.id #=> nil
+      #   datastore.save task
+      #   task.key.id #=> 123456
+      #
+      # @example Insert multiple new entities in a batch:
+      #   task1 = datastore.entity "Task" do |t|
+      #     t["type"] = "Personal"
+      #     t["done"] = false
+      #     t["priority"] = 4
+      #     t["description"] = "Learn Cloud Datastore"
+      #   end
+      #
+      #   task2 = datastore.entity "Task" do |t|
+      #     t["type"] = "Personal"
+      #     t["done"] = false
+      #     t["priority"] = 5
+      #     t["description"] = "Integrate Cloud Datastore"
+      #   end
+      #
+      #   task_key1, task_key2 = datastore.save(task1, task2).map(&:key)
+      #
+      # @example Update an existing entity:
+      #   task = datastore.find "Task", "sampleTask"
+      #   task["priority"] = 5
+      #   datastore.save task
       #
       def save *entities
         commit { |c| c.save(*entities) }
       end
+      alias_method :upsert, :save
+
+      ##
+      # Insert one or more entities to the Datastore. An InvalidArgumentError
+      # will raised if the entities cannot be inserted.
+      #
+      # @param [Entity] entities One or more entity objects to be inserted.
+      #
+      # @return [Array<Gcloud::Datastore::Entity>]
+      #
+      # @example Insert a new entity:
+      #   task = datastore.entity "Task" do |t|
+      #     t["type"] = "Personal"
+      #     t["done"] = false
+      #     t["priority"] = 4
+      #     t["description"] = "Learn Cloud Datastore"
+      #   end
+      #   task.key.id #=> nil
+      #   datastore.insert task
+      #   task.key.id #=> 123456
+      #
+      # @example Insert multiple new entities in a batch:
+      #   task1 = datastore.entity "Task" do |t|
+      #     t["type"] = "Personal"
+      #     t["done"] = false
+      #     t["priority"] = 4
+      #     t["description"] = "Learn Cloud Datastore"
+      #   end
+      #
+      #   task2 = datastore.entity "Task" do |t|
+      #     t["type"] = "Personal"
+      #     t["done"] = false
+      #     t["priority"] = 5
+      #     t["description"] = "Integrate Cloud Datastore"
+      #   end
+      #
+      #   task_key1, task_key2 = datastore.insert(task1, task2).map(&:key)
+      #
+      def insert *entities
+        commit { |c| c.insert(*entities) }
+      end
+
+      ##
+      # Update one or more entities to the Datastore. An InvalidArgumentError
+      # will raised if the entities cannot be updated.
+      #
+      # @param [Entity] entities One or more entity objects to be updated.
+      #
+      # @return [Array<Gcloud::Datastore::Entity>]
+      #
+      # @example Update an existing entity:
+      #   task = datastore.find "Task", "sampleTask"
+      #   task["done"] = true
+      #   datastore.save task
+      #
+      # @example update multiple new entities in a batch:
+      #   query = datastore.query("Task").where("done", "=", false)
+      #   tasks = datastore.run query
+      #   tasks.each { |t| t["done"] = true }
+      #   datastore.update tasks
+      #
+      def update *entities
+        commit { |c| c.update(*entities) }
+      end
 
       ##
       # Remove entities from the Datastore.
@@ -136,8 +235,8 @@ module Gcloud
       #
       # @example
       #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
-      #   dataset.delete entity1, entity2
+      #   datastore = gcloud.datastore
+      #   datastore.delete task1, task2
       #
       def delete *entities_or_keys
         commit { |c| c.delete(*entities_or_keys) }
@@ -154,26 +253,34 @@ module Gcloud
       #   persisted.
       #
       # @example
-      #   dataset.commit do |c|
-      #     c.save task1, task2
-      #     c.delete entity1, entity2
+      #   gcloud = Gcloud.new
+      #   datastore = gcloud.datastore
+      #   datastore.commit do |c|
+      #     c.save task3, task4
+      #     c.delete task1, task2
       #   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
+
+        ensure_service!
+        commit_res = service.commit c.mutations
         entities = c.entities
+        returned_keys = commit_res.mutation_results.map(&:key)
+        returned_keys.each_with_index do |key, index|
+          next if entities[index].nil?
+          entities[index].key = Key.from_grpc(key) unless key.nil?
+        end
         entities.each { |e| e.key.freeze unless e.persisted? }
         entities
+      rescue GRPC::BadStatus => e
+        raise Gcloud::Error.from_error(e)
       end
 
       ##
-      # Retrieve an entity by providing key information.
+      # Retrieve an entity by key.
       #
       # @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
@@ -190,11 +297,11 @@ module Gcloud
       # @return [Gcloud::Datastore::Entity, nil]
       #
       # @example Finding an entity with a key:
-      #   key = dataset.key "Task", 123456
-      #   task = dataset.find key
+      #   task_key = datastore.key "Task", "sampleTask"
+      #   task = datastore.find task_key
       #
       # @example Finding an entity with a `kind` and `id`/`name`:
-      #   task = dataset.find "Task", 123456
+      #   task = datastore.find "Task", "sampleTask"
       #
       def find key_or_kind, id_or_name = nil, consistency: nil
         key = key_or_kind
@@ -206,7 +313,8 @@ module Gcloud
       alias_method :get, :find
 
       ##
-      # Retrieve the entities for the provided keys.
+      # Retrieve the entities for the provided keys. The order of results is
+      # undefined and has no relation to the order of `keys` arguments.
       #
       # @param [Key] keys One or more Key objects to find records for.
       # @param [Symbol] consistency The non-transactional read consistency to
@@ -222,26 +330,30 @@ module Gcloud
       #
       # @example
       #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
-      #   key1 = dataset.key "Task", 123456
-      #   key2 = dataset.key "Task", 987654
-      #   tasks = dataset.find_all key1, key2
+      #   datastore = gcloud.datastore
+      #
+      #   task_key1 = datastore.key "Task", "sampleTask1"
+      #   task_key2 = datastore.key "Task", "sampleTask2"
+      #   tasks = datastore.find_all task_key1, task_key2
       #
       def find_all *keys, consistency: nil
+        ensure_service!
         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
+        lookup_res = service.lookup(*keys.map(&:to_grpc),
+                                    consistency: consistency)
+        entities = to_gcloud_entities lookup_res.found
+        deferred = to_gcloud_keys lookup_res.deferred
+        missing  = to_gcloud_entities lookup_res.missing
         LookupResults.new entities, deferred, missing
+      rescue GRPC::BadStatus => e
+        raise Gcloud::Error.from_error(e)
       end
       alias_method :lookup, :find_all
 
       ##
       # Retrieve entities specified by a Query.
       #
-      # @param [Query] query The Query object with the search criteria.
+      # @param [Query, GqlQuery] query The 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
@@ -255,24 +367,43 @@ module Gcloud
       # @return [Gcloud::Datastore::Dataset::QueryResults]
       #
       # @example
-      #   query = dataset.query("Task").
-      #     where("completed", "=", true)
-      #   tasks = dataset.run query
+      #   query = datastore.query("Task").
+      #     where("done", "=", false)
+      #   tasks = datastore.run query
+      #
+      # @example Run an ancestor query with eventual consistency:
+      #   task_list_key = datastore.key "TaskList", "default"
+      #   query.kind("Task").
+      #     ancestor(task_list_key)
+      #
+      #   tasks = datastore.run query, consistency: :eventual
       #
       # @example Run the query within a namespace with the `namespace` option:
-      #   query = Gcloud::Datastore::Query.new.kind("Task").
-      #     where("completed", "=", true)
-      #   tasks = dataset.run query, namespace: "ns~todo-project"
+      #   query = datastore.query("Task").
+      #     where("done", "=", false)
+      #   tasks = datastore.run query, namespace: "ns~todo-project"
+      #
+      # @example Run the query with a GQL string.
+      #   gql_query = datastore.gql "SELECT * FROM Task WHERE done = @done",
+      #                             done: false
+      #   tasks = datastore.run gql_query
+      #
+      # @example Run the GQL query within a namespace with `namespace` option:
+      #   gql_query = datastore.gql "SELECT * FROM Task WHERE done = @done",
+      #                             done: false
+      #   tasks = datastore.run gql_query, namespace: "ns~todo-project"
       #
       def run query, namespace: nil, consistency: nil
-        partition = optional_partition_id namespace
+        ensure_service!
+        unless query.is_a?(Query) || query.is_a?(GqlQuery)
+          fail ArgumentError, "Cannot run a #{query.class} object."
+        end
         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
-        QueryResults.new entities, cursor, more_results
+        query_res = service.run_query query.to_grpc, namespace,
+                                      consistency: consistency
+        QueryResults.from_grpc query_res, service, namespace, query.to_grpc.dup
+      rescue GRPC::BadStatus => e
+        raise Gcloud::Error.from_error(e)
       end
       alias_method :run_query, :run
 
@@ -286,16 +417,18 @@ module Gcloud
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
+      #   datastore = gcloud.datastore
       #
-      #   user = dataset.entity "User", "heidi" do |u|
-      #     u["name"] = "Heidi Henderson"
-      #     u["email"] = "heidi@example.net"
+      #   task = datastore.entity "Task", "sampleTask" do |t|
+      #     t["type"] = "Personal"
+      #     t["done"] = false
+      #     t["priority"] = 4
+      #     t["description"] = "Learn Cloud Datastore"
       #   end
       #
-      #   dataset.transaction do |tx|
-      #     if tx.find(user.key).nil?
-      #       tx.save user
+      #   datastore.transaction do |tx|
+      #     if tx.find(task.key).nil?
+      #       tx.save task
       #     end
       #   end
       #
@@ -303,17 +436,19 @@ module Gcloud
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
+      #   datastore = gcloud.datastore
       #
-      #   user = dataset.entity "User", "heidi" do |u|
-      #     u["name"] = "Heidi Henderson"
-      #     u["email"] = "heidi@example.net"
+      #   task = datastore.entity "Task", "sampleTask" do |t|
+      #     t["type"] = "Personal"
+      #     t["done"] = false
+      #     t["priority"] = 4
+      #     t["description"] = "Learn Cloud Datastore"
       #   end
       #
-      #   tx = dataset.transaction
+      #   tx = datastore.transaction
       #   begin
-      #     if tx.find(user.key).nil?
-      #       tx.save user
+      #     if tx.find(task.key).nil?
+      #       tx.save task
       #     end
       #     tx.commit
       #   rescue
@@ -321,7 +456,7 @@ module Gcloud
       #   end
       #
       def transaction
-        tx = Transaction.new connection
+        tx = Transaction.new service
         return tx unless block_given?
 
         begin
@@ -348,15 +483,15 @@ module Gcloud
       # @return [Gcloud::Datastore::Query]
       #
       # @example
-      #   query = dataset.query("Task").
-      #     where("completed", "=", true)
-      #   tasks = dataset.run query
+      #   query = datastore.query("Task").
+      #     where("done", "=", false)
+      #   tasks = datastore.run query
       #
       # @example The previous example is equivalent to:
       #   query = Gcloud::Datastore::Query.new.
       #     kind("Task").
-      #     where("completed", "=", true)
-      #   tasks = dataset.run query
+      #     where("done", "=", false)
+      #   tasks = datastore.run query
       #
       def query *kinds
         query = Query.new
@@ -364,77 +499,155 @@ module Gcloud
         query
       end
 
+      ##
+      # Create a new GqlQuery instance. This is a convenience method to make the
+      # creation of GqlQuery objects easier.
+      #
+      # @param [String] query The GQL query string.
+      # @param [Hash] bindings Named bindings for the GQL query string, each
+      #   key must match regex `[A-Za-z_$][A-Za-z_$0-9]*`, must not match regex
+      #   `__.*__`, and must not be `""`. The value must be an `Object` that can
+      #   be stored as an Entity property value, or a `Cursor`.
+      #
+      # @return [Gcloud::Datastore::GqlQuery]
+      #
+      # @example
+      #   gql_query = datastore.gql "SELECT * FROM Task WHERE done = @done",
+      #                             done: false
+      #   tasks = datastore.run gql_query
+      #
+      # @example The previous example is equivalent to:
+      #   gql_query = Gcloud::Datastore::GqlQuery.new
+      #   gql_query.query_string = "SELECT * FROM Task WHERE done = @done"
+      #   gql_query.named_bindings = {done: false}
+      #   tasks = datastore.run gql_query
+      #
+      def gql query, bindings = {}
+        gql = GqlQuery.new
+        gql.query_string = query
+        gql.named_bindings = bindings unless bindings.empty?
+        gql
+      end
+
       ##
       # Create a new Key instance. This is a convenience method to make the
       # creation of Key objects easier.
       #
-      # @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.
+      # @param [Array<Array(String,(String|Integer|nil))>] path An optional list
+      #   of pairs for the key's path. Each pair may include the key's kind
+      #   (String) and an id (Integer) or name (String). This is optional.
+      # @param [String] project The project of the Key. This is optional.
+      # @param [String] namespace namespace kind of the Key. This is optional.
       #
       # @return [Gcloud::Datastore::Key]
       #
       # @example
-      #   key = dataset.key "User", "heidi@example.com"
+      #   task_key = datastore.key "Task", "sampleTask"
       #
       # @example The previous example is equivalent to:
-      #   key = Gcloud::Datastore::Key.new "User", "heidi@example.com"
-      #
-      def key kind = nil, id_or_name = nil
-        Key.new kind, id_or_name
+      #   task_key = Gcloud::Datastore::Key.new "Task", "sampleTask"
+      #
+      # @example Create an empty key:
+      #   key = datastore.key
+      #
+      # @example Create an incomplete key:
+      #   key = datastore.key "User"
+      #
+      # @example Create a key with a parent:
+      #   key = datastore.key [["TaskList", "default"], ["Task", "sampleTask"]]
+      #   key.path #=> [["TaskList", "default"], ["Task", "sampleTask"]]
+      #
+      # @example Create a key with multi-level ancestry:
+      #   key = datastore.key([
+      #     ["User", "alice"],
+      #     ["TaskList", "default"],
+      #     ["Task", "sampleTask"]
+      #   ])
+      #   key.path #=> [["User", "alice"], ["TaskList", "default"], [ ... ]]
+      #
+      # @example Create an incomplete key with a parent:
+      #   key = datastore.key "TaskList", "default", "Task"
+      #   key.path #=> [["TaskList", "default"], ["Task", nil]]
+      #
+      # @example Create a key with a project and namespace:
+      #   key = datastore.key ["TaskList", "default"], ["Task", "sampleTask"],
+      #                       project: "my-todo-project",
+      #                       namespace: "ns~todo-project"
+      #   key.path #=> [["TaskList", "default"], ["Task", "sampleTask"]]
+      #   key.project #=> "my-todo-project",
+      #   key.namespace #=> "ns~todo-project"
+      #
+      def key *path, project: nil, namespace: nil
+        path = path.flatten.each_slice(2).to_a # group in pairs
+        kind, id_or_name = path.pop
+        Key.new(kind, id_or_name).tap do |k|
+          k.project = project
+          k.namespace = namespace
+          unless path.empty?
+            k.parent = key path, project: project, namespace: namespace
+          end
+        end
       end
 
       ##
       # Create a new empty Entity instance. This is a convenience method to make
       # the creation of Entity objects easier.
       #
-      # @param [Key, String, nil] key_or_kind A Key object or `kind` string
-      #   value. This is optional.
-      # @param [Integer, String, nil] id_or_name The Key's `id` or `name` value
-      #   if a `kind` was provided in the first parameter.
+      # @param [Key, Array<Array(String,(String|Integer|nil))>] key_or_path An
+      #   optional list of pairs for the key's path. Each pair may include the #
+      #   key's kind (String) and an id (Integer) or name (String). This is #
+      #   optional.
+      # @param [String] project The project of the Key. This is optional.
+      # @param [String] namespace namespace kind of the Key. This is optional.
       # @yield [entity] a block yielding a new entity
       # @yieldparam [Entity] entity the newly created entity object
       #
       # @return [Gcloud::Datastore::Entity]
       #
       # @example
-      #   entity = dataset.entity
+      #   task = datastore.entity
       #
       # @example The previous example is equivalent to:
-      #   entity = Gcloud::Datastore::Entity.new
+      #   task = Gcloud::Datastore::Entity.new
       #
       # @example The key can also be passed in as an object:
-      #   key = dataset.key "User", "heidi@example.com"
-      #   entity = dataset.entity key
+      #   task_key = datastore.key "Task", "sampleTask"
+      #   task = datastore.entity task_key
       #
       # @example Or the key values can be passed in as parameters:
-      #   entity = dataset.entity "User", "heidi@example.com"
+      #   task = datastore.entity "Task", "sampleTask"
       #
       # @example The previous example is equivalent to:
-      #   key = Gcloud::Datastore::Key.new "User", "heidi@example.com"
-      #   entity = Gcloud::Datastore::Entity.new
-      #   entity.key = key
+      #   task_key = Gcloud::Datastore::Key.new "Task", "sampleTask"
+      #   task = Gcloud::Datastore::Entity.new
+      #   task.key = task_key
       #
       # @example The newly created entity can also be configured using a block:
-      #   user = dataset.entity "User", "heidi@example.com" do |u|
-      #     u["name"] = "Heidi Henderson"
-      #  end
+      #   task = datastore.entity "Task", "sampleTask" do |t|
+      #     t["type"] = "Personal"
+      #     t["done"] = false
+      #     t["priority"] = 4
+      #     t["description"] = "Learn Cloud Datastore"
+      #   end
       #
       # @example The previous example is equivalent to:
-      #   key = Gcloud::Datastore::Key.new "User", "heidi@example.com"
-      #   entity = Gcloud::Datastore::Entity.new
-      #   entity.key = key
-      #   entity["name"] = "Heidi Henderson"
-      #
-      def entity key_or_kind = nil, id_or_name = nil
+      #   task_key = Gcloud::Datastore::Key.new "Task", "sampleTask"
+      #   task = Gcloud::Datastore::Entity.new
+      #   task.key = task_key
+      #   task["type"] = "Personal"
+      #   task["done"] = false
+      #   task["priority"] = 4
+      #   task["description"] = "Learn Cloud Datastore"
+      #
+      def entity *key_or_path, project: nil, namespace: nil
         entity = Entity.new
 
         # Set the key
-        key = key_or_kind
-        unless key.is_a? Gcloud::Datastore::Key
-          key = Key.new key_or_kind, id_or_name
+        if key_or_path.flatten.first.is_a? Gcloud::Datastore::Key
+          entity.key = key_or_path.flatten.first
+        else
+          entity.key = key key_or_path, project: project, namespace: namespace
         end
-        entity.key = key
 
         yield entity if block_given?
 
@@ -444,37 +657,27 @@ module Gcloud
       protected
 
       ##
-      # Convenince method to convert proto entities to Gcloud entities.
-      def to_gcloud_entities proto_results
-        # Entities are nested in an object.
-        Array(proto_results).map do |result|
-          Entity.from_proto result.entity
-        end
+      # @private Raise an error unless an active connection to the service is
+      # available.
+      def ensure_service!
+        fail "Must have active connection to service" unless service
       end
 
       ##
-      # Convenince method to convert proto keys to Gcloud keys.
-      def to_gcloud_keys proto_results
-        # Keys are not nested in an object like entities are.
-        Array(proto_results).map do |key|
-          Key.from_proto key
+      # Convenience method to convert GRPC entities to Gcloud entities.
+      def to_gcloud_entities grpc_entity_results
+        # Entities are nested in an object.
+        Array(grpc_entity_results).map do |result|
+          # TODO: Make this return an EntityResult with cursor...
+          Entity.from_grpc result.entity
         end
       end
 
       ##
-      # @private Update saved keys with new IDs post-commit.
-      def auto_id_assign_ids entities, auto_ids
-        Array(auto_ids).each_with_index do |key, index|
-          entity = entities[index]
-          entity.key = Key.from_proto key
-        end
-      end
-
-      def optional_partition_id namespace = nil
-        return nil if namespace.nil?
-        Proto::PartitionId.new.tap do |p|
-          p.namespace = namespace
-        end
+      # Convenience method to convert GRPC keys to Gcloud keys.
+      def to_gcloud_keys grpc_keys
+        # Keys are not nested in an object like entities are.
+        Array(grpc_keys).map { |key| Key.from_grpc key }
       end
 
       def check_consistency! consistency