// 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.v1beta;

import "google/api/field_behavior.proto";
import "google/cloud/geminidataanalytics/v1beta/credentials.proto";

option csharp_namespace = "Google.Cloud.GeminiDataAnalytics.V1Beta";
option go_package = "cloud.google.com/go/geminidataanalytics/apiv1beta/geminidataanalyticspb;geminidataanalyticspb";
option java_multiple_files = true;
option java_outer_classname = "DatasourceProto";
option java_package = "com.google.cloud.geminidataanalytics.v1beta";
option php_namespace = "Google\\Cloud\\GeminiDataAnalytics\\V1beta";
option ruby_package = "Google::Cloud::GeminiDataAnalytics::V1beta";

// 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;
  }
}

// Message representing references to BigQuery tables.
message BigQueryTableReferences {
  // Required. References to BigQuery tables.
  repeated BigQueryTableReference table_references = 1
      [(google.api.field_behavior) = REQUIRED];
}

// 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 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;
  }

  // Optional. The schema of the datasource.
  Schema schema = 7 [(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."
  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"]
  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"]
  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"]
  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"]
  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];
}