google-cloud-firestore 2.7.2 → 2.15.0

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

@@ -17,6 +17,8 @@ require "google/cloud/firestore/v1"
 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
@@ -209,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.
         #
@@ -250,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"
@@ -259,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
@@ -903,6 +944,9 @@ module Google
         ##
         # Retrieves document snapshots for the query.
         #
+        # @param [Time] read_time Reads documents as they were at the given time.
+        #   This may not be older than 270 seconds. Optional
+        #
         # @yield [documents] The block for accessing the document snapshots.
         # @yieldparam [DocumentSnapshot] document A document snapshot.
         #
@@ -923,12 +967,29 @@ module Google
         #     puts "#{city.document_id} has #{city[:population]} residents."
         #   end
         #
-        def get
+        # @example Get query with read time
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #
+        #   # Create a query
+        #   query = cities_col.select(:population)
+        #
+        #   read_time = Time.now
+        #
+        #   query.get(read_time: read_time) do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        def get read_time: nil
           ensure_service!
 
-          return enum_for :get unless block_given?
+          return enum_for :get, read_time: read_time unless block_given?
 
-          results = service.run_query parent_path, @query
+          results = service.run_query parent_path, @query, read_time: read_time
 
           # Reverse the results for Query#limit_to_last queries since that method reversed the order_by directions.
           results = results.to_a.reverse if limit_type == :last
@@ -940,6 +1001,26 @@ module Google
         end
         alias run get
 
+        ##
+        # Creates an AggregateQuery object for the query.
+        #
+        # @return [AggregateQuery] New empty aggregate query.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   query = firestore.col "cities"
+        #
+        #   # Create an aggregate query
+        #   aggregate_query = query.aggregate_query
+        #
+        def aggregate_query
+          AggregateQuery.new self, parent_path, client
+        end
+
         ##
         # Listen to this query for changes.
         #
