Skip to content
This repository was archived by the owner on Mar 4, 2026. It is now read-only.

Commit e598b9d

Browse files
gcf-owl-bot[bot]gcf-owl-bot[bot]
authored
feat: add new types ExplainOptions, ExplainMetrics, PlanSummary, ExecutionStats (#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>
1 parent 6a220a6 commit e598b9d

5 files changed

Lines changed: 99 additions & 37 deletions

File tree

‎dev/protos/google/api/client.proto‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,22 @@ extend google.protobuf.ServiceOptions {
9898
// ...
9999
// }
100100
string oauth_scopes = 1050;
101+
102+
// The API version of this service, which should be sent by version-aware
103+
// clients to the service. This allows services to abide by the schema and
104+
// behavior of the service at the time this API version was deployed.
105+
// The format of the API version must be treated as opaque by clients.
106+
// Services may use a format with an apparent structure, but clients must
107+
// not rely on this to determine components within an API version, or attempt
108+
// to construct other valid API versions. Note that this is for upcoming
109+
// functionality and may not be implemented for all services.
110+
//
111+
// Example:
112+
//
113+
// service Foo {
114+
// option (google.api.api_version) = "v1_20230821_preview";
115+
// }
116+
string api_version = 525000001;
101117
}
102118

103119
// Required information for every language.
@@ -192,6 +208,10 @@ message Publishing {
192208
// Optional link to proto reference documentation. Example:
193209
// https://cloud.google.com/pubsub/lite/docs/reference/rpc
194210
string proto_reference_documentation_uri = 110;
211+
212+
// Optional link to REST reference documentation. Example:
213+
// https://cloud.google.com/pubsub/lite/docs/reference/rest
214+
string rest_reference_documentation_uri = 111;
195215
}
196216

197217
// Settings for Java client libraries.

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

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ import "google/firestore/v1/aggregation_result.proto";
2323
import "google/firestore/v1/common.proto";
2424
import "google/firestore/v1/document.proto";
2525
import "google/firestore/v1/query.proto";
26+
import "google/firestore/v1/query_profile.proto";
2627
import "google/firestore/v1/write.proto";
2728
import "google/protobuf/empty.proto";
2829
import "google/protobuf/timestamp.proto";
@@ -576,6 +577,10 @@ message RunQueryRequest {
576577
// minute timestamp within the past 7 days.
577578
google.protobuf.Timestamp read_time = 7;
578579
}
580+
581+
// Optional. Explain options for the query. If set, additional query
582+
// statistics will be returned. If not, only query results will be returned.
583+
ExplainOptions explain_options = 10 [(google.api.field_behavior) = OPTIONAL];
579584
}
580585

581586
// The response for
@@ -612,6 +617,11 @@ message RunQueryResponse {
612617
// documents will be returned.
613618
bool done = 6;
614619
}
620+
621+
// Query explain metrics. This is only present when the
622+
// [RunQueryRequest.explain_options][google.firestore.v1.RunQueryRequest.explain_options]
623+
// is provided, and it is sent only once with the last response in the stream.
624+
ExplainMetrics explain_metrics = 11;
615625
}
616626

617627
// The request for
@@ -651,6 +661,10 @@ message RunAggregationQueryRequest {
651661
// minute timestamp within the past 7 days.
652662
google.protobuf.Timestamp read_time = 6;
653663
}
664+
665+
// Optional. Explain options for the query. If set, additional query
666+
// statistics will be returned. If not, only query results will be returned.
667+
ExplainOptions explain_options = 8 [(google.api.field_behavior) = OPTIONAL];
654668
}
655669

656670
// The response for
@@ -676,6 +690,11 @@ message RunAggregationQueryResponse {
676690
// `result` will be sent, and this represents the time at which the query
677691
// was run.
678692
google.protobuf.Timestamp read_time = 3;
693+
694+
// Query explain metrics. This is only present when the
695+
// [RunAggregationQueryRequest.explain_options][google.firestore.v1.RunAggregationQueryRequest.explain_options]
696+
// is provided, and it is sent only once with the last response in the stream.
697+
ExplainMetrics explain_metrics = 10;
679698
}
680699

681700
// The request for

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

Lines changed: 53 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ syntax = "proto3";
1616

1717
package google.firestore.v1;
1818

19+
import "google/api/field_behavior.proto";
20+
import "google/protobuf/duration.proto";
1921
import "google/protobuf/struct.proto";
2022

2123
option csharp_namespace = "Google.Cloud.Firestore.V1";
@@ -29,48 +31,62 @@ option ruby_package = "Google::Cloud::Firestore::V1";
2931

3032
// Specification of the Firestore Query Profile fields.
3133

