google-cloud-firestore 2.6.0 → 2.10.0

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

@@ -50,15 +50,18 @@ module Google
           end
 
           def fields_to_hash fields, client
-            Hash[fields.map do |key, value|
-              [key.to_sym, value_to_raw(value, client)]
-            end]
+            # Google::Protobuf::Map#to_h ignores the given block, unlike Hash#to_h
+            # rubocop:disable Style/MapToHash
+            fields
+              .map { |key, value| [key.to_sym, value_to_raw(value, client)] }
+              .to_h
+            # rubocop:enable Style/MapToHash
           end
 
           def hash_to_fields hash
-            Hash[hash.map do |key, value|
+            hash.to_h do |key, value|
               [String(key), raw_to_value(value)]
-            end]
+            end
           end
 
           def value_to_raw value, client
@@ -304,7 +307,7 @@ module Google
             field_paths = new_data_pairs.map(&:first)
 
             delete_paths.map!(&:first)
-            root_field_paths_and_values = Hash[root_field_paths_and_values]
+            root_field_paths_and_values = root_field_paths_and_values.to_h
 
             data, nested_deletes = remove_field_value_from data, :delete
             raise ArgumentError, "DELETE cannot be nested" if nested_deletes.any?
@@ -425,7 +428,7 @@ module Google
             end
 
             # return new data hash and field path/values hash
-            [Hash[new_pairs.compact], Hash[paths]]
+            [new_pairs.compact.to_h, paths.to_h]
           end
 
           def identify_leaf_nodes hash
@@ -495,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/field_path.rb

@@ -209,19 +209,15 @@ module Google
 
         protected
 
-        START_FIELD_PATH_CHARS = /\A[a-zA-Z_]/.freeze
         INVALID_FIELD_PATH_CHARS = %r{[~*/\[\]]}.freeze
+        SIMPLE_FIELD_PATH_CHARS = /\A[_a-zA-Z][_a-zA-Z0-9]*\Z/.freeze
 
         def escape_field_for_path field
           field = String field
 
-          if INVALID_FIELD_PATH_CHARS.match(field) ||
-             field["."] || field["`"] || field["\\"]
-            escaped_field = field.gsub(/[`\\]/, "`" => "\\\`", "\\" => "\\\\")
-            return "`#{escaped_field}`"
-          end
+          return field if SIMPLE_FIELD_PATH_CHARS.match field
 
-          return field if START_FIELD_PATH_CHARS.match field
+          field = field.gsub(/[`\\]/, "`" => "\\`", "\\" => "\\\\")
 
           "`#{field}`"
         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}" }
+              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
@@ -189,7 +225,7 @@ module Google
         def document_mask mask
           return nil if mask.nil?
 
-          mask = Array(mask).map(&:to_s).reject(&:nil?).reject(&:empty?)
+          mask = Array(mask).map(&:to_s).reject(&:empty?)
           return nil if mask.empty?
 
           Google::Cloud::Firestore::V1::DocumentMask.new field_paths: mask

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

@@ -269,6 +269,51 @@ module Google
         end
         alias run get
 
+        ##
+        # Retrieves aggregate query snapshots for the given value. Valid values can be
+        # a string representing either a document or a collection of documents,
+        # a document reference object, a collection reference object, or a query
+        # to be run.
+        #
+        # @param [AggregateQuery] aggregate_query
+        #   An AggregateQuery object
+        #
+        # @yield [documents] The block for accessing the aggregate query snapshot.
+        # @yieldparam [AggregateQuerySnapshot] aggregate_snapshot An aggregate query snapshot.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   query = firestore.col "cities"
+        #
+        #   # Create an aggregate query
+        #   aq = query.aggregate_query
+        #             .add_count
+        #
+        #   firestore.transaction do |tx|
+        #     tx.get_aggregate aq do |aggregate_snapshot|
+        #       puts aggregate_snapshot.get
+        #     end
+        #   end
+        #
+        def get_aggregate aggregate_query
+          ensure_not_closed!
+          ensure_service!
+
+          return enum_for :get_aggregate, aggregate_query unless block_given?
+
+          results = service.run_aggregate_query aggregate_query.parent_path,
+                                                aggregate_query.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.6.0".freeze
+      VERSION = "2.10.0".freeze
     end
   end
 end

data/lib/google/cloud/firestore/watch/inventory.rb

@@ -134,7 +134,7 @@ module Google
           end
 
           def order_for docs
-            Hash[docs.map { |doc| [doc.path, doc.updated_at] }]
+            docs.to_h { |doc| [doc.path, doc.updated_at] }
           end
 
           def current_order

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
 
@@ -122,6 +128,8 @@ module Google
       #   parameter `keyfile` is considered deprecated, but may also be used.)
       # * `scope` - (String, Array<String>) The OAuth 2.0 scopes controlling
       #   the set of resources and operations that the connection can access.
+      # * `quota_project` - (String) The project ID for a project that can be
+      #   used by client libraries for quota and billing purposes.
       # * `timeout` - (Integer) Default timeout to use in requests.
       # * `endpoint` - (String) Override of the endpoint host name, or `nil`
       #   to use the default endpoint.

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