@@ -1046,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 = [
@@ -1097,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/rate_limiter.rb

@@ -0,0 +1,80 @@
+# 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.
+
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # @private Implements 5/5/5 ramp-up via Token Bucket algorithm.
+      #
+      # 5/5/5 is a ramp up strategy that starts with a budget of 500 operations per
+      # second. Additionally, every 5 minutes, the maximum budget can increase by
+      # 50%. Thus, at 5:01 into a long bulk-writing process, the maximum budget
+      # becomes 750 operations per second. At 10:01, the budget becomes 1,125
+      # operations per second.
+      #
+      class RateLimiter
+        DEFAULT_STARTING_MAXIMUM_OPS_PER_SECOND = 500.0
+        DEFAULT_PHASE_LENGTH = 300.0
+
+        attr_reader :bandwidth
+
+        ##
+        # Initialize the object
+        def initialize starting_ops: nil, phase_length: nil
+          @start_time = time
+          @last_fetched = time
+          @bandwidth = (starting_ops || DEFAULT_STARTING_MAXIMUM_OPS_PER_SECOND).to_f
+          @phase_length = phase_length || DEFAULT_PHASE_LENGTH
+        end
+
+        ##
+        # Wait till the number of tokens is available
+        # Assumes that the bandwidth is distributed evenly across the entire second.
+        #
+        # Example - If the limit is 500 qps, then it has been further broken down to 2e+6 nsec
+        # per query
+        #
+        # @return [nil]
+        def wait_for_tokens size
+          available_time = @last_fetched + (size / @bandwidth)
+          waiting_time = [0, available_time - time].max
+          sleep waiting_time
+          @last_fetched = time
+          increase_bandwidth
+        end
+
+        private
+
+        ##
+        # Returns time elapsed since epoch.
+        #
+        # @return [Float] Float denoting time elapsed since epoch
+        def time
+          Time.now.to_f
+        end
+
+        ##
+        # Increase the bandwidth as per 555 rule
+        #
+        # @return [nil]
+        def increase_bandwidth
+          intervals = (time - @start_time) / @phase_length
+          @bandwidth = (DEFAULT_STARTING_MAXIMUM_OPS_PER_SECOND * (1.5**intervals.floor)).to_f
+        end
+      end
+    end
+  end
+end

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

@@ -30,29 +30,34 @@ module Google
         attr_accessor :credentials
         attr_accessor :timeout
         attr_accessor :host
+        attr_accessor :database
 
         ##
         # Creates a new Service instance.
-        def initialize project, credentials, host: nil, timeout: nil
+        def initialize project, credentials, host: nil, timeout: nil, database: nil, transport: :grpc
           @project = project
           @credentials = credentials
           @host = host
           @timeout = timeout
+          @database = database
+          @transport = transport
         end
 
         def firestore
-          @firestore ||= \
-            V1::Firestore::Client.new do |config|
+          @firestore ||= begin
+            client_class = @transport == :rest ? V1::Firestore::Rest::Client : V1::Firestore::Client
+            client_class.new do |config|
               config.credentials = credentials if credentials
               config.timeout = timeout if timeout
               config.endpoint = host if host
               config.lib_name = "gccl"
               config.lib_version = Google::Cloud::Firestore::VERSION
-              config.metadata = { "google-cloud-resource-prefix": "projects/#{@project}/databases/(default)" }
+              config.metadata = { "google-cloud-resource-prefix": "projects/#{@project}/databases/#{@database}" }
             end
+          end
         end
 
-        def get_documents document_paths, mask: nil, transaction: nil
+        def get_documents document_paths, mask: nil, transaction: nil, read_time: nil
           batch_get_req = {
             database:  database_path,
             documents: document_paths,
@@ -63,7 +68,9 @@ module Google
           elsif transaction
             batch_get_req[:new_transaction] = transaction
           end
-
+          if read_time
+            batch_get_req[:read_time] = read_time_to_timestamp(read_time)
+          end
           firestore.batch_get_documents batch_get_req, call_options(parent: database_path)
         end
 
@@ -74,23 +81,25 @@ module Google
         # the showMissing flag to true to support full document traversal. If
         # there are too many documents, recommendation will be not to call this
         # method.
-        def list_documents parent, collection_id, token: nil, max: nil
+        def list_documents parent, collection_id, token: nil, max: nil, read_time: nil
           mask = { field_paths: [] }
-          paged_enum = firestore.list_documents parent:        parent,
+          paged_enum = firestore.list_documents parent: parent,
                                                 collection_id: collection_id,
-                                                page_size:     max,
-                                                page_token:    token,
-                                                mask:          mask,
-                                                show_missing:  true
+                                                page_size: max,
+                                                page_token: token,
+                                                mask: mask,
+                                                show_missing: true,
+                                                read_time: read_time_to_timestamp(read_time)
           paged_enum.response
         end
 
-        def list_collections parent, token: nil, max: nil
+        def list_collections parent, token: nil, max: nil, read_time: nil
           firestore.list_collection_ids(
             {
-              parent:     parent,
-              page_size:  max,
-              page_token: token
+              parent: parent,
+              page_size: max,
+              page_token: token,
+              read_time: read_time_to_timestamp(read_time)
             },
             call_options(parent: database_path)
           )
@@ -98,19 +107,20 @@ module Google
 
         ##
         # Returns Google::Cloud::Firestore::V1::PartitionQueryResponse
-        def partition_query parent, query_grpc, partition_count, token: nil, max: nil
+        def partition_query parent, query_grpc, partition_count, token: nil, max: nil, read_time: nil
           request = Google::Cloud::Firestore::V1::PartitionQueryRequest.new(
             parent: parent,
             structured_query: query_grpc,
             partition_count: partition_count,
             page_token: token,
-            page_size: max
+            page_size: max,
+            read_time: read_time_to_timestamp(read_time)
           )
           paged_enum = firestore.partition_query request
           paged_enum.response
         end
 
-        def run_query path, query_grpc, transaction: nil
+        def run_query path, query_grpc, transaction: nil, read_time: nil
           run_query_req = {
             parent:           path,
             structured_query: query_grpc
@@ -120,10 +130,28 @@ module Google
           elsif transaction
             run_query_req[:new_transaction] = transaction
           end
+          if read_time
+            run_query_req[:read_time] = read_time_to_timestamp(read_time)
+          end
 
           firestore.run_query run_query_req, call_options(parent: database_path)
         end
 
+        ##
+        # Returns Google::Cloud::Firestore::V1::RunAggregationQueryResponse
+        def run_aggregate_query parent, structured_aggregation_query, transaction: nil
+          request = Google::Cloud::Firestore::V1::RunAggregationQueryRequest.new(
+            parent: parent,
+            structured_aggregation_query: structured_aggregation_query
+          )
+          if transaction.is_a? String
+            request.transaction = transaction
+          elsif transaction
+            request.new_transaction = transaction
+          end
+          firestore.run_aggregation_query request
+        end
+
         def listen enum
           firestore.listen enum, call_options(parent: database_path)
         end
@@ -158,18 +186,41 @@ module Google
           )
         end
 
-        def database_path project_id: project, database_id: "(default)"
+        ##
+        # Makes the BatchWrite API call. Contains the list of write operations to be processed.
+        #
+        # @return [::Google::Cloud::Firestore::V1::BatchWriteResponse]
+        def batch_write writes
+          batch_write_req = {
+            database: database_path,
+            writes: writes
+          }
+          firestore.batch_write batch_write_req, call_options(parent: database_path)
+        end
+
+        def database_path project_id: project, database_id: database
           # Originally used V1::FirestoreClient.database_root_path until it was removed in #5405.
           "projects/#{project_id}/databases/#{database_id}"
         end
 
-        def documents_path project_id: project, database_id: "(default)"
+        def documents_path project_id: project, database_id: database
           # Originally used V1::FirestoreClient.document_root_path until it was removed in #5405.
           "projects/#{project_id}/databases/#{database_id}/documents"
         end
 
         def inspect
-          "#{self.class}(#{@project})"
+          "#{self.class}(#{@project})(#{@database})"
+        end
+
+        def read_time_to_timestamp read_time
+          return nil if read_time.nil?
+
+          raise TypeError, "read_time is expected to be a Time object" unless read_time.is_a? Time
+
+          Google::Protobuf::Timestamp.new(
+            seconds: read_time.to_i,
+            nanos:   read_time.usec * 1000
+          )
         end
 
         protected
@@ -183,7 +234,7 @@ module Google
           Gapic::CallOptions.new(**{
             metadata:   default_headers(parent),
             page_token: token
-          }.delete_if { |_, v| v.nil? })
+          }.compact)
         end
 
         def document_mask mask

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

