google-cloud-firestore 2.7.2 → 2.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cb9b1838e2d0de1dd7a122b6395a7506e1c9ffdc237edc88ece03b38902694d
-  data.tar.gz: 92cd04357a9295dec00b34c748cf0e1a9b7f44165915d41e8dac3b5eff40ef84
+  metadata.gz: 16163a09797c60820b760bb85283dc3ab8532aacc329dbdf0e8672ab7b8e4066
+  data.tar.gz: a502101923eaeffb2b8ca9112134ffc14e8971970509cb9f34e5263c5889a791
 SHA512:
-  metadata.gz: 3fc0b6e13ba161fc579a969fdf3848621d8aaf45bdd6e64fa5ad2dc2a4d4efd4a934034724f03f7bdc7b2fb50a4976ea3c3fb6dbc99576ef274bbf435e1d0e02
-  data.tar.gz: 465c31a8a2a581f90107b305d0d465e4e8c4da368c5b00651075b45031708a38e47e3e7a2deae8bacae32b8f8779ca164b68a5a99dfec1f6d0832d1f70d67089
+  metadata.gz: 06e1cb717e9ccdb4560f66d38af4845610aaed131557956d5dea7c86a97169c7f7af979e956ef53a7ac3ce36f19ade87c3a00a7f568bcdc2ea82aaf77dfafb77
+  data.tar.gz: 388eb390a647550643bdce6c1a0b57bcb98fa9ad63fdb24808971dafeac3342ac6a0943bc86103d892b9a4e572746ec01ddf167f9629ff29df768bedcc606c59

data/AUTHENTICATION.md

@@ -124,15 +124,6 @@ To configure your system for this, simply:
 **NOTE:** This is _not_ recommended for running in production. The Cloud SDK
 *should* only be used during development.
 
