google-cloud-firestore 2.7.2 → 2.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cb9b1838e2d0de1dd7a122b6395a7506e1c9ffdc237edc88ece03b38902694d
-  data.tar.gz: 92cd04357a9295dec00b34c748cf0e1a9b7f44165915d41e8dac3b5eff40ef84
+  metadata.gz: 11756f53d816d451097f95dfbddda050a3cbdcaf5b732f227e7c2eed5770300b
+  data.tar.gz: 4b140ef2eefbc2c4f990b27b340fd39f30eb395e25173093b1d041754c2ac969
 SHA512:
-  metadata.gz: 3fc0b6e13ba161fc579a969fdf3848621d8aaf45bdd6e64fa5ad2dc2a4d4efd4a934034724f03f7bdc7b2fb50a4976ea3c3fb6dbc99576ef274bbf435e1d0e02
-  data.tar.gz: 465c31a8a2a581f90107b305d0d465e4e8c4da368c5b00651075b45031708a38e47e3e7a2deae8bacae32b8f8779ca164b68a5a99dfec1f6d0832d1f70d67089
+  metadata.gz: 2961e4c3898492087255b15223c22136a30fa08984106c48e66fc8afc2ab6410df31d83ea4d96c03f484c0d1c6a093d8d976b192b03554c158a8880714b9d8e8
+  data.tar.gz: d9bc499cac0f2fa388ed139a50ddc1bc6ef380991a57a5cd8b38973b677b1f609d9d2c862472427870112690a28cf63a802a1be9cd2508a34ccf9da9734029d7

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Release History
 
