org.apache.flink.table.api

Interface TableEnvironment

All Known Subinterfaces:

BatchTableEnvironment, StreamTableEnvironment, TableEnvironmentInternal

All Known Implementing Classes:

StreamTableEnvironmentImpl, TableEnvironmentImpl

@PublicEvolving
public interface TableEnvironment

A table environment is the base class, entry point, and central context for creating Table and SQL API programs.

It is unified both on a language level for all JVM-based languages (i.e. there is no distinction between Scala and Java API) and for bounded and unbounded data processing.

A table environment is responsible for:

• Connecting to external systems.
• Registering and retrieving Tables and other meta objects from a catalog.
• Executing SQL statements.
• Offering further configuration options.

The syntax for path in methods such as createTemporaryView(String, Table)is following [[catalog-name.]database-name.]object-name, where the catalog name and database are optional. For path resolution see useCatalog(String) and useDatabase(String).

Example: `cat.1`.`db`.`Table` resolves to an object named 'Table' in a catalog named 'cat.1' and database named 'db'.

Note: This environment is meant for pure table programs. If you would like to convert from or to other Flink APIs, it might be necessary to use one of the available language-specific table environments in the corresponding bridging modules.

Method Summary

Modifier and Type	Method and Description
ConnectTableDescriptor	connect(ConnectorDescriptor connectorDescriptor) Deprecated. The SQL CREATE TABLE DDL is richer than this part of the API. This method might be refactored in the next versions. Please use executeSql(ddl) to register a table instead.
static TableEnvironment	create(EnvironmentSettings settings) Creates a table environment that is the entry point and central context for creating Table and SQL API programs.
void	createFunction(String path, Class<? extends UserDefinedFunction> functionClass) Registers a UserDefinedFunction class as a catalog function in the given path.
void	createFunction(String path, Class<? extends UserDefinedFunction> functionClass, boolean ignoreIfExists) Registers a UserDefinedFunction class as a catalog function in the given path.
StatementSet	createStatementSet() Create a StatementSet instance which accepts DML statements or Tables, the planner can optimize all added statements and Tables together and then submit as one job.
void	createTemporaryFunction(String path, Class<? extends UserDefinedFunction> functionClass) Registers a UserDefinedFunction class as a temporary catalog function.
void	createTemporaryFunction(String path, UserDefinedFunction functionInstance) Registers a UserDefinedFunction instance as a temporary catalog function.
void	createTemporarySystemFunction(String name, Class<? extends UserDefinedFunction> functionClass) Registers a UserDefinedFunction class as a temporary system function.
void	createTemporarySystemFunction(String name, UserDefinedFunction functionInstance) Registers a UserDefinedFunction instance as a temporary system function.
void	createTemporaryView(String path, Table view) Registers a Table API object as a temporary view similar to SQL temporary views.
boolean	dropFunction(String path) Drops a catalog function registered in the given path.
boolean	dropTemporaryFunction(String path) Drops a temporary catalog function registered in the given path.
boolean	dropTemporarySystemFunction(String name) Drops a temporary system function registered under the given name.
boolean	dropTemporaryTable(String path) Drops a temporary table registered in the given path.
boolean	dropTemporaryView(String path) Drops a temporary view registered in the given path.
JobExecutionResult	execute(String jobName) Deprecated. use executeSql(String) or Table.executeInsert(String) for single sink, use createStatementSet() for multiple sinks.
TableResult	executeSql(String statement) Execute the given single statement, and return the execution result.
String	explain(boolean extended) Deprecated. use StatementSet.explain(ExplainDetail...).
String	explain(Table table) Deprecated. use Table.explain(ExplainDetail...).
String	explain(Table table, boolean extended) Deprecated. use Table.explain(ExplainDetail...).
String	explainSql(String statement, ExplainDetail... extraDetails) Returns the AST of the specified statement and the execution plan to compute the result of the given statement.
Table	from(String path) Reads a registered table and returns the resulting Table.
Table	fromTableSource(TableSource<?> source) Deprecated.
Table	fromValues(AbstractDataType<?> rowType, Expression... values) Creates a Table from given collection of objects with a given row type.
Table	fromValues(AbstractDataType<?> rowType, Iterable<?> values) Creates a Table from given collection of objects with a given row type.
default Table	fromValues(AbstractDataType<?> rowType, Object... values) Creates a Table from given collection of objects with a given row type.
Table	fromValues(Expression... values) Creates a Table from given values.
Table	fromValues(Iterable<?> values) Creates a Table from given collection of objects.
default Table	fromValues(Object... values) Creates a Table from given values.
Optional<Catalog>	getCatalog(String catalogName) Gets a registered Catalog by name.
String[]	getCompletionHints(String statement, int position) Deprecated. Will be removed in the next release
TableConfig	getConfig() Returns the table config that defines the runtime behavior of the Table API.
String	getCurrentCatalog() Gets the current default catalog name of the current session.
String	getCurrentDatabase() Gets the current default database name of the running session.
void	insertInto(String targetPath, Table table) Deprecated. use Table.executeInsert(String) for single sink, use createStatementSet() for multiple sinks.
void	insertInto(Table table, String sinkPath, String... sinkPathContinued) Deprecated. use Table.executeInsert(String) for single sink, use createStatementSet() for multiple sinks.
String[]	listCatalogs() Gets the names of all catalogs registered in this environment.
String[]	listDatabases() Gets the names of all databases registered in the current catalog.
String[]	listFunctions() Gets the names of all functions in this environment.
String[]	listModules() Gets an array of names of all modules in this environment in the loaded order.
String[]	listTables() Gets the names of all tables available in the current namespace (the current database of the current catalog).
String[]	listTemporaryTables() Gets the names of all temporary tables and views available in the current namespace (the current database of the current catalog).
String[]	listTemporaryViews() Gets the names of all temporary views available in the current namespace (the current database of the current catalog).
String[]	listUserDefinedFunctions() Gets the names of all user defined functions registered in this environment.
String[]	listViews() Gets the names of all views available in the current namespace (the current database of the current catalog).
void	loadModule(String moduleName, Module module) Loads a Module under a unique name.
void	registerCatalog(String catalogName, Catalog catalog) Registers a Catalog under a unique name.
void	registerFunction(String name, ScalarFunction function) Deprecated. Use createTemporarySystemFunction(String, UserDefinedFunction) instead. Please note that the new method also uses the new type system and reflective extraction logic. It might be necessary to update the function implementation as well. See the documentation of ScalarFunction for more information on the new function design.
void	registerTable(String name, Table table) Deprecated. use createTemporaryView(String, Table)
void	registerTableSink(String name, String[] fieldNames, TypeInformation<?>[] fieldTypes, TableSink<?> tableSink) Deprecated. Use executeSql(ddl) to register a table instead.
void	registerTableSink(String name, TableSink<?> configuredSink) Deprecated. Use executeSql(ddl) to register a table instead.
void	registerTableSource(String name, TableSource<?> tableSource) Deprecated. Use executeSql(ddl) to register a table instead.
Table	scan(String... tablePath) Deprecated. use from(String)
Table	sqlQuery(String query) Evaluates a SQL query on registered tables and retrieves the result as a Table.
void	sqlUpdate(String stmt) Deprecated. use executeSql(String) for single statement, use createStatementSet() for multiple DML statements.
void	unloadModule(String moduleName) Unloads a Module with given name.
void	useCatalog(String catalogName) Sets the current catalog to the given value.
void	useDatabase(String databaseName) Sets the current default database.