32-
// The mode in which the query request must be processed.
33-
enum QueryMode {
34-
// The default mode. Only the query results are returned.
35-
NORMAL = 0;
34+
// Explain options for the query.
35+
message ExplainOptions {
36+
// Optional. Whether to execute this query.
37+
//
38+
// When false (the default), the query will be planned, returning only
39+
// metrics from the planning stages.
40+
//
41+
// When true, the query will be planned and executed, returning the full
42+
// query results along with both planning and execution stage metrics.
43+
bool analyze = 1 [(google.api.field_behavior) = OPTIONAL];
44+
}
3645

37-
// This mode returns only the query plan, without any results or execution
38-
// statistics information.
39-
PLAN = 1;
46+
// Explain metrics for the query.
47+
message ExplainMetrics {
48+
// Planning phase information for the query.
49+
PlanSummary plan_summary = 1;
4050

41-
// This mode returns both the query plan and the execution statistics along
42-
// with the results.
43-
PROFILE = 2;
51+
// Aggregated stats from the execution of the query. Only present when
52+
// [ExplainOptions.analyze][google.firestore.v1.ExplainOptions.analyze] is set
53+
// to true.
54+
ExecutionStats execution_stats = 2;
4455
}
4556

46-
// Plan for the query.
47-
message QueryPlan {
48-
// Planning phase information for the query. It will include:
49-
//
50-
// {
51-
// "indexes_used": [
52-
// {"query_scope": "Collection", "properties": "(foo ASC, __name__ ASC)"},
53-
// {"query_scope": "Collection", "properties": "(bar ASC, __name__ ASC)"}
54-
// ]
55-
// }
56-
google.protobuf.Struct plan_info = 1;
57+
// Planning phase information for the query.
58+
message PlanSummary {
59+
// The indexes selected for the query. For example:
60+
// [
61+
// {"query_scope": "Collection", "properties": "(foo ASC, __name__ ASC)"},
62+
// {"query_scope": "Collection", "properties": "(bar ASC, __name__ ASC)"}
63+
// ]
64+
repeated google.protobuf.Struct indexes_used = 1;
5765
}
5866

59-
// Planning and execution statistics for the query.
60-
message ResultSetStats {
61-
// Plan for the query.
62-
QueryPlan query_plan = 1;
67+
// Execution statistics for the query.
68+
message ExecutionStats {
69+
// Total number of results returned, including documents, projections,
70+
// aggregation results, keys.
71+
int64 results_returned = 1;
6372

64-
// Aggregated statistics from the execution of the query.
65-
//
66-
// This will only be present when the request specifies `PROFILE` mode.
67-
// For example, a query will return the statistics including:
68-
//
69-
// {
70-
// "results_returned": "20",
71-
// "documents_scanned": "20",
72-
// "indexes_entries_scanned": "10050",
73-
// "total_execution_time": "100.7 msecs"
74-
// }
75-
google.protobuf.Struct query_stats = 2;
73+
// Total time to execute the query in the backend.
74+
google.protobuf.Duration execution_duration = 3;
75+
76+
// Total billable read operations.
77+
int64 read_operations = 4;
78+
79+
// Debugging statistics from the execution of the query. Note that the
80+
// debugging stats are subject to change as Firestore evolves. It could
81+
// include:
82+
// {
83+
// "indexes_entries_scanned": "1000",
84+
// "documents_scanned": "20",
85+
// "billing_details" : {
86+
// "documents_billable": "20",
87+
// "index_entries_billable": "1000",
88+
// "min_query_cost": "0"
89+
// }
90+
// }
91+
google.protobuf.Struct debug_stats = 5;
7692
}

‎dev/src/v1/firestore_client.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1281,6 +1281,9 @@ export class FirestoreClient {
12811281
* This must be a microsecond precision timestamp within the past one hour,
12821282
* or if Point-in-Time Recovery is enabled, can additionally be a whole
12831283
* minute timestamp within the past 7 days.
1284+
* @param {google.firestore.v1.ExplainOptions} [request.explainOptions]
1285+
* Optional. Explain options for the query. If set, additional query
1286+
* statistics will be returned. If not, only query results will be returned.
12841287
* @param {object} [options]
12851288
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
12861289
* @returns {Stream}
@@ -1347,6 +1350,9 @@ export class FirestoreClient {
13471350
* This must be a microsecond precision timestamp within the past one hour,
13481351
* or if Point-in-Time Recovery is enabled, can additionally be a whole
13491352
* minute timestamp within the past 7 days.
1353+
* @param {google.firestore.v1.ExplainOptions} [request.explainOptions]
1354+
* Optional. Explain options for the query. If set, additional query
1355+
* statistics will be returned. If not, only query results will be returned.
13501356
* @param {object} [options]
13511357
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
13521358
* @returns {Stream}

‎dev/src/v1/firestore_proto_list.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,6 @@
55
"../../protos/google/firestore/v1/document.proto",
66
"../../protos/google/firestore/v1/firestore.proto",
77
"../../protos/google/firestore/v1/query.proto",
8+
"../../protos/google/firestore/v1/query_profile.proto",
89
"../../protos/google/firestore/v1/write.proto"
910
]

0 commit comments

Comments
 (0)