Expressions and Column References

/**
 * Creates a column reference expression
 * @param name Column name
 * @return Expression referencing the specified column
 */
public static Expression $(String name);

/**
 * Creates a literal value expression
 * @param value Literal value (String, Number, Boolean, etc.)
 * @return Expression representing the literal value
 */
public static Expression lit(Object value);

/**
 * Creates a column reference from a table and column
 * @param table Table alias or name
 * @param column Column name
 * @return Qualified column reference expression
 */
public static Expression $(String table, String column);

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

// Column references
Expression nameCol = $("name");
Expression ageCol = $("age"); 
Expression qualifiedCol = $("employees", "salary");

// Literals
Expression stringLit = lit("Active");
Expression numberLit = lit(100);
Expression boolLit = lit(true);
Expression nullLit = lit(null);

// Using in table operations
Table result = sourceTable.select(
    $("employee_id"),
    $("name"),
    lit("EMPLOYEE").as("type"),
    lit(1.0).as("multiplier")
);

/**
 * Addition operation
 * @param left Left operand expression
 * @param right Right operand expression
 * @return Expression representing left + right
 */
public static Expression plus(Object left, Object right);

/**
 * Subtraction operation
 * @param left Left operand expression  
 * @param right Right operand expression
 * @return Expression representing left - right
 */
public static Expression minus(Object left, Object right);

/**
 * Multiplication operation
 * @param left Left operand expression
 * @param right Right operand expression
 * @return Expression representing left * right
 */
public static Expression times(Object left, Object right);

/**
 * Division operation
 * @param left Left operand expression
 * @param right Right operand expression
 * @return Expression representing left / right
 */
public static Expression dividedBy(Object left, Object right);

/**
 * Modulo operation
 * @param left Left operand expression
 * @param right Right operand expression
 * @return Expression representing left % right
 */
public static Expression mod(Object left, Object right);

// Basic arithmetic
Expression totalSalary = plus($("base_salary"), $("bonus"));
Expression netPay = minus($("gross_pay"), $("deductions"));
Expression area = times($("length"), $("width"));
Expression average = dividedBy($("total"), $("count"));

// Chain operations using Expression methods
Expression complexCalc = $("salary")
    .multiply(1.1)  // 10% increase
    .plus($("bonus"))
    .minus($("tax"));

// Mixed literals and columns
Expression adjustedPrice = $("price").multiply(lit(1.08)); // Add 8% tax

/**
 * Equality comparison
 * @param left Left operand expression
 * @param right Right operand expression
 * @return Boolean expression for left == right
 */
public static Expression isEqual(Object left, Object right);

/**
 * Inequality comparison
 * @param left Left operand expression
 * @param right Right operand expression
 * @return Boolean expression for left != right
 */
public static Expression isNotEqual(Object left, Object right);

/**
 * Greater than comparison
 * @param left Left operand expression
 * @param right Right operand expression
 * @return Boolean expression for left > right
 */
public static Expression isGreater(Object left, Object right);

/**
 * Greater than or equal comparison
 * @param left Left operand expression
 * @param right Right operand expression
 * @return Boolean expression for left >= right
 */
public static Expression isGreaterOrEqual(Object left, Object right);

/**
 * Less than comparison
 * @param left Left operand expression
 * @param right Right operand expression
 * @return Boolean expression for left < right
 */
public static Expression isLess(Object left, Object right);

/**
 * Less than or equal comparison
 * @param left Left operand expression
 * @param right Right operand expression
 * @return Boolean expression for left <= right
 */
public static Expression isLessOrEqual(Object left, Object right);

// Comparison filters
Table adults = sourceTable.filter(isGreaterOrEqual($("age"), 18));
Table highEarners = sourceTable.filter(isGreater($("salary"), 100000));
Table specificDept = sourceTable.filter(isEqual($("department"), "Engineering"));

// Complex comparisons
Table filtered = sourceTable.filter(
    isGreaterOrEqual($("experience_years"), 5)
    .and(isLessOrEqual($("age"), 50))
    .and(isNotEqual($("status"), "INACTIVE"))
);

/**
 * Logical AND operation
 * @param left Left boolean expression
 * @param right Right boolean expression
 * @return Boolean expression for left AND right
 */
public static Expression and(Object left, Object right);

/**
 * Logical OR operation
 * @param left Left boolean expression
 * @param right Right boolean expression
 * @return Boolean expression for left OR right
 */
