Built-in Functions

/** Returns the current SQL date in local time zone (DataTypes.DATE) */
def currentDate(): Expression

/** Returns the current SQL time in local time zone (DataTypes.TIME) */
def currentTime(): Expression

/** Returns the current SQL timestamp in local time zone (DataTypes.TIMESTAMP_LTZ) */
def currentTimestamp(): Expression

/** Synonym for currentTime() */
def localTime(): Expression

/** Returns the current SQL timestamp in local time zone (DataTypes.TIMESTAMP) */
def localTimestamp(): Expression

/** Returns the current database name (DataTypes.STRING) */
def currentDatabase(): Expression

/**
 * Returns current watermark for rowtime attribute, or NULL if unavailable
 * @param rowtimeAttribute The rowtime attribute expression
 * @return Watermark with same type as rowtime but precision 3
 */
def currentWatermark(rowtimeAttribute: Expression): Expression

// Current date/time operations
table.select(
  $"event",
  currentDate() as "processDate",
  currentTimestamp() as "processTime"
)

// Watermark operations
table.filter($"eventTime" > currentWatermark($"eventTime"))

/**
 * Converts date string with format 'yyyy-MM-dd' to DATE type
 * @param dateStr Date string expression
 * @return DATE expression
 */
def toDate(dateStr: Expression): Expression

/**
 * Converts date string with specified format to DATE type
 * @param dateStr Date string expression  
 * @param format Format pattern expression
 * @return DATE expression
 */
def toDate(dateStr: Expression, format: Expression): Expression

/**
 * Converts datetime string 'yyyy-MM-dd HH:mm:ss' to TIMESTAMP (UTC+0)
 * @param timestampStr Timestamp string expression
 * @return TIMESTAMP expression
 */
def toTimestamp(timestampStr: Expression): Expression

/**
 * Converts datetime string with format to TIMESTAMP (UTC+0)
 * @param timestampStr Timestamp string expression
 * @param format Format pattern expression  
 * @return TIMESTAMP expression
 */
def toTimestamp(timestampStr: Expression, format: Expression): Expression

/**
 * Converts numeric epoch time to TIMESTAMP_LTZ
 * @param numericEpochTime Epoch time expression
 * @param precision Precision (0=seconds, 3=milliseconds)
 * @return TIMESTAMP_LTZ expression
 */
def toTimestampLtz(numericEpochTime: Expression, precision: Expression): Expression

// Date conversions
table.select(
  toDate($"dateString") as "parsedDate",
  toDate($"customDate", "MM/dd/yyyy") as "customParsedDate",
  toTimestamp($"timestampString") as "parsedTimestamp"
)

// Epoch conversions
table.select(
  toTimestampLtz($"epochSeconds", 0) as "timestampFromSeconds",
  toTimestampLtz($"epochMillis", 3) as "timestampFromMillis"
)

/**
 * Formats timestamp as string using MySQL date formatting syntax
 * @param timestamp Timestamp expression to format
 * @param format Format pattern (MySQL syntax)
 * @return Formatted string expression
 */
def dateFormat(timestamp: Expression, format: Expression): Expression

/**
 * Returns signed number of time units between two time points
 * @param timePointUnit Unit for difference calculation
 * @param timePoint1 First time point
 * @param timePoint2 Second time point  
 * @return Difference as integer
 */
def timestampDiff(
  timePointUnit: TimePointUnit,
  timePoint1: Expression, 
  timePoint2: Expression
): Expression

/**
 * Determines if two time intervals overlap
 * @param leftTimePoint Start of first interval
 * @param leftTemporal Duration of first interval
 * @param rightTimePoint Start of second interval
 * @param rightTemporal Duration of second interval
 * @return Boolean indicating overlap
 */
def temporalOverlaps(
  leftTimePoint: Expression,
  leftTemporal: Expression,
  rightTimePoint: Expression, 
  rightTemporal: Expression
): Expression

// Date formatting
table.select(
  dateFormat($"timestamp", "%Y-%m-%d") as "dateOnly",
  dateFormat($"timestamp", "%H:%i:%s") as "timeOnly"
)

