Expressions (flink 1.11-SNAPSHOT API)

java.lang.Object
- org.apache.flink.table.api.Expressions

```
@PublicEvolving
public final class Expressions
extends Object
```
Entry point of the Table API Expression DSL such as: $("myField").plus(10).abs()
This class contains static methods for referencing table columns, creating literals, and building more complex Expression chains. ApiExpressions are pure API entities that are further translated into ResolvedExpressions under the hood.
For fluent definition of expressions and easier readability, we recommend to add a star import to the methods of this class:
```
 import static org.apache.flink.table.api.Expressions.*;
 
```
Check the documentation for more programming language specific APIs, for example, by using Scala implicits.

Field Summary

Fields
Modifier and Type	Field and Description
`static ApiExpression`	`CURRENT_RANGE` Offset constant to be used in the `following` clause of `Over` windows.
`static ApiExpression`	`CURRENT_ROW` Offset constant to be used in the `following` clause of `Over` windows.
`static ApiExpression`	`UNBOUNDED_RANGE` Offset constant to be used in the `preceding` clause of unbounded `Over` windows.
`static ApiExpression`	`UNBOUNDED_ROW` Offset constant to be used in the `preceding` clause of unbounded `Over` windows.

Constructor Summary

Constructors
Constructor and Description

Expressions()

Constructors
Constructor and Description
`Expressions()`

Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static ApiExpression`	`$(String name)` Creates an unresolved reference to a table's field.
`static ApiExpression`	`and(Object predicate0, Object predicate1, Object... predicates)` Boolean AND in three-valued logic.
`static ApiExpression`	`array(Object head, Object... tail)` Creates an array of literals.
`static ApiExpression`	`atan2(Object y, Object x)` Calculates the arc tangent of a given coordinate.
`static ApiExpression`	`call(Class<? extends UserDefinedFunction> function, Object... arguments)` A call to an unregistered, inline function.
`static ApiExpression`	`call(String path, Object... arguments)` A call to a function that will be looked up in a catalog.
`static ApiExpression`	`call(UserDefinedFunction function, Object... arguments)` A call to an unregistered, inline function.
`static ApiExpression`	`concat(Object string, Object... strings)` Returns the string that results from concatenating the arguments.
`static ApiExpression`	`concatWs(Object separator, Object string, Object... strings)` Returns the string that results from concatenating the arguments and separator.
`static ApiExpression`	`currentDate()` Returns the current SQL date in UTC time zone.
`static ApiExpression`	`currentTime()` Returns the current SQL time in UTC time zone.
`static ApiExpression`	`currentTimestamp()` Returns the current SQL timestamp in UTC time zone.
`static ApiExpression`	`dateFormat(Object timestamp, Object format)` Formats a timestamp as a string using a specified format.
`static ApiExpression`	`e()` Returns a value that is closer than any other value to e.
`static ApiExpression`	`ifThenElse(Object condition, Object ifTrue, Object ifFalse)` Ternary conditional operator that decides which of two other expressions should be evaluated based on a evaluated boolean condition.
`static ApiExpression`	`lit(Object v)` Creates a SQL literal.
`static ApiExpression`	`lit(Object v, DataType dataType)` Creates a SQL literal of a given `DataType`.
`static ApiExpression`	`localTime()` Returns the current SQL time in local time zone.
`static ApiExpression`	`localTimestamp()` Returns the current SQL timestamp in local time zone.
`static ApiExpression`	`log(Object value)` Calculates the logarithm of the given value.
`static ApiExpression`	`log(Object base, Object value)` Calculates the logarithm of the given value to the given base.
`static ApiExpression`	`map(Object key, Object value, Object... tail)` Creates a map of expressions.
`static ApiExpression`	`negative(Object v)` Returns negative numeric.
`static ApiExpression`	`nullOf(DataType dataType)` Returns a null literal value of a given data type.
`static ApiExpression`	`nullOf(TypeInformation<?> typeInfo)` Deprecated. This method will be removed in future versions as it uses the old type system. It is recommended to use `nullOf(DataType)` instead which uses the new type system based on `DataTypes`. Please make sure to use either the old or the new type system consistently to avoid unintended behavior. See the website documentation for more information.
`static ApiExpression`	`or(Object predicate0, Object predicate1, Object... predicates)` Boolean OR in three-valued logic.
`static ApiExpression`	`pi()` Returns a value that is closer than any other value to pi.
`static ApiExpression`	`rand()` Returns a pseudorandom double value between 0.0 (inclusive) and 1.0 (exclusive).
`static ApiExpression`	`rand(Object seed)` Returns a pseudorandom double value between 0.0 (inclusive) and 1.0 (exclusive) with a initial seed.
`static ApiExpression`	`randInteger(Object bound)` Returns a pseudorandom integer value between 0.0 (inclusive) and the specified value (exclusive).
`static ApiExpression`	`randInteger(Object seed, Object bound)` Returns a pseudorandom integer value between 0.0 (inclusive) and the specified value (exclusive) with a initial seed.
`static ApiExpression`	`range(int start, int end)` Indicates an index based range, which can be used in columns selection.
`static ApiExpression`	`range(String start, String end)` Indicates a range from 'start' to 'end', which can be used in columns selection.
`static ApiExpression`	`row(Object head, Object... tail)` Creates a row of expressions.
`static ApiExpression`	`rowInterval(Long rows)` Creates an interval of rows.
`static ApiExpression`	`temporalOverlaps(Object leftTimePoint, Object leftTemporal, Object rightTimePoint, Object rightTemporal)` Determines whether two anchored time intervals overlap.
`static ApiExpression`	`timestampDiff(TimePointUnit timePointUnit, Object timePoint1, Object timePoint2)` Returns the (signed) number of `TimePointUnit` between timePoint1 and timePoint2.
`static ApiExpression`	`uuid()` Returns an UUID (Universally Unique Identifier) string (e.g., "3d3c68f7-f608-473f-b60c-b0c44ad4cc4e") according to RFC 4122 type 4 (pseudo randomly generated) UUID.
`static ApiExpression`	`withColumns(Object head, Object... tail)` Creates an expression that selects a range of columns.
`static ApiExpression`	`withoutColumns(Object head, Object... tail)` Creates an expression that selects all columns except for the given range of columns.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - UNBOUNDED_ROW
```
public static final ApiExpression UNBOUNDED_ROW
```
    Offset constant to be used in the preceding clause of unbounded Over windows. Use this constant for a time interval. Unbounded over windows start with the first row of a partition.
  - UNBOUNDED_RANGE
```
public static final ApiExpression UNBOUNDED_RANGE
```
    Offset constant to be used in the preceding clause of unbounded Over windows. Use this constant for a row-count interval. Unbounded over windows start with the first row of a partition.
  - CURRENT_ROW
```
public static final ApiExpression CURRENT_ROW
```
    Offset constant to be used in the following clause of Over windows. Use this for setting the upper bound of the window to the current row.
  - CURRENT_RANGE
```
public static final ApiExpression CURRENT_RANGE
```
    Offset constant to be used in the following clause of Over windows. Use this for setting the upper bound of the window to the sort key of the current row, i.e., all rows with the same sort key as the current row are included in the window.
- Constructor Detail
  - Expressions
```
public Expressions()
```
- Method Detail
  - $
```
public static ApiExpression $(String name)
```
    Creates an unresolved reference to a table's field.
    Example:
```
 tab.select($("key"), $("value"))
 