public static Expression or(Object left, Object right);

/**
 * Logical NOT operation
 * @param expression Boolean expression to negate
 * @return Boolean expression for NOT expression
 */
public static Expression not(Object expression);

// Logical combinations
Expression seniorDeveloper = and(
    isEqual($("role"), "Developer"),
    isGreaterOrEqual($("experience"), 5)
);

Expression eligibleForBonus = or(
    isEqual($("performance"), "Excellent"),
    and(
        isEqual($("performance"), "Good"),
        isGreaterOrEqual($("tenure"), 2)
    )
);

Expression notInactive = not(isEqual($("status"), "INACTIVE"));

// Using in table operations
Table filtered = sourceTable.filter(
    and(
        isGreaterOrEqual($("age"), 25),
        or(
            isEqual($("department"), "Engineering"),
            isEqual($("department"), "Research")
        )
    )
);

/**
 * String concatenation
 * @param left Left string expression
 * @param right Right string expression
 * @return Expression for concatenated string
 */
public static Expression concat(Object left, Object right);

/**
 * String LIKE pattern matching
 * @param str String expression to match
 * @param pattern Pattern string with % and _ wildcards
 * @return Boolean expression for pattern match
 */
public static Expression like(Object str, Object pattern);

/**
 * String length function
 * @param str String expression
 * @return Expression for string length
 */
public static Expression length(Object str);

/**
 * Uppercase conversion
 * @param str String expression
 * @return Expression for uppercase string
 */
public static Expression upper(Object str);

/**
 * Lowercase conversion  
 * @param str String expression
 * @return Expression for lowercase string
 */
public static Expression lower(Object str);

/**
 * Trim whitespace from string
 * @param str String expression
 * @return Expression for trimmed string
 */
public static Expression trim(Object str);

/**
 * Substring extraction
 * @param str String expression
 * @param start Start position (1-based)
 * @param length Length of substring
 * @return Expression for substring
 */
public static Expression substring(Object str, Object start, Object length);

// String operations
Table processed = sourceTable.select(
    $("id"),
    upper($("name")).as("name_upper"),
    concat($("first_name"), lit(" "), $("last_name")).as("full_name"),
    trim($("description")).as("clean_description")
);

// String filtering
Table nameFiltered = sourceTable.filter(like($("name"), "John%"));
Table domainFiltered = sourceTable.filter(like($("email"), "%@company.com"));

// String transformations
Table transformed = sourceTable.select(
    $("id"),
    substring($("code"), 1, 3).as("prefix"),
    length($("description")).as("desc_length"),
    lower(trim($("category"))).as("normalized_category")
);

/**
 * Check if expression is null
 * @param expr Expression to check
 * @return Boolean expression for null check
 */
public static Expression isNull(Object expr);

/**
 * Check if expression is not null
 * @param expr Expression to check
 * @return Boolean expression for not null check
 */
public static Expression isNotNull(Object expr);

/**
 * Return alternative value if expression is null
 * @param expr Expression to check
 * @param ifNull Value to return if expr is null
 * @return Expression with null handling
 */
public static Expression ifNull(Object expr, Object ifNull);

/**
 * Null-safe equality comparison
 * @param left Left expression
 * @param right Right expression
 * @return Boolean expression for null-safe equality
 */
public static Expression isNotDistinctFrom(Object left, Object right);

// Null checks
Table withNonNullEmails = sourceTable.filter(isNotNull($("email")));
Table missingPhones = sourceTable.filter(isNull($("phone")));

// Null handling
Table processed = sourceTable.select(
    $("id"),
    $("name"),
    ifNull($("middle_name"), lit("")).as("middle_name"),
    ifNull($("salary"), lit(0)).as("salary_or_zero")
);

// Null-safe comparisons
Table matched = sourceTable.filter(isNotDistinctFrom($("category"), lit("PREMIUM")));

/**
 * Creates a CASE WHEN expression builder
 * @param condition Boolean condition expression
 * @param result Result expression when condition is true
 * @return CaseWhenBuilder for additional when/otherwise clauses
 */
public static ApiExpression when(Object condition, Object result);

// Simple conditional
Expression statusDescription = when($("status").isEqual("A"), "Active")
    .otherwise("Inactive");

// Multiple conditions
Expression salaryGrade = when($("salary").isGreater(100000), "Senior")
    .when($("salary").isGreater(70000), "Mid")
    .when($("salary").isGreater(40000), "Junior")
    .otherwise("Entry");