// Time differences
table.select(
  timestampDiff(TimePointUnit.DAY, $"startDate", $"endDate") as "daysDiff",
  timestampDiff(TimePointUnit.HOUR, $"startTime", $"endTime") as "hoursDiff"
)

/**
 * Converts datetime between timezones
 * @param dateStr Datetime string (ISO format)
 * @param tzFrom Source timezone  
 * @param tzTo Target timezone
 * @return Converted datetime string
 */
def convertTz(dateStr: Expression, tzFrom: Expression, tzTo: Expression): ApiExpression

/**
 * Converts Unix timestamp to datetime string 'yyyy-MM-dd HH:mm:ss'
 * @param unixtime Unix timestamp expression
 * @return Formatted datetime string
 */
def fromUnixtime(unixtime: Expression): Expression

/**
 * Converts Unix timestamp to datetime string with custom format
 * @param unixtime Unix timestamp expression
 * @param format Custom format pattern
 * @return Formatted datetime string
 */
def fromUnixtime(unixtime: Expression, format: Expression): Expression

/** Gets current Unix timestamp in seconds (non-deterministic) */
def unixTimestamp(): Expression

/**
 * Converts datetime string to Unix timestamp using table config timezone
 * @param timestampStr Datetime string 'yyyy-MM-dd HH:mm:ss'
 * @return Unix timestamp in seconds
 */
def unixTimestamp(timestampStr: Expression): Expression

/**
 * Converts datetime string with format to Unix timestamp
 * @param timestampStr Datetime string
 * @param format Format pattern
 * @return Unix timestamp in seconds
 */
def unixTimestamp(timestampStr: Expression, format: Expression): Expression

// Timezone conversions
table.select(
  convertTz($"utcTime", "UTC", "America/Los_Angeles") as "localTime"
)

// Unix timestamp operations
table.select(
  fromUnixtime($"epochTime") as "readableTime",
  unixTimestamp($"datetimeString") as "epochTime",
  unixTimestamp() as "currentEpoch"
)

/** Returns value closest to pi */
def pi(): Expression

/** Returns value closest to e (Euler's number) */
def e(): Expression

/** Returns pseudorandom double between 0.0 (inclusive) and 1.0 (exclusive) */
def rand(): Expression

/**
 * Returns pseudorandom double with initial seed
 * @param seed Seed expression for reproducible randomness
 * @return Random double between 0.0 and 1.0
 */
def rand(seed: Expression): Expression

/**
 * Returns pseudorandom integer up to bound (exclusive)
 * @param bound Upper bound (exclusive)
 * @return Random integer between 0 and bound
 */
def randInteger(bound: Expression): Expression

/**
 * Returns pseudorandom integer with seed up to bound
 * @param seed Seed for reproducible randomness
 * @param bound Upper bound (exclusive)  
 * @return Random integer between 0 and bound
 */
def randInteger(seed: Expression, bound: Expression): Expression

/**
 * Calculates arc tangent of given coordinates
 * @param y Y coordinate
 * @param x X coordinate
 * @return Arc tangent result
 */
def atan2(y: Expression, x: Expression): Expression

/**
 * Calculates natural logarithm of value
 * @param value Input value
 * @return Natural logarithm
 */
def log(value: Expression): Expression

/**
 * Calculates logarithm of value to given base
 * @param base Logarithm base
 * @param value Input value
 * @return Logarithm result
 */
def log(base: Expression, value: Expression): Expression

/**
 * Returns negative numeric value
 * @param v Numeric expression
 * @return Negated expression
 */
def negative(v: Expression): Expression

// Mathematical constants and operations
table.select(
  pi() * $"radius" * $"radius" as "area",
  log($"value") as "naturalLog",
  log(10, $"value") as "log10",
  rand() as "randomValue"
)

/**
 * Concatenates strings, returns NULL if any argument is NULL
 * @param string First string
 * @param strings Additional strings
 * @return Concatenated string
 */
def concat(string: Expression, strings: Expression*): Expression

