google-cloud-firestore 0.23.0 → 0.24.0

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

@@ -302,6 +302,56 @@ module Google
           FieldValue.server_time
         end
 
+        ##
+        # Creates a sentinel value to indicate the union of the given values
+        # with an array.
+        #
+        # @param [Object] values The values to add to the array. Required.
+        #
+        # @return [FieldValue] The array union field value object.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a document reference
+        #   nyc_ref = firestore.doc "cities/NYC"
+        #
+        #   array_union = firestore.field_array_union 1, 2, 3
+        #
+        #   nyc_ref.update({ name: "New York City",
+        #                    lucky_numbers: array_union })
+        #
+        def field_array_union *values
+          FieldValue.array_union(*values)
+        end
+
+        ##
+        # Creates a sentinel value to indicate the removal of the given values
+        # with an array.
+        #
+        # @param [Object] values The values to remove from the array. Required.
+        #
+        # @return [FieldValue] The array delete field value object.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a document reference
+        #   nyc_ref = firestore.doc "cities/NYC"
+        #
+        #   array_delete = firestore.field_array_delete 7, 8, 9
+        #
+        #   nyc_ref.update({ name: "New York City",
+        #                    lucky_numbers: array_delete })
+        #
+        def field_array_delete *values
+          FieldValue.array_delete(*values)
+        end
+
         # @!endgroup
 
         # @!group Operations

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

@@ -153,9 +153,9 @@ module Google
             end
             raise ArgumentError, "data is required" unless data.is_a? Hash
 
-            data, server_time_paths = remove_field_value_from data, :server_time
+            data, field_paths_and_values = remove_field_value_from data
 