-[gce-how-to]: https://cloud.google.com/compute/docs/authentication#using
-[dev-console]: https://console.cloud.google.com/project
-
-[enable-apis]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/enable-apis.png
-
-[create-new-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account.png
-[create-new-service-account-existing-keys]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account-existing-keys.png
-[reuse-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/reuse-service-account.png
-
 ## Creating a Service Account
 
 Google Cloud requires a **Project ID** and **Service Account Credentials** to
@@ -143,31 +134,22 @@ If you are not running this client within [Google Cloud Platform
 environments](#google-cloud-platform-environments), you need a Google
 Developers service account.
 
-1. Visit the [Google Developers Console][dev-console].
+1. Visit the [Google Cloud Console](https://console.cloud.google.com/project).
 1. Create a new project or click on an existing project.
-1. Activate the slide-out navigation tray and select **API Manager**. From
+1. Activate the menu in the upper left and select **APIs & Services**. From
    here, you will enable the APIs that your application requires.
 
-   ![Enable the APIs that your application requires][enable-apis]
-
    *Note: You may need to enable billing in order to use these services.*
 
 1. Select **Credentials** from the side navigation.
 
-   You should see a screen like one of the following.
-
-   ![Create a new service account][create-new-service-account]
-
-   ![Create a new service account With Existing Keys][create-new-service-account-existing-keys]
-
-   Find the "Add credentials" drop down and select "Service account" to be
-   guided through downloading a new JSON key file.
-
-   If you want to re-use an existing service account, you can easily generate a
-   new key file. Just select the account you wish to re-use, and click "Generate
-   new JSON key":
+   Find the "Create credentials" drop down near the top of the page, and select
+   "Service account" to be guided through downloading a new JSON key file.
 
-   ![Re-use an existing service account][reuse-service-account]
+   If you want to re-use an existing service account, you can easily generate 
+   a new key file. Just select the account you wish to re-use click the pencil
+   tool on the right side to edit the service account, select the **Keys** tab,
+   and then select **Add Key**.
 
    The key file you download will be used by this library to authenticate API
    requests and should be stored in a secure location.

data/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Release History
 
+### 2.15.0 (2024-03-07)
+
+#### Features
+
+* Update minimum supported Ruby version to 2.7 ([#25298](https://github.com/googleapis/google-cloud-ruby/issues/25298)) 
+
+### 2.14.0 (2024-01-31)
+
+#### Features
+
+* Support sum & avg aggregate functions ([#23446](https://github.com/googleapis/google-cloud-ruby/issues/23446)) 
+
+### 2.13.1 (2023-06-16)
+
+#### Documentation
+
+* Fixed broken links in authentication documentation ([#21619](https://github.com/googleapis/google-cloud-ruby/issues/21619)) 
+
+### 2.13.0 (2023-05-10)
+
+#### Features
+
+* Added support for bulk writer ([#21426](https://github.com/googleapis/google-cloud-ruby/issues/21426)) 
+
+### 2.12.0 (2023-04-20)
+
+#### Features
+
+* Add support for OR query ([#20920](https://github.com/googleapis/google-cloud-ruby/issues/20920)) 
+
+### 2.11.0 (2023-02-23)
+
+#### Features
+
+* Support REST transport ([#20446](https://github.com/googleapis/google-cloud-ruby/issues/20446)) 
+
+### 2.10.1 (2023-02-16)
+
+#### Bug Fixes
+
+* update version of firestore-v1 in gemspec ([#20433](https://github.com/googleapis/google-cloud-ruby/issues/20433)) 
+
+### 2.10.0 (2023-02-09)
+
+#### Features
+
+* Added support for multiple databases ([#20029](https://github.com/googleapis/google-cloud-ruby/issues/20029)) 
+
+### 2.9.1 (2023-02-03)
+
+#### Bug Fixes
+
+* Change "aggregate_alias" to optional param ([#20082](https://github.com/googleapis/google-cloud-ruby/issues/20082)) 
+
+### 2.9.0 (2023-01-26)
+
+#### Features
+
+* Added support for read time ([#19851](https://github.com/googleapis/google-cloud-ruby/issues/19851)) 
+
+### 2.8.0 (2023-01-05)
+
+#### Features
+
+* Support query count for Firestore ([#19457](https://github.com/googleapis/google-cloud-ruby/issues/19457)) 
+#### Bug Fixes
+
+* Add support for merging null field in a document ([#19918](https://github.com/googleapis/google-cloud-ruby/issues/19918)) 
+
 ### 2.7.2 (2022-08-24)
 
 #### Documentation

data/LOGGING.md

@@ -3,7 +3,7 @@
 To enable logging for this library, set the logger for the underlying
 [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The logger
 that you set may be a Ruby stdlib
-[`Logger`](https://ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger.html) as
+[`Logger`](https://ruby-doc.org/current/stdlibs/logger/Logger.html) as
 shown below, or a
 [`Google::Cloud::Logging::Logger`](https://googleapis.dev/ruby/google-cloud-logging/latest)
 that will write logs to [Stackdriver

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

@@ -0,0 +1,285 @@
+# 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::Query object.
+        attr_reader :query
+
+        ##
+        # @private Object of type
+        # Google::Cloud::Firestore::V1::StructuredAggregationQuery
+        attr_reader :grpc
+
+        # @private
+        DEFAULT_COUNT_ALIAS = "count".freeze
+
+        # @private
+        DEFAULT_SUM_ALIAS = "sum".freeze
+
+        # @private
+        DEFAULT_AVG_ALIAS = "avg".freeze
+
+        ##
+        # @private Creates a new AggregateQuery
+        def initialize query, parent_path, client
+          @query = query
+          @parent_path = parent_path
+          @client = client
+          @grpc = Google::Cloud::Firestore::V1::StructuredAggregationQuery.new(
+            structured_query: @query.query,
+            aggregations: []
+          )
+        end
+
+        ##
+        # Adds a count aggregate.
+        #
+        # @param aggregate_alias [String] 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 ||= DEFAULT_COUNT_ALIAS
+          new_aggregate = Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation.new(
+            count: Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation::Count.new,
+            alias: aggregate_alias
+          )
+
+          start new_aggregate
+        end
+
+        ##
+        # Adds a sum aggregate.
+        #
+        # @param field [String] The field to sum by
+        # @param aggregate_alias [String] Alias to refer to the aggregate
+        #
+        # @return [AggregateQuery] A new aggregate query with the added sum 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_sum("population")
+        #
+        #   aggregate_query.get do |aggregate_snapshot|
+        #     puts aggregate_snapshot.get
+        #   end
+        #
+        def add_sum field, aggregate_alias: nil
+          aggregate_alias ||= DEFAULT_SUM_ALIAS
+          field = FieldPath.parse field unless field.is_a? FieldPath
+          new_aggregate = Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation.new(
+            sum: Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation::Sum.new(
+              field: Google::Cloud::Firestore::V1::StructuredQuery::FieldReference.new(
+                field_path: field.formatted_string
+              )
+            ),
+            alias: aggregate_alias
+          )
+
+          start new_aggregate
+        end
+
+        ##
+        # Adds an average aggregate.
+        #
+        # @param field [String] The field to apply average on
+        # @param aggregate_alias [String] Alias to refer to the aggregate
+        #
+        # @return [AggregateQuery] A new aggregate query with the added average 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_avg("population")
+        #
+        #   aggregate_query.get do |aggregate_snapshot|
+        #     puts aggregate_snapshot.get
+        #   end
+        #
+        def add_avg field, aggregate_alias: nil
+          aggregate_alias ||= DEFAULT_AVG_ALIAS
+          field = FieldPath.parse field unless field.is_a? FieldPath
+          new_aggregate = Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation.new(
+            avg: Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation::Avg.new(
+              field: Google::Cloud::Firestore::V1::StructuredQuery::FieldReference.new(
+                field_path: field.formatted_string
+              )
+            ),
+            alias: aggregate_alias
+          )
+
+          start new_aggregate
+        end
+
+        ##
+        # @private
+        def start new_aggregate
+          combined_aggregates = [].concat(grpc.aggregations).push(new_aggregate)
+          new_grpc = Google::Cloud::Firestore::V1::StructuredAggregationQuery.new(
+            structured_query: @query.query,
+            aggregations: combined_aggregates
+          )
+          self.class.new(@query, @parent_path, @client).tap do |aq|
+            aq.instance_variable_set :@grpc, new_grpc
+          end
+        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, @grpc
+          responses.each do |response|
+            next if response.result.nil?
+            yield AggregateQuerySnapshot.from_run_aggregate_query_response response
+          end
+        end
+
+        ##
+        # @private
+        def to_grpc
+          @grpc
+        end
+
+        protected
+
+        ##
+        # @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,145 @@
+# 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
+        ##
+        # @private Object of type [Hash{String => Object}]
+        #
+        # String can have the following values:
+        #   - an aggregate literal "sum", "avg", or "count"
+        #   - a custom aggregate alias
+        # Object can have the following types:
+        #   - Integer
+        #   - Float
+        #   - nil
+        #   - NaN
+        attr_reader :aggregate_fields
+
+        ##
+        # 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, Float, nil, NaN] The aggregate value.
+        #   Returns `nil` if the aggregate_alias does not exist.
+        #   Returns `NaN` if the aggregate field contains one or more NaN values.
+        #
+        # @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
+          # rubocop:disable Style/MapToHash
+          aggregate_fields = response
+                             .result
+                             .aggregate_fields
+                             .map do |aggregate_alias, value| # convert from protobuf to ruby map
+                               if value.has_integer_value?
+                                 [aggregate_alias, value.integer_value]
+                               elsif value.has_double_value?
+                                 [aggregate_alias, value.double_value]
+                               elsif value.has_null_value?
+                                 [aggregate_alias, nil]
+                               end
+                             end
+                             .to_h
+          # rubocop:enable Style/MapToHash
+
+          new.tap do |s|
+            s.instance_variable_set :@aggregate_fields, aggregate_fields
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# Copyright 2023 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
+      ##
+      #
+      # @private Accumulate write operations to be sent in a batch. Use this for higher
+      # volumes (e.g., via `BulkWriter`) and when the order of operations
+      # within a given batch is unimportant.
+      #
+      # Because the order in which individual write operations are applied to the database
+      # is not guaranteed, `batch_write` RPCs can never contain multiple operations
+      # to the same document. In practice, the BulkWriter class handle this case.
+      #
+      class BulkCommitBatch
+        attr_reader :operations
+
+        ##
+        # Initialize the object
+        def initialize service, operations
+          @service = service
+          @operations = operations
+        end
+
+        ##
+        # Updates the operation based on the result received from the API request.
+        #
+        # @param [Google::Cloud::Firestore::V1::BatchWriteResponse] responses
+        #
+        # @return [nil]
+        #
+        def parse_results responses
+          @operations.zip responses.write_results, responses.status do |operation, write_result, status|
+            begin
+              status&.code&.zero? ? operation.on_success(write_result) : operation.on_failure(status)
+            rescue StandardError
+              # TODO: Log the error while parsing response
+            end
+          end
+        end
+
+        ##
+        # Makes the BatchWrite API request with all the operations in the batch and
+        # parses the results for each operation.
+        #
+        # @return [nil]
+        #
+        def commit
+          begin
+            responses = @service.batch_write @operations.map(&:write)
+            parse_results responses
+          rescue StandardError => e
+            raise BulkCommitBatchError, e
+          end
+        end
+      end
+    end
+  end
+end