feat: add new types QueryMode, QueryPlan, ResultSetStats

Google APIs · copybara-github · commit 20278077049f · 2024-01-04T12:17:37.000-08:00
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: 595771083
diff --git a/google/firestore/v1/BUILD.bazel b/google/firestore/v1/BUILD.bazel
@@ -27,6 +27,7 @@ proto_library(
         "document.proto",
         "firestore.proto",
         "query.proto",
+        "query_profile.proto",
         "write.proto",
     ],
     deps = [
diff --git a/google/firestore/v1/firestore.proto b/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,11 @@ message RunQueryRequest {
     // minute timestamp within the past 7 days.
     google.protobuf.Timestamp read_time = 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 = 9 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The response for
@@ -612,6 +618,13 @@ message RunQueryResponse {
     // documents will be returned.
     bool done = 6;
   }
+
+  // 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`
+  // and is sent only once with the last response in the stream.
+  ResultSetStats stats = 7;
 }
 
 // The request for
@@ -651,6 +664,11 @@ message RunAggregationQueryRequest {
     // minute timestamp within the past 7 days.
     google.protobuf.Timestamp read_time = 6;
   }
+
+  // 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 = 7 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The response for
@@ -676,6 +694,13 @@ message RunAggregationQueryResponse {
   // `result` will be sent, and this represents the time at which the query
   // was run.
   google.protobuf.Timestamp read_time = 3;
+
+  // 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`
+  // and is sent only once with the last response in the stream.
+  ResultSetStats stats = 6;
 }
 
 // The request for
diff --git a/google/firestore/v1/query_profile.proto b/google/firestore/v1/query_profile.proto
@@ -0,0 +1,76 @@
+// 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.firestore.v1;
+
+import "google/protobuf/struct.proto";
+
+option csharp_namespace = "Google.Cloud.Firestore.V1";
+option go_package = "cloud.google.com/go/firestore/apiv1/firestorepb;firestorepb";
+option java_multiple_files = true;
+option java_outer_classname = "QueryProfileProto";
+option java_package = "com.google.firestore.v1";
+option objc_class_prefix = "GCFS";
+option php_namespace = "Google\\Cloud\\Firestore\\V1";
+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;
+
+  // 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;
+}