```
  - lit
```
public static ApiExpression lit(Object v)
```
    Creates a SQL literal.
    The data type is derived from the object's class and its value.
    For example:
    - lit(12) leads to INT
    - lit("abc") leads to CHAR(3)
    - lit(new BigDecimal("123.45")) leads to DECIMAL(5, 2)
    See ValueDataTypeConverter for a list of supported literal values.
  - lit
```
public static ApiExpression lit(Object v,
                                DataType dataType)
```
    Creates a SQL literal of a given DataType.
    The method lit(Object) is preferred as it extracts the DataType automatically. Use this method only when necessary. The class of v must be supported according to the LogicalType.supportsInputConversion(Class).
  - range
```
public static ApiExpression range(String start,
                                  String end)
```
    Indicates a range from 'start' to 'end', which can be used in columns selection.
    Example:
```
 Table table = ...
 table.select(withColumns(range(b, c)))
 
```
    See Also:
    
    withColumns(Object, Object...), withoutColumns(Object, Object...)
  - range
```
public static ApiExpression range(int start,
                                  int end)
```
    Indicates an index based range, which can be used in columns selection.
    Example:
```
 Table table = ...
 table.select(withColumns(range(3, 4)))
 
```
    See Also:
    
    withColumns(Object, Object...), withoutColumns(Object, Object...)
  - and
```
public static ApiExpression and(Object predicate0,
                                Object predicate1,
                                Object... predicates)
```
    Boolean AND in three-valued logic.
  - or
```
public static ApiExpression or(Object predicate0,
                               Object predicate1,
                               Object... predicates)