Method Detail

create

static TableEnvironment create(EnvironmentSettings settings)

Creates a table environment that is the entry point and central context for creating Table and SQL API programs.

It is unified both on a language level for all JVM-based languages (i.e. there is no distinction between Scala and Java API) and for bounded and unbounded data processing.

A table environment is responsible for:

• Connecting to external systems.
• Registering and retrieving Tables and other meta objects from a catalog.
• Executing SQL statements.
• Offering further configuration options.

Note: This environment is meant for pure table programs. If you would like to convert from or to other Flink APIs, it might be necessary to use one of the available language-specific table environments in the corresponding bridging modules.

Parameters:

settings - The environment settings used to instantiate the TableEnvironment.

fromValues

default Table fromValues(Object... values)

Creates a Table from given values.

Examples:

You can use a row(...) expression to create a composite rows:

 tEnv.fromValues(
     row(1, "ABC"),
     row(2L, "ABCDE")
 )
 

will produce a Table with a schema as follows:

 root
 |-- f0: BIGINT NOT NULL     // original types INT and BIGINT are generalized to BIGINT
 |-- f1: VARCHAR(5) NOT NULL // original types CHAR(3) and CHAR(5) are generalized to VARCHAR(5)
                             // it uses VARCHAR instead of CHAR so that no padding is applied
 

The method will derive the types automatically from the input expressions. If types at a certain position differ, the method will try to find a common super type for all types. If a common super type does not exist, an exception will be thrown. If you want to specify the requested type explicitly see fromValues(AbstractDataType, Object...).

It is also possible to use Row object instead of row expressions.

ROWs that are a result of e.g. a function call are not flattened

 public class RowFunction extends ScalarFunction {
     {@literal @}DataTypeHint("ROW<f0 BIGINT, f1 VARCHAR(5)>")
     Row eval();
 }

 tEnv.fromValues(
     call(new RowFunction()),
     call(new RowFunction())
 )
 

