feat: add new types QueryMode, QueryPlan, ResultSetStats (#1216)

* fix: correct long audio synthesis HTTP binding
docs: Deprecate the custom voice usage field

PiperOrigin-RevId: 595119987

Source-Link: googleapis/googleapis@c22f408

Source-Link: googleapis/googleapis-gen@4e9ca63
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiNGU5Y2E2M2QyY2M3OTMzZWI3YzM4M2NlOGI3OTRmY2UxNTJlYTJmYyJ9

* 🦉 Updates from OwlBot post-processor

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

* feat: add new types QueryMode, QueryPlan, ResultSetStats
feat: add QueryMode field to RunQueryRequest
feat: add ResultSetStats field to RunQueryResponse
feat: add QueryMode field to RunAggregationQueryRequest
feat: add ResultSetStats field to RunAggregationQueryResponse

PiperOrigin-RevId: 595774772

Source-Link: googleapis/googleapis@03e7ed4

Source-Link: googleapis/googleapis-gen@dc63e0d
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiZGM2M2UwZGVhODQyM2MyMzBkNWZiMDkzN2FjYjNjOTg3MTljOTM5NSJ9

* 🦉 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>

.jsdoc.js

@@ -1,4 +1,4 @@
-// Copyright 2023 Google LLC
+// Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -40,7 +40,7 @@ module.exports = {
     includePattern: '\\.js$'
   },
   templates: {
-    copyright: 'Copyright 2023 Google LLC',
+    copyright: 'Copyright 2024 Google LLC',
     includeDate: false,
     sourceFiles: false,
     systemName: '@google-cloud/datastore',

protos/google/datastore/v1/datastore.proto

@@ -23,6 +23,7 @@ import "google/api/routing.proto";
 import "google/datastore/v1/aggregation_result.proto";
 import "google/datastore/v1/entity.proto";
 import "google/datastore/v1/query.proto";
+import "google/datastore/v1/query_profile.proto";
 import "google/protobuf/timestamp.proto";
 
 option csharp_namespace = "Google.Cloud.Datastore.V1";
@@ -232,6 +233,11 @@ message RunQueryRequest {
     // The GQL query to run. This query must be a non-aggregation query.
     GqlQuery gql_query = 7;
   }
+
+  // Optional. The mode in which the query request is processed. This field is
+  // optional, and when not provided, it defaults to `NORMAL` mode where no
+  // additional statistics will be returned with the query results.
+  QueryMode mode = 11 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The response for
@@ -251,6 +257,12 @@ message RunQueryResponse {
   // was set in
   // [RunQueryRequest.read_options][google.datastore.v1.RunQueryRequest.read_options].
   bytes transaction = 5;
+
+  // Query plan and execution statistics. Note that the returned stats are
+  // subject to change as Firestore evolves.
+  //
+  // This is only present when the request specifies a mode other than `NORMAL`.
+  ResultSetStats stats = 6;
 }
 
 // The request for
@@ -282,6 +294,11 @@ message RunAggregationQueryRequest {
     // The GQL query to run. This query must be an aggregation query.
     GqlQuery gql_query = 7;
   }
+
+  // Optional. The mode in which the query request is processed. This field is
+  // optional, and when not provided, it defaults to `NORMAL` mode where no
+  // additional statistics will be returned with the query results.
+  QueryMode mode = 10 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The response for
@@ -301,6 +318,12 @@ message RunAggregationQueryResponse {
   // was set in
   // [RunAggregationQueryRequest.read_options][google.datastore.v1.RunAggregationQueryRequest.read_options].
   bytes transaction = 5;
+
+  // Query plan and execution statistics. Note that the returned stats are
+  // subject to change as Firestore evolves.
+  //
+  // This is only present when the request specifies a mode other than `NORMAL`.
+  ResultSetStats stats = 6;
 }
 
 // The request for

protos/google/datastore/v1/query_profile.proto

@@ -0,0 +1,75 @@
+// 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
+//
+//     http://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.
+
+syntax = "proto3";
+
+package google.datastore.v1;
+
+import "google/protobuf/struct.proto";
+
+option csharp_namespace = "Google.Cloud.Datastore.V1";
+option go_package = "google.golang.org/genproto/googleapis/datastore/v1;datastore";
+option java_multiple_files = true;
+option java_outer_classname = "QueryProfileProto";
+option java_package = "com.google.datastore.v1";
+option php_namespace = "Google\\Cloud\\Datastore\\V1";
+option ruby_package = "Google::Cloud::Datastore::V1";
+
+// Specification of the Datastore 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;
+
+  // This mode returns only the query plan, without any results or execution
+  // statistics information.
+  PLAN = 1;
+
+  // This mode returns both the query plan and the execution statistics along
+  // with the results.
+  PROFILE = 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 and execution statistics for the query.
+message ResultSetStats {
+  // Plan for the query.
+  QueryPlan query_plan = 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;
+}