google-cloud-firestore-v1 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa7a3a05d20f035e538491503f205b0a3f615dba137d0deec1154581d7c27a8b
-  data.tar.gz: 13549cd8a54e0c0c9981b63e5acf2d8058b42c543cd551d705c4af1ffe53a069
+  metadata.gz: dcc0798a8aa1b6a70669958d01f1353dff7e9d002ded6fc42a27ec538d92e597
+  data.tar.gz: 5e35f28c24d813ad220148bfe15ba385359440563dedb5b2342a2d262add911c
 SHA512:
-  metadata.gz: f345b6be6955df190af0e0e272917495d95d9deed05c0363c88a3a5cc6211b91474456755225c3143b78cc59f1dabd288e5ade2e3ef41097fa68d85f9b585257
-  data.tar.gz: 1742819230867bea83eb93de132c7035100c1957e3dea8f25a82d94459a835e975ebe519d953c70b8c6e8ea0658d381ac0b48c2445b711762b57912ba5008eca
+  metadata.gz: 237cc0f52525a3c60eb4e0783d27c461cc2b21d02359d6e19eccdec1ce70d0dd4aa940fdcc1ae26f71191171c8e7b6a75761bf5402f44bf0aafc6f06df18965b
+  data.tar.gz: 6d75b35dc3929b94ea27cbb684f630c7b7b6ff9a569a349688bf25505f4a9d8e54a1ff8836a25d62bb25f3b10c376cd0aede9bb657a854942c9155b0061a59d0

data/AUTHENTICATION.md

@@ -114,7 +114,7 @@ credentials are discovered.
 To configure your system for this, simply:
 
 1. [Download and install the Cloud SDK](https://cloud.google.com/sdk)
-2. Authenticate using OAuth 2.0 `$ gcloud auth login`
+2. Authenticate using OAuth 2.0 `$ gcloud auth application-default login`
 3. Write code as if already authenticated.
 
 **NOTE:** This is _not_ recommended for running in production. The Cloud SDK

data/lib/google/cloud/firestore/v1/firestore/client.rb

@@ -18,6 +18,7 @@
 
 require "google/cloud/errors"
 require "google/firestore/v1/firestore_pb"
+require "google/cloud/location"
 
 module Google
   module Cloud
@@ -114,6 +115,11 @@ module Google
                   initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14, 13, 4]
                 }
 