// Complex conditions
Expression performanceBonus = when(
        and(
            isEqual($("performance"), "Excellent"),
            isGreaterOrEqual($("tenure"), 1)
        ),
        $("salary").multiply(0.1)
    )
    .when(isEqual($("performance"), "Good"), $("salary").multiply(0.05))
    .otherwise(lit(0));

// Using in select
Table categorized = sourceTable.select(
    $("employee_id"),
    $("name"),
    $("salary"),
    salaryGrade.as("grade"),
    performanceBonus.as("bonus")
);

/**
 * Check if value is in a collection
 * @param expr Expression to check
 * @param values Collection of values to check against
 * @return Boolean expression for membership test
 */
public static Expression in(Object expr, Object... values);

/**
 * Array element access
 * @param array Array expression
 * @param index Index expression (0-based)
 * @return Expression for array element
 */
public static Expression at(Object array, Object index);

/**
 * Array cardinality (size)
 * @param array Array expression
 * @return Expression for array size
 */
public static Expression cardinality(Object array);

// IN predicates
Table filtered = sourceTable.filter(
    in($("department"), "Engineering", "Research", "Product")
);

Table statusFiltered = sourceTable.filter(
    in($("status"), "ACTIVE", "PENDING", "APPROVED")
);

// Array operations (if your data contains arrays)
Table arrayProcessed = sourceTable.select(
    $("id"),
    at($("tags"), 0).as("primary_tag"),
    cardinality($("skills")).as("skill_count")
);

/**
 * Generic function call
 * @param name Function name
 * @param args Function arguments
 * @return Expression representing function call
 */
public static Expression call(String name, Object... args);

/**
 * Call user-defined function
 * @param function Function class or instance
 * @param args Function arguments
 * @return Expression representing UDF call
 */
public static Expression call(Class<?> function, Object... args);

// Built-in function calls
Expression currentTime = call("CURRENT_TIMESTAMP");
Expression rounded = call("ROUND", $("price"), 2);
Expression dayOfWeek = call("DAYOFWEEK", $("created_date"));

// Mathematical functions
Expression sqrtValue = call("SQRT", $("area"));
Expression logValue = call("LOG", $("value"));

// User-defined function calls
Expression customHash = call("MY_HASH_FUNCTION", $("user_id"), $("timestamp"));

// Using in operations
Table processed = sourceTable.select(
    $("id"),
    call("UPPER", $("name")).as("name_upper"),
    call("DATE_FORMAT", $("created_date"), "yyyy-MM-dd").as("date_str"),
    call("GREATEST", $("score1"), $("score2"), $("score3")).as("max_score")
);

public interface Expression {
    /**
     * Creates an alias for this expression
     * @param alias Alias name
     * @return Expression with alias
     */
    Expression as(String alias);
    
    /**
     * Equality comparison (instance method)
     * @param other Value to compare with
     * @return Boolean expression for equality
     */
    Expression isEqual(Object other);
    
    /**
     * Greater than comparison (instance method)
     * @param other Value to compare with
     * @return Boolean expression for greater than
     */
    Expression isGreater(Object other);
    
    /**
     * Addition (instance method)
     * @param other Value to add
     * @return Expression for addition
     */
    Expression plus(Object other);
    
    /**
     * Subtraction (instance method)
     * @param other Value to subtract
     * @return Expression for subtraction
     */
    Expression minus(Object other);
    
    /**
     * Multiplication (instance method)
     * @param other Value to multiply by
     * @return Expression for multiplication
     */
    Expression multiply(Object other);
    
    /**
     * String concatenation (instance method)
     * @param other String to concatenate
     * @return Expression for concatenation
     */
    Expression concat(Object other);
    
    /**
     * LIKE pattern matching (instance method)
     * @param pattern Pattern string
     * @return Boolean expression for pattern match
     */
    Expression like(Object pattern);
}

// Fluent expression chaining
Expression complexExpr = $("base_salary")
    .multiply(lit(1.1))     // 10% increase
    .plus($("bonus"))       // Add bonus
    .minus($("tax"))        // Subtract tax
    .as("net_salary");      // Alias the result

// Method chaining for comparisons
Table filtered = sourceTable.filter(
    $("salary")
        .multiply(lit(12))  // Annual salary
        .isGreater(lit(100000))
);

// String method chaining
Expression processedName = $("raw_name")
    .concat(lit(" (processed)"))
    .as("processed_name");