will produce a Table with a schema as follows:

 root
 |-- f0: ROW<`f0` BIGINT, `f1` VARCHAR(5)>
 

The row constructor can be dropped to create a table with a single column:

ROWs that are a result of e.g. a function call are not flattened

 tEnv.fromValues(
     1,
     2L,
     3
 )
 

will produce a Table with a schema as follows:

 root
 |-- f0: BIGINT NOT NULL
 

Parameters:

values - Expressions for constructing rows of the VALUES table.

fromValues

default Table fromValues(AbstractDataType<?> rowType,
                         Object... values)

Creates a Table from given collection of objects with a given row type.

The difference between this method and fromValues(Object...) is that the schema can be manually adjusted. It might be helpful for assigning more generic types like e.g. DECIMAL or naming the columns.

Examples:

 tEnv.fromValues(
     DataTypes.ROW(
         DataTypes.FIELD("id", DataTypes.DECIMAL(10, 2)),
         DataTypes.FIELD("name", DataTypes.STRING())
     ),
     row(1, "ABC"),
     row(2L, "ABCDE")
 )
 

will produce a Table with a schema as follows:

 root
 |-- id: DECIMAL(10, 2)
 |-- f1: STRING
 

For more examples see fromValues(Object...).

Parameters:

rowType - Expected row type for the values.

values - Expressions for constructing rows of the VALUES table.

See Also:

fromValues(Object...)

fromValues

Table fromValues(Expression... values)

Creates a Table from given values.

Examples:

You can use a row(...) expression to create a composite rows:

 tEnv.fromValues(
     row(1, "ABC"),
     row(2L, "ABCDE")
 )
 

will produce a Table with a schema as follows:

  root
  |-- f0: BIGINT NOT NULL     // original types INT and BIGINT are generalized to BIGINT
  |-- f1: VARCHAR(5) NOT NULL // original types CHAR(3) and CHAR(5) are generalized to VARCHAR(5)
 	 *                          // it uses VARCHAR instead of CHAR so that no padding is applied
 

The method will derive the types automatically from the input expressions. If types at a certain position differ, the method will try to find a common super type for all types. If a common super type does not exist, an exception will be thrown. If you want to specify the requested type explicitly see #fromValues(DataType, Expression...).

It is also possible to use Row object instead of row expressions.

ROWs that are a result of e.g. a function call are not flattened

 public class RowFunction extends ScalarFunction {
     {@literal @}DataTypeHint("ROW<f0 BIGINT, f1 VARCHAR(5)>")
     Row eval();
 }

 tEnv.fromValues(
     call(new RowFunction()),
     call(new RowFunction())
 )
 

will produce a Table with a schema as follows:

 root
 |-- f0: ROW<`f0` BIGINT, `f1` VARCHAR(5)>
 

The row constructor can be dropped to create a table with a single column:

ROWs that are a result of e.g. a function call are not flattened

 tEnv.fromValues(
     lit(1).plus(2),
     lit(2L),
     lit(3)
 )
 

will produce a Table with a schema as follows:

 root
 |-- f0: BIGINT NOT NULL
 

Parameters:

values - Expressions for constructing rows of the VALUES table.

fromValues

Table fromValues(AbstractDataType<?> rowType,
                 Expression... values)

Creates a Table from given collection of objects with a given row type.

The difference between this method and fromValues(Expression...) is that the schema can be manually adjusted. It might be helpful for assigning more generic types like e.g. DECIMAL or naming the columns.

Examples:

 tEnv.fromValues(
     DataTypes.ROW(
         DataTypes.FIELD("id", DataTypes.DECIMAL(10, 2)),
         DataTypes.FIELD("name", DataTypes.STRING())
     ),
     row(1, "ABC"),
     row(2L, "ABCDE")
 )
 

will produce a Table with a schema as follows:

 root
 |-- id: DECIMAL(10, 2)
 |-- name: STRING
 

For more examples see fromValues(Expression...).

Parameters:

rowType - Expected row type for the values.

values - Expressions for constructing rows of the VALUES table.

See Also:

fromValues(Expression...)

fromValues

Table fromValues(Iterable<?> values)

Creates a Table from given collection of objects.

See fromValues(Object...) for more explanation.

Parameters:

values - Expressions for constructing rows of the VALUES table.

See Also:

fromValues(Object...)

fromValues

Table fromValues(AbstractDataType<?> rowType,
                 Iterable<?> values)

Creates a Table from given collection of objects with a given row type.

See fromValues(AbstractDataType, Object...) for more explanation.

Parameters:

rowType - Expected row type for the values.

values - Expressions for constructing rows of the VALUES table.

