Skip to content

Commit b32495a

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: add a QueryData API for NL2SQL conversion
feat: A new message `AgentContextReference` is added feat: A new method `QueryData` is added to service `DataChatService` feat: A new message `QueryDataRequest` is added feat: A new message `GenerationOptions` is added feat: A new message `QueryDataContext` is added feat: A new message `QueryDataResponse` is added feat: A new message `ExecutedQueryResult` is added feat: A new field `alloydb` is added to message `.google.cloud.geminidataanalytics.v1beta.DatasourceReferences` feat: A new field `spanner_reference` is added to message `.google.cloud.geminidataanalytics.v1beta.DatasourceReferences` feat: A new field `cloud_sql_reference` is added to message `.google.cloud.geminidataanalytics.v1beta.DatasourceReferences` feat: A new message `AlloyDbReference` is added feat: A new message `AlloyDbDatabaseReference` is added feat: A new message `SpannerReference` is added feat: A new message `SpannerDatabaseReference` is added feat: A new message `CloudSqlReference` is added feat: A new message `CloudSqlDatabaseReference` is added feat: A new field `alloy_db_reference` is added to message `.google.cloud.geminidataanalytics.v1beta.Datasource` feat: A new field `spanner_reference` is added to message `.google.cloud.geminidataanalytics.v1beta.Datasource` feat: A new field `cloud_sql_reference` is added to message `.google.cloud.geminidataanalytics.v1beta.Datasource` PiperOrigin-RevId: 842905100
1 parent dba0863 commit b32495a

File tree

4 files changed

+311
-0
lines changed

4 files changed

+311
-0
lines changed

‎google/cloud/geminidataanalytics/v1beta/BUILD.bazel‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ load("@rules_proto//proto:defs.bzl", "proto_library")
2424
proto_library(
2525
name = "geminidataanalytics_proto",
2626
srcs = [
27+
"agent_context.proto",
2728
"context.proto",
2829
"conversation.proto",
2930
"credentials.proto",

‎google/cloud/geminidataanalytics/v1beta/agent_context.proto‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
// Copyright 2025 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
syntax = "proto3";
16+
17+
package google.cloud.geminidataanalytics.v1beta;
18+
19+
import "google/api/field_behavior.proto";
20+
21+
option csharp_namespace = "Google.Cloud.GeminiDataAnalytics.V1Beta";
22+
option go_package = "cloud.google.com/go/geminidataanalytics/apiv1beta/geminidataanalyticspb;geminidataanalyticspb";
23+
option java_multiple_files = true;
24+
option java_outer_classname = "AgentContextProto";
25+
option java_package = "com.google.cloud.geminidataanalytics.v1beta";
26+
option php_namespace = "Google\\Cloud\\GeminiDataAnalytics\\V1beta";
27+
option ruby_package = "Google::Cloud::GeminiDataAnalytics::V1beta";
28+
29+
// Message representing a reference to Agent Context.
30+
message AgentContextReference {
31+
// Required. Context set ID to retrieve.
32+
string context_set_id = 1 [(google.api.field_behavior) = REQUIRED];
33+
}

‎google/cloud/geminidataanalytics/v1beta/data_chat_service.proto‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,141 @@ service DataChatService {
9797
};
9898
option (google.api.method_signature) = "parent";
9999
}
100+
101+
// Queries data from a natural language user query.
102+
rpc QueryData(QueryDataRequest) returns (QueryDataResponse) {
103+
option (google.api.http) = {
104+
post: "/v1beta/{parent=projects/*/locations/*}:queryData"
105+
body: "*"
106+
};
107+
}
108+
}
109+
110+
// Request to query data from a natural language query.
111+
message QueryDataRequest {
112+
// Required. The parent resource to generate the query for.
113+
// Format: projects/{project}/locations/{location}
114+
string parent = 1 [
115+
(google.api.field_behavior) = REQUIRED,
116+
(google.api.resource_reference) = {
117+
type: "locations.googleapis.com/Location"
118+
}
119+
];
120+
121+
// Required. The natural language query for which to generate query.
122+
// Example: "What are the top 5 best selling products this month?"
123+
string prompt = 2 [(google.api.field_behavior) = REQUIRED];
124+
125+
// Required. The context for the data query, including the data sources to
126+
// use.
127+
QueryDataContext context = 3 [(google.api.field_behavior) = REQUIRED];
128+
129+
// Optional. Options to control query generation and execution behavior.
130+
GenerationOptions generation_options = 4
131+
[(google.api.field_behavior) = OPTIONAL];
132+
}
133+
134+
// Options to control query generation, execution, and response format.
135+
message GenerationOptions {
136+
// Optional. If true, the generated query will be executed, and the result
137+
// data will be returned in the response.
138+
bool generate_query_result = 1 [(google.api.field_behavior) = OPTIONAL];
139+
140+
// Optional. If true, a natural language answer based on the query execution
141+
// result will be generated and returned in the response.
142+
bool generate_natural_language_answer = 2
143+
[(google.api.field_behavior) = OPTIONAL];
144+
145+
// Optional. If true, an explanation of the generated query will be returned
146+
// in the response.
147+
bool generate_explanation = 3 [(google.api.field_behavior) = OPTIONAL];
148+
149+
// Optional. If true (default to false), the service may return a
150+
// clarifying_question if the input query is ambiguous.
151+
bool generate_disambiguation_question = 4
152+
[(google.api.field_behavior) = OPTIONAL];
153+
}
154+
155+
// References to data sources and context to use for the query.
156+
message QueryDataContext {
157+
// Required. The datasource references to use for the query.
158+
DatasourceReferences datasource_references = 1
159+
[(google.api.field_behavior) = REQUIRED];
160+
}
161+
162+
// Response containing the generated query and related information.
163+
message QueryDataResponse {
164+
// Generated query for the given user prompt.
165+
string generated_query = 1;
166+
167+
// A natural language explanation of the generated query.
168+
// Populated if options.generate_explanation was true in the request.
169+
string intent_explanation = 2;
170+
171+
// The result of executing the query.
172+
// Populated if options.generate_query_result or
173+
// options.generate_natural_language_answer was true in the request, and
174+
// execution was successful or attempted.
175+
ExecutedQueryResult query_result = 3;
176+
177+
// A natural language answer to the query, based on the query_result.
178+
// Populated if options.generate_natural_language_answer was true in the
179+
// request and query execution was successful based in the response from
180+
// executeSql API.
181+
string natural_language_answer = 4;
182+
183+
// If ambiguity was detected in the natural language query and
184+
// options.generate_disambiguation_question was true, this field contains a
185+
// question to the user for clarification. The returned represents the
186+
// service's best effort based on the ambiguous input.
187+
repeated string disambiguation_question = 5;
188+
}
189+
190+
// The result of a query execution. The design is generic for all dialects.
191+
message ExecutedQueryResult {
192+
// Describes a single column in the result set.
193+
message Column {
194+
// The name of the column.
195+
string name = 1;
196+
197+
// The type of the column (e.g., "VARCHAR", "INT64", "TIMESTAMP").
198+
string type = 2;
199+
}
200+
201+
// Represents a single value within a row.
202+
message Value {
203+
// The cell value, represented in a string format.
204+
// Timestamps could be formatted, for example, using RFC3339Nano.
205+
// This field is used if the value is not null.
206+
string value = 1;
207+
}
208+
209+
// Represents a single row in the result set.
210+
message Row {
211+
// The values in the row, corresponding positionally to the columns.
212+
repeated Value values = 1;
213+
}
214+
215+
// The columns in the result set, in order.
216+
repeated Column columns = 1;
217+
218+
// The rows returned by the query.
219+
repeated Row rows = 2;
220+
221+
// The total number of rows in the full result set, if known.
222+
// This may be an estimate or an exact count.
223+
int64 total_row_count = 3;
224+
225+
// Set to true if the returned rows in `query_result` are a subset of the
226+
// full result. This can happen, for example, if the query execution hits a
227+
// row limit. When true, the `query_result` does not contain all
228+
// rows. To retrieve the complete result, consider using the
229+
// `generated_query` in `QueryDataResponse` and executing it in your own
230+
// environment.
231+
bool partial_result = 4;
232+
233+
// The error message if the query execution failed.
234+
string query_execution_error = 5;
100235
}
101236

