/*
 * Copyright (2024) The Delta Lake Project Authors.
 *
 * 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 delta.connect;

import "delta/connect/base.proto";
import "spark/connect/expressions.proto";
import "spark/connect/relations.proto";
import "spark/connect/types.proto";

option java_multiple_files = true;
option java_package = "io.delta.connect.proto";

// Message to hold all relation extensions in Delta Connect.
message DeltaRelation {
  oneof relation_type {
    Scan scan = 1;
    DescribeHistory describe_history = 2;
    DescribeDetail describe_detail = 3;
    ConvertToDelta convert_to_delta = 4;
    RestoreTable restore_table = 5;
    IsDeltaTable is_delta_table = 6;
    DeleteFromTable delete_from_table = 7;
    UpdateTable update_table = 8;
    MergeIntoTable merge_into_table = 9;
    OptimizeTable optimize_table = 10;    
  }
}

// Relation that reads from a Delta table.
message Scan {
  // (Required) The Delta table to scan.
  DeltaTable table = 1;
}

// Relation containing information of the latest commits on a Delta table.
// The information is in reverse chronological order.
message DescribeHistory {
  // (Required) The Delta table to read the history of.
  DeltaTable table = 1;
}

// Relation containing the details of a Delta table such as the format, name, and size.
message DescribeDetail {
  // (Required) The Delta table to describe the details of.
  DeltaTable table = 1;
}

// Command that turns a Parquet table into a Delta table.
//
// This needs to be a Relation as it returns the identifier of the resulting table.
// We cannot simply reuse the input identifier, as it could be a path-based identifier,
// and in that case we need to replace "parquet.`...`" with "delta.`...`".
message ConvertToDelta {
  // (Required) Parquet table identifier formatted as "parquet.`path`"
  string identifier = 1;

  // (Optional) Partitioning schema of the input table
  oneof partition_schema {
    // Hive DDL formatted string
    string partition_schema_string = 2;
    // Struct with names and types of partitioning columns
    spark.connect.DataType partition_schema_struct = 3;
  }
}

// Command that restores the DeltaTable to an older version of the table specified by either a
// version number or a timestamp.
//
// Needs to be a Relation, as it returns a row containing the execution metrics.
message RestoreTable {
  // (Required) The Delta table to restore to an earlier version.
  DeltaTable table = 1;

  // (Required) Version to restore to.
  oneof version_or_timestamp {
    // The version number to restore to.
    int64 version = 2;
    // The timestamp to restore to.
    string timestamp = 3;
  }
}

// Relation containing a single row containing a single boolean that indicates whether the provided
// path contains a Delta table.
message IsDeltaTable {
  // (Required) The path to check.
  string path = 1;
}

// Command that deletes data from the target table that matches the given condition.
//
// Needs to be a Relation, as it returns a row containing the execution metrics.
message DeleteFromTable {
  // (Required) Target table to delete data from. Must either be a DeltaRelation containing a Scan
  // or a SubqueryAlias with a DeltaRelation containing a Scan as its input.
  spark.connect.Relation target = 1;

  // (Optional) Expression returning a boolean.
  spark.connect.Expression condition = 2;
}

// Command that updates data in the target table using the given assignments for rows that matches
// the given condition.
//
// Needs to be a Relation, as it returns a row containing the execution metrics.
message UpdateTable {
  // (Required) Target table to delete data from. Must either be a DeltaRelation containing a Scan
  // or a SubqueryAlias with a DeltaRelation containing a Scan as its input.
  spark.connect.Relation target = 1;

  // (Optional) Condition that determines which rows must be updated.
  // Must be an expression returning a boolean.
  spark.connect.Expression condition = 2;

  // (Optional) Set of assignments to apply to the rows matching the condition.
  repeated Assignment assignments = 3;
}

// Command that merges a source query/table into a Delta table,
//
// Needs to be a Relation, as it returns a row containing the execution metrics.
message MergeIntoTable {
  // (Required) Target table to merge into.
  spark.connect.Relation target = 1;

  // (Required) Source data to merge from.
  spark.connect.Relation source = 2;

  // (Required) Condition for a source row to match with a target row.
  spark.connect.Expression condition = 3;

  // (Optional) Actions to apply when a source row matches a target row.
  repeated Action matched_actions = 4;

  // (Optional) Actions to apply when a source row does not match a target row.
  repeated Action not_matched_actions = 5;

  // (Optional) Actions to apply when a target row does not match a source row.
  repeated Action not_matched_by_source_actions = 6;

  // (Optional) Whether Schema Evolution is enabled for this command.
  optional bool with_schema_evolution = 7;

  // Rule that specifies how the target table should be modified.
  message Action {
    // (Optional) Condition for the action to be applied.
    spark.connect.Expression condition = 1;

    // (Required)
    oneof action_type {
      DeleteAction delete_action = 2;
      UpdateAction update_action = 3;
      UpdateStarAction update_star_action = 4;
      InsertAction insert_action = 5;
      InsertStarAction insert_star_action = 6;
    }

    // Action that deletes the target row.
    message DeleteAction {}

    // Action that updates the target row using a set of assignments.
    message UpdateAction {
      // (Optional) Set of assignments to apply.
      repeated Assignment assignments = 1;
    }

    // Action that updates the target row by overwriting all columns.
    message UpdateStarAction {}

    // Action that inserts the source row into the target using a set of assignments.
    message InsertAction {
      // (Optional) Set of assignments to apply.
      repeated Assignment assignments = 1;
    }

    // Action that inserts the source row into the target by setting all columns.
    message InsertStarAction {}
  }
}

// Represents an assignment of a value to a field.
message Assignment {
  // (Required) Expression identifying the (struct) field that is assigned a new value.
  spark.connect.Expression field = 1;

  // (Required) Expression that produces the value to assign to the field.
  spark.connect.Expression value = 2;
}


// Command that optimizes the layout of a Delta table by either compacting small files or
// by ordering the data. Allows specifying partition filters to limit the scope of the data
// reorganization.
//
// Needs to be a Relation, as it returns a row containing the execution metrics.
message OptimizeTable {
  // (Required) The Delta table to optimize.
  DeltaTable table = 1;

  // (Optional) Partition filters that limit the operation to the files in the matched partitions.
  repeated string partition_filters = 2;

  // (Optional) Columns to z-order by. Compaction is performed when no z-order columns are provided.
  repeated string zorder_columns = 3;
}