google-cloud-firestore 2.7.2 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cb9b1838e2d0de1dd7a122b6395a7506e1c9ffdc237edc88ece03b38902694d
-  data.tar.gz: 92cd04357a9295dec00b34c748cf0e1a9b7f44165915d41e8dac3b5eff40ef84
+  metadata.gz: c5c050184924a624eb5f83c42f528334296cc01392d5a9b1d891d81c2b7f4e50
+  data.tar.gz: '085ffdcff90414ab769e585164e331a4d27b1edcfed7341d6c09998aca4a58c6'
 SHA512:
-  metadata.gz: 3fc0b6e13ba161fc579a969fdf3848621d8aaf45bdd6e64fa5ad2dc2a4d4efd4a934034724f03f7bdc7b2fb50a4976ea3c3fb6dbc99576ef274bbf435e1d0e02
-  data.tar.gz: 465c31a8a2a581f90107b305d0d465e4e8c4da368c5b00651075b45031708a38e47e3e7a2deae8bacae32b8f8779ca164b68a5a99dfec1f6d0832d1f70d67089
+  metadata.gz: d5b99c1fa86740df4973731ecf715158cfbb8025fc46833f7b78cf9102d78245106133aed9e92311d5ae0879289054bbc7c832396792141e0df09abc7e6d7357
+  data.tar.gz: 9ccefface707ebaf31f3c8e7a998e7ae7f95713a9ec71df4e691d3be3997eadc528f95dfaf5de8bce00162a2c69856b704b198fd4ccea0376f4804451f1f4c77

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Release History
 
