// Copyright 2025 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.cloud.geminidataanalytics.v1alpha;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/geminidataanalytics/v1alpha/datasource.proto";

option csharp_namespace = "Google.Cloud.GeminiDataAnalytics.V1Alpha";
option go_package = "cloud.google.com/go/geminidataanalytics/apiv1alpha/geminidataanalyticspb;geminidataanalyticspb";
option java_multiple_files = true;
option java_outer_classname = "ContextRetrievalServiceProto";
option java_package = "com.google.cloud.geminidataanalytics.v1alpha";
option php_namespace = "Google\\Cloud\\GeminiDataAnalytics\\V1alpha";
option ruby_package = "Google::Cloud::GeminiDataAnalytics::V1alpha";

// Service to ask a natural language question with a provided project,
// returns BigQuery tables that are relevant to the question within the project
// scope that is accessible to the user, along with contextual data including
// table schema information as well as sample values.
service ContextRetrievalService {
  option (google.api.default_host) = "geminidataanalytics.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Retrieves BigQuery table contextual data for provided table references.
  // Contextual data includes table schema information as well as sample
  // values.
  rpc RetrieveBigQueryTableContexts(RetrieveBigQueryTableContextsRequest)
      returns (RetrieveBigQueryTableContextsResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{parent=projects/*/locations/*}/retrieval:retrieveBigQueryTableContexts"
      body: "*"
    };
  }

  // Retrieves BigQuery table contextual data from recently accessed tables.
  // Contextual data includes table schema information as well as sample
  // values.
  rpc RetrieveBigQueryTableContextsFromRecentTables(
      RetrieveBigQueryTableContextsFromRecentTablesRequest)
      returns (RetrieveBigQueryTableContextsFromRecentTablesResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{parent=projects/*/locations/*}/retrieval:retrieveBigQueryTableContextsFromRecentTables"
      body: "*"
    };
  }

  // Retrieves BigQuery table schema with suggested table and column
  // descriptions.
  rpc RetrieveBigQueryTableSuggestedDescriptions(
      RetrieveBigQueryTableSuggestedDescriptionsRequest)
      returns (RetrieveBigQueryTableSuggestedDescriptionsResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{parent=projects/*/locations/*}/retrieval:retrieveBigQueryTableSuggestedDescriptions"
      body: "*"
    };
  }

  // Retrieves BigQuery table schema with suggested NL-SQL examples.
  rpc RetrieveBigQueryTableSuggestedExamples(
      RetrieveBigQueryTableSuggestedExamplesRequest)
      returns (RetrieveBigQueryTableSuggestedExamplesResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{parent=projects/*/locations/*}/retrieval:retrieveBigQueryTableSuggestedExamples"
      body: "*"
    };
  }

  // Retrieves BigQuery table references from recently accessed tables.
  rpc RetrieveBigQueryRecentRelevantTables(
      RetrieveBigQueryRecentRelevantTablesRequest)
      returns (RetrieveBigQueryRecentRelevantTablesResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{parent=projects/*/locations/*}/retrieval:retrieveBigQueryRecentRelevantTables"
      body: "*"
    };
  }
}

// Request for retrieving BigQuery table contextual data via direct lookup.
message RetrieveBigQueryTableContextsRequest {
  // Required. Parent value for RetrieveBigQueryTableContextRequest.
  // Pattern: `projects/{project}/locations/{location}`
  // For location, use "global" for now. Regional location value will be
  // supported in the future.
  string parent = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. User query in natural language.
  string query = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A list of direct lookup parameters.
  repeated DirectLookup direct_lookups = 3
      [(google.api.field_behavior) = OPTIONAL];
}

// Response for retrieving BigQuery table contextual data via direct lookup.
message RetrieveBigQueryTableContextsResponse {
  // List of retrieved candidates with their bundled metadata.
  repeated TableCandidate table_candidates = 1;
}

// Request for retrieving BigQuery table contextual data from recently accessed
// tables. Response is sorted by semantic similarity to the query.
message RetrieveBigQueryTableContextsFromRecentTablesRequest {
  // Required. Parent value for
  // RetrieveBigQueryTableContextsFromRecentTablesRequest. Pattern:
  // `projects/{project}/locations/{location}` For location, use "global" for
  // now. Regional location value will be supported in the future.
  string parent = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. User query in natural language.
  string query = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Response for retrieving BigQuery table contextual data from recently
// accessed tables. Response is sorted by semantic similarity to the query.
message RetrieveBigQueryTableContextsFromRecentTablesResponse {
  // List of retrieved candidates with their bundled metadata.
  repeated TableCandidate table_candidates = 1;
}

// Request for retrieving BigQuery table schema with suggested table and column
// descriptions. Columns are sorted by default BigQuery table schema order.
message RetrieveBigQueryTableSuggestedDescriptionsRequest {
  // Required. Parent value for
  // RetrieveBigQueryTableSuggestedDescriptionsRequest. Pattern:
  // `projects/{project}/locations/{location}` For location, use "global" for
  // now. Regional location value will be supported in the future.
  string parent = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. A list of direct lookup parameters.
  repeated DirectLookup direct_lookup = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// Response for retrieving BigQuery table schema with suggested table and column
// descriptions. Columns are sorted by default BigQuery table schema order.
message RetrieveBigQueryTableSuggestedDescriptionsResponse {
  // List of retrieved candidates with their bundled metadata.
  repeated TableCandidate table_candidates = 1;
}

// Request for retrieving BigQuery table schema with suggested NL-SQL examples.
message RetrieveBigQueryTableSuggestedExamplesRequest {
  // Required. Parent value for RetrieveBigQueryTableSuggestedExamplesRequest.
  // Pattern: `projects/{project}/locations/{location}`
  // For location, use "global" for now. Regional location value will be
  // supported in the future.
  string parent = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. A list of direct lookup parameters.
  repeated DirectLookup direct_lookup = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// Request for retrieving BigQuery table schema with suggested NL-SQL examples.
message RetrieveBigQueryTableSuggestedExamplesResponse {
  // A suggested BigQuery NL-SQL example for the given table.
  message ExampleSuggestion {
    // The natural language query.
    string nl_query = 1;

    // The SQL answer to the query.
    string sql = 2;

    // The linked table resources for the suggested example.
    repeated string linked_bigquery_tables = 3;
  }

  // List of suggested examples.
  repeated ExampleSuggestion example_suggestions = 2;
}

// Request for retrieving BigQuery table references from recently accessed
// tables. Response is sorted by semantic similarity to the query.
message RetrieveBigQueryRecentRelevantTablesRequest {
  // Required. Parent value for RetrieveBigQueryRecentTablesRequest.
  // Pattern: `projects/{project}/locations/{location}`
  // For location, use "global" for now. Regional location value will be
  // supported in the future.
  string parent = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. User query in natural language.
  string query = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Response for retrieving BigQuery table references from recently accessed
// tables. Response is sorted by semantic similarity to the query.
message RetrieveBigQueryRecentRelevantTablesResponse {
  // List of retrieved table ids.
  // The unique identifier for the table. Names are case-sensitive.
  // Example for BigQuery Table: `{project}.{dataset}.{table}`.
  repeated string table_ids = 1;
}

// Direct lookup parameters.
message DirectLookup {
  // Optional. Table reference that server invokes a direct lookup of table
  // metadata upon. The returned candidate will be TableMetadataResult.
  BigQueryTableReference big_query_table_reference = 1
      [(google.api.field_behavior) = OPTIONAL];
}

// A retrieved BigQuery table candidate.
message TableCandidate {
  // A suggested description for a field.
  message FieldSuggestion {
    // The field name.
    string field = 1;

    // The suggested description, if descriptions were requested.
    string suggested_description = 2;

    // Suggestions for nested fields.
    repeated FieldSuggestion nested = 3;
  }

  // The fully qualified resource name of the candidate in its source system,
  // if applicable. E.g. for BigQuery tables, the format is:
  // `bigquery.googleapis.com/projects/{project_id}/datasets/{dataset_id}/tables/{table_id}`.
  string linked_resource = 1;

  // In-context-learning string. For example, could be in DDL format.
  string icl_string = 2;

  // Suggested field descriptions for this candidate, if requested.
  repeated FieldSuggestion field_suggestions = 3;
}