See Also:

fromValues(AbstractDataType, Object...)

fromTableSource

@Deprecated
Table fromTableSource(TableSource<?> source)

Deprecated.

Creates a table from a table source.

Parameters:

source - table source used as table

registerCatalog

void registerCatalog(String catalogName,
                     Catalog catalog)

Registers a Catalog under a unique name. All tables registered in the Catalog can be accessed.

Parameters:

catalogName - The name under which the catalog will be registered.

catalog - The catalog to register.

getCatalog

Optional<Catalog> getCatalog(String catalogName)

Gets a registered Catalog by name.

Parameters:

catalogName - The name to look up the Catalog.

Returns:

The requested catalog, empty if there is no registered catalog with given name.

loadModule

void loadModule(String moduleName,
                Module module)

Loads a Module under a unique name. Modules will be kept in the loaded order. ValidationException is thrown when there is already a module with the same name.

Parameters:

moduleName - name of the Module

module - the module instance

unloadModule

void unloadModule(String moduleName)

Unloads a Module with given name. ValidationException is thrown when there is no module with the given name

Parameters:

moduleName - name of the Module

registerFunction

@Deprecated
void registerFunction(String name,
                                  ScalarFunction function)

Deprecated. Use createTemporarySystemFunction(String, UserDefinedFunction) instead. Please note that the new method also uses the new type system and reflective extraction logic. It might be necessary to update the function implementation as well. See the documentation of ScalarFunction for more information on the new function design.

Registers a ScalarFunction under a unique name. Replaces already existing user-defined functions under this name.

createTemporarySystemFunction

@Experimental
void createTemporarySystemFunction(String name,
                                                 Class<? extends UserDefinedFunction> functionClass)

Registers a UserDefinedFunction class as a temporary system function.

Compared to createTemporaryFunction(String, Class), system functions are identified by a global name that is independent of the current catalog and current database. Thus, this method allows to extend the set of built-in system functions like TRIM, ABS, etc.

Temporary functions can shadow permanent ones. If a permanent function under a given name exists, it will be inaccessible in the current session. To make the permanent function available again one can drop the corresponding temporary system function.

Parameters:

name - The name under which the function will be registered globally.

functionClass - The function class containing the implementation.

createTemporarySystemFunction

@Experimental
void createTemporarySystemFunction(String name,
                                                 UserDefinedFunction functionInstance)

Registers a UserDefinedFunction instance as a temporary system function.

Compared to createTemporarySystemFunction(String, Class), this method takes a function instance that might have been parameterized before (e.g. through its constructor). This might be useful for more interactive sessions. Make sure that the instance is Serializable.

Compared to createTemporaryFunction(String, UserDefinedFunction), system functions are identified by a global name that is independent of the current catalog and current database. Thus, this method allows to extend the set of built-in system functions like TRIM, ABS, etc.

Temporary functions can shadow permanent ones. If a permanent function under a given name exists, it will be inaccessible in the current session. To make the permanent function available again one can drop the corresponding temporary system function.

Parameters:

name - The name under which the function will be registered globally.

functionInstance - The (possibly pre-configured) function instance containing the implementation.

dropTemporarySystemFunction

@Experimental
boolean dropTemporarySystemFunction(String name)

Drops a temporary system function registered under the given name.

If a permanent function with the given name exists, it will be used from now on for any queries that reference this name.

Parameters:

name - The name under which the function has been registered globally.

Returns:

true if a function existed under the given name and was removed

createFunction

@Experimental
void createFunction(String path,
                                  Class<? extends UserDefinedFunction> functionClass)

Registers a UserDefinedFunction class as a catalog function in the given path.

Compared to system functions with a globally defined name, catalog functions are always (implicitly or explicitly) identified by a catalog and database.

There must not be another function (temporary or permanent) registered under the same path.

Parameters:

path - The path under which the function will be registered. See also the TableEnvironment class description for the format of the path.

functionClass - The function class containing the implementation.

createFunction

@Experimental
void createFunction(String path,
                                  Class<? extends UserDefinedFunction> functionClass,
                                  boolean ignoreIfExists)

Registers a UserDefinedFunction class as a catalog function in the given path.

Compared to system functions with a globally defined name, catalog functions are always (implicitly or explicitly) identified by a catalog and database.

Parameters:

path - The path under which the function will be registered. See also the TableEnvironment class description for the format of the path.

functionClass - The function class containing the implementation.

ignoreIfExists - If a function exists under the given path and this flag is set, no operation is executed. An exception is thrown otherwise.

dropFunction

@Experimental
boolean dropFunction(String path)

Drops a catalog function registered in the given path.

Parameters:

path - The path under which the function has been registered. See also the TableEnvironment class description for the format of the path.

