google-cloud-firestore 2.7.1 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f45d22f61cfd606f0a800da541058804c823a60d38896e77aac5ca72b01b34f4
-  data.tar.gz: 320a237aa81d52be3add1144de0d0bee460eb90786f4ab878e93ad79fd2c862f
+  metadata.gz: 389203f8e3c58b6e61e856d294ae723f1b9101119d36172a5a503408bab5e629
+  data.tar.gz: e1cfa1b4c701550f80da65ee573e83bea391cd1fd1cb7e605b215b91facbba05
 SHA512:
-  metadata.gz: d56c986ef8914c7b486d5c4877e4fdd681051b2203332f9a83278365826438353df177a3fb4a80bb9a11b8c33b6b190dd97e475c1de2273d11f759e01f2d7daa
-  data.tar.gz: b2916ce31ded50b667377bbc397356153cffeeff1a8c3f4ef71426211f5c1ed9ffe5ab53a319355d9ecbccf5079e1dd0617bc11e1c42f2009d1444d19ee840e1
+  metadata.gz: adcda0a3707c9e0c1055fef937e46c6080db4960ac86a9572780d495722c9a0cdfb39ab07c0d6134c51584c18e43661e06d7c167b1bcf03c773adfdf52bda85a
+  data.tar.gz: 9649e1d619412c0e7786f2e78e47dcb0913c0bd989ca95bab358c9c0a8bd8bd7a1047abba62268a4114a6a2b935446f69987ba86bbf922a8b30193d7ea165d3a

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Release History
 