@@ -269,6 +269,51 @@ module Google
         end
         alias run get
 
+        ##
+        # Retrieves aggregate query snapshots for the given value. Valid values can be
+        # a string representing either a document or a collection of documents,
+        # a document reference object, a collection reference object, or a query
+        # to be run.
+        #
+        # @param [AggregateQuery] aggregate_query
+        #   An AggregateQuery object
+        #
+        # @yield [documents] The block for accessing the aggregate query snapshot.
+        # @yieldparam [AggregateQuerySnapshot] aggregate_snapshot An aggregate query snapshot.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   query = firestore.col "cities"
+        #
+        #   # Create an aggregate query
+        #   aq = query.aggregate_query
+        #             .add_count
+        #
+        #   firestore.transaction do |tx|
+        #     tx.get_aggregate aq do |aggregate_snapshot|
+        #       puts aggregate_snapshot.get
+        #     end
+        #   end
+        #
+        def get_aggregate aggregate_query
+          ensure_not_closed!
+          ensure_service!
+
+          return enum_for :get_aggregate, aggregate_query unless block_given?
+
+          results = service.run_aggregate_query aggregate_query.parent_path,
+                                                aggregate_query.to_grpc,
+                                                transaction: transaction_or_create
+          results.each do |result|
+            extract_transaction_from_result! result
+            next if result.result.nil?
+            yield AggregateQuerySnapshot.from_run_aggregate_query_response result
+          end
+        end
+
         # @!endgroup
 
         # @!group Modifications
@@ -643,10 +688,12 @@ module Google
 
         ##
         # @private New Transaction reference object from a path.
-        def self.from_client client, previous_transaction: nil
+        def self.from_client client, previous_transaction: nil, read_time: nil, read_only: nil
           new.tap do |s|
             s.instance_variable_set :@client, client
             s.instance_variable_set :@previous_transaction, previous_transaction
+            s.instance_variable_set :@read_time, read_time
+            s.instance_variable_set :@read_only, read_only
           end
         end
 
@@ -699,6 +746,10 @@ module Google
         ##
         # @private
         def transaction_opt
+          read_only = \
+            Google::Cloud::Firestore::V1::TransactionOptions::ReadOnly.new \
+              read_time: service.read_time_to_timestamp(@read_time)
+
           read_write = \
             Google::Cloud::Firestore::V1::TransactionOptions::ReadWrite.new
 
@@ -707,9 +758,11 @@ module Google
             @previous_transaction = nil
           end
 
-          Google::Cloud::Firestore::V1::TransactionOptions.new(
-            read_write: read_write
-          )
+          if @read_only
+            Google::Cloud::Firestore::V1::TransactionOptions.new read_only: read_only
+          else
+            Google::Cloud::Firestore::V1::TransactionOptions.new read_write: read_write
+          end
         end
 
         ##

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

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