+                default_config.rpcs.run_aggregation_query.timeout = 300.0
+                default_config.rpcs.run_aggregation_query.retry_policy = {
+                  initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14, 13, 4]
+                }
+
                 default_config.rpcs.partition_query.timeout = 300.0
                 default_config.rpcs.partition_query.retry_policy = {
                   initial_delay: 0.1, max_delay: 60.0, multiplier: 1.3, retry_codes: [8, 14, 13, 4]
@@ -210,6 +216,12 @@ module Google
               @quota_project_id = @config.quota_project
               @quota_project_id ||= credentials.quota_project_id if credentials.respond_to? :quota_project_id
 
+              @location_client = Google::Cloud::Location::Locations::Client.new do |config|
+                config.credentials = credentials
+                config.quota_project = @quota_project_id
+                config.endpoint = @config.endpoint
+              end
+
               @firestore_stub = ::Gapic::ServiceStub.new(
                 ::Google::Cloud::Firestore::V1::Firestore::Stub,
                 credentials:  credentials,
@@ -219,6 +231,13 @@ module Google
               )
             end
 
+            ##
+            # Get the associated client for mix-in of the Locations.
+            #
+            # @return [Google::Cloud::Location::Locations::Client]
+            #
+            attr_reader :location_client
+
             # Service calls
 
             ##
@@ -1123,6 +1142,127 @@ module Google
               raise ::Google::Cloud::Error.from_error(e)
             end
 
+            ##
+            # Runs an aggregation query.
+            #
+            # Rather than producing {::Google::Cloud::Firestore::V1::Document Document} results like {::Google::Cloud::Firestore::V1::Firestore::Client#run_query Firestore.RunQuery},
+            # this API allows running an aggregation to produce a series of
+            # {::Google::Cloud::Firestore::V1::AggregationResult AggregationResult} server-side.
+            #
+            # High-Level Example:
+            #
+            # ```
+            # -- Return the number of documents in table given a filter.
+            # SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );
+            # ```
+            #
+            # @overload run_aggregation_query(request, options = nil)
+            #   Pass arguments to `run_aggregation_query` via a request object, either of type
+            #   {::Google::Cloud::Firestore::V1::RunAggregationQueryRequest} or an equivalent Hash.
+            #
+            #   @param request [::Google::Cloud::Firestore::V1::RunAggregationQueryRequest, ::Hash]
+            #     A request object representing the call parameters. Required. To specify no
+            #     parameters, or to keep all the default parameter values, pass an empty Hash.
+            #   @param options [::Gapic::CallOptions, ::Hash]
+            #     Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
+            #
+            # @overload run_aggregation_query(parent: nil, structured_aggregation_query: nil, transaction: nil, new_transaction: nil, read_time: nil)
+            #   Pass arguments to `run_aggregation_query` via keyword arguments. Note that at
+            #   least one keyword argument is required. To specify no parameters, or to keep all
+            #   the default parameter values, pass an empty Hash as a request object (see above).
+            #
+            #   @param parent [::String]
+            #     Required. The parent resource name. In the format:
+            #     `projects/{project_id}/databases/{database_id}/documents` or
+            #     `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
+            #     For example:
+            #     `projects/my-project/databases/my-database/documents` or
+            #     `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
+            #   @param structured_aggregation_query [::Google::Cloud::Firestore::V1::StructuredAggregationQuery, ::Hash]
+            #     An aggregation query.
+            #   @param transaction [::String]
+            #     Run the aggregation within an already active transaction.
+            #
+            #     The value here is the opaque transaction ID to execute the query in.
+            #   @param new_transaction [::Google::Cloud::Firestore::V1::TransactionOptions, ::Hash]
+            #     Starts a new transaction as part of the query, defaulting to read-only.
+            #
+            #     The new transaction ID will be returned as the first response in the
+            #     stream.
+            #   @param read_time [::Google::Protobuf::Timestamp, ::Hash]
+            #     Executes the query at the given timestamp.
+            #
+            #     Requires:
+            #
+            #     * Cannot be more than 270 seconds in the past.
+            #
+            # @yield [response, operation] Access the result along with the RPC operation
+            # @yieldparam response [::Enumerable<::Google::Cloud::Firestore::V1::RunAggregationQueryResponse>]
+            # @yieldparam operation [::GRPC::ActiveCall::Operation]
+            #
+            # @return [::Enumerable<::Google::Cloud::Firestore::V1::RunAggregationQueryResponse>]
+            #
+            # @raise [::Google::Cloud::Error] if the RPC is aborted.
+            #
+            # @example Basic example
+            #   require "google/cloud/firestore/v1"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::Firestore::V1::Firestore::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Cloud::Firestore::V1::RunAggregationQueryRequest.new
+            #
+            #   # Call the run_aggregation_query method.
+            #   result = client.run_aggregation_query request
+            #
+            #   # The returned object is a streamed enumerable yielding elements of
+            #   # type ::Google::Cloud::Firestore::V1::RunAggregationQueryResponse.
+            #   result.each do |response|
+            #     p response
+            #   end
+            #
+            def run_aggregation_query request, options = nil
+              raise ::ArgumentError, "request must be provided" if request.nil?
+
+              request = ::Gapic::Protobuf.coerce request, to: ::Google::Cloud::Firestore::V1::RunAggregationQueryRequest
+
+              # Converts hash and nil to an options object
+              options = ::Gapic::CallOptions.new(**options.to_h) if options.respond_to? :to_h
+
+              # Customize the options with defaults
+              metadata = @config.rpcs.run_aggregation_query.metadata.to_h
+
+              # Set x-goog-api-client and x-goog-user-project headers
+              metadata[:"x-goog-api-client"] ||= ::Gapic::Headers.x_goog_api_client \
+                lib_name: @config.lib_name, lib_version: @config.lib_version,
+                gapic_version: ::Google::Cloud::Firestore::V1::VERSION
+              metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
+
+              header_params = {}
+              if request.parent
+                header_params["parent"] = request.parent
+              end
+
+              request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
+              metadata[:"x-goog-request-params"] ||= request_params_header
+
+              options.apply_defaults timeout:      @config.rpcs.run_aggregation_query.timeout,
+                                     metadata:     metadata,
+                                     retry_policy: @config.rpcs.run_aggregation_query.retry_policy
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
+                                     retry_policy: @config.retry_policy
+
+              @firestore_stub.call_rpc :run_aggregation_query, request, options: options do |response, operation|
+                yield response, operation if block_given?
+                return response
+              end
+            rescue ::GRPC::BadStatus => e
+              raise ::Google::Cloud::Error.from_error(e)
+            end
+
             ##
             # Partitions a query by returning partition cursors that can be used to run
             # the query in parallel. The returned partition cursors are split points that
@@ -1897,6 +2037,11 @@ module Google
                 #
                 attr_reader :run_query
                 ##
+                # RPC-specific configuration for `run_aggregation_query`
+                # @return [::Gapic::Config::Method]
+                #
+                attr_reader :run_aggregation_query
+                ##
                 # RPC-specific configuration for `partition_query`
                 # @return [::Gapic::Config::Method]
                 #
@@ -1947,6 +2092,8 @@ module Google
                   @rollback = ::Gapic::Config::Method.new rollback_config
                   run_query_config = parent_rpcs.run_query if parent_rpcs.respond_to? :run_query
                   @run_query = ::Gapic::Config::Method.new run_query_config
+                  run_aggregation_query_config = parent_rpcs.run_aggregation_query if parent_rpcs.respond_to? :run_aggregation_query
+                  @run_aggregation_query = ::Gapic::Config::Method.new run_aggregation_query_config
                   partition_query_config = parent_rpcs.partition_query if parent_rpcs.respond_to? :partition_query
                   @partition_query = ::Gapic::Config::Method.new partition_query_config
                   write_config = parent_rpcs.write if parent_rpcs.respond_to? :write

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

@@ -21,7 +21,7 @@ module Google
   module Cloud
     module Firestore
       module V1
-        VERSION = "0.7.0"
+        VERSION = "0.8.0"
       end
     end
   end

data/lib/google/firestore/v1/aggregation_result_pb.rb

@@ -0,0 +1,24 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: google/firestore/v1/aggregation_result.proto
+
+require 'google/protobuf'
+
+require 'google/firestore/v1/document_pb'
+
+Google::Protobuf::DescriptorPool.generated_pool.build do
+  add_file("google/firestore/v1/aggregation_result.proto", :syntax => :proto3) do
+    add_message "google.firestore.v1.AggregationResult" do
+      map :aggregate_fields, :string, :message, 2, "google.firestore.v1.Value"
+    end
+  end
+end
+
+module Google
+  module Cloud
+    module Firestore
+      module V1
+        AggregationResult = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.firestore.v1.AggregationResult").msgclass
+      end
+    end
+  end
+end

data/lib/google/firestore/v1/firestore_pb.rb

@@ -6,6 +6,7 @@ require 'google/protobuf'
 require 'google/api/annotations_pb'
 require 'google/api/client_pb'
 require 'google/api/field_behavior_pb'
+require 'google/firestore/v1/aggregation_result_pb'
 require 'google/firestore/v1/common_pb'
 require 'google/firestore/v1/document_pb'
 require 'google/firestore/v1/query_pb'
@@ -116,6 +117,22 @@ Google::Protobuf::DescriptorPool.generated_pool.build do
         optional :done, :bool, 6
       end
     end
+    add_message "google.firestore.v1.RunAggregationQueryRequest" do
+      optional :parent, :string, 1
+      oneof :query_type do
+        optional :structured_aggregation_query, :message, 2, "google.firestore.v1.StructuredAggregationQuery"
+      end
+      oneof :consistency_selector do
+        optional :transaction, :bytes, 4
+        optional :new_transaction, :message, 5, "google.firestore.v1.TransactionOptions"
+        optional :read_time, :message, 6, "google.protobuf.Timestamp"
+      end
+    end
+    add_message "google.firestore.v1.RunAggregationQueryResponse" do
+      optional :result, :message, 1, "google.firestore.v1.AggregationResult"
+      optional :transaction, :bytes, 2
+      optional :read_time, :message, 3, "google.protobuf.Timestamp"
+    end
     add_message "google.firestore.v1.PartitionQueryRequest" do
       optional :parent, :string, 1
       optional :partition_count, :int64, 3
@@ -240,6 +257,8 @@ module Google
         RollbackRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.firestore.v1.RollbackRequest").msgclass
         RunQueryRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.firestore.v1.RunQueryRequest").msgclass
         RunQueryResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.firestore.v1.RunQueryResponse").msgclass
+        RunAggregationQueryRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.firestore.v1.RunAggregationQueryRequest").msgclass
+        RunAggregationQueryResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.firestore.v1.RunAggregationQueryResponse").msgclass
         PartitionQueryRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.firestore.v1.PartitionQueryRequest").msgclass
         PartitionQueryResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.firestore.v1.PartitionQueryResponse").msgclass
         WriteRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.firestore.v1.WriteRequest").msgclass

data/lib/google/firestore/v1/firestore_services_pb.rb

@@ -63,6 +63,19 @@ module Google
             rpc :Rollback, ::Google::Cloud::Firestore::V1::RollbackRequest, ::Google::Protobuf::Empty
             # Runs a query.
             rpc :RunQuery, ::Google::Cloud::Firestore::V1::RunQueryRequest, stream(::Google::Cloud::Firestore::V1::RunQueryResponse)
+            # Runs an aggregation query.
+            #
+            # Rather than producing [Document][google.firestore.v1.Document] results like [Firestore.RunQuery][google.firestore.v1.Firestore.RunQuery],
+            # this API allows running an aggregation to produce a series of
+            # [AggregationResult][google.firestore.v1.AggregationResult] server-side.
+            #
+            # High-Level Example:
+            #
+            # ```
+            # -- Return the number of documents in table given a filter.
+            # SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );
+            # ```
+            rpc :RunAggregationQuery, ::Google::Cloud::Firestore::V1::RunAggregationQueryRequest, stream(::Google::Cloud::Firestore::V1::RunAggregationQueryResponse)
             # Partitions a query by returning partition cursors that can be used to run
             # the query in parallel. The returned partition cursors are split points that
             # can be used by RunQuery as starting/end points for the query results.

data/lib/google/firestore/v1/query_pb.rb

@@ -84,6 +84,21 @@ Google::Protobuf::DescriptorPool.generated_pool.build do
       value :ASCENDING, 1
       value :DESCENDING, 2
     end
+    add_message "google.firestore.v1.StructuredAggregationQuery" do
+      repeated :aggregations, :message, 3, "google.firestore.v1.StructuredAggregationQuery.Aggregation"
+      oneof :query_type do
+        optional :structured_query, :message, 1, "google.firestore.v1.StructuredQuery"
+      end
+    end
+    add_message "google.firestore.v1.StructuredAggregationQuery.Aggregation" do
+      optional :alias, :string, 7
+      oneof :operator do
+        optional :count, :message, 1, "google.firestore.v1.StructuredAggregationQuery.Aggregation.Count"
+      end
+    end
+    add_message "google.firestore.v1.StructuredAggregationQuery.Aggregation.Count" do
+      optional :up_to, :message, 1, "google.protobuf.Int64Value"
+    end
     add_message "google.firestore.v1.Cursor" do
       repeated :values, :message, 1, "google.firestore.v1.Value"
       optional :before, :bool, 2
@@ -108,6 +123,9 @@ module Google
         StructuredQuery::FieldReference = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.firestore.v1.StructuredQuery.FieldReference").msgclass
         StructuredQuery::Projection = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.firestore.v1.StructuredQuery.Projection").msgclass
         StructuredQuery::Direction = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.firestore.v1.StructuredQuery.Direction").enummodule
+        StructuredAggregationQuery = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.firestore.v1.StructuredAggregationQuery").msgclass
+        StructuredAggregationQuery::Aggregation = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.firestore.v1.StructuredAggregationQuery.Aggregation").msgclass
+        StructuredAggregationQuery::Aggregation::Count = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.firestore.v1.StructuredAggregationQuery.Aggregation.Count").msgclass
         Cursor = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.firestore.v1.Cursor").msgclass
       end
     end

data/proto_docs/google/firestore/v1/aggregation_result.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# 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.
+
+# Auto-generated by gapic-generator-ruby. DO NOT EDIT!
+
+
+module Google
+  module Cloud
+    module Firestore
+      module V1
+        # The result of a single bucket from a Firestore aggregation query.
+        #
+        # The keys of `aggregate_fields` are the same for all results in an aggregation
+        # query, unlike document queries which can have different fields present for
+        # each result.
+        # @!attribute [rw] aggregate_fields
+        #   @return [::Google::Protobuf::Map{::String => ::Google::Cloud::Firestore::V1::Value}]
+        #     The result of the aggregation functions, ex: `COUNT(*) AS total_docs`.
+        #
+        #     The key is the {::Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation#alias alias}
+        #     assigned to the aggregation function on input and the size of this map
+        #     equals the number of aggregation functions in the query.
+        class AggregationResult
+          include ::Google::Protobuf::MessageExts
+          extend ::Google::Protobuf::MessageExts::ClassMethods
+
+          # @!attribute [rw] key
+          #   @return [::String]
+          # @!attribute [rw] value
+          #   @return [::Google::Cloud::Firestore::V1::Value]
+          class AggregateFieldsEntry
+            include ::Google::Protobuf::MessageExts
+            extend ::Google::Protobuf::MessageExts::ClassMethods
+          end
+        end
+      end
+    end
+  end
+end

data/proto_docs/google/firestore/v1/firestore.rb

@@ -369,6 +369,61 @@ module Google
           extend ::Google::Protobuf::MessageExts::ClassMethods
         end
 
+        # The request for {::Google::Cloud::Firestore::V1::Firestore::Client#run_aggregation_query Firestore.RunAggregationQuery}.
+        # @!attribute [rw] parent
+        #   @return [::String]
+        #     Required. The parent resource name. In the format:
+        #     `projects/{project_id}/databases/{database_id}/documents` or
+        #     `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
+        #     For example:
+        #     `projects/my-project/databases/my-database/documents` or
+        #     `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
+        # @!attribute [rw] structured_aggregation_query
+        #   @return [::Google::Cloud::Firestore::V1::StructuredAggregationQuery]
+        #     An aggregation query.
+        # @!attribute [rw] transaction
+        #   @return [::String]
+        #     Run the aggregation within an already active transaction.
+        #
+        #     The value here is the opaque transaction ID to execute the query in.
+        # @!attribute [rw] new_transaction
+        #   @return [::Google::Cloud::Firestore::V1::TransactionOptions]
+        #     Starts a new transaction as part of the query, defaulting to read-only.
+        #
+        #     The new transaction ID will be returned as the first response in the
+        #     stream.
+        # @!attribute [rw] read_time
+        #   @return [::Google::Protobuf::Timestamp]
+        #     Executes the query at the given timestamp.
+        #
+        #     Requires:
+        #
+        #     * Cannot be more than 270 seconds in the past.
+        class RunAggregationQueryRequest
+          include ::Google::Protobuf::MessageExts
+          extend ::Google::Protobuf::MessageExts::ClassMethods
+        end
+
+        # The response for {::Google::Cloud::Firestore::V1::Firestore::Client#run_aggregation_query Firestore.RunAggregationQuery}.
+        # @!attribute [rw] result
+        #   @return [::Google::Cloud::Firestore::V1::AggregationResult]
+        #     A single aggregation result.
+        #
+        #     Not present when reporting partial progress.
+        # @!attribute [rw] transaction
+        #   @return [::String]
+        #     The transaction that was started as part of this request.
+        #
+        #     Only present on the first response when the request requested to start
+        #     a new transaction.
+        # @!attribute [rw] read_time
+        #   @return [::Google::Protobuf::Timestamp]
+        #     The time at which the aggregate value is valid for.
+        class RunAggregationQueryResponse
+          include ::Google::Protobuf::MessageExts
+          extend ::Google::Protobuf::MessageExts::ClassMethods
+        end
+
         # The request for {::Google::Cloud::Firestore::V1::Firestore::Client#partition_query Firestore.PartitionQuery}.
         # @!attribute [rw] parent
         #   @return [::String]

data/proto_docs/google/firestore/v1/query.rb

@@ -35,40 +35,87 @@ module Google
         #   @return [::Array<::Google::Cloud::Firestore::V1::StructuredQuery::Order>]
         #     The order to apply to the query results.
         #
-        #     Firestore guarantees a stable ordering through the following rules:
+        #     Firestore allows callers to provide a full ordering, a partial ordering, or
+        #     no ordering at all. In all cases, Firestore guarantees a stable ordering
+        #     through the following rules:
         #
-        #      * Any field required to appear in `order_by`, that is not already
-        #        specified in `order_by`, is appended to the order in field name order
-        #        by default.
+        #      * The `order_by` is required to reference all fields used with an
+        #        inequality filter.
+        #      * All fields that are required to be in the `order_by` but are not already
+        #        present are appended in lexicographical ordering of the field name.
         #      * If an order on `__name__` is not specified, it is appended by default.
         #
         #     Fields are appended with the same sort direction as the last order
         #     specified, or 'ASCENDING' if no order was specified. For example:
         #
-        #      * `SELECT * FROM Foo ORDER BY A` becomes
-        #        `SELECT * FROM Foo ORDER BY A, __name__`
-        #      * `SELECT * FROM Foo ORDER BY A DESC` becomes
-        #        `SELECT * FROM Foo ORDER BY A DESC, __name__ DESC`
-        #      * `SELECT * FROM Foo WHERE A > 1` becomes
-        #        `SELECT * FROM Foo WHERE A > 1 ORDER BY A, __name__`
+        #      * `ORDER BY a` becomes `ORDER BY a ASC, __name__ ASC`
+        #      * `ORDER BY a DESC` becomes `ORDER BY a DESC, __name__ DESC`
+        #      * `WHERE a > 1` becomes `WHERE a > 1 ORDER BY a ASC, __name__ ASC`
+        #      * `WHERE __name__ > ... AND a > 1` becomes
+        #         `WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC`
         # @!attribute [rw] start_at
         #   @return [::Google::Cloud::Firestore::V1::Cursor]
-        #     A starting point for the query results.
+        #     A potential prefix of a position in the result set to start the query at.
+        #
+        #     The ordering of the result set is based on the `ORDER BY` clause of the
+        #     original query.
+        #
+        #     ```
+        #     SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC;
+        #     ```
+        #
+        #     This query's results are ordered by `(b ASC, __name__ ASC)`.
+        #
+        #     Cursors can reference either the full ordering or a prefix of the location,
+        #     though it cannot reference more fields than what are in the provided
+        #     `ORDER BY`.
+        #
+        #     Continuing off the example above, attaching the following start cursors
+        #     will have varying impact:
+        #
+        #     - `START BEFORE (2, /k/123)`: start the query right before `a = 1 AND
+        #        b > 2 AND __name__ > /k/123`.
+        #     - `START AFTER (10)`: start the query right after `a = 1 AND b > 10`.
+        #
+        #     Unlike `OFFSET` which requires scanning over the first N results to skip,
+        #     a start cursor allows the query to begin at a logical position. This
+        #     position is not required to match an actual result, it will scan forward
+        #     from this position to find the next document.
+        #
+        #     Requires:
+        #
+        #     * The number of values cannot be greater than the number of fields
+        #       specified in the `ORDER BY` clause.
         # @!attribute [rw] end_at
         #   @return [::Google::Cloud::Firestore::V1::Cursor]
-        #     A end point for the query results.
+        #     A potential prefix of a position in the result set to end the query at.
+        #
+        #     This is similar to `START_AT` but with it controlling the end position
+        #     rather than the start position.
+        #
+        #     Requires:
+        #
+        #     * The number of values cannot be greater than the number of fields
+        #       specified in the `ORDER BY` clause.
         # @!attribute [rw] offset
         #   @return [::Integer]
-        #     The number of results to skip.
+        #     The number of documents to skip before returning the first result.
+        #
+        #     This applies after the constraints specified by the `WHERE`, `START AT`, &
+        #     `END AT` but before the `LIMIT` clause.
         #
-        #     Applies before limit, but after all other constraints. Must be >= 0 if
-        #     specified.
+        #     Requires:
+        #
+        #     * The value must be greater than or equal to zero if specified.
         # @!attribute [rw] limit
         #   @return [::Google::Protobuf::Int32Value]
         #     The maximum number of results to return.
         #
         #     Applies after all other constraints.
-        #     Must be >= 0 if specified.
+        #
+        #     Requires:
+        #
+        #     * The value must be greater than or equal to zero if specified.
         class StructuredQuery
           include ::Google::Protobuf::MessageExts
           extend ::Google::Protobuf::MessageExts::ClassMethods
@@ -270,9 +317,14 @@ module Google
             extend ::Google::Protobuf::MessageExts::ClassMethods
           end
 
-          # A reference to a field, such as `max(messages.time) as max_time`.
+          # A reference to a field in a document, ex: `stats.operations`.
           # @!attribute [rw] field_path
           #   @return [::String]
+          #     The relative path of the document being referenced.
+          #
+          #     Requires:
+          #
+          #     * Conform to {::Google::Cloud::Firestore::V1::Document#fields document field name} limitations.
           class FieldReference
             include ::Google::Protobuf::MessageExts
             extend ::Google::Protobuf::MessageExts::ClassMethods
@@ -303,6 +355,93 @@ module Google
           end
         end
 
+        # Firestore query for running an aggregation over a {::Google::Cloud::Firestore::V1::StructuredQuery StructuredQuery}.
+        # @!attribute [rw] structured_query
+        #   @return [::Google::Cloud::Firestore::V1::StructuredQuery]
+        #     Nested structured query.
+        # @!attribute [rw] aggregations
+        #   @return [::Array<::Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation>]
+        #     Optional. Series of aggregations to apply over the results of the `structured_query`.
+        #
+        #     Requires:
+        #
+        #     * A minimum of one and maximum of five aggregations per query.
+        class StructuredAggregationQuery
+          include ::Google::Protobuf::MessageExts
+          extend ::Google::Protobuf::MessageExts::ClassMethods
+
+          # Defines a aggregation that produces a single result.
+          # @!attribute [rw] count
+          #   @return [::Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation::Count]
+          #     Count aggregator.
+          # @!attribute [rw] alias
+          #   @return [::String]
+          #     Optional. Optional name of the field to store the result of the aggregation into.
+          #
+          #     If not provided, Firestore will pick a default name following the format
+          #     `field_<incremental_id++>`. For example:
+          #
+          #     ```
+          #     AGGREGATE
+          #       COUNT_UP_TO(1) AS count_up_to_1,
+          #       COUNT_UP_TO(2),
+          #       COUNT_UP_TO(3) AS count_up_to_3,
+          #       COUNT_UP_TO(4)
+          #     OVER (
+          #       ...
+          #     );
+          #     ```
+          #
+          #     becomes:
+          #
+          #     ```
+          #     AGGREGATE
+          #       COUNT_UP_TO(1) AS count_up_to_1,
+          #       COUNT_UP_TO(2) AS field_1,
+          #       COUNT_UP_TO(3) AS count_up_to_3,
+          #       COUNT_UP_TO(4) AS field_2
+          #     OVER (
+          #       ...
+          #     );
+          #     ```
+          #
+          #     Requires:
+          #
+          #     * Must be unique across all aggregation aliases.
+          #     * Conform to {::Google::Cloud::Firestore::V1::Document#fields document field name} limitations.
+          class Aggregation
+            include ::Google::Protobuf::MessageExts
+            extend ::Google::Protobuf::MessageExts::ClassMethods
+
+            # Count of documents that match the query.
+            #
+            # The `COUNT(*)` aggregation function operates on the entire document
+            # so it does not require a field reference.
+            # @!attribute [rw] up_to
+            #   @return [::Google::Protobuf::Int64Value]
+            #     Optional. Optional constraint on the maximum number of documents to count.
+            #
+            #     This provides a way to set an upper bound on the number of documents
+            #     to scan, limiting latency and cost.
+            #
+            #     Unspecified is interpreted as no bound.
+            #
+            #     High-Level Example:
+            #
+            #     ```
+            #     AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );
+            #     ```
+            #
+            #     Requires:
+            #
+            #     * Must be greater than zero when present.
+            class Count
+              include ::Google::Protobuf::MessageExts
+              extend ::Google::Protobuf::MessageExts::ClassMethods
+            end
+          end
+        end
+
         # A position in a query result set.
         # @!attribute [rw] values
         #   @return [::Array<::Google::Cloud::Firestore::V1::Value>]

data/proto_docs/google/protobuf/empty.rb

@@ -26,8 +26,6 @@ module Google
     #     service Foo {
     #       rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
     #     }
-    #
-    # The JSON representation for `Empty` is empty JSON object `{}`.
     class Empty
       include ::Google::Protobuf::MessageExts
       extend ::Google::Protobuf::MessageExts::ClassMethods

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-firestore-v1
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Google LLC
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-07-02 00:00:00.000000000 Z
+date: 2022-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gapic-common
@@ -44,6 +44,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: google-cloud-location
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.a
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.a
 - !ruby/object:Gem::Dependency
   name: google-style
   requirement: !ruby/object:Gem::Requirement
@@ -175,6 +195,7 @@ files:
 - lib/google/cloud/firestore/v1/firestore/client.rb
 - lib/google/cloud/firestore/v1/firestore/credentials.rb
 - lib/google/cloud/firestore/v1/version.rb
+- lib/google/firestore/v1/aggregation_result_pb.rb
 - lib/google/firestore/v1/common_pb.rb
 - lib/google/firestore/v1/document_pb.rb
 - lib/google/firestore/v1/firestore_pb.rb
@@ -184,6 +205,7 @@ files:
 - proto_docs/README.md
 - proto_docs/google/api/field_behavior.rb
 - proto_docs/google/api/resource.rb
+- proto_docs/google/firestore/v1/aggregation_result.rb
 - proto_docs/google/firestore/v1/common.rb
 - proto_docs/google/firestore/v1/document.rb
 - proto_docs/google/firestore/v1/firestore.rb