Table Operations and Transformations

/**
 * Selects specific fields from the table
 * @param fields Column expressions to select
 * @return New Table with selected fields
 */
public Table select(Expression... fields);

/**
 * Selects fields using string field references (deprecated)
 * @param fields Field names as strings
 * @return New Table with selected fields
 * @deprecated Use select(Expression...) instead
 */
@Deprecated
public Table select(String fields);

import static org.apache.flink.table.api.Expressions.*;

// Basic column selection
Table result = sourceTable.select($("name"), $("age"), $("salary"));

// Computed columns
Table computed = sourceTable.select(
    $("name"),
    $("age"),
    $("salary").multiply(1.1).as("adjusted_salary"),
    $("first_name").concat($("last_name")).as("full_name")
);

// Complex expressions
Table complex = sourceTable.select(
    $("customer_id"),
    $("order_date").extract(IntervalUnit.YEAR).as("order_year"),
    when($("amount").isGreater(1000), "HIGH")
        .otherwise(when($("amount").isGreater(500), "MEDIUM")
        .otherwise("LOW")).as("order_category")
);

/**
 * Renames the fields of the table for disambiguation
 * @param field First field name
 * @param fields Additional field names
 * @return New Table with renamed fields
 */
public Table as(String field, String... fields);

/**
 * Renames fields using expressions (deprecated)
 * @param fields Field expressions for renaming
 * @return New Table with renamed fields
 * @deprecated Use as(String, String...) instead
 */
@Deprecated
public Table as(Expression... fields);

// Rename all fields in order
Table renamedTable = sourceTable.as("customer_id", "customer_name", "total_orders");

// Use for disambiguation before joins
Table customers = customerTable.as("c_id", "c_name", "c_email");
Table orders = orderTable.as("o_id", "o_customer_id", "o_amount");

Table joined = customers.join(
    orders,
    $("c_id").isEqual($("o_customer_id"))
);

/**
 * Filters table rows based on the given predicate
 * @param predicate Boolean expression to filter on
 * @return New Table with filtered rows
 */
public Table filter(Expression predicate);

/**
 * Filters table rows using string expression (deprecated)
 * @param predicate Boolean expression as string
 * @return New Table with filtered rows
 * @deprecated Use filter(Expression) instead
 */
@Deprecated
public Table filter(String predicate);

/**
 * Alternative name for filter operation
 * @param predicate Boolean expression to filter on
 * @return New Table with filtered rows
 */
public Table where(Expression predicate);

// Simple filters
Table adults = sourceTable.filter($("age").isGreaterOrEqual(18));
Table highSalary = sourceTable.filter($("salary").isGreater(50000));

// Complex predicates
Table filtered = sourceTable.filter(
    $("age").isGreaterOrEqual(25)
    .and($("department").isEqual("Engineering"))
    .and($("salary").isGreater(60000))
);

// String matching
Table nameFilter = sourceTable.filter($("name").like("John%"));

// Null checks
Table nonNull = sourceTable.filter($("email").isNotNull());

// IN predicates
Table departments = sourceTable.filter(
    $("department").in("Engineering", "Sales", "Marketing")
);

/**
 * Inner join with another table
 * @param right Table to join with
 * @param joinPredicate Join condition expression
 * @return New Table with joined data
 */
public Table join(Table right, Expression joinPredicate);

/**
 * Left outer join with another table
 * @param right Table to join with  
 * @param joinPredicate Join condition expression
 * @return New Table with left outer joined data
 */
public Table leftOuterJoin(Table right, Expression joinPredicate);

/**
 * Right outer join with another table
 * @param right Table to join with
 * @param joinPredicate Join condition expression
 * @return New Table with right outer joined data
 */
public Table rightOuterJoin(Table right, Expression joinPredicate);

/**
 * Full outer join with another table
 * @param right Table to join with
 * @param joinPredicate Join condition expression
 * @return New Table with full outer joined data
 */
public Table fullOuterJoin(Table right, Expression joinPredicate);

/**
 * Inner join with a table function (lateral join)
 * @param tableFunctionCall Table function call expression
 * @return New Table with lateral joined data
 */
public Table joinLateral(Expression tableFunctionCall);