Returns:

true if a function existed in the given path and was removed

createTemporaryFunction

@Experimental
void createTemporaryFunction(String path,
                                           Class<? extends UserDefinedFunction> functionClass)

Registers a UserDefinedFunction class as a temporary catalog function.

Compared to createTemporarySystemFunction(String, Class) with a globally defined name, catalog functions are always (implicitly or explicitly) identified by a catalog and database.

Temporary functions can shadow permanent ones. If a permanent function under a given name exists, it will be inaccessible in the current session. To make the permanent function available again one can drop the corresponding temporary function.

Parameters:

path - The path under which the function will be registered. See also the TableEnvironment class description for the format of the path.

functionClass - The function class containing the implementation.

createTemporaryFunction

@Experimental
void createTemporaryFunction(String path,
                                           UserDefinedFunction functionInstance)

Registers a UserDefinedFunction instance as a temporary catalog function.

Compared to createTemporaryFunction(String, Class), this method takes a function instance that might have been parameterized before (e.g. through its constructor). This might be useful for more interactive sessions. Make sure that the instance is Serializable.

Compared to createTemporarySystemFunction(String, UserDefinedFunction) with a globally defined name, catalog functions are always (implicitly or explicitly) identified by a catalog and database.

Temporary functions can shadow permanent ones. If a permanent function under a given name exists, it will be inaccessible in the current session. To make the permanent function available again one can drop the corresponding temporary function.

Parameters:

path - The path under which the function will be registered. See also the TableEnvironment class description for the format of the path.

functionInstance - The (possibly pre-configured) function instance containing the implementation.

dropTemporaryFunction

@Experimental
boolean dropTemporaryFunction(String path)

Drops a temporary catalog function registered in the given path.

If a permanent function with the given path exists, it will be used from now on for any queries that reference this path.

Parameters:

path - The path under which the function will be registered. See also the TableEnvironment class description for the format of the path.

Returns:

true if a function existed in the given path and was removed

registerTable

@Deprecated
void registerTable(String name,
                               Table table)

Deprecated. use createTemporaryView(String, Table)

Registers a Table under a unique name in the TableEnvironment's catalog. Registered tables can be referenced in SQL queries.

Temporary objects can shadow permanent ones. If a permanent object in a given path exists, it will be inaccessible in the current session. To make the permanent object available again one can drop the corresponding temporary object.

Parameters:

name - The name under which the table will be registered.

table - The table to register.

createTemporaryView

void createTemporaryView(String path,
                         Table view)

Registers a Table API object as a temporary view similar to SQL temporary views.

Temporary objects can shadow permanent ones. If a permanent object in a given path exists, it will be inaccessible in the current session. To make the permanent object available again one can drop the corresponding temporary object.

Parameters:

path - The path under which the view will be registered. See also the TableEnvironment class description for the format of the path.

view - The view to register.

registerTableSource

@Deprecated
void registerTableSource(String name,
                                     TableSource<?> tableSource)

Deprecated. Use executeSql(ddl) to register a table instead.

Registers an external TableSource in this TableEnvironment's catalog. Registered tables can be referenced in SQL queries.

Temporary objects can shadow permanent ones. If a permanent object in a given path exists, it will be inaccessible in the current session. To make the permanent object available again one can drop the corresponding temporary object.

Parameters:

name - The name under which the TableSource is registered.

tableSource - The TableSource to register.

registerTableSink

@Deprecated
void registerTableSink(String name,
                                   String[] fieldNames,
                                   TypeInformation<?>[] fieldTypes,
                                   TableSink<?> tableSink)

Deprecated. Use executeSql(ddl) to register a table instead.

Registers an external TableSink with given field names and types in this TableEnvironment's catalog. Registered sink tables can be referenced in SQL DML statements.

Temporary objects can shadow permanent ones. If a permanent object in a given path exists, it will be inaccessible in the current session. To make the permanent object available again one can drop the corresponding temporary object.

Parameters:

name - The name under which the TableSink is registered.

fieldNames - The field names to register with the TableSink.

fieldTypes - The field types to register with the TableSink.

tableSink - The TableSink to register.

registerTableSink

@Deprecated
void registerTableSink(String name,
                                   TableSink<?> configuredSink)

Deprecated. Use executeSql(ddl) to register a table instead.

Registers an external TableSink with already configured field names and field types in this TableEnvironment's catalog. Registered sink tables can be referenced in SQL DML statements.

Temporary objects can shadow permanent ones. If a permanent object in a given path exists, it will be inaccessible in the current session. To make the permanent object available again one can drop the corresponding temporary object.

Parameters:

name - The name under which the TableSink is registered.

configuredSink - The configured TableSink to register.

