google-cloud-firestore 2.8.0 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 389203f8e3c58b6e61e856d294ae723f1b9101119d36172a5a503408bab5e629
-  data.tar.gz: e1cfa1b4c701550f80da65ee573e83bea391cd1fd1cb7e605b215b91facbba05
+  metadata.gz: c5c050184924a624eb5f83c42f528334296cc01392d5a9b1d891d81c2b7f4e50
+  data.tar.gz: '085ffdcff90414ab769e585164e331a4d27b1edcfed7341d6c09998aca4a58c6'
 SHA512:
-  metadata.gz: adcda0a3707c9e0c1055fef937e46c6080db4960ac86a9572780d495722c9a0cdfb39ab07c0d6134c51584c18e43661e06d7c167b1bcf03c773adfdf52bda85a
-  data.tar.gz: 9649e1d619412c0e7786f2e78e47dcb0913c0bd989ca95bab358c9c0a8bd8bd7a1047abba62268a4114a6a2b935446f69987ba86bbf922a8b30193d7ea165d3a
+  metadata.gz: d5b99c1fa86740df4973731ecf715158cfbb8025fc46833f7b78cf9102d78245106133aed9e92311d5ae0879289054bbc7c832396792141e0df09abc7e6d7357
+  data.tar.gz: 9ccefface707ebaf31f3c8e7a998e7ae7f95713a9ec71df4e691d3be3997eadc528f95dfaf5de8bce00162a2c69856b704b198fd4ccea0376f4804451f1f4c77

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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

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/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

@@ -904,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.
         #
@@ -924,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

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,6 +125,9 @@ 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
@@ -187,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

@@ -682,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
 
@@ -738,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
 
@@ -746,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.8.0".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.8.0
+  version: 2.9.0
 platform: ruby
 authors:
 - Google Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-01-06 00:00:00.000000000 Z
+date: 2023-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -274,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