Catalogs

Catalog 提供了元数据信息，例如数据库、表、分区、视图以及数据库或其他外部系统中存储的函数和信息。

数据处理最关键的方面之一是管理元数据。 元数据可以是临时的，例如临时表、或者通过 TableEnvironment 注册的 UDF。 元数据也可以是持久化的，例如 Hive Metastore 中的元数据。Catalog 提供了一个统一的API，用于管理元数据，并使其可以从 Table API 和 SQL 查询语句中来访问。

Catalog 类型

GenericInMemoryCatalog

GenericInMemoryCatalog 是基于内存实现的 Catalog，所有元数据只在 session 的生命周期内可用。

JdbcCatalog

JdbcCatalog 使得用户可以将 Flink 通过 JDBC 协议连接到关系数据库。Postgres Catalog 和 MySQL Catalog 是目前 JDBC Catalog 仅有的两种实现。 参考 JdbcCatalog 文档 获取关于配置 JDBC catalog 的详细信息。

HiveCatalog

HiveCatalog 有两个用途：作为原生 Flink 元数据的持久化存储，以及作为读写现有 Hive 元数据的接口。 Flink 的 Hive 文档 提供了有关设置 HiveCatalog 以及访问现有 Hive 元数据的详细信息。

警告 Hive Metastore 以小写形式存储所有元数据对象名称。而 GenericInMemoryCatalog 区分大小写。

用户自定义 Catalog

Catalog 是可扩展的，用户可以通过实现 Catalog 接口来开发自定义 Catalog。 想要在 SQL CLI 中使用自定义 Catalog，用户除了需要实现自定义的 Catalog 之外，还需要为这个 Catalog 实现对应的 CatalogFactory 接口。

CatalogFactory 定义了一组属性，用于 SQL CLI 启动时配置 Catalog。 这组属性集将传递给发现服务，在该服务中，服务会尝试将属性关联到 CatalogFactory 并初始化相应的 Catalog 实例。

从 Flink v1.16 开始, TableEnvironment 引入了一个用户类加载器，以在 table 程序、SQL Client、SQL Gateway 中保持一致的类加载行为。该类加载器会统一管理所有的用户 jar 包，包括通过 ADD JAR 或 CREATE FUNCTION .. USING JAR .. 添加的 jar 资源。 在用户自定义 catalog 中，应该将 Thread.currentThread().getContextClassLoader() 替换成该用户类加载器去加载类。否则，可能会发生 ClassNotFoundException 的异常。该用户类加载器可以通过 CatalogFactory.Context#getClassLoader 获得。

如何创建 Flink 表并将其注册到 Catalog

使用 SQL DDL

用户可以使用 DDL 通过 Table API 或者 SQL Client 在 Catalog 中创建表。

Java

  1. TableEnvironment tableEnv = ...;
  3. // Create a HiveCatalog 
  4. Catalog catalog = new HiveCatalog("myhive", null, "<path_of_hive_conf>");
  6. // Register the catalog
  7. tableEnv.registerCatalog("myhive", catalog);
  9. // Create a catalog database
  10. tableEnv.executeSql("CREATE DATABASE mydb WITH (...)");
  12. // Create a catalog table
  13. tableEnv.executeSql("CREATE TABLE mytable (name STRING, age INT) WITH (...)");
  15. tableEnv.listTables(); // should return the tables in current catalog and database.

Scala

  1. val tableEnv = ...
  3. // Create a HiveCatalog 
  4. val catalog = new HiveCatalog("myhive", null, "<path_of_hive_conf>");
  6. // Register the catalog
  7. tableEnv.registerCatalog("myhive", catalog);
  9. // Create a catalog database
  10. tableEnv.executeSql("CREATE DATABASE mydb WITH (...)");
  12. // Create a catalog table
  13. tableEnv.executeSql("CREATE TABLE mytable (name STRING, age INT) WITH (...)");
  15. tableEnv.listTables(); // should return the tables in current catalog and database.

