google-cloud-firestore 2.11.0 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8fe0d4f3e79da21256a4495d0a19da58febfaf27298ea1735fef2042c8c7281
-  data.tar.gz: 10e4929cd461e369991e153356d3878add4b179c972715880734456b566832ca
+  metadata.gz: c8d082b21e20a784bbc4ded66f836f6d04bd36b9925791edabe11e8d134427b4
+  data.tar.gz: f7d0f0cc23591434e68a92fee5132860fa6128cdaa3fbe4d3143911eb0c5f147
 SHA512:
-  metadata.gz: 7491e2f8033a2e2033e37e77b16e0401f9ecd77e9e357ecf47c72ab55204df6a7b8aa0a8bdf508d58215c3f6e3818a3ffaa7eebd0cc425e9355fe987df1bc478
-  data.tar.gz: 0f92c886ee8ba0043782aae64166947efd7d5ea1ccd0968fd21fa1bc2e7936f2eba3cb4805853a569d3631e221415fb2649a9c6a5aac101c87cdab1976558472
+  metadata.gz: 19c611f16d93bedede808df8f049f9e6ec500a49e1b883b4d7e658d3c7f940c7afdf05eb4407615b80e91ee849eea6091662a886bf442b0a12f7887837578c8b
+  data.tar.gz: 9948560560760181151c1ec60f0c005a84e6ec1ae29c05f40efcca77d6be159f60592eafed854c69e7ab75a075c19b3786316782dccd5b98efaa814354f7d7e1

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 2.12.0 (2023-04-20)
+
+#### Features
+
+* Add support for OR query ([#20920](https://github.com/googleapis/google-cloud-ruby/issues/20920)) 
+
 ### 2.11.0 (2023-02-23)
 
 #### Features

data/lib/google/cloud/firestore/client.rb

@@ -23,6 +23,7 @@ require "google/cloud/firestore/document_snapshot"
 require "google/cloud/firestore/collection_group"
 require "google/cloud/firestore/batch"
 require "google/cloud/firestore/transaction"
+require "google/cloud/firestore/filter"
 
 module Google
   module Cloud
@@ -185,6 +186,56 @@ module Google
         end
         alias collection_group col_group
 
+        ##
+        # Creates a filter object.
+        #
+        # @param field [FieldPath, String, Symbol] A field path to filter
+        #   results with.
+        #   If a {FieldPath} object is not provided then the field will be
+        #   treated as a dotted string, meaning the string represents individual
+        #   fields joined by ".". Fields containing `~`, `*`, `/`, `[`, `]`, and
+        #   `.` cannot be in a dotted string, and should provided using a
+        #   {FieldPath} object instead.
+        #
+        # @param operator [String, Symbol] The operation to compare the field
+        #   to. Acceptable values include:
+        #   * less than: `<`, `lt`
+        #   * less than or equal: `<=`, `lte`
+        #   * greater than: `>`, `gt`
+        #   * greater than or equal: `>=`, `gte`
+        #   * equal: `=`, `==`, `eq`, `eql`, `is`
+        #   * not equal: `!=`
+        #   * in: `in`
+        #   * not in: `not-in`, `not_in`
+        #   * array contains: `array-contains`, `array_contains`
+        #
+        # @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::Firestore::Filter] New filter object.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Create a filter
+        #   filter = firestore.filter(:population, :>=, 1000000)
+        #
+        def filter field, operator, value
+          Filter.new field, operator, value
+        end
+
         ##
         # Retrieves a document reference.
         #

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

@@ -0,0 +1,326 @@
+# 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/firestore/v1"
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # Represents the filter for structured query.
+      #
+      class Filter
+        ##
+        # @private Object of type
+        # Google::Cloud::Firestore::V1::StructuredQuery::Filter
+        attr_accessor :filter
+
+        ##
+        # Create a Filter object.
+        #
+        # @param field [FieldPath, String, Symbol] A field path to filter
+        #   results with.
+        #   If a {FieldPath} object is not provided then the field will be
+        #   treated as a dotted string, meaning the string represents individual
+        #   fields joined by ".". Fields containing `~`, `*`, `/`, `[`, `]`, and
+        #   `.` cannot be in a dotted string, and should provided using a
+        #   {FieldPath} object instead.
+        #
+        # @param operator [String, Symbol] The operation to compare the field
+        #   to. Acceptable values include:
+        #   * less than: `<`, `lt`
+        #   * less than or equal: `<=`, `lte`
+        #   * greater than: `>`, `gt`
+        #   * greater than or equal: `>=`, `gte`
+        #   * equal: `=`, `==`, `eq`, `eql`, `is`
+        #   * not equal: `!=`
+        #   * in: `in`
+        #   * not in: `not-in`, `not_in`
+        #   * array contains: `array-contains`, `array_contains`
+        #
+        # @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::Firestore::Filter] New filter for the given condition
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Create a Filter
+        #   Google::Cloud::Firestore::Filter.new(:population, :>=, 1000000)
+        #
+        def initialize field, operator, value
+          @filter = create_filter field, operator, value
+        end
+
+        ##
+        # Joins filter using AND operator.
+        #
+        # @overload where(filter)
+        #   Pass Firestore::Filter to `where` via field_or_filter argument.
+        #
+        #  @param filter [::Google::Cloud::Firestore::Filter]
+        #
+        # @overload where(field, operator, value)
+        #   Pass arguments to `where` via positional arguments.
+        #
+        #   @param field [FieldPath, String, Symbol] A field path to filter
+        #     results with.
+        #     If a {FieldPath} object is not provided then the field will be
+        #     treated as a dotted string, meaning the string represents individual
+        #     fields joined by ".". Fields containing `~`, `*`, `/`, `[`, `]`, and
+        #     `.` cannot be in a dotted string, and should provided using a
+        #     {FieldPath} object instead.
+        #
+        #   @param operator [String, Symbol] The operation to compare the field
+        #     to. Acceptable values include:
+        #     * less than: `<`, `lt`
+        #     * less than or equal: `<=`, `lte`
+        #     * greater than: `>`, `gt`
+        #     * greater than or equal: `>=`, `gte`
+        #     * equal: `=`, `==`, `eq`, `eql`, `is`
+        #     * not equal: `!=`
+        #     * in: `in`
+        #     * not in: `not-in`, `not_in`
+        #     * array contains: `array-contains`, `array_contains`
+        #
+        #   @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 [Filter] New Filter object.
+        #
+        # @example Pass a Filter type object in argument
+        #   require "google/cloud/firestore"
+        #
+        #   filter_1 = Google::Cloud::Firestore.Firestore.new(:population, :>=, 1000000)
+        #   filter_2 = Google::Cloud::Firestore.Firestore.new("done", "=", "false")
+        #
+        #   filter = filter_1.and(filter_2)
+        #
+        # @example Pass filter conditions in the argument
+        #   require "google/cloud/firestore"
+        #
+        #   filter_1 = Google::Cloud::Firestore.Firestore.new(:population, :>=, 1000000)
+        #
+        #   filter = filter_1.and("done", "=", "false")
+        #
+        def and filter_or_field = nil, operator = nil, value = nil
+          combine_filters composite_filter_and, filter_or_field, operator, value
+        end
+
+        ##
+        # Joins filter using OR operator.
+        #
+        # @overload where(filter)
+        #   Pass Firestore::Filter to `where` via field_or_filter argument.
+        #
+        #  @param filter [::Google::Cloud::Firestore::Filter]
+        #
+        # @overload where(field, operator, value)
+        #   Pass arguments to `where` via positional arguments.
+        #
+        #   @param field [FieldPath, String, Symbol] A field path to filter
+        #     results with.
+        #     If a {FieldPath} object is not provided then the field will be
+        #     treated as a dotted string, meaning the string represents individual
+        #     fields joined by ".". Fields containing `~`, `*`, `/`, `[`, `]`, and
+        #     `.` cannot be in a dotted string, and should provided using a
+        #     {FieldPath} object instead.
+        #
+        #   @param operator [String, Symbol] The operation to compare the field
+        #     to. Acceptable values include:
+        #     * less than: `<`, `lt`
+        #     * less than or equal: `<=`, `lte`
+        #     * greater than: `>`, `gt`
+        #     * greater than or equal: `>=`, `gte`
+        #     * equal: `=`, `==`, `eq`, `eql`, `is`
+        #     * not equal: `!=`
+        #     * in: `in`
+        #     * not in: `not-in`, `not_in`
+        #     * array contains: `array-contains`, `array_contains`
+        #
+        #   @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 [Filter] New Filter object.
+        #
+        # @example Pass a Filter type object in argument
+        #   require "google/cloud/firestore"
+        #
+        #   filter_1 = Google::Cloud::Firestore.Firestore.new(:population, :>=, 1000000)
+        #   filter_2 = Google::Cloud::Firestore.Firestore.new("done", "=", "false")
+        #
+        #   filter = filter_1.or(filter_2)
+        #
+        # @example Pass filter conditions in the argument
+        #   require "google/cloud/firestore"
+        #
+        #   filter_1 = Google::Cloud::Firestore.Firestore.new(:population, :>=, 1000000)
+        #
+        #   filter = filter_1.or("done", "=", "false")
+        #
+        def or filter_or_field = nil, operator = nil, value = nil
+          combine_filters composite_filter_or, filter_or_field, operator, value
+        end
+
+        private
+
+        ##
+        # @private
+        StructuredQuery = Google::Cloud::Firestore::V1::StructuredQuery
+
+        ##
+        # @private
+        FILTER_OPS = {
+          "<"                  => :LESS_THAN,
+          "lt"                 => :LESS_THAN,
+          "<="                 => :LESS_THAN_OR_EQUAL,
+          "lte"                => :LESS_THAN_OR_EQUAL,
+          ">"                  => :GREATER_THAN,
+          "gt"                 => :GREATER_THAN,
+          ">="                 => :GREATER_THAN_OR_EQUAL,
+          "gte"                => :GREATER_THAN_OR_EQUAL,
+          "="                  => :EQUAL,
+          "=="                 => :EQUAL,
+          "eq"                 => :EQUAL,
+          "eql"                => :EQUAL,
+          "is"                 => :EQUAL,
+          "!="                 => :NOT_EQUAL,
+          "array_contains"     => :ARRAY_CONTAINS,
+          "array-contains"     => :ARRAY_CONTAINS,
+          "include"            => :ARRAY_CONTAINS,
+          "include?"           => :ARRAY_CONTAINS,
+          "has"                => :ARRAY_CONTAINS,
+          "in"                 => :IN,
+          "not_in"             => :NOT_IN,
+          "not-in"             => :NOT_IN,
+          "array_contains_any" => :ARRAY_CONTAINS_ANY,
+          "array-contains-any" => :ARRAY_CONTAINS_ANY
+        }.freeze
+
+        ##
+        # @private
+        INEQUALITY_FILTERS = [
+          :LESS_THAN,
+          :LESS_THAN_OR_EQUAL,
+          :GREATER_THAN,
+          :GREATER_THAN_OR_EQUAL
+        ].freeze
+
+        def composite_filter_and
+          StructuredQuery::Filter.new(
+            composite_filter: StructuredQuery::CompositeFilter.new(op: :AND)
+          )
+        end
+
+        def composite_filter_or
+          StructuredQuery::Filter.new(
+            composite_filter: StructuredQuery::CompositeFilter.new(op: :OR)
+          )
+        end
+
+        def combine_filters new_filter, filter_or_field, operator, value
+          new_filter.composite_filter.filters << @filter
+          new_filter.composite_filter.filters << if filter_or_field.is_a? Google::Cloud::Firestore::Filter
+                                                   filter_or_field.filter
+                                                 else
+                                                   create_filter filter_or_field, operator, value
+                                                 end
+          dup.tap do |f|
+            f.filter = new_filter
+          end
+        end
+
+        def value_nil? value
+          [nil, :null, :nil].include? value
+        end
+
+        def value_nan? value
+          # Comparing NaN values raises, so check for #nan? first.
+          return true if value.respond_to?(:nan?) && value.nan?
+          [:nan].include? value
+        end
+
+        def value_unary? value
+          value_nil?(value) || value_nan?(value)
+        end
+
+        def create_filter field, op_key, value
+          return if field.nil? && op_key.nil? && value.nil?
+          field = FieldPath.parse field unless field.is_a? FieldPath
+          field = StructuredQuery::FieldReference.new field_path: field.formatted_string.to_s
+          operator = FILTER_OPS[op_key.to_s.downcase]
+          raise ArgumentError, "unknown operator #{op_key}" if operator.nil?
+
+          if value_unary? value
+            operator = case operator
+                       when :EQUAL
+                         value_nan?(value) ? :IS_NAN : :IS_NULL
+                       when :NOT_EQUAL
+                         value_nan?(value) ? :IS_NOT_NAN : :IS_NOT_NULL
+                       else
+                         raise ArgumentError, "can only perform '==' and '!=' comparisons on #{value} values"
+                       end
+
+            return StructuredQuery::Filter.new(
+              unary_filter: StructuredQuery::UnaryFilter.new(
+                field: field, op: operator
+              )
+            )
+          end
+
+          value = Convert.raw_to_value value
+          StructuredQuery::Filter.new(
+            field_filter: StructuredQuery::FieldFilter.new(
+              field: field, op: operator, value: value
+            )
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -18,6 +18,7 @@ require "google/cloud/firestore/document_snapshot"
 require "google/cloud/firestore/query_listener"
 require "google/cloud/firestore/convert"
 require "google/cloud/firestore/aggregate_query"
+require "google/cloud/firestore/filter"
 require "json"
 
 module Google
@@ -210,29 +211,48 @@ module Google
         end
 
         ##
-        # Filters the query on a field.
-        #
-        # @param [FieldPath, String, Symbol] field A field path to filter
-        #   results with.
-        #
-        #   If a {FieldPath} object is not provided then the field will be
-        #   treated as a dotted string, meaning the string represents individual
-        #   fields joined by ".". Fields containing `~`, `*`, `/`, `[`, `]`, and
-        #   `.` cannot be in a dotted string, and should provided using a
-        #   {FieldPath} object instead.
-        # @param [String, Symbol] operator The operation to compare the field
-        #   to. Acceptable values include:
-        #
-        #   * less than: `<`, `lt`
-        #   * less than or equal: `<=`, `lte`
-        #   * greater than: `>`, `gt`
-        #   * greater than or equal: `>=`, `gte`
-        #   * equal: `=`, `==`, `eq`, `eql`, `is`
-        #   * not equal: `!=`
-        #   * in: `in`
-        #   * not in: `not-in`, `not_in`
-        #   * array contains: `array-contains`, `array_contains`
-        # @param [Object] value A value the field is compared to.
+        # Adds filter to the where clause
+        #
+        # @overload where(filter)
+        #   Pass Firestore::Filter to `where` via field_or_filter argument.
+        #
+        #  @param filter [::Google::Cloud::Firestore::Filter]
+        #
+        # @overload where(field, operator, value)
+        #   Pass arguments to `where` via positional arguments.
+        #
+        #   @param field [FieldPath, String, Symbol] A field path to filter
+        #     results with.
+        #     If a {FieldPath} object is not provided then the field will be
+        #     treated as a dotted string, meaning the string represents individual
+        #     fields joined by ".". Fields containing `~`, `*`, `/`, `[`, `]`, and
+        #     `.` cannot be in a dotted string, and should provided using a
+        #     {FieldPath} object instead.
+        #
+        #   @param operator [String, Symbol] The operation to compare the field
+        #     to. Acceptable values include:
+        #     * less than: `<`, `lt`
+        #     * less than or equal: `<=`, `lte`
+        #     * greater than: `>`, `gt`
+        #     * greater than or equal: `>=`, `gte`
+        #     * equal: `=`, `==`, `eq`, `eql`, `is`
+        #     * not equal: `!=`
+        #     * in: `in`
+        #     * not in: `not-in`, `not_in`
+        #     * array contains: `array-contains`, `array_contains`
+        #
+        #   @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 [Query] New query with `where` called on it.
         #
@@ -251,7 +271,25 @@ module Google
         #     puts "#{city.document_id} has #{city[:population]} residents."
         #   end
         #
-        def where field, operator, value
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #
+        #   # Create a filter
+        #   filter = Filter.create(:population, :>=, 1000000)
+        #
+        #   # Add filter to where clause
+        #   query = query.where filter
+        #
+        #   query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        def where filter_or_field = nil, operator = nil, value = nil
           if query_has_cursors?
             raise "cannot call where after calling " \
                   "start_at, start_after, end_before, or end_at"
@@ -260,10 +298,12 @@ module Google
           new_query = @query.dup
           new_query ||= StructuredQuery.new
 
-          field = FieldPath.parse field unless field.is_a? FieldPath
-
-          new_filter = filter field.formatted_string, operator, value
-          add_filters_to_query new_query, new_filter
+          if filter_or_field.is_a? Google::Cloud::Firestore::Filter
+            new_query.where = filter_or_field.filter
+          else
+            new_filter = Google::Cloud::Firestore::Filter.new filter_or_field, operator, value
+            add_filters_to_query new_query, new_filter.filter
+          end
 
           Query.start new_query, parent_path, client, limit_type: limit_type
         end
@@ -1087,34 +1127,6 @@ module Google
         # @private
         StructuredQuery = Google::Cloud::Firestore::V1::StructuredQuery
 
-        ##
-        # @private
-        FILTER_OPS = {
-          "<"                  => :LESS_THAN,
-          "lt"                 => :LESS_THAN,
-          "<="                 => :LESS_THAN_OR_EQUAL,
-          "lte"                => :LESS_THAN_OR_EQUAL,
-          ">"                  => :GREATER_THAN,
-          "gt"                 => :GREATER_THAN,
-          ">="                 => :GREATER_THAN_OR_EQUAL,
-          "gte"                => :GREATER_THAN_OR_EQUAL,
-          "="                  => :EQUAL,
-          "=="                 => :EQUAL,
-          "eq"                 => :EQUAL,
-          "eql"                => :EQUAL,
-          "is"                 => :EQUAL,
-          "!="                 => :NOT_EQUAL,
-          "array_contains"     => :ARRAY_CONTAINS,
-          "array-contains"     => :ARRAY_CONTAINS,
-          "include"            => :ARRAY_CONTAINS,
-          "include?"           => :ARRAY_CONTAINS,
-          "has"                => :ARRAY_CONTAINS,
-          "in"                 => :IN,
-          "not_in"             => :NOT_IN,
-          "not-in"             => :NOT_IN,
-          "array_contains_any" => :ARRAY_CONTAINS_ANY,
-          "array-contains-any" => :ARRAY_CONTAINS_ANY
-        }.freeze
         ##
         # @private
         INEQUALITY_FILTERS = [
@@ -1138,36 +1150,6 @@ module Google
           value_nil?(value) || value_nan?(value)
         end
 
-        def filter name, op_key, value
-          field = StructuredQuery::FieldReference.new field_path: name.to_s
-          operator = FILTER_OPS[op_key.to_s.downcase]
-          raise ArgumentError, "unknown operator #{op_key}" if operator.nil?
-
-          if value_unary? value
-            operator = case operator
-                       when :EQUAL
-                         value_nan?(value) ? :IS_NAN : :IS_NULL
-                       when :NOT_EQUAL
-                         value_nan?(value) ? :IS_NOT_NAN : :IS_NOT_NULL
-                       else
-                         raise ArgumentError, "can only perform '==' and '!=' comparisons on #{value} values"
-                       end
-
-            return StructuredQuery::Filter.new(
-              unary_filter: StructuredQuery::UnaryFilter.new(
-                field: field, op: operator
-              )
-            )
-          end
-
-          value = Convert.raw_to_value value
-          StructuredQuery::Filter.new(
-            field_filter: StructuredQuery::FieldFilter.new(
-              field: field, op: operator, value: value
-            )
-          )
-        end
-
         def composite_filter
           StructuredQuery::Filter.new(
             composite_filter: StructuredQuery::CompositeFilter.new(op: :AND)

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Firestore
-      VERSION = "2.11.0".freeze
+      VERSION = "2.12.0".freeze
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-firestore
 version: !ruby/object:Gem::Version
-  version: 2.11.0
+  version: 2.12.0
 platform: ruby
 authors:
 - Google Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-02-23 00:00:00.000000000 Z
+date: 2023-04-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -242,6 +242,7 @@ files:
 - lib/google/cloud/firestore/document_snapshot.rb
 - lib/google/cloud/firestore/field_path.rb
 - lib/google/cloud/firestore/field_value.rb
+- lib/google/cloud/firestore/filter.rb
 - lib/google/cloud/firestore/generate.rb
 - lib/google/cloud/firestore/query.rb
 - lib/google/cloud/firestore/query_listener.rb