```
    Boolean OR in three-valued logic.
  - currentDate
```
public static ApiExpression currentDate()
```
    Returns the current SQL date in UTC time zone.
  - currentTime
```
public static ApiExpression currentTime()
```
    Returns the current SQL time in UTC time zone.
  - currentTimestamp
```
public static ApiExpression currentTimestamp()
```
    Returns the current SQL timestamp in UTC time zone.
  - localTime
```
public static ApiExpression localTime()
```
    Returns the current SQL time in local time zone.
  - localTimestamp
```
public static ApiExpression localTimestamp()
```
    Returns the current SQL timestamp in local time zone.
  - temporalOverlaps
```
public static ApiExpression temporalOverlaps(Object leftTimePoint,
                                             Object leftTemporal,
                                             Object rightTimePoint,
                                             Object rightTemporal)
```
    Determines whether two anchored time intervals overlap. Time point and temporal are transformed into a range defined by two time points (start, end). The function evaluates leftEnd >= rightStart && rightEnd >= leftStart.
    It evaluates: leftEnd >= rightStart && rightEnd >= leftStart
    e.g.
```
 temporalOverlaps(
      lit("2:55:00").toTime(),
      lit(1).hours(),
      lit("3:30:00").toTime(),
      lit(2).hours()
 )
 
```
    leads to true
  - dateFormat
```
public static ApiExpression dateFormat(Object timestamp,
                                       Object format)
```
    Formats a timestamp as a string using a specified format. The format must be compatible with MySQL's date formatting syntax as used by the date_parse function.
    For example dataFormat($("time"), "%Y, %d %M") results in strings formatted as "2017, 05 May".
    
    Parameters:
    
    timestamp - The timestamp to format as string.
    
    format - The format of the string.
    
    Returns:
    
    The formatted timestamp as string.
  - timestampDiff
```
public static ApiExpression timestampDiff(TimePointUnit timePointUnit,
                                          Object timePoint1,
                                          Object timePoint2)
```
    Returns the (signed) number of TimePointUnit between timePoint1 and timePoint2.
    For example, timestampDiff(TimePointUnit.DAY, lit("2016-06-15").toDate(), lit("2016-06-18").toDate() leads to 3.
    
    Parameters:
    
    timePointUnit - The unit to compute diff.
    
    timePoint1 - The first point in time.
    
    timePoint2 - The second point in time.
    
    Returns:
    
    The number of intervals as integer value.
  - array
```
public static ApiExpression array(Object head,
                                  Object... tail)
```
    Creates an array of literals.
  - row
```
public static ApiExpression row(Object head,
                                Object... tail)
```
    Creates a row of expressions.
  - map
```
public static ApiExpression map(Object key,
                                Object value,
                                Object... tail)
```
    Creates a map of expressions.
```
 table.select(
     map(
         "key1", 1,
         "key2", 2,
         "key3", 3
     ))
 
```
    Note keys and values should have the same types for all entries.
  - rowInterval
```
public static ApiExpression rowInterval(Long rows)
```
    Creates an interval of rows.
    
    See Also:
    
    Table.window(GroupWindow), Table.window(OverWindow...)
  - pi
```
public static ApiExpression pi()
```
    Returns a value that is closer than any other value to pi.
  - e
```
public static ApiExpression e()
```
    Returns a value that is closer than any other value to e.
  - rand
```
public static ApiExpression rand()
```
    Returns a pseudorandom double value between 0.0 (inclusive) and 1.0 (exclusive).
  - rand
```
public static ApiExpression rand(Object seed)
```
    Returns a pseudorandom double value between 0.0 (inclusive) and 1.0 (exclusive) with a initial seed. Two rand() functions will return identical sequences of numbers if they have same initial seed.
  - randInteger
```
public static ApiExpression randInteger(Object bound)
```
    Returns a pseudorandom integer value between 0.0 (inclusive) and the specified value (exclusive).
  - randInteger
```
public static ApiExpression randInteger(Object seed,
                                        Object bound)
```
    Returns a pseudorandom integer value between 0.0 (inclusive) and the specified value (exclusive) with a initial seed. Two randInteger() functions will return identical sequences of numbers if they have same initial seed and same bound.
  - concat
```
public static ApiExpression concat(Object string,
                                   Object... strings)
```
    Returns the string that results from concatenating the arguments. Returns NULL if any argument is NULL.
  - atan2
```
public static ApiExpression atan2(Object y,
                                  Object x)
```
    Calculates the arc tangent of a given coordinate.
  - negative
```
public static ApiExpression negative(Object v)
```
    Returns negative numeric.
  - concatWs
```
public static ApiExpression concatWs(Object separator,
                                     Object string,
                                     Object... strings)