/**
 * Concatenates strings with separator, skips NULL values after separator
 * @param separator String separator
 * @param string First string
 * @param strings Additional strings  
 * @return Concatenated string with separators
 */
def concatWs(separator: Expression, string: Expression, strings: Expression*): Expression

/**
 * Generates RFC 4122 type 4 UUID string
 * @return UUID string expression
 */
def uuid(): Expression

// String operations
table.select(
  concat($"firstName", " ", $"lastName") as "fullName",
  concatWs("-", $"year", $"month", $"day") as "dateString",
  uuid() as "uniqueId"
)

/**
 * Creates array of expressions
 * @param head First element
 * @param tail Additional elements
 * @return Array expression
 */
def array(head: Expression, tail: Expression*): Expression

/**
 * Creates row of expressions  
 * @param head First field
 * @param tail Additional fields
 * @return Row expression
 */
def row(head: Expression, tail: Expression*): Expression

/**
 * Creates map from key-value pairs
 * @param key First key
 * @param value First value
 * @param tail Additional key-value pairs
 * @return Map expression
 */
def map(key: Expression, value: Expression, tail: Expression*): Expression

/**
 * Creates map from arrays of keys and values
 * @param key Array of keys
 * @param value Array of values
 * @return Map expression
 */
def mapFromArrays(key: Expression, value: Expression): Expression

// Collection construction
table.select(
  array($"item1", $"item2", $"item3") as "items",
  row($"x", $"y", $"z") as "coordinates", 
  map("key1", $"value1", "key2", $"value2") as "metadata"
)

/**
 * Creates null literal of specified DataType
 * @param dataType Type for null literal
 * @return Null expression of specified type
 */
def nullOf(dataType: DataType): Expression

/**
 * Ternary conditional operator
 * @param condition Boolean condition
 * @param ifTrue Expression if condition is true
 * @param ifFalse Expression if condition is false
 * @return Conditional expression result
 */
def ifThenElse(condition: Expression, ifTrue: Expression, ifFalse: Expression): Expression

/**
 * Returns first non-null argument
 * @param args Input expressions
 * @return First non-null value, or NULL if all are NULL
 */
def coalesce(args: Expression*): Expression

/**
 * Selects range of columns
 * @param head Start of range
 * @param tail Additional range specifications
 * @return Column selection expression
 */
def withColumns(head: Expression, tail: Expression*): Expression

/**
 * Excludes range of columns
 * @param head Start of exclusion range
 * @param tail Additional exclusion ranges
 * @return Column exclusion expression
 */
def withoutColumns(head: Expression, tail: Expression*): Expression

/**
 * Boolean AND with multiple predicates
 * @param predicate0 First predicate
 * @param predicate1 Second predicate
 * @param predicates Additional predicates
 * @return AND result
 */
def and(predicate0: Expression, predicate1: Expression, predicates: Expression*): Expression

/**
 * Boolean OR with multiple predicates
 * @param predicate0 First predicate
 * @param predicate1 Second predicate
 * @param predicates Additional predicates
 * @return OR result
 */
def or(predicate0: Expression, predicate1: Expression, predicates: Expression*): Expression

/**
 * Boolean NOT preserving three-valued logic 
 * @param expression Boolean expression to invert
 * @return Inverted boolean expression
 */
def not(expression: Expression): Expression

// Utility operations
table.select(
  coalesce($"preferredName", $"firstName", "Unknown") as "displayName",
  ifThenElse($"age" >= 18, "Adult", "Minor") as "ageGroup",
  withColumns($"name" to $"email"), // Select column range
  not($"deleted") as "active"
)

/**
 * Source watermark declaration marker for Schema
 * No runtime implementation - used only in Schema.Builder#watermark
 * Requires connector support for SupportsSourceWatermark
 * @return Source watermark marker expression
 */
def sourceWatermark(): Expression

// Used in schema definitions (not in regular queries)
val schema = Schema.newBuilder()
  .column("eventTime", DataTypes.TIMESTAMP_LTZ(3))
  .watermark("eventTime", sourceWatermark())
  .build()