google-cloud-datastore 2.6.0 → 2.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1471082bad6f76859fd0172a40bac47c81c31d3bc7f42e0f5135547f280307a6
-  data.tar.gz: a182edc1deadbfe697c45fad2bcde90379c58d07985833fd3f4bca64584bfaf2
+  metadata.gz: 646ed90d461784d6870d425a6f98271a249338a72696200b3b2707d3e4725098
+  data.tar.gz: 963afff082dd55de2dce0f58715bd76c17497e118b0db92b7a542b6dd813b00d
 SHA512:
-  metadata.gz: 41ae448187ef6bbd842bcafcb2c6cbd107b81e4dfb55b72bbfb62857af387a82b4361cc3b86cdf00ab2657a5b98bcf6f51c1caf2090b2c922f8f3db03016e19a
-  data.tar.gz: 25725fc96567a06df8c6b75c4b29f9ff8077e77b59a7bb1c31d0c384a9a0d880d9e0d807653f75986c56d428dbcf7aaf09fa4074f7335eef76dcc520e21c9304
+  metadata.gz: 832baf39842dd1261ee5394284a0cc8448bd65fbf08162cc49a95f16654676f4dae76d4cb80be58a2692f7035f613b3b1668bf6e5f7d73f175a3f3ad7d6e3eb0
+  data.tar.gz: dd2b0d16cf4727a342e305a6c3dee82add4ce10f5faac8c691216e9e4a88d356d89cb49684cc71b92bfe162bc9aa099abca54c260698ca96722400a729a952e7

data/AUTHENTICATION.md

@@ -125,15 +125,6 @@ To configure your system for this, simply:
 **NOTE:** This is _not_ recommended for running in production. The Cloud SDK
 *should* only be used during development.
 
