google-cloud-datastore 0.21.0 → 0.23.0

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

@@ -34,7 +34,7 @@ module Google
                        client_config: nil
           @project = project
           @credentials = credentials
-          @host = host || V1::DatastoreApi::SERVICE_ADDRESS
+          @host = host || V1::DatastoreClient::SERVICE_ADDRESS
           @timeout = timeout
           @client_config = client_config || {}
         end
@@ -53,7 +53,7 @@ module Google
 
         def service
           return mocked_service if mocked_service
-          @service ||= V1::DatastoreApi.new(
+          @service ||= V1::DatastoreClient.new(
             service_path: host,
             channel: channel,
             timeout: timeout,

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

@@ -27,6 +27,10 @@ module Google
       #   Transactions
       #
       # @example Transactional update:
+      #   require "google/cloud/datastore"
+      #
+      #   datastore = Google::Cloud::Datastore.new
+      #
       #   def transfer_funds from_key, to_key, amount
       #     datastore.transaction do |tx|
       #       from = tx.find from_key
@@ -37,16 +41,11 @@ module Google
       #     end
       #   end
       #
-      # @example Retry logic using the transactional update example above:
-      #   (1..5).each do |i|
-      #     begin
-      #       return transfer_funds from_key, to_key, amount
-      #     rescue Google::Cloud::Error => e
-      #       raise e if i == 5
-      #     end
-      #   end
-      #
       # @example Transactional read:
+      #   require "google/cloud/datastore"
+      #
+      #   datastore = Google::Cloud::Datastore.new
+      #
       #   task_list_key = datastore.key "TaskList", "default"
       #   datastore.transaction do |tx|
       #     task_list = tx.find task_list_key
@@ -70,6 +69,10 @@ module Google
         # Persist entities in a transaction.
         #
         # @example Transactional get or create:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   task_key = datastore.key "Task", "sampleTask"
         #
         #   task = nil
@@ -98,6 +101,10 @@ module Google
         # if the entities cannot be inserted.
         #
         # @example Transactional insert:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   task_key = datastore.key "Task", "sampleTask"
         #
         #   task = nil
@@ -125,6 +132,10 @@ module Google
         # if the entities cannot be updated.
         #
         # @example Transactional update:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   task_key = datastore.key "Task", "sampleTask"
         #
         #   task = nil
@@ -146,6 +157,10 @@ module Google
         # Remove entities in a transaction.
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   datastore.transaction do |tx|
         #     if tx.find(task_list.key).nil?
         #       tx.delete task1, task2
@@ -167,10 +182,18 @@ module Google
         # @return [Google::Cloud::Datastore::Entity, nil]
         #
         # @example Finding an entity with a key:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   task_key = datastore.key "Task", "sampleTask"
         #   task = datastore.find task_key
         #
         # @example Finding an entity with a `kind` and `id`/`name`:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   task = datastore.find "Task", "sampleTask"
         #
         def find key_or_kind, id_or_name = nil
@@ -191,7 +214,10 @@ module Google
         # @return [Google::Cloud::Datastore::Dataset::LookupResults]
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
         #   datastore = Google::Cloud::Datastore.new
+        #
         #   task_key1 = datastore.key "Task", 123456
         #   task_key2 = datastore.key "Task", 987654
         #   tasks = datastore.find_all task_key1, task_key2
@@ -214,6 +240,10 @@ module Google
         # @return [Google::Cloud::Datastore::Dataset::QueryResults]
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = datastore.query("Task").
         #     where("done", "=", false)
         #   datastore.transaction do |tx|
@@ -221,6 +251,10 @@ module Google
         #   end
         #
         # @example Run the query within a namespace with the `namespace` option:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new.kind("Task").
         #     where("done", "=", false)
         #   datastore.transaction do |tx|
@@ -287,8 +321,8 @@ module Google
         #   tx = datastore.transaction
         #   begin
         #     tx.commit do |c|
-        #       c.save task1, task2
-        #       c.delete entity1, entity2
+        #     c.save task3, task4
+        #     c.delete task1, task2
         #     end
         #   rescue
         #     tx.rollback

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

@@ -13,4 +13,4 @@
 # limitations under the License.
 
 
-require "google/cloud/datastore/v1/datastore_api"
+require "google/cloud/datastore/v1/datastore_client"

data/lib/google/cloud/datastore/v1/{datastore_api.rb → datastore_client.rb}

@@ -41,7 +41,7 @@ module Google
         #
         # @!attribute [r] datastore_stub
         #   @return [Google::Datastore::V1::Datastore::Stub]
-        class DatastoreApi
+        class DatastoreClient
           attr_reader :datastore_stub
 
           # The default address of the service.
@@ -165,27 +165,27 @@ module Google
           # @return [Google::Datastore::V1::LookupResponse]
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
           # @example
-          #   require "google/cloud/datastore/v1/datastore_api"
+          #   require "google/cloud/datastore/v1/datastore_client"
           #
-          #   DatastoreApi = Google::Cloud::Datastore::V1::DatastoreApi
+          #   DatastoreClient = Google::Cloud::Datastore::V1::DatastoreClient
           #   ReadOptions = Google::Datastore::V1::ReadOptions
           #
-          #   datastore_api = DatastoreApi.new
+          #   datastore_client = DatastoreClient.new
           #   project_id = ''
           #   read_options = ReadOptions.new
           #   keys = []
-          #   response = datastore_api.lookup(project_id, read_options, keys)
+          #   response = datastore_client.lookup(project_id, read_options, keys)
 
           def lookup \
               project_id,
               read_options,
               keys,
               options: nil
-            req = Google::Datastore::V1::LookupRequest.new(
+            req = Google::Datastore::V1::LookupRequest.new({
               project_id: project_id,
               read_options: read_options,
               keys: keys
-            )
+            }.delete_if { |_, v| v.nil? })
             @lookup.call(req, options)
           end
 
@@ -210,17 +210,17 @@ module Google
           # @return [Google::Datastore::V1::RunQueryResponse]
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
           # @example
-          #   require "google/cloud/datastore/v1/datastore_api"
+          #   require "google/cloud/datastore/v1/datastore_client"
           #
-          #   DatastoreApi = Google::Cloud::Datastore::V1::DatastoreApi
+          #   DatastoreClient = Google::Cloud::Datastore::V1::DatastoreClient
           #   PartitionId = Google::Datastore::V1::PartitionId
           #   ReadOptions = Google::Datastore::V1::ReadOptions
           #
-          #   datastore_api = DatastoreApi.new
+          #   datastore_client = DatastoreClient.new
           #   project_id = ''
           #   partition_id = PartitionId.new
           #   read_options = ReadOptions.new
-          #   response = datastore_api.run_query(project_id, partition_id, read_options)
+          #   response = datastore_client.run_query(project_id, partition_id, read_options)
 
           def run_query \
               project_id,
@@ -229,13 +229,13 @@ module Google
               query: nil,
               gql_query: nil,
               options: nil
-            req = Google::Datastore::V1::RunQueryRequest.new(
+            req = Google::Datastore::V1::RunQueryRequest.new({
               project_id: project_id,
               partition_id: partition_id,
-              read_options: read_options
-            )
-            req.query = query unless query.nil?
-            req.gql_query = gql_query unless gql_query.nil?
+              read_options: read_options,
+              query: query,
+              gql_query: gql_query
+            }.delete_if { |_, v| v.nil? })
             @run_query.call(req, options)
           end
 
@@ -249,20 +249,20 @@ module Google
           # @return [Google::Datastore::V1::BeginTransactionResponse]
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
           # @example
-          #   require "google/cloud/datastore/v1/datastore_api"
+          #   require "google/cloud/datastore/v1/datastore_client"
           #
-          #   DatastoreApi = Google::Cloud::Datastore::V1::DatastoreApi
+          #   DatastoreClient = Google::Cloud::Datastore::V1::DatastoreClient
           #
-          #   datastore_api = DatastoreApi.new
+          #   datastore_client = DatastoreClient.new
           #   project_id = ''
-          #   response = datastore_api.begin_transaction(project_id)
+          #   response = datastore_client.begin_transaction(project_id)
 
           def begin_transaction \
               project_id,
               options: nil
-            req = Google::Datastore::V1::BeginTransactionRequest.new(
+            req = Google::Datastore::V1::BeginTransactionRequest.new({
               project_id: project_id
-            )
+            }.delete_if { |_, v| v.nil? })
             @begin_transaction.call(req, options)
           end
 
@@ -297,16 +297,16 @@ module Google
           # @return [Google::Datastore::V1::CommitResponse]
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
           # @example
-          #   require "google/cloud/datastore/v1/datastore_api"
+          #   require "google/cloud/datastore/v1/datastore_client"
           #
-          #   DatastoreApi = Google::Cloud::Datastore::V1::DatastoreApi
+          #   DatastoreClient = Google::Cloud::Datastore::V1::DatastoreClient
           #   Mode = Google::Datastore::V1::CommitRequest::Mode
           #
-          #   datastore_api = DatastoreApi.new
+          #   datastore_client = DatastoreClient.new
           #   project_id = ''
           #   mode = Mode::MODE_UNSPECIFIED
           #   mutations = []
-          #   response = datastore_api.commit(project_id, mode, mutations)
+          #   response = datastore_client.commit(project_id, mode, mutations)
 
           def commit \
               project_id,
@@ -314,12 +314,12 @@ module Google
               mutations,
               transaction: nil,
               options: nil
-            req = Google::Datastore::V1::CommitRequest.new(
+            req = Google::Datastore::V1::CommitRequest.new({
               project_id: project_id,
               mode: mode,
-              mutations: mutations
-            )
-            req.transaction = transaction unless transaction.nil?
+              mutations: mutations,
+              transaction: transaction
+            }.delete_if { |_, v| v.nil? })
             @commit.call(req, options)
           end
 
@@ -336,23 +336,23 @@ module Google
           # @return [Google::Datastore::V1::RollbackResponse]
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
           # @example
-          #   require "google/cloud/datastore/v1/datastore_api"
+          #   require "google/cloud/datastore/v1/datastore_client"
           #
-          #   DatastoreApi = Google::Cloud::Datastore::V1::DatastoreApi
+          #   DatastoreClient = Google::Cloud::Datastore::V1::DatastoreClient
           #
-          #   datastore_api = DatastoreApi.new
+          #   datastore_client = DatastoreClient.new
           #   project_id = ''
           #   transaction = ''
-          #   response = datastore_api.rollback(project_id, transaction)
+          #   response = datastore_client.rollback(project_id, transaction)
 
           def rollback \
               project_id,
               transaction,
               options: nil
-            req = Google::Datastore::V1::RollbackRequest.new(
+            req = Google::Datastore::V1::RollbackRequest.new({
               project_id: project_id,
               transaction: transaction
-            )
+            }.delete_if { |_, v| v.nil? })
             @rollback.call(req, options)
           end
 
@@ -370,23 +370,23 @@ module Google
           # @return [Google::Datastore::V1::AllocateIdsResponse]
           # @raise [Google::Gax::GaxError] if the RPC is aborted.
           # @example
-          #   require "google/cloud/datastore/v1/datastore_api"
+          #   require "google/cloud/datastore/v1/datastore_client"
           #
-          #   DatastoreApi = Google::Cloud::Datastore::V1::DatastoreApi
+          #   DatastoreClient = Google::Cloud::Datastore::V1::DatastoreClient
           #
-          #   datastore_api = DatastoreApi.new
+          #   datastore_client = DatastoreClient.new
           #   project_id = ''
           #   keys = []
-          #   response = datastore_api.allocate_ids(project_id, keys)
+          #   response = datastore_client.allocate_ids(project_id, keys)
 
           def allocate_ids \
               project_id,
               keys,
               options: nil
-            req = Google::Datastore::V1::AllocateIdsRequest.new(
+            req = Google::Datastore::V1::AllocateIdsRequest.new({
               project_id: project_id,
               keys: keys
-            )
+            }.delete_if { |_, v| v.nil? })
             @allocate_ids.call(req, options)
           end
         end

data/lib/google/cloud/datastore/v1/doc/google/datastore/v1/datastore.rb

@@ -0,0 +1,240 @@
+# 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 Google
+  module Datastore
+    module V1
+      # The request for Datastore::Lookup.
+      # @!attribute [rw] project_id
+      #   @return [String]
+      #     The ID of the project against which to make the request.
+      # @!attribute [rw] read_options
+      #   @return [Google::Datastore::V1::ReadOptions]
+      #     The options for this lookup request.
+      # @!attribute [rw] keys
+      #   @return [Array<Google::Datastore::V1::Key>]
+      #     Keys of entities to look up.
+      class LookupRequest; end
+
+      # The response for Datastore::Lookup.
+      # @!attribute [rw] found
+      #   @return [Array<Google::Datastore::V1::EntityResult>]
+      #     Entities found as +ResultType.FULL+ entities. The order of results in this
+      #     field is undefined and has no relation to the order of the keys in the
+      #     input.
+      # @!attribute [rw] missing
+      #   @return [Array<Google::Datastore::V1::EntityResult>]
+      #     Entities not found as +ResultType.KEY_ONLY+ entities. The order of results
+      #     in this field is undefined and has no relation to the order of the keys
+      #     in the input.
+      # @!attribute [rw] deferred
+      #   @return [Array<Google::Datastore::V1::Key>]
+      #     A list of keys that were not looked up due to resource constraints. The
+      #     order of results in this field is undefined and has no relation to the
+      #     order of the keys in the input.
+      class LookupResponse; end
+
+      # The request for Datastore::RunQuery.
+      # @!attribute [rw] project_id
+      #   @return [String]
+      #     The ID of the project against which to make the request.
+      # @!attribute [rw] partition_id
+      #   @return [Google::Datastore::V1::PartitionId]
+      #     Entities are partitioned into subsets, identified by a partition ID.
+      #     Queries are scoped to a single partition.
+      #     This partition ID is normalized with the standard default context
+      #     partition ID.
+      # @!attribute [rw] read_options
+      #   @return [Google::Datastore::V1::ReadOptions]
+      #     The options for this query.
+      # @!attribute [rw] query
+      #   @return [Google::Datastore::V1::Query]
+      #     The query to run.
+      # @!attribute [rw] gql_query
+      #   @return [Google::Datastore::V1::GqlQuery]
+      #     The GQL query to run.
+      class RunQueryRequest; end
+
+      # The response for Datastore::RunQuery.
+      # @!attribute [rw] batch
+      #   @return [Google::Datastore::V1::QueryResultBatch]
+      #     A batch of query results (always present).
+      # @!attribute [rw] query
+      #   @return [Google::Datastore::V1::Query]
+      #     The parsed form of the +GqlQuery+ from the request, if it was set.
+      class RunQueryResponse; end
+
+      # The request for Datastore::BeginTransaction.
+      # @!attribute [rw] project_id
+      #   @return [String]
+      #     The ID of the project against which to make the request.
+      class BeginTransactionRequest; end
+
+      # The response for Datastore::BeginTransaction.
+      # @!attribute [rw] transaction
+      #   @return [String]
+      #     The transaction identifier (always present).
+      class BeginTransactionResponse; end
+
+      # The request for Datastore::Rollback.
+      # @!attribute [rw] project_id
+      #   @return [String]
+      #     The ID of the project against which to make the request.
+      # @!attribute [rw] transaction
+      #   @return [String]
+      #     The transaction identifier, returned by a call to
+      #     Datastore::BeginTransaction.
+      class RollbackRequest; end
+
+      # The response for Datastore::Rollback.
+      # (an empty message).
+      class RollbackResponse; end
+
+      # The request for Datastore::Commit.
+      # @!attribute [rw] project_id
+      #   @return [String]
+      #     The ID of the project against which to make the request.
+      # @!attribute [rw] mode
+      #   @return [Google::Datastore::V1::CommitRequest::Mode]
+      #     The type of commit to perform. Defaults to +TRANSACTIONAL+.
+      # @!attribute [rw] transaction
+      #   @return [String]
+      #     The identifier of the transaction associated with the commit. A
+      #     transaction identifier is returned by a call to
+      #     Datastore::BeginTransaction.
+      # @!attribute [rw] mutations
+      #   @return [Array<Google::Datastore::V1::Mutation>]
+      #     The mutations to perform.
+      #
+      #     When mode is +TRANSACTIONAL+, mutations affecting a single entity are
+      #     applied in order. The following sequences of mutations affecting a single
+      #     entity are not permitted in a single +Commit+ request:
+      #
+      #     - +insert+ followed by +insert+
+      #     - +update+ followed by +insert+
+      #     - +upsert+ followed by +insert+
+      #     - +delete+ followed by +update+
+      #
+      #     When mode is +NON_TRANSACTIONAL+, no two mutations may affect a single
+      #     entity.
+      class CommitRequest
+        # The modes available for commits.
+        module Mode
+          # Unspecified. This value must not be used.
+          MODE_UNSPECIFIED = 0
+
+          # Transactional: The mutations are either all applied, or none are applied.
+          # Learn about transactions {here}[https://cloud.google.com/datastore/docs/concepts/transactions].
+          TRANSACTIONAL = 1
+
+          # Non-transactional: The mutations may not apply as all or none.
+          NON_TRANSACTIONAL = 2
+        end
+      end
+
+      # The response for Datastore::Commit.
+      # @!attribute [rw] mutation_results
+      #   @return [Array<Google::Datastore::V1::MutationResult>]
+      #     The result of performing the mutations.
+      #     The i-th mutation result corresponds to the i-th mutation in the request.
+      # @!attribute [rw] index_updates
+      #   @return [Integer]
+      #     The number of index entries updated during the commit, or zero if none were
+      #     updated.
+      class CommitResponse; end
+
+      # The request for Datastore::AllocateIds.
+      # @!attribute [rw] project_id
+      #   @return [String]
+      #     The ID of the project against which to make the request.
+      # @!attribute [rw] keys
+      #   @return [Array<Google::Datastore::V1::Key>]
+      #     A list of keys with incomplete key paths for which to allocate IDs.
+      #     No key may be reserved/read-only.
+      class AllocateIdsRequest; end
+
+      # The response for Datastore::AllocateIds.
+      # @!attribute [rw] keys
+      #   @return [Array<Google::Datastore::V1::Key>]
+      #     The keys specified in the request (in the same order), each with
+      #     its key path completed with a newly allocated ID.
+      class AllocateIdsResponse; end
+
+      # A mutation to apply to an entity.
+      # @!attribute [rw] insert
+      #   @return [Google::Datastore::V1::Entity]
+      #     The entity to insert. The entity must not already exist.
+      #     The entity key's final path element may be incomplete.
+      # @!attribute [rw] update
+      #   @return [Google::Datastore::V1::Entity]
+      #     The entity to update. The entity must already exist.
+      #     Must have a complete key path.
+      # @!attribute [rw] upsert
+      #   @return [Google::Datastore::V1::Entity]
+      #     The entity to upsert. The entity may or may not already exist.
+      #     The entity key's final path element may be incomplete.
+      # @!attribute [rw] delete
+      #   @return [Google::Datastore::V1::Key]
+      #     The key of the entity to delete. The entity may or may not already exist.
+      #     Must have a complete key path and must not be reserved/read-only.
+      # @!attribute [rw] base_version
+      #   @return [Integer]
+      #     The version of the entity that this mutation is being applied to. If this
+      #     does not match the current version on the server, the mutation conflicts.
+      class Mutation; end
+
+      # The result of applying a mutation.
+      # @!attribute [rw] key
+      #   @return [Google::Datastore::V1::Key]
+      #     The automatically allocated key.
+      #     Set only when the mutation allocated a key.
+      # @!attribute [rw] version
+      #   @return [Integer]
+      #     The version of the entity on the server after processing the mutation. If
+      #     the mutation doesn't change anything on the server, then the version will
+      #     be the version of the current entity or, if no entity is present, a version
+      #     that is strictly greater than the version of any previous entity and less
+      #     than the version of any possible future entity.
+      # @!attribute [rw] conflict_detected
+      #   @return [true, false]
+      #     Whether a conflict was detected for this mutation. Always false when a
+      #     conflict detection strategy field is not set in the mutation.
+      class MutationResult; end
+
+      # The options shared by read requests.
+      # @!attribute [rw] read_consistency
+      #   @return [Google::Datastore::V1::ReadOptions::ReadConsistency]
+      #     The non-transactional read consistency to use.
+      #     Cannot be set to +STRONG+ for global queries.
+      # @!attribute [rw] transaction
+      #   @return [String]
+      #     The identifier of the transaction in which to read. A
+      #     transaction identifier is returned by a call to
+      #     Datastore::BeginTransaction.
+      class ReadOptions
+        # The possible values for read consistencies.
+        module ReadConsistency
+          # Unspecified. This value must not be used.
+          READ_CONSISTENCY_UNSPECIFIED = 0
+
+          # Strong consistency.
+          STRONG = 1
+
+          # Eventual consistency.
+          EVENTUAL = 2
+        end
+      end
+    end
+  end
+end