feat: add new types ExplainOptions, ExplainMetrics, PlanSummary, Exec…

…utionStats (#2013)

* feat: add new types ExplainOptions, ExplainMetrics, PlanSummary, ExecutionStats
feat: add ExplainOptions field to RunQueryRequest
feat: add ExplainMetrics field to RunQueryResponse
feat: add ExplainOptions field to RunAggregationQueryRequest
feat: add ExplainMetrics field to RunAggregationQueryResponse

PiperOrigin-RevId: 615158086

Source-Link: googleapis/googleapis@dbd2d6d

Source-Link: googleapis/googleapis-gen@a1d5d01
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiYTFkNWQwMTkzMDBkMjA2OTg5NzQ2YWRkZGE5MjFlMjFkMWIwMmU4MiJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

dev/protos/google/api/client.proto

@@ -98,6 +98,22 @@ extend google.protobuf.ServiceOptions {
   //     ...
   //   }
   string oauth_scopes = 1050;
+
+  // The API version of this service, which should be sent by version-aware
+  // clients to the service. This allows services to abide by the schema and
+  // behavior of the service at the time this API version was deployed.
+  // The format of the API version must be treated as opaque by clients.
+  // Services may use a format with an apparent structure, but clients must
+  // not rely on this to determine components within an API version, or attempt
+  // to construct other valid API versions. Note that this is for upcoming
+  // functionality and may not be implemented for all services.
+  //
+  // Example:
+  //
+  //   service Foo {
+  //     option (google.api.api_version) = "v1_20230821_preview";
+  //   }
+  string api_version = 525000001;
 }
 
 // Required information for every language.
@@ -192,6 +208,10 @@ message Publishing {
   // Optional link to proto reference documentation.  Example:
   // https://cloud.google.com/pubsub/lite/docs/reference/rpc
   string proto_reference_documentation_uri = 110;
+
+  // Optional link to REST reference documentation.  Example:
+  // https://cloud.google.com/pubsub/lite/docs/reference/rest
+  string rest_reference_documentation_uri = 111;
 }
 
 // Settings for Java client libraries.

dev/protos/google/firestore/v1/firestore.proto

@@ -23,6 +23,7 @@ import "google/firestore/v1/aggregation_result.proto";
 import "google/firestore/v1/common.proto";
 import "google/firestore/v1/document.proto";
 import "google/firestore/v1/query.proto";
+import "google/firestore/v1/query_profile.proto";
 import "google/firestore/v1/write.proto";
 import "google/protobuf/empty.proto";
 import "google/protobuf/timestamp.proto";
@@ -576,6 +577,10 @@ message RunQueryRequest {
     // minute timestamp within the past 7 days.
     google.protobuf.Timestamp read_time = 7;
   }
+
+  // Optional. Explain options for the query. If set, additional query
+  // statistics will be returned. If not, only query results will be returned.
+  ExplainOptions explain_options = 10 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The response for
@@ -612,6 +617,11 @@ message RunQueryResponse {
     // documents will be returned.
     bool done = 6;
   }
+
+  // Query explain metrics. This is only present when the
+  // [RunQueryRequest.explain_options][google.firestore.v1.RunQueryRequest.explain_options]
+  // is provided, and it is sent only once with the last response in the stream.
+  ExplainMetrics explain_metrics = 11;
 }
 
 // The request for
@@ -651,6 +661,10 @@ message RunAggregationQueryRequest {
     // minute timestamp within the past 7 days.
     google.protobuf.Timestamp read_time = 6;
   }
+
+  // Optional. Explain options for the query. If set, additional query
+  // statistics will be returned. If not, only query results will be returned.
+  ExplainOptions explain_options = 8 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The response for
@@ -676,6 +690,11 @@ message RunAggregationQueryResponse {
   // `result` will be sent, and this represents the time at which the query
   // was run.
   google.protobuf.Timestamp read_time = 3;
+
+  // Query explain metrics. This is only present when the
+  // [RunAggregationQueryRequest.explain_options][google.firestore.v1.RunAggregationQueryRequest.explain_options]
+  // is provided, and it is sent only once with the last response in the stream.
+  ExplainMetrics explain_metrics = 10;
 }
 
 // The request for

dev/protos/google/firestore/v1/query_profile.proto

@@ -16,6 +16,8 @@ syntax = "proto3";
 
 package google.firestore.v1;
 
+import "google/api/field_behavior.proto";
+import "google/protobuf/duration.proto";
 import "google/protobuf/struct.proto";
 
 option csharp_namespace = "Google.Cloud.Firestore.V1";
@@ -29,48 +31,62 @@ option ruby_package = "Google::Cloud::Firestore::V1";
 
 // Specification of the Firestore Query Profile fields.
 