102237
// Request for listing chat messages based on parent and conversation_id.

‎google/cloud/geminidataanalytics/v1beta/datasource.proto‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ syntax = "proto3";
1717
package google.cloud.geminidataanalytics.v1beta;
1818

1919
import "google/api/field_behavior.proto";
20+
import "google/cloud/geminidataanalytics/v1beta/agent_context.proto";
2021
import "google/cloud/geminidataanalytics/v1beta/credentials.proto";
2122
import "google/protobuf/struct.proto";
2223

@@ -51,6 +52,15 @@ message DatasourceReferences {
5152

5253
// References to Looker Explores.
5354
LookerExploreReferences looker = 3;
55+
56+
// Reference to an AlloyDB database.
57+
AlloyDbReference alloydb = 8;
58+
59+
// Reference to a Spanner database.
60+
SpannerReference spanner_reference = 9;
61+
62+
// Reference to a CloudSql database.
63+
CloudSqlReference cloud_sql_reference = 10;
5464
}
5565
}
5666

@@ -88,6 +98,129 @@ message StudioDatasourceReference {
8898
string datasource_id = 1 [(google.api.field_behavior) = REQUIRED];
8999
}
90100

101+
// Message representing reference to an AlloyDB database and agent context.
102+
message AlloyDbReference {
103+
// Required. Singular proto that supports specifying which database and tables
104+
// to include.
105+
AlloyDbDatabaseReference database_reference = 1
106+
[(google.api.field_behavior) = REQUIRED];
107+
108+
// Optional. Parameters for retrieving data from Agent Context.
109+
AgentContextReference agent_context_reference = 3
110+
[(google.api.field_behavior) = OPTIONAL];
111+
}
112+
113+
// Message representing a reference to a single AlloyDB database.
114+
message AlloyDbDatabaseReference {
115+
// Required. The project the instance belongs to.
116+
string project_id = 1 [(google.api.field_behavior) = REQUIRED];
117+
118+
// Required. The region of the instance.
119+
string region = 2 [(google.api.field_behavior) = REQUIRED];
120+
121+
// Required. The cluster id.
122+
string cluster_id = 3 [(google.api.field_behavior) = REQUIRED];
123+
124+
// Required. The instance id.
125+
string instance_id = 4 [(google.api.field_behavior) = REQUIRED];
126+
127+
// Required. The database id.
128+
string database_id = 5 [(google.api.field_behavior) = REQUIRED];
129+
130+
// Optional. The table ids. Denotes all tables if unset.
131+
repeated string table_ids = 6 [(google.api.field_behavior) = OPTIONAL];
132+
}
133+
134+
// Message representing reference to a Spanner database and agent context.
135+
message SpannerReference {
136+
// Required. Singular proto that supports specifying which database and tables
137+
// to include.
138+
SpannerDatabaseReference database_reference = 1
139+
[(google.api.field_behavior) = REQUIRED];
140+
141+
// Optional. Parameters for retrieving data from Agent Context.
142+
AgentContextReference agent_context_reference = 2
143+
[(google.api.field_behavior) = OPTIONAL];
144+
}
145+
146+
// Message representing a reference to a single Spanner database.
147+
message SpannerDatabaseReference {
148+
// The database engine.
149+
enum Engine {
150+
// Engine is not specified.
151+
ENGINE_UNSPECIFIED = 0;
152+
153+
// Google SQL
154+
GOOGLE_SQL = 1;
155+
156+
// PostgreSQL
157+
POSTGRESQL = 2;
158+
}
159+
160+
// Required. The engine of the Spanner instance.
161+
Engine engine = 6 [(google.api.field_behavior) = REQUIRED];
162+
163+
// Required. The project the instance belongs to.
164+
string project_id = 1 [(google.api.field_behavior) = REQUIRED];
165+
166+
// Required. The region of the instance.
167+
string region = 2 [(google.api.field_behavior) = REQUIRED];
168+
169+
// Required. The instance id.
170+
string instance_id = 3 [(google.api.field_behavior) = REQUIRED];
171+
172+
// Required. The database id.
173+
string database_id = 4 [(google.api.field_behavior) = REQUIRED];
174+
175+
// Optional. The table ids. Denotes all tables if unset.
176+
repeated string table_ids = 5 [(google.api.field_behavior) = OPTIONAL];
177+
}
178+
179+
// Message representing reference to a CloudSQL database and agent context.
180+
message CloudSqlReference {
181+
// Required. Singular proto that supports specifying which database and tables
182+
// to include.
183+
CloudSqlDatabaseReference database_reference = 1
184+
[(google.api.field_behavior) = REQUIRED];
185+
186+
// Optional. Parameters for retrieving data from Agent Context.
187+
AgentContextReference agent_context_reference = 2
188+
[(google.api.field_behavior) = OPTIONAL];
189+
}
190+
191+
// Message representing a reference to a single CloudSQL database.
192+
message CloudSqlDatabaseReference {
193+
// The database engine.
194+
enum Engine {
195+
// Engine is not specified.
196+
ENGINE_UNSPECIFIED = 0;
197+
198+
// PostgreSQL
199+
POSTGRESQL = 1;
200+
201+
// MySQL
202+
MYSQL = 2;
203+
}
204+
205+
// Required. The engine of the Cloud SQL instance.
206+
Engine engine = 1 [(google.api.field_behavior) = REQUIRED];
207+
208+
// Required. The project the instance belongs to.
209+
string project_id = 2 [(google.api.field_behavior) = REQUIRED];
210+
211+
// Required. The region of the instance.
212+
string region = 3 [(google.api.field_behavior) = REQUIRED];
213+
214+
// Required. The instance id.
215+
string instance_id = 4 [(google.api.field_behavior) = REQUIRED];
216+
217+
// Required. The database id.
218+
string database_id = 5 [(google.api.field_behavior) = REQUIRED];
219+
220+
// Optional. The table ids. Denotes all tables if unset.
221+
repeated string table_ids = 7 [(google.api.field_behavior) = OPTIONAL];
222+
}
223+
91224
// Message representing references to Looker explores.
92225
message LookerExploreReferences {
93226
// Required. References to Looker explores.
@@ -152,6 +285,15 @@ message Datasource {
152285

153286
// A reference to a Looker explore.
154287
LookerExploreReference looker_explore_reference = 4;
288+
289+
// A reference to an AlloyDB database.
290+
AlloyDbReference alloy_db_reference = 12;
291+
292+
// A reference to a Spanner database.
293+
SpannerReference spanner_reference = 13;
294+
295+
// A reference to a CloudSQL database.
296+
CloudSqlReference cloud_sql_reference = 14;
155297
}
156298

157299
// Optional. The schema of the datasource.

0 commit comments

Comments
 (0)