Python

  1. from pyflink.table.catalog import HiveCatalog
  3. # Create a HiveCatalog
  4. catalog = HiveCatalog("myhive", None, "<path_of_hive_conf>")
  6. # Register the catalog
  7. t_env.register_catalog("myhive", catalog)
  9. # Create a catalog database
  10. t_env.execute_sql("CREATE DATABASE mydb WITH (...)")
  12. # Create a catalog table
  13. t_env.execute_sql("CREATE TABLE mytable (name STRING, age INT) WITH (...)")
  15. # should return the tables in current catalog and database.
  16. t_env.list_tables()

SQL Client

  1. // the catalog should have been registered via yaml file
  2. Flink SQL> CREATE DATABASE mydb WITH (...);
  4. Flink SQL> CREATE TABLE mytable (name STRING, age INT) WITH (...);
  6. Flink SQL> SHOW TABLES;
  7. mytable

更多详细信息，请参考Flink SQL CREATE DDL。

使用 Java/Scala

用户可以用编程的方式使用Java 或者 Scala 来创建 Catalog 表。

Java

  1. import org.apache.flink.table.api.*;
  2. import org.apache.flink.table.catalog.*;
  3. import org.apache.flink.table.catalog.hive.HiveCatalog;
  5. TableEnvironment tableEnv = TableEnvironment.create(EnvironmentSettings.inStreamingMode());
  7. // Create a HiveCatalog
  8. Catalog catalog = new HiveCatalog("myhive", null, "<path_of_hive_conf>");
  10. // Register the catalog
  11. tableEnv.registerCatalog("myhive", catalog);
  13. // Create a catalog database
  14. catalog.createDatabase("mydb", new CatalogDatabaseImpl(...));
  16. // Create a catalog table
  17. final Schema schema = Schema.newBuilder()
  18.     .column("name", DataTypes.STRING())
  19.     .column("age", DataTypes.INT())
  20.     .build();
  22. tableEnv.createTable("myhive.mydb.mytable", TableDescriptor.forConnector("kafka")
  23.     .schema(schema)
  24.     // …
  25.     .build());
  27. List<String> tables = catalog.listTables("mydb"); // tables should contain "mytable"

Scala

  1. import org.apache.flink.table.api._
  2. import org.apache.flink.table.catalog._
  3. import org.apache.flink.table.catalog.hive.HiveCatalog
  5. val tableEnv = TableEnvironment.create(EnvironmentSettings.inStreamingMode())
  7. // Create a HiveCatalog
  8. val catalog = new HiveCatalog("myhive", null, "<path_of_hive_conf>")
  10. // Register the catalog
  11. tableEnv.registerCatalog("myhive", catalog)
  13. // Create a catalog database
  14. catalog.createDatabase("mydb", new CatalogDatabaseImpl(...))
  16. // Create a catalog table
  17. val schema = Schema.newBuilder()
  18.     .column("name", DataTypes.STRING())
  19.     .column("age", DataTypes.INT())
  20.     .build()
  22. tableEnv.createTable("myhive.mydb.mytable", TableDescriptor.forConnector("kafka")
  23.     .schema(schema)
  24.     // …
  25.     .build())
  27. val tables = catalog.listTables("mydb") // tables should contain "mytable"

Python

  1. from pyflink.table import *
  2. from pyflink.table.catalog import HiveCatalog, CatalogDatabase, ObjectPath, CatalogBaseTable
  3. from pyflink.table.descriptors import Kafka
  5. settings = EnvironmentSettings.in_batch_mode()
  6. t_env = TableEnvironment.create(settings)
  8. # Create a HiveCatalog
  9. catalog = HiveCatalog("myhive", None, "<path_of_hive_conf>")
  11. # Register the catalog
  12. t_env.register_catalog("myhive", catalog)
  14. # Create a catalog database
  15. database = CatalogDatabase.create_instance({"k1": "v1"}, None)
  16. catalog.create_database("mydb", database)
  18. # Create a catalog table
  19. schema = Schema.new_builder() \
  20.     .column("name", DataTypes.STRING()) \
  21.     .column("age", DataTypes.INT()) \
  22.     .build()
  24. catalog_table = t_env.create_table("myhive.mydb.mytable", TableDescriptor.for_connector("kafka")
  25.     .schema(schema)
  26.     # …
  27.     .build())
  29. # tables should contain "mytable"
  30. tables = catalog.list_tables("mydb")

