google-cloud-datastore 1.5.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84e32dc83d15b1968b75bce2847502aaf2bd391a67f7dc19ba704c3d9af9b245
-  data.tar.gz: 213483d73df19c3babf7d45f654ec2c7e7c7c596b9b56be1e0b1da1c4b7a11ac
+  metadata.gz: 72ce967e2225a7f45b099b3183e72b450e2a424540423ccdbcecd3f04d4df5a7
+  data.tar.gz: 7bc5dc5ef826d16c6e3732ed496deacb53e239c3a0583fa46babeeb5253bc91c
 SHA512:
-  metadata.gz: bbf78ed2bc3775acf045de75cf42681382a236a3285cf05b950b0e75a7dd1c92d7fb95dfd3cef3f097273be974afd74c118b3b7b782526ea26c848bc03a6e406
-  data.tar.gz: 86698b32f18c809a98d4089b73eb8c1cc1490c5ec6c5680799849f7ace763efa8c2330e34cb72ad214275d7ced5bd769b596e8aff20a7aea6a00a63b3c6aa3ae
+  metadata.gz: 0babd961bc284b94502cb3dcccfa5da0fea60fd6277ca5c8da2a5527e9cde189d0d18eb1ac6d3b66f0f1676e81d0eddfdd5e068cbfe3a3da0c1f07e05651fb34
+  data.tar.gz: 03d6099865662209ce9824bfd3601391b78996d62377b34d80bbaff2c8f9b25fe04ff8c8563aa8fcdf24a000850d20df1243ddd96b963ca80a2906475ea1f421

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Release History
 
+### 1.5.1 / 2019-02-13
+
+* Add `ReadOnlyTransaction` convenience methods:
+  * Add `ReadOnlyTransaction#query`
+  * Add `ReadOnlyTransaction#gql`
+  * Add `ReadOnlyTransaction#key`
+
 ### 1.5.0 / 2019-02-01
 
 * Make use of Credentials#project_id
@@ -8,7 +15,7 @@
     This value was added in googleauth 0.7.0.
   * Loosen googleauth dependency
     Allow for new releases up to 0.10.
-    The googleauth devs have committed to maintanining the current API
+    The googleauth devs have committed to maintaining the current API
     and will not make backwards compatible changes before 0.10.
 
 ### 1.4.4 / 2018-09-20

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

@@ -139,9 +139,9 @@ module Google
         #
         #   datastore = Google::Cloud::Datastore.new
         #
-        #   query = datastore.query("Task").
-        #     where("done", "=", false)
         #   datastore.read_only_transaction do |tx|
+        #     query = tx.query("Task").
+        #       where("done", "=", false)
         #     tasks = tx.run query
         #   end
         #
@@ -179,12 +179,12 @@ module Google
         #   datastore = Google::Cloud::Datastore.new
         #
         #   task_list_key = datastore.key "TaskList", "default"
-        #   query = datastore.query("Task").
-        #     ancestor(task_list_key)
         #
         #   tx = datastore.transaction
         #   task_list = tx.find task_list_key
         #   if task_list
+        #     query = tx.query("Task").
+        #       ancestor(task_list_key)
         #     tasks = tx.run query
         #   end
         #   tx.commit
@@ -209,12 +209,12 @@ module Google
         #   datastore = Google::Cloud::Datastore.new
         #
         #   task_list_key = datastore.key "TaskList", "default"
-        #   query = datastore.query("Task").
-        #     ancestor(task_list_key)
         #
         #   tx = datastore.transaction
         #   task_list = tx.find task_list_key
         #   if task_list
+        #     query = tx.query("Task").
+        #       ancestor(task_list_key)
         #     tasks = tx.run query
         #   end
         #   tx.rollback
@@ -236,6 +236,152 @@ module Google
           @id = nil
         end
 
+        ##
+        # Create a new Query instance. This is a convenience method to make the
+        # creation of Query objects easier.
+        #
+        # @param [String] kinds The kind of entities to query. This is optional.
+        #
+        # @return [Google::Cloud::Datastore::Query]
+        #
+        # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   datastore.read_only_transaction do |tx|
+        #     query = tx.query("Task").
+        #       where("done", "=", false)
+        #     tasks = tx.run query
+        #   end
+        #
+        def query *kinds
+          query = Query.new
+          query.kind(*kinds) unless kinds.empty?
+          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 [Google::Cloud::Datastore::GqlQuery]
+        #
+        # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   datastore.read_only_transaction do |tx|
+        #     gql_query = tx.gql "SELECT * FROM Task WHERE done = @done",
+        #                        done: false
+        #     tasks = tx.run gql_query
+        #   end
+        #
+        # @example The previous example is equivalent to:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   datastore.read_only_transaction do |tx|
+        #     gql_query = Google::Cloud::Datastore::GqlQuery.new
+        #     gql_query.query_string = "SELECT * FROM Task WHERE done = @done"
+        #     gql_query.named_bindings = {done: false}
+        #     tasks = tx.run gql_query
+        #   end
+        #
+        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 [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 [Google::Cloud::Datastore::Key]
+        #
+        # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   datastore.read_only_transaction do |tx|
+        #     task_key = tx.key "Task", "sampleTask"
+        #   end
+        #
+        # @example The previous example is equivalent to:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   datastore.read_only_transaction do |tx|
+        #     task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
+        #   end
+        #
+        # @example Create a key with a parent:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   datastore.read_only_transaction do |tx|
+        #     key = tx.key [["TaskList", "default"], ["Task", "sampleTask"]]
+        #     results = tx.find_all key
+        #   end
+        #
+        # @example Create a key with multi-level ancestry:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   datastore.read_only_transaction do |tx|
+        #     key = tx.key([
+        #       ["User", "alice"],
+        #       ["TaskList", "default"],
+        #       ["Task", "sampleTask"]
+        #     ])
+        #     results = tx.find_all key
+        #   end
+        #
+        # @example Create a key with a project and namespace:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   datastore.read_only_transaction do |tx|
+        #     key = tx.key ["TaskList", "default"], ["Task", "sampleTask"],
+        #                  project: "my-todo-project",
+        #                  namespace: "example-ns"
+        #     results = tx.find_all key
+        #   end
+        #
+        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
+
         protected
 
         ##

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Datastore
-      VERSION = "1.5.0".freeze
+      VERSION = "1.5.1".freeze
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-datastore
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.5.1
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-02-01 00:00:00.000000000 Z
+date: 2019-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core