+### 2.9.0 (2023-01-26)
+
+#### Features
+
+* Added support for read time ([#19851](https://github.com/googleapis/google-cloud-ruby/issues/19851)) 
+
+### 2.8.0 (2023-01-05)
+
+#### Features
+
+* Support query count for Firestore ([#19457](https://github.com/googleapis/google-cloud-ruby/issues/19457)) 
+#### Bug Fixes
+
+* Add support for merging null field in a document ([#19918](https://github.com/googleapis/google-cloud-ruby/issues/19918)) 
+
 ### 2.7.2 (2022-08-24)
 
 #### Documentation

data/LOGGING.md

@@ -3,7 +3,7 @@
 To enable logging for this library, set the logger for the underlying
 [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The logger
 that you set may be a Ruby stdlib
-[`Logger`](https://ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger.html) as
+[`Logger`](https://ruby-doc.org/current/stdlibs/logger/Logger.html) as
 shown below, or a
 [`Google::Cloud::Logging::Logger`](https://googleapis.dev/ruby/google-cloud-logging/latest)
 that will write logs to [Stackdriver

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

@@ -0,0 +1,202 @@
+# Copyright 2022 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"
+require "google/cloud/firestore/aggregate_query_snapshot"
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # # AggregateQuery
+      #
+      # An aggregate query can be used to fetch aggregate values (ex: count) for a query
+      #
+      # Instances of this class are immutable. All methods that refine the aggregate query
+      # return new instances.
+      #
+      # @example
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   query = firestore.col "cities"
+      #
+      #   # Create an aggregate query
+      #   aggregate_query = query.aggregate_query
+      #                          .add_count
+      #
+      #   aggregate_query.get do |aggregate_snapshot|
+      #     puts aggregate_snapshot.get('count')
+      #   end
+      #
+      # @example Alias an aggregate query
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   # Create a query
+      #   query = firestore.col "cities"
+      #
+      #   # Create an aggregate query
+      #   aggregate_query = query.aggregate_query
+      #                          .add_count aggregate_alias: 'total_cities'
+      #
+      #   aggregate_query.get do |aggregate_snapshot|
+      #     puts aggregate_snapshot.get('total_cities')
+      #   end
+      #
+      class AggregateQuery
+        ##
+        # @private The firestore client object.
+        attr_accessor :client
+
+        ##
+        # @private The type for limit queries.
+        attr_reader :parent_path
+
+        ##
+        # @private The Google::Cloud::Firestore::V1::StructuredQuery object.
+        attr_reader :query
+
+        ##
+        # @private Array of Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation objects
+        attr_reader :aggregates
+
+        ##
+        # @private Creates a new AggregateQuery
+        def initialize query, parent_path, client, aggregates: []
+          @query = query
+          @parent_path = parent_path
+          @aggregates = aggregates
+          @client = client
+        end
+
+        ##
+        # Adds a count aggregate.
+        #
+        # @param [aggregate_alias] Alias to refer to the aggregate. Optional
+        #
+        # @return [AggregateQuery] A new aggregate query with the added count aggregate.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   query = firestore.col "cities"
+        #
+        #   # Create an aggregate query
+        #   aggregate_query = query.aggregate_query
+        #                          .add_count
+        #
+        #   aggregate_query.get do |aggregate_snapshot|
+        #     puts aggregate_snapshot.get('count')
+        #   end
+        #
+        def add_count aggregate_alias: nil
+          aggregate_alias ||= ALIASES[:count]
+          new_aggregates = @aggregates.dup
+          new_aggregates << StructuredAggregationQuery::Aggregation.new(
+            count: StructuredAggregationQuery::Aggregation::Count.new,
+            alias: aggregate_alias
+          )
+          AggregateQuery.start query, new_aggregates, parent_path, client
+        end
+
+        ##
+        # Retrieves aggregate snapshot for the query.
+        #
+        # @yield [snapshot] The block for accessing the aggregate query snapshots.
+        # @yieldparam [AggregateQuerySnapshot] An aggregate query snapshot.
+        #
+        # @return [Enumerator<AggregateQuerySnapshot>] A list of aggregate query snapshots.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   query = firestore.col "cities"
+        #
+        #   # Create an aggregate query
+        #   aggregate_query = query.aggregate_query
+        #                          .add_count
+        #
+        #   aggregate_query.get do |aggregate_snapshot|
+        #     puts aggregate_snapshot.get('count')
+        #   end
+        #
+        def get
+          ensure_service!
+
+          return enum_for :get unless block_given?
+
+          responses = service.run_aggregate_query @parent_path, structured_aggregation_query
+          responses.each do |response|
+            next if response.result.nil?
+            yield AggregateQuerySnapshot.from_run_aggregate_query_response response
+          end
+        end
+
+        ##
+        # @private Creates a Google::Cloud::Firestore::V1::StructuredAggregationQuery object
+        def structured_aggregation_query
+          StructuredAggregationQuery.new(
+            structured_query: @query,
+            aggregations: @aggregates
+          )
+        end
+
+        ##
+        # @private Start a new AggregateQuery.
+        def self.start query, aggregates, parent_path, client
+          new query, parent_path, client, aggregates: aggregates
+        end
+
+        protected
+
+        ##
+        # @private
+        StructuredAggregationQuery = Google::Cloud::Firestore::V1::StructuredAggregationQuery
+
+        ##
+        # @private
+        ALIASES = {
+          count: "count"
+        }.freeze
+
+        ##
+        # @private Raise an error unless a database is available.
+        def ensure_client!
+          raise "Must have active connection to service" unless client
+        end
+
+        ##
+        # @private Raise an error unless an active connection to the service
+        # is available.
+        def ensure_service!
+          raise "Must have active connection to service" unless service
+        end
+
+        ##
+        # @private The Service object.
+        def service
+          ensure_client!
+          client.service
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# Copyright 2022 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
+      ##
+      # # AggregateQuerySnapshot
+      #
+      # An aggregate query snapshot object is an immutable representation for
+      # an aggregate query result.
+      #
+      # @example
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   query = firestore.col "cities"
+      #
+      #   # Create an aggregate query
+      #   aggregate_query = query.aggregate_query
+      #                          .add_count
+      #
+      #   aggregate_query.get do |aggregate_snapshot|
+      #     puts aggregate_snapshot.get('count')
+      #   end
+      #
+      class AggregateQuerySnapshot
+        ##
+        # Retrieves the aggregate data.
+        #
+        # @param [String] aggregate_alias The alias used
+        #   to access the aggregate value. For count, the
+        #   default value is "count".
+        #
+        # @return [Integer] The aggregate value.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   query = firestore.col "cities"
+        #
+        #   # Create an aggregate query
+        #   aggregate_query = query.aggregate_query
+        #                          .add_count
+        #
+        #   aggregate_query.get do |aggregate_snapshot|
+        #     puts aggregate_snapshot.get('count')
+        #   end
+        def get aggregate_alias
+          @aggregate_fields[aggregate_alias]
+        end
+
+        ##
+        # @private New AggregateQuerySnapshot from a
+        # Google::Cloud::Firestore::V1::RunAggregationQueryResponse object.
+        def self.from_run_aggregate_query_response response
+          aggregate_fields = response
+                             .result
+                             .aggregate_fields
+                             .to_h # convert from protobuf to ruby map
+                             .transform_values { |v| v[:integer_value] }
+
+          new.tap do |s|
+            s.instance_variable_set :@aggregate_fields, aggregate_fields
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -85,6 +85,9 @@ module Google
         ##
         # Retrieves an enumerator for the root collections.
         #
+        # @param [Time] read_time Reads documents as they were at the given time.
+        #   This may not be older than 270 seconds. Optional
+        #
         # @yield [collections] The block for accessing the collections.
         # @yieldparam [CollectionReference] collection A collection reference object.
         #
@@ -101,10 +104,21 @@ module Google
         #     puts col.collection_id
         #   end
         #
-        def cols &block
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #   read_time = Time.now
+        #
+        #   # Get the root collections
+        #   firestore.cols(read_time: read_time).each do |col|
+        #     puts col.collection_id
+        #   end
+        #
+        def cols read_time: nil, &block
           ensure_service!
-          grpc = service.list_collections "#{path}/documents"
-          cols_enum = CollectionReferenceList.from_grpc(grpc, self, "#{path}/documents").all
+          grpc = service.list_collections "#{path}/documents", read_time: read_time
+          cols_enum = CollectionReferenceList.from_grpc(grpc, self, "#{path}/documents", read_time: read_time).all
           cols_enum.each(&block) if block_given?
           cols_enum
         end
@@ -217,6 +231,8 @@ module Google
         #   individual fields joined by ".". Fields containing `~`, `*`, `/`,
         #   `[`, `]`, and `.` cannot be in a dotted string, and should provided
         #   using a {FieldPath} object instead. (See {#field_path}.)
+        # @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.
@@ -245,11 +261,24 @@ module Google
         #     puts "#{city.document_id} has #{city[:population]} residents."
         #   end
         #
-        def get_all *docs, field_mask: nil
+        # @example Get docs using a read_time:
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   read_time = Time.now
+        #
+        #   # Get and print city documents
+        #   cities = ["cities/NYC", "cities/SF", "cities/LA"]
+        #   firestore.get_all(cities, read_time: read_time).each do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        def get_all *docs, field_mask: nil, read_time: nil
           ensure_service!
 
           unless block_given?
-            return enum_for :get_all, *docs, field_mask: field_mask
+            return enum_for :get_all, *docs, field_mask: field_mask, read_time: read_time
           end
 
           doc_paths = Array(docs).flatten.map do |doc_path|
@@ -264,7 +293,7 @@ module Google
           end
           mask = nil if mask.empty?
 
-          results = service.get_documents doc_paths, mask: mask
+          results = service.get_documents doc_paths, mask: mask, read_time: read_time
           results.each do |result|
             next if result.result.nil?
             yield DocumentSnapshot.from_batch_result result, self
@@ -668,13 +697,54 @@ module Google
           end
         end
 
+        ##
+        # Create a transaction to perform multiple reads that are
+        # executed atomically at a single logical point in time in a database.
+        #
+        # All changes are accumulated in memory until the block completes.
+        # Transactions will be automatically retried when documents change
+        # before the transaction is committed. See {Transaction}.
+        #
+        # @see https://firebase.google.com/docs/firestore/manage-data/transactions
+        #   Transactions and Batched Writes
+        #
+        # @param [Time] read_time The maximum number of retries for
+        #   transactions failed due to errors. Default is 5. Optional.
+        #
+        # @yield [transaction] The block for reading data.
+        # @yieldparam [Transaction] transaction The transaction object for
+        #   making changes.
+        #
+        # @return [Object] The return value of the provided
+        #   yield block
+        #
+        # @example Read only transaction with read time
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a document reference
+        #   nyc_ref = firestore.doc "cities/NYC"
+        #
+        #   read_time = Time.now
+        #
+        #   firestore.read_only_transaction(read_time: read_time) do |tx|
+        #     # Get a document snapshot
+        #     nyc_snap = tx.get nyc_ref
+        #   end
+        #
+        def read_only_transaction read_time: nil
+          transaction = Transaction.from_client self, read_time: read_time, read_only: true
+          yield transaction
+        end
+
         # @!endgroup
 
         # @private
-        def list_documents parent, collection_id, token: nil, max: nil
+        def list_documents parent, collection_id, token: nil, max: nil, read_time: nil
           ensure_service!
-          grpc = service.list_documents parent, collection_id, token: token, max: max
-          DocumentReference::List.from_grpc grpc, self, parent, collection_id
+          grpc = service.list_documents parent, collection_id, token: token, max: max, read_time: read_time
+          DocumentReference::List.from_grpc grpc, self, parent, collection_id, read_time: read_time
         end
 
         protected

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

@@ -48,6 +48,8 @@ module Google
         #
         # @param [Integer] partition_count The desired maximum number of partition points. The number must be strictly
         #   positive. The actual number of partitions returned may be fewer.
+        # @param [Time] read_time Reads documents as they were at the given time.
+        #   This may not be older than 270 seconds. Optional
         #
         # @return [Array<QueryPartition>] An ordered array of query partitions.
         #
@@ -62,7 +64,20 @@ module Google
         #
         #   queries = partitions.map(&:to_query)
         #
-        def partitions partition_count
+        # @example partition with read time
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   col_group = firestore.col_group "cities"
+        #
+        #   read_time = Time.now
+        #
+        #   partitions = col_group.partitions 3, read_time: read_time
+        #
+        #   queries = partitions.map(&:to_query)
+        #
+        def partitions partition_count, read_time: nil
           ensure_service!
 
           raise ArgumentError, "partition_count must be > 0" unless partition_count.positive?
@@ -75,7 +90,7 @@ module Google
 
           grpc_partitions = if partition_count.positive?
                               # Retrieve all pages, since cursor order is not guaranteed and they must be sorted.
-                              list_all partition_count, query_with_default_order
+                              list_all partition_count, query_with_default_order, read_time
                             else
                               [] # Ensure that a single, empty QueryPartition is returned.
                             end
@@ -118,11 +133,12 @@ module Google
 
         protected
 
-        def list_all partition_count, query_with_default_order
+        def list_all partition_count, query_with_default_order, read_time
           grpc_partitions = []
           token = nil
           loop do
-            grpc = service.partition_query parent_path, query_with_default_order.query, partition_count, token: token
+            grpc = service.partition_query parent_path, query_with_default_order.query, partition_count,
+                                           token: token, read_time: read_time
             grpc_partitions += Array(grpc.partitions)
             token = grpc.next_page_token
             token = nil if token == ""

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

@@ -147,6 +147,8 @@ module Google
         # @param [String] token A previously-returned page token representing
         #   part of the larger set of results to view.
         # @param [Integer] max Maximum number of results to return.
+        # @param [Time] read_time Reads documents as they were at the given time.
+        #   This may not be older than 270 seconds. Optional
         #
         # @return [Array<DocumentReference>] An array of document references.
         #
@@ -161,10 +163,23 @@ module Google
         #     puts doc_ref.document_id
         #   end
         #
-        def list_documents token: nil, max: nil
+        # @example List documents with read time
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   read_time = Time.now
+        #
+        #   col = firestore.col "cities"
+        #
+        #   col.list_documents(read_time: read_time).each do |doc_ref|
+        #     puts doc_ref.document_id
+        #   end
+        #
+        def list_documents token: nil, max: nil, read_time: nil
           ensure_client!
           client.list_documents \
-            parent_path, collection_id, token: token, max: max
+            parent_path, collection_id, token: token, max: max, read_time: read_time
         end
 
         ##

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

@@ -52,8 +52,8 @@ module Google
         def next
           return nil unless next?
           ensure_service!
-          grpc = @client.service.list_collections @parent, token: token, max: @max
-          self.class.from_grpc grpc, @client, @parent, max: @max
+          grpc = @client.service.list_collections @parent, token: token, max: @max, read_time: @read_time
+          self.class.from_grpc grpc, @client, @parent, max: @max, read_time: @read_time
         end
 
         ##
@@ -110,7 +110,7 @@ module Google
         ##
         # @private New CollectionReference::List from a `Google::Cloud::Firestore::V1::ListCollectionIdsResponse`
         # object.
-        def self.from_grpc grpc, client, parent, max: nil
+        def self.from_grpc grpc, client, parent, max: nil, read_time: nil
           raise ArgumentError, "parent is required" unless parent
           cols = CollectionReferenceList.new(Array(grpc.collection_ids).map do |collection_id|
             CollectionReference.from_path "#{parent}/#{collection_id}", client
@@ -121,6 +121,7 @@ module Google
           cols.instance_variable_set :@client, client
           cols.instance_variable_set :@parent, parent
           cols.instance_variable_set :@max, max
+          cols.instance_variable_set :@read_time, read_time
           cols
         end
 

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

@@ -498,7 +498,6 @@ module Google
               dup_hash = dup_hash[field]
             end
             prev_hash[last_field] = dup_hash
-            prev_hash.delete_if { |_k, v| v.nil? }
             ret_hash
           end
 

data/lib/google/cloud/firestore/document_reference/list.rb

@@ -86,8 +86,9 @@ module Google
           def next
             return nil unless next?
             ensure_client!
-            grpc = @client.service.list_documents @parent, @collection_id, token: token, max: @max
-            self.class.from_grpc grpc, @client, @parent, @collection_id, @max
+            grpc = @client.service.list_documents @parent, @collection_id, token: token, max: @max, \
+              read_time: @read_time
+            self.class.from_grpc grpc, @client, @parent, @collection_id, @max, read_time: @read_time
           end
 
           ##
@@ -162,7 +163,7 @@ module Google
           ##
           # @private New DocumentReference::List from a
           # Google::Cloud::Firestore::V1::ListDocumentsResponse object.
-          def self.from_grpc grpc, client, parent, collection_id, max = nil
+          def self.from_grpc grpc, client, parent, collection_id, max = nil, read_time: nil
             documents = List.new(Array(grpc.documents).map do |document|
               DocumentReference.from_path document.name, client
             end)
@@ -173,6 +174,7 @@ module Google
             documents.instance_variable_set :@token, token
             documents.instance_variable_set :@client, client
             documents.instance_variable_set :@max, max
+            documents.instance_variable_set :@read_time, read_time
             documents
           end
 

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

@@ -73,6 +73,9 @@ module Google
         ##
         # Retrieves an enumerator for the collections nested under the document snapshot.
         #
+        # @param [Time] read_time Reads documents as they were at the given time.
+        #   This may not be older than 270 seconds. Optional
+        #
         # @yield [collections] The block for accessing the collections.
         # @yieldparam [CollectionReference] collection A collection reference object.
         #
@@ -91,10 +94,24 @@ module Google
         #     puts col.collection_id
         #   end
         #
-        def cols &block
+        # @example Get collection with read time
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   read_time = Time.now
+        #
+        #   # Get a document reference
+        #   nyc_ref = firestore.doc "cities/NYC"
+        #
+        #   nyc_ref.cols(read_time: read_time).each do |col|
+        #     puts col.collection_id
+        #   end
+        #
+        def cols read_time: nil, &block
           ensure_service!
-          grpc = service.list_collections path
-          cols_enum = CollectionReferenceList.from_grpc(grpc, client, path).all
+          grpc = service.list_collections path, read_time: read_time
+          cols_enum = CollectionReferenceList.from_grpc(grpc, client, path, read_time: read_time).all
           cols_enum.each(&block) if block_given?
           cols_enum
         end

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

@@ -17,6 +17,7 @@ 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 "json"
 
 module Google
@@ -903,6 +904,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 +927,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 +961,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 query, parent_path, client
+        end
+
         ##
         # Listen to this query for changes.
         #

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

@@ -52,7 +52,7 @@ module Google
             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 +63,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 +76,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 +102,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 +125,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
@@ -172,6 +195,17 @@ module Google
           "#{self.class}(#{@project})"
         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
 
         def default_headers parent = nil

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

@@ -269,6 +269,45 @@ 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
+        #
+        #   firestore.transaction do |tx|
+        #     tx.get_aggregate aq do |aggregate_snapshot|
+        #       puts aggregate_snapshot.get('count')
+        #     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.structured_aggregation_query,
+                                                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 +682,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 +740,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 +752,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.9.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.7.2
+  version: 2.9.0
 platform: ruby
 authors:
 - Google Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-08-24 00:00:00.000000000 Z
+date: 2023-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -225,6 +225,8 @@ files:
 - TROUBLESHOOTING.md
 - lib/google-cloud-firestore.rb
 - lib/google/cloud/firestore.rb
+- lib/google/cloud/firestore/aggregate_query.rb
+- lib/google/cloud/firestore/aggregate_query_snapshot.rb
 - lib/google/cloud/firestore/batch.rb
 - lib/google/cloud/firestore/client.rb
 - lib/google/cloud/firestore/collection_group.rb
@@ -272,7 +274,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.14
+rubygems_version: 3.4.2
 signing_key: 
 specification_version: 4
 summary: API Client library for Google Cloud Firestore API