/**
 * Inner join with a table function and join predicate
 * @param tableFunctionCall Table function call expression
 * @param joinPredicate Join condition expression
 * @return New Table with lateral joined data
 */
public Table joinLateral(Expression tableFunctionCall, Expression joinPredicate);

/**
 * Left outer join with a table function (lateral join)
 * @param tableFunctionCall Table function call expression
 * @return New Table with left outer lateral joined data
 */
public Table leftOuterJoinLateral(Expression tableFunctionCall);

/**
 * Left outer join with a table function and join predicate
 * @param tableFunctionCall Table function call expression
 * @param joinPredicate Join condition expression
 * @return New Table with left outer lateral joined data
 */
public Table leftOuterJoinLateral(Expression tableFunctionCall, Expression joinPredicate);

Table customers = tableEnv.from("customers");
Table orders = tableEnv.from("orders");

// Inner join
Table customerOrders = customers.join(
    orders,
    $("customers.id").isEqual($("orders.customer_id"))
);

// Left outer join with column selection
Table allCustomers = customers
    .leftOuterJoin(orders, $("customers.id").isEqual($("orders.customer_id")))
    .select($("customers.name"), $("customers.email"), $("orders.order_id"), $("orders.amount"));

// Multiple join conditions
Table complexJoin = customers.join(
    orders,
    $("customers.id").isEqual($("orders.customer_id"))
    .and($("customers.region").isEqual($("orders.shipping_region")))
);

// Lateral join with table function (UDTF)
// Assuming you have a SplitFunction that splits strings
Table lateralResult = sourceTable
    .joinLateral(call("split_string", $("tags"), lit(",")))
    .select($("id"), $("name"), $("f0").as("tag"), $("f1").as("position"));

// Left outer lateral join with predicate
Table leftLateralResult = sourceTable
    .leftOuterJoinLateral(
        call("split_string", $("categories"), lit(";")),
        $("id").isGreater(100)
    )
    .select($("id"), $("name"), $("f0").as("category"));

/**
 * Groups the table by the given fields
 * @param fields Fields to group by
 * @return GroupedTable for aggregation operations
 */
public GroupedTable groupBy(Expression... fields);

/**
 * Groups the table using string field references (deprecated)
 * @param fields Field names as strings
 * @return GroupedTable for aggregation operations
 * @deprecated Use groupBy(Expression...) instead
 */
@Deprecated
public GroupedTable groupBy(String fields);

// Basic grouping
GroupedTable byDepartment = sourceTable.groupBy($("department"));

// Multiple grouping fields
GroupedTable byDeptAndLevel = sourceTable.groupBy($("department"), $("level"));

// Grouping with computed fields
GroupedTable byYearMonth = sourceTable.groupBy(
    $("hire_date").extract(IntervalUnit.YEAR).as("hire_year"),
    $("hire_date").extract(IntervalUnit.MONTH).as("hire_month")
);

/**
 * Orders the table by the given fields in ascending order
 * @param fields Fields to order by
 * @return New Table with ordered data
 */
public Table orderBy(Expression... fields);

/**
 * Orders the table using string field references (deprecated)
 * @param fields Field names as strings
 * @return New Table with ordered data
 * @deprecated Use orderBy(Expression...) instead
 */
@Deprecated
public Table orderBy(String fields);

// Single field ordering (ascending by default)
Table sorted = sourceTable.orderBy($("name"));

// Multiple fields with explicit ordering
Table multiSort = sourceTable.orderBy($("department").asc(), $("salary").desc());

// Order by computed expressions
Table computedSort = sourceTable.orderBy(
    $("salary").multiply($("bonus_factor")).desc(),
    $("hire_date").asc()
);

/**
 * Limits the table to the first n rows
 * @param fetch Number of rows to return
 * @return New Table with limited rows
 */
public Table limit(int fetch);

/**
 * Limits the table with offset and fetch count
 * @param offset Number of rows to skip
 * @param fetch Number of rows to return after offset
 * @return New Table with limited rows
 */
public Table limit(int offset, int fetch);

// Get first 10 rows
Table top10 = sourceTable
    .orderBy($("salary").desc())
    .limit(10);

// Pagination: skip 20 rows, take next 10
Table page3 = sourceTable
    .orderBy($("id"))
    .limit(20, 10);