```
    Returns the string that results from concatenating the arguments and separator. Returns NULL If the separator is NULL.
    Note: this function does not skip empty strings. However, it does skip any NULL values after the separator argument.
  - uuid
```
public static ApiExpression uuid()
```
    Returns an UUID (Universally Unique Identifier) string (e.g., "3d3c68f7-f608-473f-b60c-b0c44ad4cc4e") according to RFC 4122 type 4 (pseudo randomly generated) UUID. The UUID is generated using a cryptographically strong pseudo random number generator.
  - nullOf
```
public static ApiExpression nullOf(DataType dataType)
```
    Returns a null literal value of a given data type.
    e.g. nullOf(DataTypes.INT())
  - nullOf
```
public static ApiExpression nullOf(TypeInformation<?> typeInfo)
```
    Deprecated. This method will be removed in future versions as it uses the old type system. It is recommended to use nullOf(DataType) instead which uses the new type system based on DataTypes. Please make sure to use either the old or the new type system consistently to avoid unintended behavior. See the website documentation for more information.
  - log
```
public static ApiExpression log(Object value)
```
    Calculates the logarithm of the given value.
  - log
```
public static ApiExpression log(Object base,
                                Object value)
```
    Calculates the logarithm of the given value to the given base.
  - ifThenElse
```
public static ApiExpression ifThenElse(Object condition,
                                       Object ifTrue,
                                       Object ifFalse)
```
    Ternary conditional operator that decides which of two other expressions should be evaluated based on a evaluated boolean condition.
    e.g. ifThenElse($("f0") > 5, "A", "B") leads to "A"
    
    Parameters:
    
    condition - boolean condition
    
    ifTrue - expression to be evaluated if condition holds
    
    ifFalse - expression to be evaluated if condition does not hold
  - withColumns
```
public static ApiExpression withColumns(Object head,
                                        Object... tail)
```
    Creates an expression that selects a range of columns. It can be used wherever an array of expression is accepted such as function calls, projections, or groupings.
    A range can either be index-based or name-based. Indices start at 1 and boundaries are inclusive.
    e.g. withColumns(range("b", "c")) or withoutColumns($("*"))
  - withoutColumns
```
public static ApiExpression withoutColumns(Object head,
                                           Object... tail)
```
    Creates an expression that selects all columns except for the given range of columns. It can be used wherever an array of expression is accepted such as function calls, projections, or groupings.
    A range can either be index-based or name-based. Indices start at 1 and boundaries are inclusive.
    e.g. withoutColumns(range("b", "c")) or withoutColumns($("c"))
  - call
```
public static ApiExpression call(String path,
                                 Object... arguments)
```
    A call to a function that will be looked up in a catalog. There are two kinds of functions:
    - System functions - which are identified with one part names
    - Catalog functions - which are identified always with three parts names (catalog, database, function)
    Moreover each function can either be a temporary function or permanent one (which is stored in an external catalog).
    Based on that two properties the resolution order for looking up a function based on the provided functionName is following:
    - Temporary system function
    - System function
    - Temporary catalog function
    - Catalog function
    See Also:
    
    TableEnvironment.useCatalog(String), TableEnvironment.useDatabase(String), TableEnvironment.createTemporaryFunction(java.lang.String, java.lang.Class<? extends org.apache.flink.table.functions.UserDefinedFunction>), TableEnvironment.createTemporarySystemFunction(java.lang.String, java.lang.Class<? extends org.apache.flink.table.functions.UserDefinedFunction>)
  - call
```
public static ApiExpression call(UserDefinedFunction function,
                                 Object... arguments)
```
    A call to an unregistered, inline function.
    For functions that have been registered before and are identified by a name, use call(String, Object...).
  - call
```
public static ApiExpression call(Class<? extends UserDefinedFunction> function,
                                 Object... arguments)
```
    A call to an unregistered, inline function.
    For functions that have been registered before and are identified by a name, use call(String, Object...).

Back to Flink Website

Class Expressions

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

UNBOUNDED_ROW

UNBOUNDED_RANGE

CURRENT_ROW

CURRENT_RANGE

Constructor Detail

Expressions

Method Detail

$

lit

lit

range

range

and

or

currentDate

currentTime

currentTimestamp

localTime

localTimestamp

temporalOverlaps

dateFormat

timestampDiff

array

row

map

rowInterval

pi

e

rand

rand

randInteger

randInteger

concat

atan2

negative

concatWs

uuid

nullOf

nullOf

log

log

ifThenElse

withColumns

withoutColumns

call

call

call