Catalog API

注意：这里只列出了编程方式的 Catalog API，用户可以使用 SQL DDL 实现许多相同的功能。 关于 DDL 的详细信息请参考 SQL CREATE DDL。

数据库操作

Java/Scala

  1. // create database
  2. catalog.createDatabase("mydb", new CatalogDatabaseImpl(...), false);
  4. // drop database
  5. catalog.dropDatabase("mydb", false);
  7. // alter database
  8. catalog.alterDatabase("mydb", new CatalogDatabaseImpl(...), false);
  10. // get database
  11. catalog.getDatabase("mydb");
  13. // check if a database exist
  14. catalog.databaseExists("mydb");
  16. // list databases in a catalog
  17. catalog.listDatabases("mycatalog");

Python

  1. from pyflink.table.catalog import CatalogDatabase
  3. # create database
  4. catalog_database = CatalogDatabase.create_instance({"k1": "v1"}, None)
  5. catalog.create_database("mydb", catalog_database, False)
  7. # drop database
  8. catalog.drop_database("mydb", False)
  10. # alter database
  11. catalog.alter_database("mydb", catalog_database, False)
  13. # get database
  14. catalog.get_database("mydb")
  16. # check if a database exist
  17. catalog.database_exists("mydb")
  19. # list databases in a catalog
  20. catalog.list_databases()

表操作

Java/Scala

  1. // create table
  2. catalog.createTable(new ObjectPath("mydb", "mytable"), new CatalogTableImpl(...), false);
  4. // drop table
  5. catalog.dropTable(new ObjectPath("mydb", "mytable"), false);
  7. // alter table
  8. catalog.alterTable(new ObjectPath("mydb", "mytable"), new CatalogTableImpl(...), false);
  10. // rename table
  11. catalog.renameTable(new ObjectPath("mydb", "mytable"), "my_new_table");
  13. // get table
  14. catalog.getTable("mytable");
  16. // check if a table exist or not
  17. catalog.tableExists("mytable");
  19. // list tables in a database
  20. catalog.listTables("mydb");

Python

  1. from pyflink.table import *
  2. from pyflink.table.catalog import CatalogBaseTable, ObjectPath
  3. from pyflink.table.descriptors import Kafka
  5. table_schema = TableSchema.builder() \
  6.     .field("name", DataTypes.STRING()) \
  7.     .field("age", DataTypes.INT()) \
  8.     .build()
  10. table_properties = Kafka() \
  11.     .version("0.11") \
  12.     .start_from_earlist() \
  13.     .to_properties()
  15. catalog_table = CatalogBaseTable.create_table(schema=table_schema, properties=table_properties, comment="my comment")
  17. # create table
  18. catalog.create_table(ObjectPath("mydb", "mytable"), catalog_table, False)
  20. # drop table
  21. catalog.drop_table(ObjectPath("mydb", "mytable"), False)
  23. # alter table
  24. catalog.alter_table(ObjectPath("mydb", "mytable"), catalog_table, False)
  26. # rename table
  27. catalog.rename_table(ObjectPath("mydb", "mytable"), "my_new_table")
  29. # get table
  30. catalog.get_table("mytable")
  32. # check if a table exist or not
  33. catalog.table_exists("mytable")
  35. # list tables in a database
  36. catalog.list_tables("mydb")

视图操作