+### 2.10.0 (2023-02-09)
+
+#### Features
+
+* Added support for multiple databases ([#20029](https://github.com/googleapis/google-cloud-ruby/issues/20029)) 
+
+### 2.9.1 (2023-02-03)
+
+#### Bug Fixes
+
+* Change "aggregate_alias" to optional param ([#20082](https://github.com/googleapis/google-cloud-ruby/issues/20082)) 
+
+### 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
+      #   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
+        #   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
+        #   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,120 @@
+# 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
+      #   end
+      # @return [Integer] The aggregate value.
+      #
+      # @example Alias an aggregate query
+      #   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_alias: 'total'
+      #
+      #   aggregate_query.get do |aggregate_snapshot|
+      #     puts aggregate_snapshot.get('total')
+      #   end
+      class AggregateQuerySnapshot
+        ##
+        # Retrieves the aggregate data.
+        #
+        # @param aggregate_alias [String] The alias used to access
+        #   the aggregate value. For an AggregateQuery with a
+        #   single aggregate field, this parameter can be omitted.
+        #
+        # @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
+        #   end
+        # @return [Integer] The aggregate value.
+        #
+        # @example Alias an aggregate query
+        #   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_alias: 'total'
+        #
+        #   aggregate_query.get do |aggregate_snapshot|
+        #     puts aggregate_snapshot.get('total')
+        #   end
+        def get aggregate_alias = nil
+          if @aggregate_fields.count > 1 && aggregate_alias.nil?
+            raise ArgumentError, "Required param aggregate_alias for AggregateQuery with multiple aggregate fields"
+          end
+          aggregate_alias ||= @aggregate_fields.keys.first
+          @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

@@ -69,7 +69,7 @@ module Google
         #
         # @return [String] database identifier.
         def database_id
-          "(default)"
+          service.database
         end
 
         ##
@@ -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

@@ -30,14 +30,16 @@ 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
           @project = project
           @credentials = credentials
           @host = host
           @timeout = timeout
+          @database = database
         end
 
         def firestore
@@ -48,11 +50,11 @@ module Google
               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
 
-        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 +65,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 +78,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 +104,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 +127,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 +183,29 @@ module Google
           )
         end
 
-        def database_path project_id: project, database_id: "(default)"
+        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

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.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 +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.10.0".freeze
     end
   end
 end

data/lib/google/cloud/firestore.rb

@@ -59,6 +59,8 @@ module Google
       #   If the param is nil, uses the default endpoint.
       # @param [String] emulator_host Firestore emulator host. Optional.
       #   If the param is nil, uses the value of the `emulator_host` config.
+      # @param [String] database_id Identifier for a Firestore database. If not
+      #   present, the default database of the project is used.
       # @param [String] project Alias for the `project_id` argument. Deprecated.
       # @param [String] keyfile Alias for the `credentials` argument.
       #   Deprecated.
@@ -76,19 +78,22 @@ module Google
                    timeout: nil,
                    endpoint: nil,
                    emulator_host: nil,
+                   database_id: nil,
                    project: nil,
                    keyfile: nil
-        project_id    ||= (project || default_project_id)
-        scope         ||= configure.scope
-        timeout       ||= configure.timeout
-        endpoint      ||= configure.endpoint
+        project_id ||= (project || default_project_id)
+        scope ||= configure.scope
+        timeout ||= configure.timeout
+        endpoint ||= configure.endpoint
         emulator_host ||= configure.emulator_host
+        database_id ||= configure.database_id
 
         if emulator_host
           project_id = project_id.to_s
           raise ArgumentError, "project_id is missing" if project_id.empty?
 
-          service = Firestore::Service.new project_id, :this_channel_is_insecure, host: emulator_host, timeout: timeout
+          service = Firestore::Service.new project_id, :this_channel_is_insecure, host: emulator_host,
+                                           timeout: timeout, database: database_id
           return Firestore::Client.new service
         end
 
@@ -103,7 +108,8 @@ module Google
         project_id = project_id.to_s
         raise ArgumentError, "project_id is missing" if project_id.empty?
 
-        service = Firestore::Service.new project_id, credentials, host: endpoint, timeout: timeout
+        service = Firestore::Service.new project_id, credentials, host: endpoint,
+                                         timeout: timeout, database: database_id
         Firestore::Client.new service
       end
 

data/lib/google-cloud-firestore.rb

@@ -42,6 +42,8 @@ module Google
     #
     #   * `https://www.googleapis.com/auth/datastore`
     # @param [Integer] timeout Default timeout to use in requests. Optional.
+    # @param [String] database_id Identifier for a Firestore database. If not
+    #   present, the default database of the project is used.
     #
     # @return [Google::Cloud::Firestore::Client]
     #
@@ -58,8 +60,15 @@ module Google
     #   platform_scope = "https://www.googleapis.com/auth/cloud-platform"
     #   firestore = gcloud.firestore scope: platform_scope
     #
-    def firestore scope: nil, timeout: nil
-      Google::Cloud.firestore @project, @keyfile, scope: scope, timeout: (timeout || @timeout)
+    # @example The default database can be overridden with the `database_id` option:
+    #   require "google/cloud"
+    #
+    #   gcloud  = Google::Cloud.new
+    #   database_id = "my-todo-database"
+    #   firestore = gcloud.firestore database_id: database_id
+    #
+    def firestore scope: nil, timeout: nil, database_id: nil
+      Google::Cloud.firestore @project, @keyfile, scope: scope, timeout: (timeout || @timeout), database_id: database_id
     end
 
     ##
@@ -83,6 +92,8 @@ module Google
     #
     #   * `https://www.googleapis.com/auth/datastore`
     # @param [Integer] timeout Default timeout to use in requests. Optional.
+    # @param [String] database_id Identifier for a Firestore database. If not
+    #   present, the default database of the project is used.
     #
     # @return [Google::Cloud::Firestore::Client]
     #
@@ -91,12 +102,13 @@ module Google
     #
     #   firestore = Google::Cloud.firestore
     #
-    def self.firestore project_id = nil, credentials = nil, scope: nil, timeout: nil
+    def self.firestore project_id = nil, credentials = nil, scope: nil, timeout: nil, database_id: nil
       require "google/cloud/firestore"
-      Google::Cloud::Firestore.new project_id:  project_id,
+      Google::Cloud::Firestore.new project_id: project_id,
                                    credentials: credentials,
-                                   scope:       scope,
-                                   timeout:     timeout
+                                   scope: scope,
+                                   timeout: timeout,
+                                   database_id: database_id
     end
   end
 end
@@ -116,8 +128,7 @@ Google::Cloud.configure.add_config! :firestore do |config|
     ENV["FIRESTORE_EMULATOR_HOST"]
   end
   default_scopes = [
-    "https://www.googleapis.com/auth/cloud-platform",
-    "https://www.googleapis.com/auth/datastore"
+    "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/datastore"
   ]
 
   config.add_field! :project_id, default_project, match: String, allow_nil: true
@@ -129,4 +140,5 @@ Google::Cloud.configure.add_config! :firestore do |config|
   config.add_field! :timeout, nil, match: Integer
   config.add_field! :emulator_host, default_emulator, match: String, allow_nil: true
   config.add_field! :endpoint, "firestore.googleapis.com", match: String
+  config.add_field! :database_id, "(default)", match: String
 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.10.0
 platform: ruby
 authors:
 - Google Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-08-24 00:00:00.000000000 Z
+date: 2023-02-09 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