/**
 * Union with another table (removes duplicates)
 * @param right Table to union with
 * @return New Table with union of both tables
 */
public Table union(Table right);

/**
 * Union all with another table (keeps duplicates)
 * @param right Table to union with
 * @return New Table with union of both tables including duplicates
 */
public Table unionAll(Table right);

/**
 * Intersect with another table
 * @param right Table to intersect with
 * @return New Table with intersection of both tables
 */
public Table intersect(Table right);

/**
 * Minus operation with another table
 * @param right Table to subtract
 * @return New Table with rows from left table not in right table
 */
public Table minus(Table right);

/**
 * Returns distinct rows from the table
 * @return New Table with duplicate rows removed
 */
public Table distinct();

// Remove duplicates
Table uniqueCustomers = sourceTable.distinct();

// Distinct on specific columns (via groupBy)
Table uniqueDepartments = sourceTable
    .groupBy($("department"))
    .select($("department"));

/**
 * Executes the table operation and returns results
 * @return TableResult containing the execution results
 */
public TableResult execute();

/**
 * Executes the table as an insert operation into the specified table
 * @param tablePath Target table path for insertion
 * @return TableResult containing execution status
 */
public TableResult executeInsert(String tablePath);

/**
 * Explains the execution plan for this table
 * @return String representation of the execution plan
 */
public String explain();

/**
 * Explains the execution plan with specified format and details
 * @param format Format for the explanation output
 * @param extraDetails Additional details to include
 * @return String representation of the execution plan
 */
public String explain(ExplainFormat format, ExplainDetail... extraDetails);

// Execute and print results
Table result = sourceTable
    .filter($("age").isGreater(25))
    .select($("name"), $("age"), $("department"));

TableResult tableResult = result.execute();
tableResult.print();

// Insert into target table
sourceTable
    .filter($("status").isEqual("ACTIVE"))
    .executeInsert("target_table");

// Explain query plan
String plan = result.explain();
System.out.println(plan);

// Detailed explanation
String detailedPlan = result.explain(
    ExplainFormat.JSON,
    ExplainDetail.COST_ATTRS,
    ExplainDetail.CHANGELOG_MODE
);

/**
 * Gets the resolved schema of this table
 * @return ResolvedSchema containing column information and constraints
 */
public ResolvedSchema getResolvedSchema();

/**
 * Gets the legacy table schema (deprecated)
 * @return TableSchema with column types and names
 * @deprecated Use getResolvedSchema() instead
 */
@Deprecated
public TableSchema getSchema();

/**
 * Prints the schema of this table to the console
 */
public void printSchema();

public interface TableResult {
    /**
     * Prints the table results to the console
     */
    void print();
    
    /**
     * Collects table results as an iterator
     * @return CloseableIterator over result rows
     */
    CloseableIterator<Row> collect();
    
    /**
     * Gets the result kind (success, success with info, etc.)
     * @return ResultKind enum value
     */
    ResultKind getResultKind();
    
    /**
     * Gets the schema of the result table
     * @return ResolvedSchema of the result
     */
    ResolvedSchema getResolvedSchema();
    
    /**
     * Gets the job client for monitoring execution (if available)
     * @return Optional JobClient for job monitoring
     */
    Optional<JobClient> getJobClient();
}

public enum ResultKind {
    /** Operation completed successfully */
    SUCCESS,
    /** Operation completed successfully with additional information */
    SUCCESS_WITH_INFO
}

public interface Executable {
    /**
     * Executes the operation and returns results
     * @return TableResult with execution results
     */
    TableResult execute();
}

public interface Explainable<T> {
    /**
     * Explains the execution plan for this operation
     * @return String representation of the execution plan
     */
    String explain();
    
    /**
     * Explains with specific format and details
     * @param format Output format for explanation
     * @param extraDetails Additional details to include
     * @return Formatted explanation string
     */
    String explain(ExplainFormat format, ExplainDetail... extraDetails);
}

public enum ExplainFormat {
    /** Plain text format */
    TEXT,
    /** JSON format */
    JSON
}

public enum ExplainDetail {
    /** Include cost attributes */
    COST_ATTRS,
    /** Include changelog mode information */
    CHANGELOG_MODE,
    /** Include estimated row count */
    ESTIMATED_COST
}