Java/Scala

  1. // create view
  2. catalog.createTable(new ObjectPath("mydb", "myview"), new CatalogViewImpl(...), false);
  4. // drop view
  5. catalog.dropTable(new ObjectPath("mydb", "myview"), false);
  7. // alter view
  8. catalog.alterTable(new ObjectPath("mydb", "mytable"), new CatalogViewImpl(...), false);
  10. // rename view
  11. catalog.renameTable(new ObjectPath("mydb", "myview"), "my_new_view", false);
  13. // get view
  14. catalog.getTable("myview");
  16. // check if a view exist or not
  17. catalog.tableExists("mytable");
  19. // list views in a database
  20. catalog.listViews("mydb");

Python

  1. from pyflink.table import *
  2. from pyflink.table.catalog import CatalogBaseTable, ObjectPath
  4. table_schema = TableSchema.builder() \
  5.     .field("name", DataTypes.STRING()) \
  6.     .field("age", DataTypes.INT()) \
  7.     .build()
  9. catalog_table = CatalogBaseTable.create_view(
  10.     original_query="select * from t1",
  11.     expanded_query="select * from test-catalog.db1.t1",
  12.     schema=table_schema,
  13.     properties={},
  14.     comment="This is a view"
  15. )
  17. catalog.create_table(ObjectPath("mydb", "myview"), catalog_table, False)
  19. # drop view
  20. catalog.drop_table(ObjectPath("mydb", "myview"), False)
  22. # alter view
  23. catalog.alter_table(ObjectPath("mydb", "mytable"), catalog_table, False)
  25. # rename view
  26. catalog.rename_table(ObjectPath("mydb", "myview"), "my_new_view", False)
  28. # get view
  29. catalog.get_table("myview")
  31. # check if a view exist or not
  32. catalog.table_exists("mytable")
  34. # list views in a database
  35. catalog.list_views("mydb")

分区操作

Java/Scala

  1. // create view
  2. catalog.createPartition(
  3.     new ObjectPath("mydb", "mytable"),
  4.     new CatalogPartitionSpec(...),
  5.     new CatalogPartitionImpl(...),
  6.     false);
  8. // drop partition
  9. catalog.dropPartition(new ObjectPath("mydb", "mytable"), new CatalogPartitionSpec(...), false);
  11. // alter partition
  12. catalog.alterPartition(
  13.     new ObjectPath("mydb", "mytable"),
  14.     new CatalogPartitionSpec(...),
  15.     new CatalogPartitionImpl(...),
  16.     false);
  18. // get partition
  19. catalog.getPartition(new ObjectPath("mydb", "mytable"), new CatalogPartitionSpec(...));
  21. // check if a partition exist or not
  22. catalog.partitionExists(new ObjectPath("mydb", "mytable"), new CatalogPartitionSpec(...));
  24. // list partitions of a table
  25. catalog.listPartitions(new ObjectPath("mydb", "mytable"));
  27. // list partitions of a table under a give partition spec
  28. catalog.listPartitions(new ObjectPath("mydb", "mytable"), new CatalogPartitionSpec(...));
  30. // list partitions of a table by expression filter
  31. catalog.listPartitions(new ObjectPath("mydb", "mytable"), Arrays.asList(epr1, ...));

Python

  1. from pyflink.table.catalog import ObjectPath, CatalogPartitionSpec, CatalogPartition
  3. catalog_partition = CatalogPartition.create_instance({}, "my partition")
  5. catalog_partition_spec = CatalogPartitionSpec({"third": "2010", "second": "bob"})
  6. catalog.create_partition(
  7.     ObjectPath("mydb", "mytable"),
  8.     catalog_partition_spec,
  9.     catalog_partition,
  10.     False)
  12. # drop partition
  13. catalog.drop_partition(ObjectPath("mydb", "mytable"), catalog_partition_spec, False)
  15. # alter partition
  16. catalog.alter_partition(
  17.     ObjectPath("mydb", "mytable"),
  18.     CatalogPartitionSpec(...),
  19.     catalog_partition,
  20.     False)
  22. # get partition
  23. catalog.get_partition(ObjectPath("mydb", "mytable"), catalog_partition_spec)
  25. # check if a partition exist or not
  26. catalog.partition_exists(ObjectPath("mydb", "mytable"), catalog_partition_spec)
  28. # list partitions of a table
  29. catalog.list_partitions(ObjectPath("mydb", "mytable"))
  31. # list partitions of a table under a give partition spec
  32. catalog.list_partitions(ObjectPath("mydb", "mytable"), catalog_partition_spec)