scan

@Deprecated
Table scan(String... tablePath)

Deprecated. use from(String)

Scans a registered table and returns the resulting Table.

A table to scan must be registered in the TableEnvironment. It can be either directly registered or be an external member of a Catalog.

See the documentation of useDatabase(String) or useCatalog(String) for the rules on the path resolution.

Examples:

Scanning a directly registered table.

 Table tab = tableEnv.scan("tableName");
 

Scanning a table from a registered catalog.

 Table tab = tableEnv.scan("catalogName", "dbName", "tableName");
 

Parameters:

tablePath - The path of the table to scan.

Returns:

The resulting Table.

See Also:

useCatalog(String), useDatabase(String)

from

Table from(String path)

Reads a registered table and returns the resulting Table.

A table to scan must be registered in the TableEnvironment.

See the documentation of useDatabase(String) or useCatalog(String) for the rules on the path resolution.

Examples:

Reading a table from default catalog and database.

 Table tab = tableEnv.from("tableName");
 

Reading a table from a registered catalog.

 Table tab = tableEnv.from("catalogName.dbName.tableName");
 

Reading a table from a registered catalog with escaping. Dots in e.g. a database name must be escaped.

 Table tab = tableEnv.from("catalogName.`db.Name`.Table");
 

Parameters:

path - The path of a table API object to scan.

Returns:

Either a table or virtual table (=view).

See Also:

useCatalog(String), useDatabase(String)

insertInto

@Deprecated
void insertInto(Table table,
                            String sinkPath,
                            String... sinkPathContinued)

Deprecated. use Table.executeInsert(String) for single sink, use createStatementSet() for multiple sinks.

Writes the Table to a TableSink that was registered under the specified name.

See the documentation of useDatabase(String) or useCatalog(String) for the rules on the path resolution.

Parameters:

table - The Table to write to the sink.

sinkPath - The first part of the path of the registered TableSink to which the Table is written. This is to ensure at least the name of the TableSink is provided.

sinkPathContinued - The remaining part of the path of the registered TableSink to which the Table is written.

insertInto

@Deprecated
void insertInto(String targetPath,
                            Table table)

Deprecated. use Table.executeInsert(String) for single sink, use createStatementSet() for multiple sinks.

Instructs to write the content of a Table API object into a table.

See the documentation of useDatabase(String) or useCatalog(String) for the rules on the path resolution.

Parameters:

targetPath - The path of the registered TableSink to which the Table is written.

table - The Table to write to the sink.

connect

@Deprecated
ConnectTableDescriptor connect(ConnectorDescriptor connectorDescriptor)

Deprecated. The SQL CREATE TABLE DDL is richer than this part of the API. This method might be refactored in the next versions. Please use executeSql(ddl) to register a table instead.

Creates a temporary table from a descriptor.

Descriptors allow for declaring the communication to external systems in an implementation-agnostic way. The classpath is scanned for suitable table factories that match the desired configuration.