-            if data.any? || server_time_paths.empty?
+            if data.any? || field_paths_and_values.empty?
               write = Google::Firestore::V1beta1::Write.new(
                 update: Google::Firestore::V1beta1::Document.new(
                   name: doc_path,
@@ -166,8 +166,8 @@ module Google
               writes << write
             end
 
-            if server_time_paths.any?
-              transform_write = transform_write doc_path, server_time_paths
+            if field_paths_and_values.any?
+              transform_write = transform_write doc_path, field_paths_and_values
 
               if data.empty?
                 transform_write.current_document = \
@@ -205,7 +205,7 @@ module Google
               raise ArgumentError, "DELETE not allowed on set"
             end
 
-            data, server_time_paths = remove_field_value_from data, :server_time
+            data, field_paths_and_values = remove_field_value_from data
 
             writes << Google::Firestore::V1beta1::Write.new(
               update: Google::Firestore::V1beta1::Document.new(
@@ -213,8 +213,8 @@ module Google
                 fields: hash_to_fields(data))
             )
 
-            if server_time_paths.any?
-              writes << transform_write(doc_path, server_time_paths)
+            if field_paths_and_values.any?
+              writes << transform_write(doc_path, field_paths_and_values)
             end
 
             writes
@@ -242,15 +242,15 @@ module Google
             all_valid_check = all_valid_check.include? false
             raise ArgumentError, "all fields must be in data" if all_valid_check
 
-            data, delete_paths = remove_field_value_from data, :delete
-            data, server_time_paths = remove_field_value_from data, :server_time
+            data, delete_field_paths_and_values = remove_field_value_from data, :delete
+            data, field_paths_and_values = remove_field_value_from data
 
-            delete_valid_check = delete_paths.map do |delete_path|
-              if field_paths.include?(delete_path)
+            delete_valid_check = delete_field_paths_and_values.keys.map do |delete_field_path|
+              if field_paths.include? delete_field_path
                 true
               else
                 found_in_field_paths = field_paths.select do |fp|
-                  fp.formatted_string.start_with? "#{delete_path.formatted_string}."
+                  fp.formatted_string.start_with? "#{delete_field_path.formatted_string}."
                 end
                 found_in_field_paths.any?
               end
@@ -258,26 +258,26 @@ module Google
             delete_valid_check = delete_valid_check.include? false
             raise ArgumentError, "deleted field not included in merge" if delete_valid_check
 
-            server_time_paths.select! do |server_time_path|
+            field_paths_and_values.select! do |server_time_path|
               field_paths.any? do |field_path|
                 server_time_path.formatted_string.start_with? field_path.formatted_string
               end
             end
 
             # Choose only the data there are field paths for
-            field_paths -= delete_paths
-            field_paths -= server_time_paths
+            field_paths -= delete_field_paths_and_values.keys
+            field_paths -= field_paths_and_values.keys
             data = select_by_field_paths data, field_paths
             # Restore delete paths
-            field_paths += delete_paths
+            field_paths += delete_field_paths_and_values.keys
 
             if data.empty? && !allow_empty
-              if server_time_paths.empty? && delete_paths.empty?
+              if field_paths_and_values.empty? && delete_field_paths_and_values.empty?
                 raise ArgumentError, "data required for set with merge"
               end
             end
 
-            if data.any? || field_paths.any? || (allow_empty && server_time_paths.empty?)
+            if data.any? || field_paths.any? || (allow_empty && field_paths_and_values.empty?)
               writes << Google::Firestore::V1beta1::Write.new(
                 update: Google::Firestore::V1beta1::Document.new(
                   name: doc_path,
@@ -287,8 +287,8 @@ module Google
               )
             end
 
-            if server_time_paths.any?
-              writes << transform_write(doc_path, server_time_paths)
+            if field_paths_and_values.any?
+              writes << transform_write(doc_path, field_paths_and_values)
             end
 
             writes
@@ -312,29 +312,29 @@ module Google
               value.is_a?(FieldValue) && value.type == :delete
             end
 
-            root_server_time_paths, new_data_pairs = new_data_pairs.partition do |field_path, value|
-              value.is_a?(FieldValue) && value.type == :server_time
+            root_field_paths_and_values, new_data_pairs = new_data_pairs.partition do |field_path, value|
+              value.is_a? FieldValue
             end
 
             data = build_hash_from_field_paths_and_values new_data_pairs
             field_paths = new_data_pairs.map(&:first)
 
             delete_paths.map!(&:first)
-            root_server_time_paths.map!(&:first)
+            root_field_paths_and_values = Hash[root_field_paths_and_values]
 
             data, nested_deletes = remove_field_value_from data, :delete
             raise ArgumentError, "DELETE cannot be nested" if nested_deletes.any?
 
-            data, nested_server_time_paths = remove_field_value_from data, :server_time
+            data, nested_field_paths_and_values  = remove_field_value_from data
 
-            server_time_paths = root_server_time_paths + nested_server_time_paths
+            field_paths_and_values = root_field_paths_and_values.merge nested_field_paths_and_values
 
             field_paths = (field_paths + delete_paths).uniq
             field_paths.each do |field_path|
               raise ArgumentError, "empty paths not allowed" if field_path.fields.empty?
             end
 
-            if data.empty? && delete_paths.empty? && server_time_paths.empty?
+            if data.empty? && delete_paths.empty? && field_paths_and_values.empty?
               raise ArgumentError, "data is required"
             end
 
@@ -356,8 +356,8 @@ module Google
               writes << write
             end
 
-            if server_time_paths.any?
-              transform_write = transform_write doc_path, server_time_paths
+            if field_paths_and_values.any?
+              transform_write = transform_write doc_path, field_paths_and_values
               if data.empty?
                 transform_write.current_document = \
                   Google::Firestore::V1beta1::Precondition.new(exists: true)
@@ -387,32 +387,34 @@ module Google
             write
           end
 
-          def is_field_value_nested obj, field_value_type
-            return true if obj.is_a?(FieldValue) && obj.type == field_value_type
+          def is_field_value_nested obj, field_value_type = nil
+            return obj if obj.is_a?(FieldValue) && (field_value_type.nil? || obj.type == field_value_type)
 
             if obj.is_a? Array
-              obj.each { |o| val = is_field_value_nested o, field_value_type; return true if val }
+              obj.each { |o| val = is_field_value_nested o, field_value_type; return val if val }
             elsif obj.is_a? Hash
-              obj.each { |_k, v| val = is_field_value_nested v, field_value_type; return true if val }
+              obj.each { |_k, v| val = is_field_value_nested v, field_value_type; return val if val }
             end
-            false
+            nil
           end
 
-          def remove_field_value_from obj, field_value_type
+          def remove_field_value_from obj, field_value_type = nil
             return [nil, []] unless obj.is_a? Hash
 
             paths = []
             new_pairs = obj.map do |key, value|
-              if value.is_a?(FieldValue) && value.type == field_value_type
-                paths << [key]
+              if value.is_a?(FieldValue) && (field_value_type.nil? || value.type == field_value_type)
+                paths << [FieldPath.new(*key), value]
                 nil # will be removed by calling compact
               else
                 if value.is_a? Hash
                   unless value.empty?
                     nested_hash, nested_paths = remove_field_value_from value, field_value_type
                     if nested_paths.any?
-                      nested_paths.each do |nested_path|
-                        paths << (([key] + nested_path.fields).flatten)
+                      nested_paths.each do |nested_field_path, nested_field_value|
+                        updated_field_paths = ([key] + nested_field_path.fields).flatten
+                        updated_field_path = FieldPath.new *updated_field_paths
+                        paths << [updated_field_path, nested_field_value]
                       end
                     end
                     if nested_hash.empty?
@@ -425,8 +427,9 @@ module Google
                   end
                 else
                   if value.is_a? Array
-                    if is_field_value_nested value, field_value_type
-                      raise ArgumentError, "cannot nest #{field_value_type} under arrays"
+                    nested_field_value = is_field_value_nested value, field_value_type
+                    if nested_field_value
+                      raise ArgumentError, "cannot nest #{nested_field_value.type} under arrays"
                     end
                   end
 
@@ -435,10 +438,8 @@ module Google
               end
             end
 
-            paths.map! { |path| FieldPath.new *path }
-
-            # return a new hash and paths
-            [Hash[new_pairs.compact], paths]
+            # return new data hash and field path/values hash
+            [Hash[new_pairs.compact], Hash[paths]]
           end
 
           def identify_leaf_nodes hash
@@ -578,12 +579,9 @@ module Google
             "`#{str}`"
           end
 
-          def transform_write doc_path, paths, server_value: :REQUEST_TIME
-            field_transforms = paths.map do |path|
-              Google::Firestore::V1beta1::DocumentTransform::FieldTransform.new(
-                field_path: path.formatted_string,
-                set_to_server_value: server_value
-              )
+          def transform_write doc_path, paths
+            field_transforms = paths.map do |field_path, field_value|
+              to_field_transform field_path, field_value
             end
 
             Google::Firestore::V1beta1::Write.new(
@@ -593,6 +591,27 @@ module Google
               )
             )
           end
+
+          def to_field_transform field_path, field_value
+            if field_value.type == :server_time
+              Google::Firestore::V1beta1::DocumentTransform::FieldTransform.new(
+                field_path: field_path.formatted_string,
+                set_to_server_value: :REQUEST_TIME
+              )
+            elsif field_value.type == :array_union
+              Google::Firestore::V1beta1::DocumentTransform::FieldTransform.new(
+                field_path: field_path.formatted_string,
+                append_missing_elements: raw_to_value(Array(field_value.values)).array_value
+              )
+            elsif field_value.type == :array_delete
+              Google::Firestore::V1beta1::DocumentTransform::FieldTransform.new(
+                field_path: field_path.formatted_string,
+                remove_all_from_array: raw_to_value(Array(field_value.values)).array_value
+              )
+            else
+              raise ArgumentError, "unknown field transform #{field_value.type}"
+            end
+          end
         end
         # rubocop:enable all
 

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

@@ -35,8 +35,9 @@ module Google
         ##
         # @private Creates a field value object representing changes made to
         # fields in document data.
-        def initialize type
+        def initialize type, values = nil
           @type = type
+          @values = values
         end
 
         ##
@@ -62,6 +63,34 @@ module Google
           @type
         end
 
+        ##
+        # @private
+        # The values to change to an individual field in document data,
+        # depending on the type of change.
+        #
+        # @return [Array<Object>] The values.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a document reference
+        #   nyc_ref = firestore.doc "cities/NYC"
+        #
+        #   array_union = Google::Cloud::Firestore::FieldValue.array_union(
+        #     1, 2, 3
+        #   )
+        #   array_union.type #=> :array_union
+        #   array_union.values #=> [1, 2, 3]
+        #
+        #   nyc_ref.update({ name: "New York City",
+        #                    lucky_numbers: array_union })
+        #
+        def values
+          @values
+        end
+
         ##
         # Creates a field value object representing the deletion of a field in
         # document data.
@@ -107,6 +136,72 @@ module Google
         def self.server_time
           new :server_time
         end
+
+        ##
+        # Creates a sentinel value to indicate the union of the given values
+        # with an array.
+        #
+        # @param [Object] values The values to add to the array. Required.
+        #
+        # @return [FieldValue] The array union field value object.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a document reference
+        #   nyc_ref = firestore.doc "cities/NYC"
+        #
+        #   array_union = Google::Cloud::Firestore::FieldValue.array_union(
+        #     1, 2, 3
+        #   )
+        #
+        #   nyc_ref.update({ name: "New York City",
+        #                    lucky_numbers: array_union })
+        #
+        def self.array_union *values
+          # We can flatten the values because arrays don't support sub-arrays
+          values.flatten!
+          raise ArgumentError, "values must be provided" if values.nil?
+          # verify the values are the correct types
+          Convert.raw_to_value values
+
+          new :array_union, values
+        end
+
+        ##
+        # Creates a sentinel value to indicate the removal of the given values
+        # with an array.
+        #
+        # @param [Object] values The values to remove from the array. Required.
+        #
+        # @return [FieldValue] The array delete field value object.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a document reference
+        #   nyc_ref = firestore.doc "cities/NYC"
+        #
+        #   array_delete = Google::Cloud::Firestore::FieldValue.array_delete(
+        #     7, 8, 9
+        #   )
+        #
+        #   nyc_ref.update({ name: "New York City",
+        #                    lucky_numbers: array_delete })
+        #
+        def self.array_delete *values
+          # We can flatten the values because arrays don't support sub-arrays
+          values.flatten!
+          raise ArgumentError, "values must be provided" if values.nil?
+          # verify the values are the correct types
+          Convert.raw_to_value values
+
+          new :array_delete, values
+        end
       end
     end
   end

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

@@ -212,6 +212,7 @@ module Google
         #   * greater than: `>`, `gt`
         #   * greater than or equal: `>=`, `gte`
         #   * equal: `=`, `==`, `eq`, `eql`, `is`
+        #   * array contains: `array-contains`, `array_contains`
         # @param [Object] value A value the field is compared to.
         #
         # @return [Query] New query with `where` called on it.
@@ -887,22 +888,41 @@ module Google
         ##
         # @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
+          "<"              => :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,
+          "array_contains" => :ARRAY_CONTAINS,
+          "array-contains" => :ARRAY_CONTAINS,
+          "include"        => :ARRAY_CONTAINS,
+          "include?"       => :ARRAY_CONTAINS,
+          "has"            => :ARRAY_CONTAINS
         }.freeze
         ##
         # @private
+        EQUALITY_FILTERS = %i[
+          EQUAL
+          ARRAY_CONTAINS
+        ].freeze
+        ##
+        # @private
+        INEQUALITY_FILTERS = %i[
+          LESS_THAN
+          LESS_THAN_OR_EQUAL
+          GREATER_THAN
+          GREATER_THAN_OR_EQUAL
+        ].freeze
+        ##
+        # @private
         UNARY_NIL_VALUES = [nil, :null, :nil].freeze
         ##
         # @private
@@ -1048,7 +1068,7 @@ module Google
                     end
           ineq_filters = filters.select do |filter|
             if filter.filter_type == :field_filter
-              filter.field_filter.op != :EQUAL
+              INEQUALITY_FILTERS.include? filter.field_filter.op
             end
           end
           ineq_filters.map { |filter| filter.field_filter.field.field_path }