+### 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
+
+* fix firestore emulator guide ([#19045](https://github.com/googleapis/google-cloud-ruby/issues/19045)) 
+
 ### 2.7.1 (2022-07-15)
 
 #### Bug Fixes

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/lib/google/cloud/firestore/aggregate_query.rb

@@ -0,0 +1,202 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "google/cloud/firestore/v1"
+require "google/cloud/firestore/aggregate_query_snapshot"
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # # AggregateQuery
+      #
+      # An aggregate query can be used to fetch aggregate values (ex: count) for a query
+      #
+      # Instances of this class are immutable. All methods that refine the aggregate query
+      # return new instances.
+      #
+      # @example
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   query = firestore.col "cities"
+      #
+      #   # Create an aggregate query
+      #   aggregate_query = query.aggregate_query
+      #                          .add_count
+      #
+      #   aggregate_query.get do |aggregate_snapshot|
+      #     puts aggregate_snapshot.get('count')
+      #   end
+      #
+      # @example Alias an aggregate query
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   # Create a query
+      #   query = firestore.col "cities"
+      #
+      #   # Create an aggregate query
+      #   aggregate_query = query.aggregate_query
+      #                          .add_count aggregate_alias: 'total_cities'
+      #
+      #   aggregate_query.get do |aggregate_snapshot|
+      #     puts aggregate_snapshot.get('total_cities')
+      #   end
+      #
+      class AggregateQuery
+        ##
+        # @private The firestore client object.
+        attr_accessor :client
+
+        ##
+        # @private The type for limit queries.
+        attr_reader :parent_path
+
+        ##
+        # @private The Google::Cloud::Firestore::V1::StructuredQuery object.
+        attr_reader :query
+
+        ##
+        # @private Array of Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation objects
+        attr_reader :aggregates
+
+        ##
+        # @private Creates a new AggregateQuery
+        def initialize query, parent_path, client, aggregates: []
+          @query = query
+          @parent_path = parent_path
+          @aggregates = aggregates
+          @client = client
+        end
+
+        ##
+        # Adds a count aggregate.
+        #
+        # @param [aggregate_alias] Alias to refer to the aggregate. Optional
+        #
+        # @return [AggregateQuery] A new aggregate query with the added count aggregate.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   query = firestore.col "cities"
+        #
+        #   # Create an aggregate query
+        #   aggregate_query = query.aggregate_query
+        #                          .add_count
+        #
+        #   aggregate_query.get do |aggregate_snapshot|
+        #     puts aggregate_snapshot.get('count')
+        #   end
+        #
+        def add_count aggregate_alias: nil
+          aggregate_alias ||= ALIASES[:count]
+          new_aggregates = @aggregates.dup
+          new_aggregates << StructuredAggregationQuery::Aggregation.new(
+            count: StructuredAggregationQuery::Aggregation::Count.new,
+            alias: aggregate_alias
+          )
+          AggregateQuery.start query, new_aggregates, parent_path, client
+        end
+
+        ##
+        # Retrieves aggregate snapshot for the query.
+        #
+        # @yield [snapshot] The block for accessing the aggregate query snapshots.
+        # @yieldparam [AggregateQuerySnapshot] An aggregate query snapshot.
+        #
+        # @return [Enumerator<AggregateQuerySnapshot>] A list of aggregate query snapshots.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   query = firestore.col "cities"
+        #
+        #   # Create an aggregate query
+        #   aggregate_query = query.aggregate_query
+        #                          .add_count
+        #
+        #   aggregate_query.get do |aggregate_snapshot|
+        #     puts aggregate_snapshot.get('count')
+        #   end
+        #
+        def get
+          ensure_service!
+
+          return enum_for :get unless block_given?
+
+          responses = service.run_aggregate_query @parent_path, structured_aggregation_query
+          responses.each do |response|
+            next if response.result.nil?
+            yield AggregateQuerySnapshot.from_run_aggregate_query_response response
+          end
+        end
+
+        ##
+        # @private Creates a Google::Cloud::Firestore::V1::StructuredAggregationQuery object
+        def structured_aggregation_query
+          StructuredAggregationQuery.new(
+            structured_query: @query,
+            aggregations: @aggregates
+          )
+        end
+
+        ##
+        # @private Start a new AggregateQuery.
+        def self.start query, aggregates, parent_path, client
+          new query, parent_path, client, aggregates: aggregates
+        end
+
+        protected
+
+        ##
+        # @private
+        StructuredAggregationQuery = Google::Cloud::Firestore::V1::StructuredAggregationQuery
+
+        ##
+        # @private
+        ALIASES = {
+          count: "count"
+        }.freeze
+
+        ##
+        # @private Raise an error unless a database is available.
+        def ensure_client!
+          raise "Must have active connection to service" unless client
+        end
+
+        ##
+        # @private Raise an error unless an active connection to the service
+        # is available.
+        def ensure_service!
+          raise "Must have active connection to service" unless service
+        end
+
+        ##
+        # @private The Service object.
+        def service
+          ensure_client!
+          client.service
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # # AggregateQuerySnapshot
+      #
+      # An aggregate query snapshot object is an immutable representation for
+      # an aggregate query result.
+      #
+      # @example
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   query = firestore.col "cities"
+      #
+      #   # Create an aggregate query
+      #   aggregate_query = query.aggregate_query
+      #                          .add_count
+      #
+      #   aggregate_query.get do |aggregate_snapshot|
+      #     puts aggregate_snapshot.get('count')
+      #   end
+      #
+      class AggregateQuerySnapshot
+        ##
+        # Retrieves the aggregate data.
+        #
+        # @param [String] aggregate_alias The alias used
+        #   to access the aggregate value. For count, the
+        #   default value is "count".
+        #
+        # @return [Integer] The aggregate value.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   query = firestore.col "cities"
+        #
+        #   # Create an aggregate query
+        #   aggregate_query = query.aggregate_query
+        #                          .add_count
+        #
+        #   aggregate_query.get do |aggregate_snapshot|
+        #     puts aggregate_snapshot.get('count')
+        #   end
+        def get aggregate_alias
+          @aggregate_fields[aggregate_alias]
+        end
+
+        ##
+        # @private New AggregateQuerySnapshot from a
+        # Google::Cloud::Firestore::V1::RunAggregationQueryResponse object.
+        def self.from_run_aggregate_query_response response
+          aggregate_fields = response
+                             .result
+                             .aggregate_fields
+                             .to_h # convert from protobuf to ruby map
+                             .transform_values { |v| v[:integer_value] }
+
+          new.tap do |s|
+            s.instance_variable_set :@aggregate_fields, aggregate_fields
+          end
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/firestore/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/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
@@ -940,6 +941,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

@@ -124,6 +124,21 @@ module Google
           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

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

@@ -269,6 +269,45 @@ module Google
         end
         alias run get
 
+        ##
+        # Retrieves aggregate query snapshots for the given value. Valid values can be
+        # a string representing either a document or a collection of documents,
+        # a document reference object, a collection reference object, or a query
+        # to be run.
+        #
+        # @param [AggregateQuery] aggregate_query
+        #   An AggregateQuery object
+        #
+        # @yield [documents] The block for accessing the aggregate query snapshot.
+        # @yieldparam [AggregateQuerySnapshot] aggregate_snapshot An aggregate query snapshot.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   firestore.transaction do |tx|
+        #     tx.get_aggregate aq do |aggregate_snapshot|
+        #       puts aggregate_snapshot.get('count')
+        #     end
+        #   end
+        #
+        def get_aggregate aggregate_query
+          ensure_not_closed!
+          ensure_service!
+
+          return enum_for :get_aggregate, aggregate_query unless block_given?
+
+          results = service.run_aggregate_query aggregate_query.parent_path,
+                                                aggregate_query.structured_aggregation_query,
+                                                transaction: transaction_or_create
+          results.each do |result|
+            extract_transaction_from_result! result
+            next if result.result.nil?
+            yield AggregateQuerySnapshot.from_run_aggregate_query_response result
+          end
+        end
+
         # @!endgroup
 
         # @!group Modifications

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Firestore
-      VERSION = "2.7.1".freeze
+      VERSION = "2.8.0".freeze
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-firestore
 version: !ruby/object:Gem::Version
-  version: 2.7.1
+  version: 2.8.0
 platform: ruby
 authors:
 - Google Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-07-15 00:00:00.000000000 Z
+date: 2023-01-06 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