The following example shows how to read from a connector using a JSON format and register a temporary table as "MyTable":

 tableEnv
   .connect(
     new ExternalSystemXYZ()
       .version("0.11"))
   .withFormat(
     new Json()
       .jsonSchema("{...}")
       .failOnMissingField(false))
   .withSchema(
     new Schema()
       .field("user-name", "VARCHAR").from("u_name")
       .field("count", "DECIMAL")
   .createTemporaryTable("MyTable");
 

Parameters:

connectorDescriptor - connector descriptor describing the external system

listCatalogs

String[] listCatalogs()

Gets the names of all catalogs registered in this environment.

Returns:

A list of the names of all registered catalogs.

listModules

String[] listModules()

Gets an array of names of all modules in this environment in the loaded order.

Returns:

A list of the names of all modules in the loaded order.

listDatabases

String[] listDatabases()

Gets the names of all databases registered in the current catalog.

Returns:

A list of the names of all registered databases in the current catalog.

listTables

String[] listTables()

Gets the names of all tables available in the current namespace (the current database of the current catalog). It returns both temporary and permanent tables and views.

Returns:

A list of the names of all registered tables in the current database of the current catalog.

See Also:

listTemporaryTables(), listTemporaryViews()

listViews

String[] listViews()

Gets the names of all views available in the current namespace (the current database of the current catalog). It returns both temporary and permanent views.

Returns:

A list of the names of all registered views in the current database of the current catalog.

See Also:

listTemporaryViews()

listTemporaryTables

String[] listTemporaryTables()

Gets the names of all temporary tables and views available in the current namespace (the current database of the current catalog).

Returns:

A list of the names of all registered temporary tables and views in the current database of the current catalog.

See Also:

listTables()

listTemporaryViews

String[] listTemporaryViews()

Gets the names of all temporary views available in the current namespace (the current database of the current catalog).

Returns:

A list of the names of all registered temporary views in the current database of the current catalog.

See Also:

listTables()

listUserDefinedFunctions

String[] listUserDefinedFunctions()

Gets the names of all user defined functions registered in this environment.

listFunctions

String[] listFunctions()

Gets the names of all functions in this environment.

dropTemporaryTable

boolean dropTemporaryTable(String path)

Drops a temporary table registered in the given path.

If a permanent table with a given path exists, it will be used from now on for any queries that reference this path.

Returns:

true if a table existed in the given path and was removed

dropTemporaryView

boolean dropTemporaryView(String path)

Drops a temporary view registered in the given path.

If a permanent table or view with a given path exists, it will be used from now on for any queries that reference this path.

Returns:

true if a view existed in the given path and was removed

explain

@Deprecated
String explain(Table table)

Deprecated. use Table.explain(ExplainDetail...).

Returns the AST of the specified Table API and SQL queries and the execution plan to compute the result of the given Table.

Parameters:

table - The table for which the AST and execution plan will be returned.

explain

@Deprecated
String explain(Table table,
                           boolean extended)

Deprecated. use Table.explain(ExplainDetail...).

Returns the AST of the specified Table API and SQL queries and the execution plan to compute the result of the given Table.

Parameters:

table - The table for which the AST and execution plan will be returned.

extended - if the plan should contain additional properties, e.g. estimated cost, traits

explain

@Deprecated
String explain(boolean extended)

Deprecated. use StatementSet.explain(ExplainDetail...).

Returns the AST of the specified Table API and SQL queries and the execution plan to compute the result of multiple-sinks plan.

Parameters:

extended - if the plan should contain additional properties, e.g. estimated cost, traits

explainSql

String explainSql(String statement,
                  ExplainDetail... extraDetails)

Returns the AST of the specified statement and the execution plan to compute the result of the given statement.

Parameters:

statement - The statement for which the AST and execution plan will be returned.

extraDetails - The extra explain details which the explain result should include, e.g. estimated cost, changelog mode for streaming

Returns:

AST and the execution plan.

getCompletionHints

@Deprecated
String[] getCompletionHints(String statement,
                                        int position)

Deprecated. Will be removed in the next release

Returns completion hints for the given statement at the given cursor position. The completion happens case insensitively.

Parameters:

statement - Partial or slightly incorrect SQL statement

position - cursor position

Returns:

completion hints that fit at the current cursor position

sqlQuery

Table sqlQuery(String query)

Evaluates a SQL query on registered tables and retrieves the result as a Table.

All tables referenced by the query must be registered in the TableEnvironment. A Table is automatically registered when its Table#toString() method is called, for example when it is embedded into a String. Hence, SQL queries can directly reference a Table as follows:

 Table table = ...;
 String tableName = table.toString();
 // the table is not registered to the table environment
 tEnv.sqlQuery("SELECT * FROM tableName");
 

Parameters:

query - The SQL query to evaluate.

Returns:

The result of the query as Table

executeSql

TableResult executeSql(String statement)

Execute the given single statement, and return the execution result.

The statement can be DDL/DML/DQL/SHOW/DESCRIBE/EXPLAIN/USE. For DML and DQL, this method returns TableResult once the job has been submitted. For DDL and DCL statements, TableResult is returned once the operation has finished.

Returns:

content for DQL/SHOW/DESCRIBE/EXPLAIN, the affected row count for `DML` (-1 means unknown), or a string message ("OK") for other statements.

sqlUpdate

@Deprecated
void sqlUpdate(String stmt)

Deprecated. use executeSql(String) for single statement, use createStatementSet() for multiple DML statements.

Evaluates a SQL statement such as INSERT, UPDATE or DELETE; or a DDL statement; NOTE: Currently only SQL INSERT statements and CREATE TABLE statements are supported.

All tables referenced by the query must be registered in the TableEnvironment. A Table is automatically registered when its Table#toString() method is called, for example when it is embedded into a String. Hence, SQL queries can directly reference a Table as follows:

 // register the configured table sink into which the result is inserted.
 tEnv.registerTableSinkInternal("sinkTable", configuredSink);
 Table sourceTable = ...
 String tableName = sourceTable.toString();
 // sourceTable is not registered to the table environment
 tEnv.sqlUpdate(s"INSERT INTO sinkTable SELECT * FROM tableName");
 

A DDL statement can also be executed to create a table: For example, the below DDL statement would create a CSV table named `tbl1` into the current catalog:

    create table tbl1(
      a int,
      b bigint,
      c varchar
    ) with (
      'connector.type' = 'filesystem',
      'format.type' = 'csv',
      'connector.path' = 'xxx'
    )
 

SQL queries can directly execute as follows:

    String sinkDDL = "create table sinkTable(
                        a int,
                        b varchar
                      ) with (
                        'connector.type' = 'filesystem',
                        'format.type' = 'csv',
                        'connector.path' = 'xxx'
                      )";

    String sourceDDL ="create table sourceTable(
                        a int,
                        b varchar
                      ) with (
                        'connector.type' = 'kafka',
                        'update-mode' = 'append',
                        'connector.topic' = 'xxx',
                        'connector.properties.bootstrap.servers' = 'localhost:9092',
                        ...
                      )";

    String query = "INSERT INTO sinkTable SELECT * FROM sourceTable";

    tEnv.sqlUpdate(sourceDDL);
    tEnv.sqlUpdate(sinkDDL);
    tEnv.sqlUpdate(query);
    tEnv.execute("MyJob");
 

