googleapis/google/cloud/geminidataanalytics/v1alpha/datasource.proto

// Copyright 2026 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/field_behavior.proto";
import "google/cloud/geminidataanalytics/v1alpha/agent_context.proto";
import "google/cloud/geminidataanalytics/v1alpha/credentials.proto";
import "google/protobuf/struct.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 = "DatasourceProto";
option java_package = "com.google.cloud.geminidataanalytics.v1alpha";
option php_namespace = "Google\\Cloud\\GeminiDataAnalytics\\V1alpha";
option ruby_package = "Google::Cloud::GeminiDataAnalytics::V1alpha";

// The type of filter present on a datasource, such as ALWAYS_FILTER.
enum DataFilterType {
  // The filter type was not specified.
  DATA_FILTER_TYPE_UNSPECIFIED = 0;

  // A filter that the user configures, and any queries to the Explore will
  // always apply this filter by default. Currently only used for Looker data
  // sources.
  ALWAYS_FILTER = 1;
}

// A collection of references to datasources.
message DatasourceReferences {
  // The datasources to use.
  oneof references {
    // References to BigQuery tables.
    BigQueryTableReferences bq = 1;

    // References to Looker Studio datasources.
    StudioDatasourceReferences studio = 2;

    // References to Looker Explores.
    LookerExploreReferences looker = 3;

    // Reference to an AlloyDB database. Only supported for the `QueryData`
    // method.
    AlloyDbReference alloydb = 8;

    // Reference to a Spanner database. Only supported for the `QueryData`
    // method.
    SpannerReference spanner_reference = 9;

    // Reference to a CloudSql database. Only supported for the `QueryData`
    // method.
    CloudSqlReference cloud_sql_reference = 10;
  }
}

// Message representing references to BigQuery tables and property graphs.
// At least one of `table_references` or `property_graph_references` must be
// populated.
message BigQueryTableReferences {
  // Optional. References to BigQuery tables.
  repeated BigQueryTableReference table_references = 1
      [(google.api.field_behavior) = OPTIONAL];
}

// Message representing a reference to a single BigQuery table.
message BigQueryTableReference {
  // Required. The project that the table belongs to.
  string project_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The dataset that the table belongs to.
  string dataset_id = 3 [(google.api.field_behavior) = REQUIRED];

  // Required. The table id.
  string table_id = 4 [(google.api.field_behavior) = REQUIRED];

  // Optional. The schema of the datasource.
  Schema schema = 6 [(google.api.field_behavior) = OPTIONAL];
}

// Message representing references to Looker Studio datasources.
message StudioDatasourceReferences {
  // The references to the studio datasources.
  repeated StudioDatasourceReference studio_references = 2;
}

// Message representing a reference to a single Looker Studio datasource.
message StudioDatasourceReference {
  // Required. The id of the datasource.
  string datasource_id = 1 [(google.api.field_behavior) = REQUIRED];
}

// Message representing reference to an AlloyDB database and agent context.
// Only supported for the `QueryData` method.
message AlloyDbReference {
  // Required. Singular proto that supports specifying which database and tables
  // to include.
  AlloyDbDatabaseReference database_reference = 1
      [(google.api.field_behavior) = REQUIRED];

  // Optional. Parameters for retrieving data from Agent Context.
  AgentContextReference agent_context_reference = 3
      [(google.api.field_behavior) = OPTIONAL];
}

// Message representing a reference to a single AlloyDB database.
message AlloyDbDatabaseReference {
  // Required. The project the instance belongs to.
  string project_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The region of the instance.
  string region = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The cluster id.
  string cluster_id = 3 [(google.api.field_behavior) = REQUIRED];

  // Required. The instance id.
  string instance_id = 4 [(google.api.field_behavior) = REQUIRED];

  // Required. The database id.
  string database_id = 5 [(google.api.field_behavior) = REQUIRED];

  // Optional. The table ids. Denotes all tables if unset.
  repeated string table_ids = 6 [(google.api.field_behavior) = OPTIONAL];
}