-// The mode in which the query request must be processed.
-enum QueryMode {
-  // The default mode. Only the query results are returned.
-  NORMAL = 0;
+// Explain options for the query.
+message ExplainOptions {
+  // Optional. Whether to execute this query.
+  //
+  // When false (the default), the query will be planned, returning only
+  // metrics from the planning stages.
+  //
+  // When true, the query will be planned and executed, returning the full
+  // query results along with both planning and execution stage metrics.
+  bool analyze = 1 [(google.api.field_behavior) = OPTIONAL];
+}
 
-  // This mode returns only the query plan, without any results or execution
-  // statistics information.
-  PLAN = 1;
+// Explain metrics for the query.
+message ExplainMetrics {
+  // Planning phase information for the query.
+  PlanSummary plan_summary = 1;
 
-  // This mode returns both the query plan and the execution statistics along
-  // with the results.
-  PROFILE = 2;
+  // Aggregated stats from the execution of the query. Only present when
+  // [ExplainOptions.analyze][google.firestore.v1.ExplainOptions.analyze] is set
+  // to true.
+  ExecutionStats execution_stats = 2;
 }
 
-// Plan for the query.
-message QueryPlan {
-  // Planning phase information for the query. It will include:
-  //
-  // {
-  //   "indexes_used": [
-  //     {"query_scope": "Collection", "properties": "(foo ASC, __name__ ASC)"},
-  //     {"query_scope": "Collection", "properties": "(bar ASC, __name__ ASC)"}
-  //   ]
-  // }
-  google.protobuf.Struct plan_info = 1;
+// Planning phase information for the query.
+message PlanSummary {
+  // The indexes selected for the query. For example:
+  //  [
+  //    {"query_scope": "Collection", "properties": "(foo ASC, __name__ ASC)"},
+  //    {"query_scope": "Collection", "properties": "(bar ASC, __name__ ASC)"}
+  //  ]
+  repeated google.protobuf.Struct indexes_used = 1;
 }
 
-// Planning and execution statistics for the query.
-message ResultSetStats {
-  // Plan for the query.
-  QueryPlan query_plan = 1;
+// Execution statistics for the query.
+message ExecutionStats {
+  // Total number of results returned, including documents, projections,
+  // aggregation results, keys.
+  int64 results_returned = 1;
 
-  // Aggregated statistics from the execution of the query.
-  //
-  // This will only be present when the request specifies `PROFILE` mode.
-  // For example, a query will return the statistics including:
-  //
-  // {
-  //   "results_returned": "20",
-  //   "documents_scanned": "20",
-  //   "indexes_entries_scanned": "10050",
-  //   "total_execution_time": "100.7 msecs"
-  // }
-  google.protobuf.Struct query_stats = 2;
+  // Total time to execute the query in the backend.
+  google.protobuf.Duration execution_duration = 3;
+
+  // Total billable read operations.
+  int64 read_operations = 4;
+
+  // Debugging statistics from the execution of the query. Note that the
+  // debugging stats are subject to change as Firestore evolves. It could
+  // include:
+  //  {
+  //    "indexes_entries_scanned": "1000",
+  //    "documents_scanned": "20",
+  //    "billing_details" : {
+  //       "documents_billable": "20",
+  //       "index_entries_billable": "1000",
+  //       "min_query_cost": "0"
+  //    }
+  //  }
+  google.protobuf.Struct debug_stats = 5;
 }

dev/src/v1/firestore_client.ts

@@ -1281,6 +1281,9 @@ export class FirestoreClient {
    *   This must be a microsecond precision timestamp within the past one hour,
    *   or if Point-in-Time Recovery is enabled, can additionally be a whole
    *   minute timestamp within the past 7 days.
+   * @param {google.firestore.v1.ExplainOptions} [request.explainOptions]
+   *   Optional. Explain options for the query. If set, additional query
+   *   statistics will be returned. If not, only query results will be returned.
    * @param {object} [options]
    *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
    * @returns {Stream}
@@ -1347,6 +1350,9 @@ export class FirestoreClient {
    *   This must be a microsecond precision timestamp within the past one hour,
    *   or if Point-in-Time Recovery is enabled, can additionally be a whole
    *   minute timestamp within the past 7 days.
+   * @param {google.firestore.v1.ExplainOptions} [request.explainOptions]
+   *   Optional. Explain options for the query. If set, additional query
+   *   statistics will be returned. If not, only query results will be returned.
    * @param {object} [options]
    *   Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
    * @returns {Stream}

dev/src/v1/firestore_proto_list.json

@@ -5,5 +5,6 @@
   "../../protos/google/firestore/v1/document.proto",
   "../../protos/google/firestore/v1/firestore.proto",
   "../../protos/google/firestore/v1/query.proto",
+  "../../protos/google/firestore/v1/query_profile.proto",
   "../../protos/google/firestore/v1/write.proto"
 ]