This code snippet creates a job to read data from Kafka source into a CSV sink.

Parameters:

stmt - The SQL statement to evaluate.

getCurrentCatalog

String getCurrentCatalog()

Gets the current default catalog name of the current session.

Returns:

The current default catalog name that is used for the path resolution.

See Also:

useCatalog(String)

useCatalog

void useCatalog(String catalogName)

Sets the current catalog to the given value. It also sets the default database to the catalog's default one. See also useDatabase(String).

This is used during the resolution of object paths. Both the catalog and database are optional when referencing catalog objects such as tables, views etc. The algorithm looks for requested objects in following paths in that order:

1. [current-catalog].[current-database].[requested-path]
2. [current-catalog].[requested-path]
3. [requested-path]

Example:

Given structure with default catalog set to default_catalog and default database set to default_database.

 root:
   |- default_catalog
       |- default_database
           |- tab1
       |- db1
           |- tab1
   |- cat1
       |- db1
           |- tab1
 

The following table describes resolved paths:

Requested path	Resolved path
tab1	default_catalog.default_database.tab1
db1.tab1	default_catalog.db1.tab1
cat1.db1.tab1	cat1.db1.tab1

Parameters:

catalogName - The name of the catalog to set as the current default catalog.

See Also:

useDatabase(String)

getCurrentDatabase

String getCurrentDatabase()

Gets the current default database name of the running session.

Returns:

The name of the current database of the current catalog.

See Also:

useDatabase(String)

useDatabase

void useDatabase(String databaseName)

Sets the current default database. It has to exist in the current catalog. That path will be used as the default one when looking for unqualified object names.

This is used during the resolution of object paths. Both the catalog and database are optional when referencing catalog objects such as tables, views etc. The algorithm looks for requested objects in following paths in that order:

1. [current-catalog].[current-database].[requested-path]
2. [current-catalog].[requested-path]
3. [requested-path]

Example:

Given structure with default catalog set to default_catalog and default database set to default_database.

 root:
   |- default_catalog
       |- default_database
           |- tab1
       |- db1
           |- tab1
   |- cat1
       |- db1
           |- tab1
 

The following table describes resolved paths:

Requested path	Resolved path
tab1	default_catalog.default_database.tab1
db1.tab1	default_catalog.db1.tab1
cat1.db1.tab1	cat1.db1.tab1

Parameters:

databaseName - The name of the database to set as the current database.

See Also:

useCatalog(String)

getConfig

TableConfig getConfig()

Returns the table config that defines the runtime behavior of the Table API.

execute

@Deprecated
JobExecutionResult execute(String jobName)
                                throws Exception

Deprecated. use executeSql(String) or Table.executeInsert(String) for single sink, use createStatementSet() for multiple sinks.

Triggers the program execution. The environment will execute all parts of the program.

The program execution will be logged and displayed with the provided name

NOTE:It is highly advised to set all parameters in the TableConfig on the very beginning of the program. It is undefined what configurations values will be used for the execution if queries are mixed with config changes. It depends on the characteristic of the particular parameter. For some of them the value from the point in time of query construction (e.g. the currentCatalog) will be used. On the other hand some values might be evaluated according to the state from the time when this method is called (e.g. timeZone).

Once the execution finishes, any previously defined DMLs will be cleared, no matter whether the execution succeeds or not. Therefore, if you want to retry in case of failures, you have to re-define the DMLs, i.e. by calling sqlUpdate(String), before you call this method again.

Parameters:

jobName - Desired name of the job

Returns:

The result of the job execution, containing elapsed time and accumulators.

Throws:

Exception - which occurs during job execution.

createStatementSet

StatementSet createStatementSet()

Create a StatementSet instance which accepts DML statements or Tables, the planner can optimize all added statements and Tables together and then submit as one job.