Skip to content

Commit 9ced981

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: Initial commit for GeminiDataAnalytics API service (v1beta version)
PiperOrigin-RevId: 777880565
1 parent f37bfb8 commit 9ced981

12 files changed

Lines changed: 2397 additions & 0 deletions

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

Lines changed: 415 additions & 0 deletions
Large diffs are not rendered by default.

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

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
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+
import "google/cloud/geminidataanalytics/v1beta/datasource.proto";
21+
22+
option csharp_namespace = "Google.Cloud.GeminiDataAnalytics.V1Beta";
23+
option go_package = "cloud.google.com/go/geminidataanalytics/apiv1beta/geminidataanalyticspb;geminidataanalyticspb";
24+
option java_multiple_files = true;
25+
option java_outer_classname = "ContextProto";
26+
option java_package = "com.google.cloud.geminidataanalytics.v1beta";
27+
option php_namespace = "Google\\Cloud\\GeminiDataAnalytics\\V1beta";
28+
option ruby_package = "Google::Cloud::GeminiDataAnalytics::V1beta";
29+
30+
// A collection of context to apply to this conversation
31+
message Context {
32+
// Optional. The basic entry point for data owners creating domain knowledge
33+
// for Agent.
34+
//
35+
// Why: Business jargon (e.g., YTD revenue is calculated as…, Retirement Age
36+
// is 65 in the USA, etc) and system instructions (e.g., answer like a Pirate)
37+
// can help the model understand the business context around a user question.
38+
string system_instruction = 1 [(google.api.field_behavior) = OPTIONAL];
39+
40+
// Required. Datasources available for answering the question.
41+
DatasourceReferences datasource_references = 7
42+
[(google.api.field_behavior) = REQUIRED];
43+
44+
// Optional. Additional options for the conversation.
45+
ConversationOptions options = 3 [(google.api.field_behavior) = OPTIONAL];
46+
}
47+
48+
// Options for the conversation.
49+
message ConversationOptions {
50+
// Optional. Options for chart generation.
51+
ChartOptions chart = 1 [(google.api.field_behavior) = OPTIONAL];
52+
53+
// Optional. Options for analysis.
54+
AnalysisOptions analysis = 2 [(google.api.field_behavior) = OPTIONAL];
55+
}
56+
57+
// Options for chart generation.
58+
message ChartOptions {
59+
// Options for rendering images of generated charts.
60+
message ImageOptions {
61+
// No image.
62+
message NoImage {}
63+
64+
// SVG options.
65+
message SvgOptions {}
66+
67+
// The kind of image to render.
68+
oneof kind {
69+
// No image.
70+
NoImage no_image = 1;
71+
72+
// SVG format.
73+
SvgOptions svg = 2;
74+
}
75+
}
76+
77+
// Optional. When specified, the agent will render generated charts using the
78+
// provided format. Defaults to no image.
79+
ImageOptions image = 1 [(google.api.field_behavior) = OPTIONAL];
80+
}
81+
82+
// Options for analysis.
83+
message AnalysisOptions {
84+
// Options for Python analysis.
85+
message Python {
86+
// Optional. Whether to enable Python analysis.
87+
// Defaults to false.
88+
bool enabled = 1 [(google.api.field_behavior) = OPTIONAL];
89+
}
90+
91+
// Optional. Options for Python analysis.
92+
Python python = 1 [(google.api.field_behavior) = OPTIONAL];
93+
}

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