函数操作

Java/Scala

  1. // create function
  2. catalog.createFunction(new ObjectPath("mydb", "myfunc"), new CatalogFunctionImpl(...), false);
  4. // drop function
  5. catalog.dropFunction(new ObjectPath("mydb", "myfunc"), false);
  7. // alter function
  8. catalog.alterFunction(new ObjectPath("mydb", "myfunc"), new CatalogFunctionImpl(...), false);
  10. // get function
  11. catalog.getFunction("myfunc");
  13. // check if a function exist or not
  14. catalog.functionExists("myfunc");
  16. // list functions in a database
  17. catalog.listFunctions("mydb");

Python

  1. from pyflink.table.catalog import ObjectPath, CatalogFunction
  3. catalog_function = CatalogFunction.create_instance(class_name="my.python.udf")
  5. # create function
  6. catalog.create_function(ObjectPath("mydb", "myfunc"), catalog_function, False)
  8. # drop function
  9. catalog.drop_function(ObjectPath("mydb", "myfunc"), False)
  11. # alter function
  12. catalog.alter_function(ObjectPath("mydb", "myfunc"), catalog_function, False)
  14. # get function
  15. catalog.get_function("myfunc")
  17. # check if a function exist or not
  18. catalog.function_exists("myfunc")
  20. # list functions in a database
  21. catalog.list_functions("mydb")

通过 Table API 和 SQL Client 操作 Catalog

注册 Catalog

用户可以访问默认创建的内存 Catalog default_catalog，这个 Catalog 默认拥有一个默认数据库 default_database。 用户也可以注册其他的 Catalog 到现有的 Flink 会话中。

Java/Scala

  1. tableEnv.registerCatalog(new CustomCatalog("myCatalog"));

Python

  1. t_env.register_catalog(catalog)

YAML

使用 YAML 定义的 Catalog 必须提供 type 属性，以表示指定的 Catalog 类型。 以下几种类型可以直接使用。

CatalogType Value
GenericInMemorygeneric_in_memory
Hivehive
  1. catalogs:
  2.    - name: myCatalog
  3.      type: custom_catalog
  4.      hive-conf-dir: ...

修改当前的 Catalog 和数据库

Flink 始终在当前的 Catalog 和数据库中寻找表、视图和 UDF。

Java/Scala

  1. tableEnv.useCatalog("myCatalog");
  2. tableEnv.useDatabase("myDb");

Python

  1. t_env.use_catalog("myCatalog")
  2. t_env.use_database("myDb")

SQL

  1. Flink SQL> USE CATALOG myCatalog;
  2. Flink SQL> USE myDB;

通过提供全限定名 catalog.database.object 来访问不在当前 Catalog 中的元数据信息。

Java/Scala

  1. tableEnv.from("not_the_current_catalog.not_the_current_db.my_table");

Python

  1. t_env.from_path("not_the_current_catalog.not_the_current_db.my_table")

SQL

  1. Flink SQL> SELECT * FROM not_the_current_catalog.not_the_current_db.my_table;

列出可用的 Catalog

Java/Scala

  1. tableEnv.listCatalogs();

Python

  1. t_env.list_catalogs()

SQL

  1. Flink SQL> show catalogs;

列出可用的数据库

Java/Scala

  1. tableEnv.listDatabases();

Python

  1. t_env.list_databases()

SQL

  1. Flink SQL> show databases;

列出可用的表

Java/Scala

  1. tableEnv.listTables();

Python

  1. t_env.list_tables()

SQL

  1. Flink SQL> show tables;