google-cloud-firestore 2.6.0 → 2.10.0

data/EMULATOR.md

@@ -2,19 +2,21 @@
 
 To develop and test your application locally, you can use the [Google Cloud
 Firestore
-Emulator](https://cloud.google.com/firestore/docs/security/test-rules-emulator#install_the_emulator),
-which provides local emulation of the production Google Cloud Firestore
-environment. You can start the Google Cloud Firestore emulator using the
-[`firebase` command-line tool](https://firebase.google.com/docs/cli/).
+Emulator](https://cloud.google.com/sdk/gcloud/reference/beta/emulators/firestore/),
+which provides local emulation of the production Google Cloud Firestore 
+environment. You can start the Google Cloud Firestore emulator using 
+the `gcloud` command-line tool.
+
+`gcloud beta emulators firestore start --host-port=0.0.0.0:8080`
 
 When you run the Cloud Firestore emulator you will see a message similar to the
 following printed:
 
 ```
-$ firebase serve --only firestore
-API endpoint: http://[::1]:8080
-API endpoint: http://127.0.0.1:8080
-Dev App Server is now running.
+If you are using a library that supports the FIRESTORE_EMULATOR_HOST
+environment variable, run:
+
+  export FIRESTORE_EMULATOR_HOST=localhost:8080
 ```
 
 Now you can connect to the emulator using the `FIRESTORE_EMULATOR_HOST`

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/OVERVIEW.md

@@ -108,7 +108,7 @@ and it can't contain other collections. You do not need to "create" or "delete"
 collections. After you create the first document in a collection, the collection
 exists. If you delete all of the documents in a collection, it no longer exists.
 (For more information, see [Cloud Firestore Data
-Model](https://cloud.google.com/firestore/docs/data-model).
+Model](https://cloud.google.com/firestore/docs/data-model).)
 
 Use {Google::Cloud::Firestore::Client#cols Client#cols} to list the root-level
 collections:

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
@@ -164,8 +178,7 @@ module Google
         #
         def col_group collection_id
           if collection_id.include? "/"
-            raise ArgumentError, "Invalid collection_id: '#{collection_id}', " \
-              "must not contain '/'."
+            raise ArgumentError, "Invalid collection_id: '#{collection_id}', must not contain '/'."
           end
 
           CollectionGroup.from_collection_id service.documents_path, collection_id, self
@@ -218,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.
@@ -246,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|
@@ -265,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
@@ -628,7 +656,24 @@ module Google
             commit_return = transaction.commit
             # Conditional return value, depending on truthy commit_response
             commit_response ? commit_return : transaction_return
-          rescue Google::Cloud::UnavailableError => e
+          rescue Google::Cloud::AbortedError,
+                 Google::Cloud::CanceledError,
+                 Google::Cloud::UnknownError,
+                 Google::Cloud::DeadlineExceededError,
+                 Google::Cloud::InternalError,
+                 Google::Cloud::UnauthenticatedError,
+                 Google::Cloud::ResourceExhaustedError,
+                 Google::Cloud::UnavailableError,
+                 Google::Cloud::InvalidArgumentError => e
+
+            if e.instance_of? Google::Cloud::InvalidArgumentError
+              # Return if a previous call was retried but ultimately succeeded
+              return nil if backoff[:current].positive?
+              # The Firestore backend uses "INVALID_ARGUMENT" for transaction IDs that have expired.
+              # While INVALID_ARGUMENT is generally not retryable, we retry this specific case.
+              raise e unless e.message =~ /transaction has expired/
+            end
+
             # Re-raise if retried more than the max
             raise e if backoff[:current] > backoff[:max]
 
@@ -643,12 +688,6 @@ module Google
             transaction = Transaction.from_client \
               self, previous_transaction: transaction.transaction_id
             retry
-          rescue Google::Cloud::InvalidArgumentError => e
-            # Return if a previous call was retried but ultimately succeeded
-            return nil if backoff[:current].positive?
-
-            # Re-raise error.
-            raise e
           rescue StandardError => e
             # Rollback transaction when handling unexpected error
             transaction.rollback rescue nil
@@ -658,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