Lines changed: 296 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,296 @@
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/annotations.proto";
20+
import "google/api/client.proto";
21+
import "google/api/field_behavior.proto";
22+
import "google/api/resource.proto";
23+
import "google/cloud/geminidataanalytics/v1beta/datasource.proto";
24+
25+
option csharp_namespace = "Google.Cloud.GeminiDataAnalytics.V1Beta";
26+
option go_package = "cloud.google.com/go/geminidataanalytics/apiv1beta/geminidataanalyticspb;geminidataanalyticspb";
27+
option java_multiple_files = true;
28+
option java_outer_classname = "ContextRetrievalServiceProto";
29+
option java_package = "com.google.cloud.geminidataanalytics.v1beta";
30+
option php_namespace = "Google\\Cloud\\GeminiDataAnalytics\\V1beta";
31+
option ruby_package = "Google::Cloud::GeminiDataAnalytics::V1beta";
32+
33+
// Service to ask a natural language question with a provided project,
34+
// returns BigQuery tables that are relevant to the question within the project
35+
// scope that is accessible to the user, along with contextual data including
36+
// table schema information as well as sample values.
37+
service ContextRetrievalService {
38+
option (google.api.default_host) = "geminidataanalytics.googleapis.com";
39+
option (google.api.oauth_scopes) =
40+
"https://www.googleapis.com/auth/cloud-platform";
41+
42+
// Retrieves BigQuery table contextual data for provided table references.
43+
// Contextual data includes table schema information as well as sample
44+
// values.
45+
rpc RetrieveBigQueryTableContext(RetrieveBigQueryTableContextRequest)
46+
returns (RetrieveBigQueryTableContextResponse) {
47+
option (google.api.http) = {
48+
post: "/v1beta/{parent=projects/*/locations/*}:retrieveBigQueryTableContext"
49+
body: "*"
50+
};
51+
}
52+
53+
// Retrieves BigQuery table contextual data for provided table references.
54+
// Contextual data includes table schema information as well as sample
55+
// values.
56+
rpc RetrieveBigQueryTableContexts(RetrieveBigQueryTableContextsRequest)
57+
returns (RetrieveBigQueryTableContextsResponse) {
58+
option (google.api.http) = {
59+
post: "/v1beta/{parent=projects/*/locations/*}/retrieval:retrieveBigQueryTableContexts"
60+
body: "*"
61+
};
62+
}
63+
64+
// Retrieves BigQuery table contextual data from recently accessed tables.
65+
// Contextual data includes table schema information as well as sample
66+
// values.
67+
rpc RetrieveBigQueryTableContextsFromRecentTables(
68+
RetrieveBigQueryTableContextsFromRecentTablesRequest)
69+
returns (RetrieveBigQueryTableContextsFromRecentTablesResponse) {
70+
option (google.api.http) = {
71+
post: "/v1beta/{parent=projects/*/locations/*}/retrieval:retrieveBigQueryTableContextsFromRecentTables"
72+
body: "*"
73+
};
74+
}
75+
76+
// Retrieves BigQuery table schema with suggested table and column
77+
// descriptions.
78+
rpc RetrieveBigQueryTableSuggestedDescriptions(
79+
RetrieveBigQueryTableSuggestedDescriptionsRequest)
80+
returns (RetrieveBigQueryTableSuggestedDescriptionsResponse) {
81+
option (google.api.http) = {
82+
post: "/v1beta/{parent=projects/*/locations/*}/retrieval:retrieveBigQueryTableSuggestedDescriptions"
83+
body: "*"
84+
};
85+
}
86+
87+
// Retrieves BigQuery table schema with suggested NL-SQL examples.
88+
rpc RetrieveBigQueryTableSuggestedExamples(
89+
RetrieveBigQueryTableSuggestedExamplesRequest)
90+
returns (RetrieveBigQueryTableSuggestedExamplesResponse) {
91+
option (google.api.http) = {
92+
post: "/v1beta/{parent=projects/*/locations/*}/retrieval:retrieveBigQueryTableSuggestedExamples"
93+
body: "*"
94+
};
95+
}
96+
97+
// Retrieves BigQuery table references from recently accessed tables.
98+
rpc RetrieveBigQueryRecentRelevantTables(
99+
RetrieveBigQueryRecentRelevantTablesRequest)
100+
returns (RetrieveBigQueryRecentRelevantTablesResponse) {
101+
option (google.api.http) = {
102+
post: "/v1beta/{parent=projects/*/locations/*}/retrieval:retrieveBigQueryRecentRelevantTables"
103+
body: "*"
104+
};
105+
}
106+
}
107+
108+
// Request for retrieving BigQuery table contextual data via direct lookup.
109+
message RetrieveBigQueryTableContextRequest {
110+
// Required.
111+
string project = 5
112+
[deprecated = true, (google.api.field_behavior) = REQUIRED];
113+
114+
// Required. Parent value for RetrieveBigQueryTableContextRequest.
115+
// Pattern: `projects/{project}/locations/{location}`
116+
// For location, use "global" for now. Regional location value will be
117+
// supported in the future.
118+
string parent = 6 [(google.api.field_behavior) = REQUIRED];
119+
120+
// Optional. User query in natural language.
121+
string query = 2 [(google.api.field_behavior) = OPTIONAL];
122+
123+
// Optional. A list of direct lookup parameters.
124+
repeated DirectLookup direct_lookup = 3
125+
[(google.api.field_behavior) = OPTIONAL];
126+
}
127+
128+
// Response for retrieving BigQuery table contextual data via direct lookup.
129+
message RetrieveBigQueryTableContextResponse {
130+
// A retrieved candidate.
131+
message Candidate {
132+
// The fully qualified resource name of the candidate in its source system,
133+
// if applicable. E.g. for BigQuery tables, the format is:
134+
// `bigquery.googleapis.com/projects/{project_id}/datasets/{dataset_id}/tables/{table_id}`
135+
string linked_resource = 1;
136+
137+
// Content in string format.
138+
string content = 2;
139+
}
140+
141+
// List of retrieved candidates with their bundled metadata.
142+
repeated Candidate candidates = 1 [deprecated = true];
143+
144+
// List of retrieved candidates with their bundled metadata.
145+
repeated TableCandidate table_candidates = 2;
146+
}
147+
148+
// Request for retrieving BigQuery table contextual data via direct lookup.
149+
message RetrieveBigQueryTableContextsRequest {
150+
// Required. Parent value for RetrieveBigQueryTableContextRequest.
151+
// Pattern: `projects/{project}/locations/{location}`
152+
// For location, use "global" for now. Regional location value will be
153+
// supported in the future.
154+
string parent = 1 [(google.api.field_behavior) = REQUIRED];
155+
156+
// Optional. User query in natural language.
157+
string query = 2 [(google.api.field_behavior) = OPTIONAL];
158+
159+
// Optional. A list of direct lookup parameters.
160+
repeated DirectLookup direct_lookups = 3
161+
[(google.api.field_behavior) = OPTIONAL];
162+
}
163+
164+
// Response for retrieving BigQuery table contextual data via direct lookup.
165+
message RetrieveBigQueryTableContextsResponse {
166+
// List of retrieved candidates with their bundled metadata.
167+
repeated TableCandidate table_candidates = 1;
168+
}
169+
170+
// Request for retrieving BigQuery table contextual data from recently accessed
171+
// tables. Response is sorted by semantic similarity to the query.
172+
message RetrieveBigQueryTableContextsFromRecentTablesRequest {
173+
// Required. Parent value for
174+
// RetrieveBigQueryTableContextsFromRecentTablesRequest. Pattern:
175+
// `projects/{project}/locations/{location}` For location, use "global" for
176+
// now. Regional location value will be supported in the future.
177+
string parent = 1 [(google.api.field_behavior) = REQUIRED];
178+
179+
// Optional. User query in natural language.
180+
string query = 2 [(google.api.field_behavior) = OPTIONAL];
181+
}
182+
183+
// Response for retrieving BigQuery table contextual data from recently
184+
// accessed tables. Response is sorted by semantic similarity to the query.
185+
message RetrieveBigQueryTableContextsFromRecentTablesResponse {
186+
// List of retrieved candidates with their bundled metadata.
187+
repeated TableCandidate table_candidates = 1;
188+
}
189+
190+
// Request for retrieving BigQuery table schema with suggested table and column
191+
// descriptions. Columns are sorted by default BigQuery table schema order.
192+
message RetrieveBigQueryTableSuggestedDescriptionsRequest {
193+
// Required. Parent value for
194+
// RetrieveBigQueryTableSuggestedDescriptionsRequest. Pattern:
195+
// `projects/{project}/locations/{location}` For location, use "global" for
196+
// now. Regional location value will be supported in the future.
197+
string parent = 1 [(google.api.field_behavior) = REQUIRED];
198+
199+
// Optional. A list of direct lookup parameters.
200+
repeated DirectLookup direct_lookup = 2
201+
[(google.api.field_behavior) = OPTIONAL];
202+
}
203+
204+
// Response for retrieving BigQuery table schema with suggested table and column
205+
// descriptions. Columns are sorted by default BigQuery table schema order.
206+
message RetrieveBigQueryTableSuggestedDescriptionsResponse {
207+
// List of retrieved candidates with their bundled metadata.
208+
repeated TableCandidate table_candidates = 1;
209+
}
210+
211+
// Request for retrieving BigQuery table schema with suggested NL-SQL examples.
212+
message RetrieveBigQueryTableSuggestedExamplesRequest {
213+
// Required. Parent value for RetrieveBigQueryTableSuggestedExamplesRequest.
214+
// Pattern: `projects/{project}/locations/{location}`
215+
// For location, use "global" for now. Regional location value will be
216+
// supported in the future.
217+
string parent = 1 [(google.api.field_behavior) = REQUIRED];
218+
219+
// Optional. A list of direct lookup parameters.
220+
repeated DirectLookup direct_lookup = 2
221+
[(google.api.field_behavior) = OPTIONAL];
222+
}
223+
224+
// Request for retrieving BigQuery table schema with suggested NL-SQL examples.
225+
message RetrieveBigQueryTableSuggestedExamplesResponse {
226+
// A suggested BigQuery NL-SQL example for the given table.
227+
message ExampleSuggestion {
228+
// The natural language query.
229+
string nl_query = 1;
230+
231+
// The SQL answer to the query.
232+
string sql = 2;
233+
234+
// The linked table resources for the suggested example.
235+
repeated string linked_bigquery_tables = 3;
236+
}
237+
238+
// List of suggested examples.
239+
repeated ExampleSuggestion example_suggestions = 2;
240+
}
241+
242+
// Request for retrieving BigQuery table references from recently accessed
243+
// tables. Response is sorted by semantic similarity to the query.
244+
message RetrieveBigQueryRecentRelevantTablesRequest {
245+
// Required. Parent value for RetrieveBigQueryRecentTablesRequest.
246+
// Pattern: `projects/{project}/locations/{location}`
247+
// For location, use "global" for now. Regional location value will be
248+
// supported in the future.
249+
string parent = 1 [(google.api.field_behavior) = REQUIRED];
250+
251+
// Optional. User query in natural language.
252+
string query = 2 [(google.api.field_behavior) = OPTIONAL];
253+
}
254+
255+
// Response for retrieving BigQuery table references from recently accessed
256+
// tables. Response is sorted by semantic similarity to the query.
257+
message RetrieveBigQueryRecentRelevantTablesResponse {
258+
// List of retrieved table ids.
259+
// The unique identifier for the table. Names are case-sensitive.
260+
// Example for BigQuery Table: `{project}.{dataset}.{table}`.
261+
repeated string table_ids = 1;
262+
}
263+
264+
// Direct lookup parameters.
265+
message DirectLookup {
266+
// Optional. Table reference that server invokes a direct lookup of table
267+
// metadata upon. The returned candidate will be TableMetadataResult.
268+
BigQueryTableReference big_query_table_reference = 1
269+
[(google.api.field_behavior) = OPTIONAL];
270+
}
271+
272+
// A retrieved BigQuery table candidate.
273+
message TableCandidate {
274+
// A suggested description for a field.
275+
message FieldSuggestion {
276+
// The field name.
277+
string field = 1;
278+
279+
// The suggested description, if descriptions were requested.
280+
string suggested_description = 2;
281+
282+
// Suggestions for nested fields.
283+
repeated FieldSuggestion nested = 3;
284+
}
285+
286+
// The fully qualified resource name of the candidate in its source system,
287+
// if applicable. E.g. for BigQuery tables, the format is:
288+
// `bigquery.googleapis.com/projects/{project_id}/datasets/{dataset_id}/tables/{table_id}`.
289+
string linked_resource = 1;
290+
291+
// In-context-learning string. For example, could be in DDL format.
292+
string icl_string = 2;
293+
294+
// Suggested field descriptions for this candidate, if requested.
295+
repeated FieldSuggestion field_suggestions = 3;
296+
}

0 commit comments

Comments
 (0)