// Message representing reference to a Spanner database and agent context.
// Only supported for the `QueryData` method.
message SpannerReference {
  // Required. Singular proto that supports specifying which database and tables
  // to include.
  SpannerDatabaseReference database_reference = 1
      [(google.api.field_behavior) = REQUIRED];

  // Optional. Parameters for retrieving data from Agent Context.
  AgentContextReference agent_context_reference = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// Message representing a reference to a single Spanner database.
message SpannerDatabaseReference {
  // The database engine.
  enum Engine {
    // Engine is not specified.
    ENGINE_UNSPECIFIED = 0;

    // Google SQL
    GOOGLE_SQL = 1;

    // PostgreSQL
    POSTGRESQL = 2;
  }

  // Required. The engine of the Spanner instance.
  Engine engine = 6 [(google.api.field_behavior) = REQUIRED];

  // Required. The project the instance belongs to.
  string project_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The region of the instance.
  string region = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The instance id.
  string instance_id = 3 [(google.api.field_behavior) = REQUIRED];

  // Required. The database id.
  string database_id = 4 [(google.api.field_behavior) = REQUIRED];

  // Optional. The table ids. Denotes all tables if unset.
  repeated string table_ids = 5 [(google.api.field_behavior) = OPTIONAL];
}

// Message representing reference to a CloudSQL database and agent context.
// Only supported for the `QueryData` method.
message CloudSqlReference {
  // Required. Singular proto that supports specifying which database and tables
  // to include.
  CloudSqlDatabaseReference database_reference = 1
      [(google.api.field_behavior) = REQUIRED];

  // Optional. Parameters for retrieving data from Agent Context.
  AgentContextReference agent_context_reference = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// Message representing a reference to a single CloudSQL database.
message CloudSqlDatabaseReference {
  // The database engine.
  enum Engine {
    // Engine is not specified.
    ENGINE_UNSPECIFIED = 0;

    // PostgreSQL
    POSTGRESQL = 1;

    // MySQL
    MYSQL = 2;
  }

  // Required. The engine of the Cloud SQL instance.
  Engine engine = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The project the instance belongs to.
  string project_id = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The region of the instance.
  string region = 3 [(google.api.field_behavior) = REQUIRED];

  // Required. The instance id.
  string instance_id = 4 [(google.api.field_behavior) = REQUIRED];

  // Required. The database id.
  string database_id = 5 [(google.api.field_behavior) = REQUIRED];

  // Optional. The table ids. Denotes all tables if unset.
  repeated string table_ids = 7 [(google.api.field_behavior) = OPTIONAL];
}

// Message representing references to Looker explores.
message LookerExploreReferences {
  // Required. References to Looker explores.
  repeated LookerExploreReference explore_references = 1
      [(google.api.field_behavior) = REQUIRED];

  // Optional. The credentials to use when calling the Looker API.
  //
  // Currently supports both OAuth token and API key-based credentials, as
  // described in
  // [Authentication with an
  // SDK](https://cloud.google.com/looker/docs/api-auth#authentication_with_an_sdk).
  Credentials credentials = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Message representing a reference to a single Looker explore.
message LookerExploreReference {
  // The instance of the Looker explore.
  oneof instance {
    // Required. The base url of the Looker instance.
    string looker_instance_uri = 9;

    // Private Looker instance info.
    PrivateLookerInstanceInfo private_looker_instance_info = 10;
  }

  // Required. Looker model, as outlined in
  // [Major LookML
  // structures](https://cloud.google.com/looker/docs/lookml-terms-and-concepts#major_lookml_structures).
  // Name of the LookML model.
  string lookml_model = 4 [(google.api.field_behavior) = REQUIRED];

  // Required. Looker Explore, as outlined in
  // [Major LookML
  // structures](https://cloud.google.com/looker/docs/lookml-terms-and-concepts#major_lookml_structures).
  // Name of the LookML Explore.
  string explore = 5 [(google.api.field_behavior) = REQUIRED];

  // Optional. The schema of the datasource.
  Schema schema = 8 [(google.api.field_behavior) = OPTIONAL];
}

// Message representing a private Looker instance info required if the Looker
// instance is behind a private network.
message PrivateLookerInstanceInfo {
  // The Looker instance id.
  string looker_instance_id = 1;

  // The service directory name of the Looker instance.
  string service_directory_name = 2;
}

// A datasource that can be used to answer questions.
message Datasource {
  // The reference to the datasource.
  oneof reference {
    // A reference to a BigQuery table.
    BigQueryTableReference bigquery_table_reference = 1;

    // A reference to a Looker Studio datasource.
    string studio_datasource_id = 2;

    // A reference to a Looker explore.
    LookerExploreReference looker_explore_reference = 4;

    // A reference to an AlloyDB database.
    AlloyDbReference alloy_db_reference = 12;

    // A reference to a Spanner database.
    SpannerReference spanner_reference = 13;

    // A reference to a CloudSQL database.
    CloudSqlReference cloud_sql_reference = 14;
  }

  // Optional. The schema of the datasource.
  Schema schema = 7 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A struct representation of the schema.
  // This is populated for datasources with schemas that cannot be
  // fully represented by the strongly-typed `schema` field.
  //
  // For Looker datasources, this maps to the LookmlModelExplore type:
  // https://cloud.google.com/looker/docs/reference/looker-api/latest/types/LookmlModelExplore
  google.protobuf.Struct struct_schema = 10
      [(google.api.field_behavior) = OPTIONAL];
}

// The schema of a Datasource or QueryResult instance.
message Schema {
  // Optional. The fields in the schema.
  repeated Field fields = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A textual description of the table's content and purpose.
  // For example: "Contains information about customer orders in our e-commerce
  // store." Currently only used for BigQuery data sources.
  string description = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A list of alternative names or synonyms that can be used to refer
  // to the table. For example: ["sales", "orders", "purchases"]. Currently only
  // used for BigQuery data sources.
  repeated string synonyms = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A list of tags or keywords associated with the table, used for
  // categorization. For example: ["transaction", "revenue", "customer_data"].
  // Currently only used for BigQuery data sources.
  repeated string tags = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Table display_name (same as label in
  // cloud/data_analytics/anarres/data/looker/proto/model_explore.proto), not
  // required, currently only Looker has this field.
  string display_name = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The filters on the datasource's underlying data. Currently only
  // used for Looker data sources.
  repeated DataFilter filters = 6 [(google.api.field_behavior) = OPTIONAL];
}

// A field in a schema.
message Field {
  // Optional. The name of the field.
  string name = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The type of the field.
  string type = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A brief description of the field.
  string description = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The mode of the field (e.g., NULLABLE, REPEATED).
  string mode = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A list of alternative names or synonyms that can be used to refer
  // to this field. For example: ["id", "customerid", "cust_id"]. Currently only
  // used for BigQuery data sources.
  repeated string synonyms = 6 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A list of tags or keywords associated with the field, used for
  // categorization. For example: ["identifier", "customer", "pii"]. Currently
  // only used for BigQuery data sources.
  repeated string tags = 7 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Field display_name (same as label in
  string display_name = 8 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Recursive property for nested schema structures.
  repeated Field subfields = 9 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Field category, not required, currently only useful for Looker.
  // We are using a string to avoid depending on an external package and keep
  // this package self-contained.
  string category = 10 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Looker only. Value format of the field.
  // Ref:
  // https://cloud.google.com/looker/docs/reference/param-field-value-format
  string value_format = 11 [(google.api.field_behavior) = OPTIONAL];
}

// A filter on a datasource's underlying data. Filter syntax documentation:
// https://cloud.google.com/looker/docs/filter-expressions
message DataFilter {
  // Optional. The field to filter on. For example: ["event_date",
  // "customer_id", "product_category"]
  string field = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The default value used for this filter if the filter is not
  // overridden in a query. For example: ["after 2024-01-01", "123", "-fashion"]
  string value = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The type of filter present on a datasource, such as
  // ALWAYS_FILTER.
  DataFilterType type = 3 [(google.api.field_behavior) = OPTIONAL];
}