From 4d535ac0538bb2d4b406250d7ec10b25a17a54cf Mon Sep 17 00:00:00 2001 From: Google APIs Date: Tue, 12 Mar 2024 13:43:46 -0700 Subject: [PATCH] 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: 615158168 --- google/datastore/v1/BUILD.bazel | 2 + google/datastore/v1/datastore.proto | 19 ++++++ google/datastore/v1/query_profile.proto | 91 +++++++++++++++++++++++++ 3 files changed, 112 insertions(+) create mode 100644 google/datastore/v1/query_profile.proto diff --git a/google/datastore/v1/BUILD.bazel b/google/datastore/v1/BUILD.bazel index 4866d04b6ff71..02373208f4415 100644 --- a/google/datastore/v1/BUILD.bazel +++ b/google/datastore/v1/BUILD.bazel @@ -25,6 +25,7 @@ proto_library( "datastore.proto", "entity.proto", "query.proto", + "query_profile.proto", ], deps = [ "//google/api:annotations_proto", @@ -32,6 +33,7 @@ proto_library( "//google/api:field_behavior_proto", "//google/api:routing_proto", "//google/type:latlng_proto", + "@com_google_protobuf//:duration_proto", "@com_google_protobuf//:struct_proto", "@com_google_protobuf//:timestamp_proto", "@com_google_protobuf//:wrappers_proto", diff --git a/google/datastore/v1/datastore.proto b/google/datastore/v1/datastore.proto index 533988d777654..1a3fbdd11a307 100644 --- a/google/datastore/v1/datastore.proto +++ b/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,10 @@ message RunQueryRequest { // The GQL query to run. This query must be a non-aggregation query. GqlQuery gql_query = 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 = 12 [(google.api.field_behavior) = OPTIONAL]; } // The response for @@ -251,6 +256,11 @@ message RunQueryResponse { // was set in // [RunQueryRequest.read_options][google.datastore.v1.RunQueryRequest.read_options]. bytes transaction = 5; + + // Query explain metrics. This is only present when the + // [RunQueryRequest.explain_options][google.datastore.v1.RunQueryRequest.explain_options] + // is provided, and it is sent only once with the last response in the stream. + ExplainMetrics explain_metrics = 9; } // The request for @@ -282,6 +292,10 @@ message RunAggregationQueryRequest { // The GQL query to run. This query must be an aggregation query. GqlQuery gql_query = 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 = 11 [(google.api.field_behavior) = OPTIONAL]; } // The response for @@ -301,6 +315,11 @@ message RunAggregationQueryResponse { // was set in // [RunAggregationQueryRequest.read_options][google.datastore.v1.RunAggregationQueryRequest.read_options]. bytes transaction = 5; + + // Query explain metrics. This is only present when the + // [RunAggregationQueryRequest.explain_options][google.datastore.v1.RunAggregationQueryRequest.explain_options] + // is provided, and it is sent only once with the last response in the stream. + ExplainMetrics explain_metrics = 9; } // The request for diff --git a/google/datastore/v1/query_profile.proto b/google/datastore/v1/query_profile.proto new file mode 100644 index 0000000000000..01c9fc254755e --- /dev/null +++ b/google/datastore/v1/query_profile.proto @@ -0,0 +1,91 @@ +// 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/api/field_behavior.proto"; +import "google/protobuf/duration.proto"; +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. + +// 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]; +} + +// Explain metrics for the query. +message ExplainMetrics { + // Planning phase information for the query. + PlanSummary plan_summary = 1; + + // Aggregated stats from the execution of the query. Only present when + // [ExplainOptions.analyze][google.datastore.v1.ExplainOptions.analyze] is set + // to true. + ExecutionStats execution_stats = 2; +} + +// 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; +} + +// Execution statistics for the query. +message ExecutionStats { + // Total number of results returned, including documents, projections, + // aggregation results, keys. + int64 results_returned = 1; + + // 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; +}