-[gce-how-to]: https://cloud.google.com/compute/docs/authentication#using
-[dev-console]: https://console.cloud.google.com/project
-
-[enable-apis]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/enable-apis.png
-
-[create-new-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account.png
-[create-new-service-account-existing-keys]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account-existing-keys.png
-[reuse-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/reuse-service-account.png
-
 ## Creating a Service Account
 
 Google Cloud requires a **Project ID** and **Service Account Credentials** to
@@ -144,31 +135,22 @@ If you are not running this client within [Google Cloud Platform
 environments](#google-cloud-platform-environments), you need a Google
 Developers service account.
 
-1. Visit the [Google Developers Console][dev-console].
+1. Visit the [Google Cloud Console](https://console.cloud.google.com/project).
 1. Create a new project or click on an existing project.
-1. Activate the slide-out navigation tray and select **API Manager**. From
+1. Activate the menu in the upper left and select **APIs & Services**. From
    here, you will enable the APIs that your application requires.
 
-   ![Enable the APIs that your application requires][enable-apis]
-
    *Note: You may need to enable billing in order to use these services.*
 
 1. Select **Credentials** from the side navigation.
 
-   You should see a screen like one of the following.
-
-   ![Create a new service account][create-new-service-account]
-
-   ![Create a new service account With Existing Keys][create-new-service-account-existing-keys]
-
-   Find the "Add credentials" drop down and select "Service account" to be
-   guided through downloading a new JSON key file.
-
-   If you want to re-use an existing service account, you can easily generate a
-   new key file. Just select the account you wish to re-use, and click "Generate
-   new JSON key":
+   Find the "Create credentials" drop down near the top of the page, and select
+   "Service account" to be guided through downloading a new JSON key file.
 
-   ![Re-use an existing service account][reuse-service-account]
+   If you want to re-use an existing service account, you can easily generate 
+   a new key file. Just select the account you wish to re-use click the pencil
+   tool on the right side to edit the service account, select the **Keys** tab,
+   and then select **Add Key**.
 
    The key file you download will be used by this library to authenticate API
    requests and should be stored in a secure location.

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Release History
 
+### 2.7.1 (2023-05-18)
+
+#### Documentation
+
+* Fixed broken links in authentication documentation ([#21619](https://github.com/googleapis/google-cloud-ruby/issues/21619)) 
+
+### 2.7.0 (2023-04-12)
+
+#### Features
+
+* Support OR filter ([#21002](https://github.com/googleapis/google-cloud-ruby/issues/21002)) 
+
 ### 2.6.0 (2023-02-13)
 
 #### Features

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

@@ -57,18 +57,20 @@ module Google
       #
       class AggregateQuery
         ##
-        # @private The Google::Cloud::Datastore::V1::Query object.
-        attr_reader :query
+        # @private The Google::Cloud::Datastore::V1::AggregationQuery object.
+        attr_reader :grpc
 
         ##
-        # @private Array of Google::Cloud::Datastore::V1::AggregationQuery::Aggregation objects
-        attr_reader :aggregates
-
-        ##
-        # @private Creates a new AggregateQuery
+        # @private
+        #
+        # Returns a new AggregateQuery object
+        #
+        # @param query [Google::Cloud::Datastore::V1::Query]
         def initialize query
-          @query = query
-          @aggregates = []
+          @grpc = Google::Cloud::Datastore::V1::AggregationQuery.new(
+            nested_query: query,
+            aggregations: []
+          )
         end
 
         ##
@@ -112,7 +114,7 @@ module Google
         #
         def add_count aggregate_alias: nil
           aggregate_alias ||= ALIASES[:count]
-          aggregates << Google::Cloud::Datastore::V1::AggregationQuery::Aggregation.new(
+          @grpc.aggregations << Google::Cloud::Datastore::V1::AggregationQuery::Aggregation.new(
             count: Google::Cloud::Datastore::V1::AggregationQuery::Aggregation::Count.new,
             alias: aggregate_alias
           )
@@ -122,10 +124,7 @@ module Google
 
         # @private
         def to_grpc
-          Google::Cloud::Datastore::V1::AggregationQuery.new(
-            nested_query: query,
-            aggregations: aggregates
-          )
+          @grpc
         end
 
         ##

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

@@ -981,6 +981,38 @@ module Google
           entity
         end
 
+        ##
+        # Create a new Filter instance. This is a convenience method to make the
+        # creation of Filter objects easier.
+        #
+        # @param name [String] The property to filter by.
+        # @param operator [String] The operator to filter by. Defaults to nil.
+        # @param value [Object] The value to compare the property to. Defaults
+        #       to nil. Possible values are:
+        #         - Integer
+        #         - Float/BigDecimal
+        #         - String
+        #         - Boolean
+        #         - Array
+        #         - Date/Time
+        #         - StringIO
+        #         - Google::Cloud::Datastore::Key
+        #         - Google::Cloud::Datastore::Entity
+        #         - nil
+        #
+        # @return [Google::Cloud::Datastore::Filter]
+        #
+        # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   filter = datastore.filter("done", "=", false)
+        #
+        def filter name, operator, value
+          Filter.new name, operator, value
+        end
+
         protected
 
         ##

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

@@ -0,0 +1,222 @@
+# Copyright 2023 Google LLC
+#
+# 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
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "google/cloud/datastore/v1"
+
+module Google
+  module Cloud
+    module Datastore
+      ##
+      # Filter
+      #
+      # Represents the filter criteria for a datastore query.
+      #
+      # @example Run a query with a simple property filter.
+      #   require "google/cloud/datastore"
+      #
+      #   datastore = Google::Cloud::Datastore.new
+      #
+      #   filter = Google::Cloud::Datastore::Filter.new("done", "=", "false")
+      #
+      #   query = Google::Cloud::Datastore::Query.new
+      #   query.kind("Task")
+      #        .where(filter)
+      #
+      #   tasks = datastore.run query
+      #
+      # @example Construct a composite filter with a logical OR.
+      #   require "google/cloud/datastore"
+      #
+      #   datastore = Google::Cloud::Datastore.new
+      #
+      #   filter = Google::Cloud::Datastore::Filter.new("done", "=", "false")
+      #                                            .or("priority", ">=", "4")
+      #
+      #   query = Google::Cloud::Datastore::Query.new
+      #   query.kind("Task")
+      #        .where(filter)
+      #
+      #   tasks = datastore.run query
+      #
+      # @example Construct a composite filter by combining multiple filters.
+      #   require "google/cloud/datastore"
+      #
+      #   datastore = Google::Cloud::Datastore.new
+      #
+      #   filter_1 = Google::Cloud::Datastore::Filter.new("done", "=", "false")
+      #   filter_2 = Google::Cloud::Datastore::Filter.new("priority", ">=", "4")
+      #   filter = filter_1.or(filter_2)
+      #
+      #   query = Google::Cloud::Datastore::Query.new
+      #   query.kind("Task")
+      #        .where(filter)
+      #
+      #   tasks = datastore.run query
+      #
+      class Filter
+        ##
+        # @private Object of type
+        # Google::Cloud::Datastore::V1::Filter
+        attr_accessor :grpc
+
+        ##
+        # Creates a new Filter.
+        #
+        # @example
+        #   require "google/cloud/datastore"
+        #
+        #   filter = Google::Cloud::Datastore::Filter.new("done", "=", "false")
+        #
+        def initialize name, operator, value
+          @grpc = create_property_filter name, operator, value
+        end
+
+        ##
+        # Joins two filters with an AND operator.
+        #
+        # @overload and(name, operator, value)
+        #   Joins the filter with a property filter
+        #   @param name [String]
+        #   @param operator [String]
+        #   @param value
+        #
+        # @overload and(filter)
+        #   Joins the filter with a Filter object
+        #   @param filter [Filter]
+        #
+        # @example Join the filter with a property filter
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   filter = Google::Cloud::Filter.new("done", "=", false)
+        #                                 .and("priority", ">=", 4)
+        #
+        # @example Join the filter with a filter object
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   filter_1 = Google::Cloud::Filter.new("done", "=", false)
+        #   filter_2 = Google::Cloud::Filter.new("priority", ">=", 4)
+        #
+        #   filter = filter_1.and(filter_2)
+        #
+        def and name_or_filter, operator = nil, value = nil
+          combine_filters composite_filter_and, name_or_filter, operator, value
+        end
+
+        ##
+        # Joins two filters with an OR operator.
+        #
+        # @overload or(name, operator, value)
+        #   Joins the filter with a property filter
+        #   @param name [String] The property to filter by.
+        #   @param operator [String] The operator to filter by. Defaults to nil.
+        #   @param value [Object] The value to compare the property to. Defaults to nil.
+        #       Possible values are:
+        #         - Integer
+        #         - Float/BigDecimal
+        #         - String
+        #         - Boolean
+        #         - Array
+        #         - Date/Time
+        #         - StringIO
+        #         - Google::Cloud::Datastore::Key
+        #         - Google::Cloud::Datastore::Entity
+        #         - nil
+        #
+        # @overload or(filter)
+        #   Joins the filter with a Filter object
+        #   @param flter [Filter]
+        #
+        # @example Join the filter with a property filter
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   filter = Google::Cloud::Filter.new("done", "=", false)
+        #                                 .or("priority", ">=", 4)
+        #
+        # @example Join the filter with a filter object
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   filter_1 = Google::Cloud::Filter.new("done", "=", false)
+        #   filter_2 = Google::Cloud::Filter.new("priority", ">=", 4)
+        #
+        #   filter = filter_1.or(filter_2)
+        #
+        def or name_or_filter, operator = nil, value = nil
+          combine_filters composite_filter_or, name_or_filter, operator, value
+        end
+
+        # @private
+        def to_grpc
+          @grpc
+        end
+
+        protected
+
+        ##
+        # @private
+        #
+        # Combines self.grpc and (name_or_filter, operator, value)
+        # into the new_filter object with the specified AND/OR operator
+        def combine_filters new_filter, name_or_filter, operator, value
+          new_filter.composite_filter.filters << to_grpc
+          new_filter.composite_filter.filters << if name_or_filter.is_a? Google::Cloud::Datastore::Filter
+                                                   name_or_filter.to_grpc
+                                                 else
+                                                   create_property_filter name_or_filter, operator, value
+                                                 end
+          dup.tap do |f|
+            f.grpc = new_filter
+          end
+        end
+
+        ##
+        # @private
+        def composite_filter_and
+          Google::Cloud::Datastore::V1::Filter.new(
+            composite_filter: Google::Cloud::Datastore::V1::CompositeFilter.new(op: :AND)
+          )
+        end
+
+        ##
+        # @private
+        def composite_filter_or
+          Google::Cloud::Datastore::V1::Filter.new(
+            composite_filter: Google::Cloud::Datastore::V1::CompositeFilter.new(op: :OR)
+          )
+        end
+
+        ##
+        # @private
+        def create_property_filter name, operator, value
+          Google::Cloud::Datastore::V1::Filter.new(
+            property_filter: Google::Cloud::Datastore::V1::PropertyFilter.new(
+              property: Google::Cloud::Datastore::V1::PropertyReference.new(
+                name: name
+              ),
+              op: Convert.to_prop_filter_op(operator),
+              value: Convert.to_value(value)
+            )
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -16,6 +16,7 @@
 require "google/cloud/datastore/entity"
 require "google/cloud/datastore/key"
 require "google/cloud/datastore/aggregate_query"
+require "google/cloud/datastore/filter"
 
 module Google
   module Cloud
@@ -96,6 +97,27 @@ module Google
         ##
         # Add a property filter to the query.
         #
+        # @overload and(name, operator, value)
+        #   Joins the filter with a property filter
+        #   @param name [String] The property to filter by.
+        #   @param operator [String] The operator to filter by. Defaults to nil.
+        #   @param value [Object] The value to compare the property to. Defaults to nil.
+        #       Possible values are:
+        #         - Integer
+        #         - Float/BigDecimal
+        #         - String
+        #         - Boolean
+        #         - Array
+        #         - Date/Time
+        #         - StringIO
+        #         - Google::Cloud::Datastore::Key
+        #         - Google::Cloud::Datastore::Entity
+        #         - nil
+        #
+        # @overload and(filter)
+        #   Joins the filter with a Filter object
+        #   @param filter [Filter]
+        #
         # @example
         #   require "google/cloud/datastore"
         #
@@ -119,6 +141,34 @@ module Google
         #
         #   tasks = datastore.run query
         #
+        # @example Add a composite "AND" filter:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   filter = Google::Cloud::Filter.new("done", "=", false)
+        #                                 .and("priority", ">=", 4)
+        #
+        #   query = Google::Cloud::Datastore::Query.new
+        #   query.kind("Task")
+        #        .where(filter)
+        #
+        #   tasks = datastore.run query
+        #
+        # @example Add a composite "OR" filter:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   filter = Google::Cloud::Filter.new("done", "=", false)
+        #                                 .or("priority", ">=", 4)
+        #
+        #   query = Google::Cloud::Datastore::Query.new
+        #   query.kind("Task")
+        #        .where(filter)
+        #
+        #   tasks = datastore.run query
+        #
         # @example Add an inequality filter on a **single** property only:
         #   require "google/cloud/datastore"
         #
@@ -177,22 +227,18 @@ module Google
         #
         #   tasks = datastore.run query
         #
-        def where name, operator, value
+        def where name_or_filter, operator = nil, value = nil
           @grpc.filter ||= Google::Cloud::Datastore::V1::Filter.new(
             composite_filter: Google::Cloud::Datastore::V1::CompositeFilter.new(
               op: :AND
             )
           )
-          @grpc.filter.composite_filter.filters << \
-            Google::Cloud::Datastore::V1::Filter.new(
-              property_filter: Google::Cloud::Datastore::V1::PropertyFilter.new(
-                property: Google::Cloud::Datastore::V1::PropertyReference.new(
-                  name: name
-                ),
-                op: Convert.to_prop_filter_op(operator),
-                value: Convert.to_value(value)
-              )
-            )
+          if name_or_filter.is_a? Google::Cloud::Datastore::Filter
+            @grpc.filter.composite_filter.filters << name_or_filter.to_grpc
+          else
+            @grpc.filter.composite_filter.filters << \
+              Google::Cloud::Datastore::Filter.new(name_or_filter, operator, value).to_grpc
+          end
 
           self
         end

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

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-datastore
 version: !ruby/object:Gem::Version
-  version: 2.6.0
+  version: 2.7.1
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-02-13 00:00:00.000000000 Z
+date: 2023-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -210,6 +210,7 @@ files:
 - lib/google/cloud/datastore/dataset/query_results.rb
 - lib/google/cloud/datastore/entity.rb
 - lib/google/cloud/datastore/errors.rb
+- lib/google/cloud/datastore/filter.rb
 - lib/google/cloud/datastore/gql_query.rb
 - lib/google/cloud/datastore/key.rb
 - lib/google/cloud/datastore/properties.rb