From e598b9daf628cbc54dc10dab80bb0f46e2a3e2a2 Mon Sep 17 00:00:00 2001 From: "gcf-owl-bot[bot]" <78513119+gcf-owl-bot[bot]@users.noreply.github.com> Date: Wed, 13 Mar 2024 09:33:34 -0700 Subject: [PATCH] feat: add new types ExplainOptions, ExplainMetrics, PlanSummary, ExecutionStats (#2013) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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: https://github.com/googleapis/googleapis/commit/dbd2d6de9fd7942c1d3507979eff666e37470e18 Source-Link: https://github.com/googleapis/googleapis-gen/commit/a1d5d019300d206989746addda921e21d1b02e82 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 --- dev/protos/google/api/client.proto | 20 +++++ .../google/firestore/v1/firestore.proto | 19 ++++ .../google/firestore/v1/query_profile.proto | 90 +++++++++++-------- dev/src/v1/firestore_client.ts | 6 ++ dev/src/v1/firestore_proto_list.json | 1 + 5 files changed, 99 insertions(+), 37 deletions(-) diff --git a/dev/protos/google/api/client.proto b/dev/protos/google/api/client.proto index 39bdde82a..0952e8373 100644 --- a/dev/protos/google/api/client.proto +++ b/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. diff --git a/dev/protos/google/firestore/v1/firestore.proto b/dev/protos/google/firestore/v1/firestore.proto index 3b843eed5..8d78ce4f4 100644 --- a/dev/protos/google/firestore/v1/firestore.proto +++ b/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 diff --git a/dev/protos/google/firestore/v1/query_profile.proto b/dev/protos/google/firestore/v1/query_profile.proto index 371aa1ef2..931e083b0 100644 --- a/dev/protos/google/firestore/v1/query_profile.proto +++ b/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; } diff --git a/dev/src/v1/firestore_client.ts b/dev/src/v1/firestore_client.ts index ada44a3fa..705694bb3 100644 --- a/dev/src/v1/firestore_client.ts +++ b/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} diff --git a/dev/src/v1/firestore_proto_list.json b/dev/src/v1/firestore_proto_list.json index 5c2cd76e2..318c636c1 100644 --- a/dev/src/v1/firestore_proto_list.json +++ b/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" ]