Skip to content

Commit

Permalink
feat: add new types ExplainOptions, ExplainMetrics, PlanSummary, Exec…
Browse files Browse the repository at this point in the history 
…utionStats (#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>
  • Loading branch information
@gcf-owl-bot
gcf-owl-bot[bot] and gcf-owl-bot[bot] committed Mar 13, 2024
1 parent 6a220a6 commit e598b9d
Show file tree
Hide file tree
Showing 5 changed files with 99 additions and 37 deletions.
20 changes: 20 additions & 0 deletions dev/protos/google/api/client.proto
View file
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
19 changes: 19 additions & 0 deletions dev/protos/google/firestore/v1/firestore.proto
View file
Expand Up @@ -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";
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
90 changes: 53 additions & 37 deletions dev/protos/google/firestore/v1/query_profile.proto
View file
Expand Up @@ -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";
Expand All @@ -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;
}
6 changes: 6 additions & 0 deletions dev/src/v1/firestore_client.ts
View file
Expand Up @@ -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}
Expand Down Expand Up @@ -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}
Expand Down
1 change: 1 addition & 0 deletions dev/src/v1/firestore_proto_list.json
View file
Expand Up @@ -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"
]

0 comments on commit e598b9d

Please sign in to comment.