From 9dab1ee91afe9e87993fa398a84e507b31955627 Mon Sep 17 00:00:00 2001 From: Zzm0809 <934230207@qq.com> Date: Fri, 1 Mar 2024 20:05:45 +0800 Subject: [PATCH] [Feature] Add addfile syntax document (#3211) --- .../src/main/resources/db/db-h2-dml.sql | 18 ++---- .../expand_statements/add_file_statement.md | 59 +++++++++++++++++++ .../expand_statements/add_jar_statement.md | 6 +- script/sql/dinky-mysql.sql | 8 ++- script/sql/dinky-pg.sql | 14 ++--- .../upgrade/1.0.0_schema/mysql/dinky_dml.sql | 10 ++-- 6 files changed, 82 insertions(+), 33 deletions(-) create mode 100644 docs/docs/extend/expand_statements/add_file_statement.md diff --git a/dinky-admin/src/main/resources/db/db-h2-dml.sql b/dinky-admin/src/main/resources/db/db-h2-dml.sql index cf04d65ca4..894558ffa3 100644 --- a/dinky-admin/src/main/resources/db/db-h2-dml.sql +++ b/dinky-admin/src/main/resources/db/db-h2-dml.sql @@ -2223,12 +2223,6 @@ VALUES ( 233, 'Reference', 'SQL_TEMPLATE', 'FlinkCDC', 'EXECUTE CDCSOURCE mysql2 INSERT INTO dinky_flink_document ( id, category, type, subtype, name , description, fill_value, version, like_num, enabled , create_time, update_time, creator, updater) -VALUES ( 234, 'Reference', 'FUN_UDF', 'OTHER_FUNCTION', 'ADD JAR' - , 'ADD JAR', 'ADD JAR ${1:}; -- str path ', 'All Versions', 0, 1 - , '2023-10-31 16:19:52', '2023-12-28 00:02:02', NULL, NULL); -INSERT INTO dinky_flink_document ( id, category, type, subtype, name - , description, fill_value, version, like_num, enabled - , create_time, update_time, creator, updater) VALUES ( 235, 'Function', 'Other', 'Other', 'SHOW FRAGMENTS' , 'SHOW FRAGMENTS', 'SHOW FRAGMENTS;', 'All Versions', 0, 1 , '2023-10-31 16:20:30', '2023-12-28 09:57:55', NULL, NULL); @@ -2465,13 +2459,11 @@ WITH ''sink.auto-create'' = ''true'', );', 'All Versions', 0, 1 , '2023-12-27 16:53:37', '2023-12-28 12:05:20', 1, 1); -INSERT INTO dinky_flink_document ( id, category, type, subtype, name - , description, fill_value, version, like_num, enabled - , create_time, update_time, creator, updater) -VALUES ( 248, 'Reference', 'FUN_UDF', 'OTHER_FUNCTION', 'add-customjar' - , 'add CUSTOMJAR 为 Dinky 扩展语法 功能实现和 add jar 类似 , 推荐使用此方式', '-- add CUSTOMJAR 为 Dinky 扩展语法 功能实现和 add jar 类似 , 推荐使用此方式 -add CUSTOMJAR ''${1:}'';', 'All Versions', 0, 1 - , '2023-12-28 10:50:17', '2023-12-28 15:49:40', 1, 1); +insert into dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) values (248, 'Variable', 'FUN_UDF', 'OTHER_FUNCTION', 'ADD-CUSTOMJAR', 'add CUSTOMJAR 为 Dinky 扩展语法 功能实现和 add jar 类似 , 推荐使用此方式', '-- add CUSTOMJAR 为 Dinky 扩展语法 功能实现和 add jar 类似 , 推荐使用此方式 +ADD CUSTOMJAR ''${1:}'';', 'All Versions', 0, 1, '2023-12-28 10:50:17', '2024-03-01 17:15:44', 1, 1); +insert into dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) values (249, 'Variable', 'FUN_UDF', 'OTHER_FUNCTION', 'ADD-FILE', 'ADD FILE 为 Dinky 扩展语法 可以向环境中添加依赖jar(与ADD CUSTOMJAR 一致) 还可以添加其他类型的文件 +', '-- ADD FILE 为 Dinky 扩展语法 可以向环境中添加依赖jar(与add customjar 一致) 还可以添加其他类型的文件 +ADD FILE ''${1:}''; -- str path ', 'All Versions', 0, 1, '2024-03-01 17:13:05', '2024-03-01 17:15:55', 1, 1); diff --git a/docs/docs/extend/expand_statements/add_file_statement.md b/docs/docs/extend/expand_statements/add_file_statement.md new file mode 100644 index 0000000000..7dd3b42c1a --- /dev/null +++ b/docs/docs/extend/expand_statements/add_file_statement.md @@ -0,0 +1,59 @@ +--- +sidebar_position: 8 +position: 4 +id: add_file_statement +title: ADD FILE +--- + +:::info 背景 + +在某些场景下,用户不仅需要将 jar 上传到 Flink 集群中,可能还需要添加一些其他类型的文件到环境中,比如配置文件、资源文件等。 + +为了支持这种场景,我们在 Dinky 中新增了`ADD FILE` 语法, 原理与`ADD CUSTOMJAR`类似, 用于将文件添加到环境中, 以供 Flink 任务使用。 + +同样支持全模式提交。也支持从资源中心(rs:/ 协议)中获取文件。 + +ADD FILE 同样可以达到 `ADD CUSTOMJAR` 的效果, 但是从设计上 ADD CUSTOMJAR 更适合于添加 jar 包, ADD FILE 更适合于添加其他类型的文件。 + +::: + +> 语法: +```sql +ADD FILE '.jar' +``` + + +## 实战范围 + + + +当需要添加一些文件到环境中时,可以使用 ADD FILE 语法,比如: + +```sql + +ADD FILE '/tmp/dinky/resource/file.properties' +``` + +## 实战场景 + +> 在 Dinky v1.0.0 版本中,支持了`资源管理`,同时扩展了 rs 协议, 使得用户可以通过 rs 协议调用该 jar , 有关 `资源管理rs 协议`的使用请参考 [资源管理](../../user_guide/register_center/resource)。 + +> 如果使用 rs 协议访问, 请参考 [资源管理](../../user_guide/register_center/resource) 中的使用方式, 以下示例中,我们使用 rs 协议访问资源中心中的 jar 资源 + +eg: 假设: + +1. 在 `配置中心` -> `Resource 配置` 中使用 `LOCAL` 协议 ,并设置了 `上传根路径`为 /tmp/dinky/resource +2. 在资源中心 Root 根目录下上传了一个 app.jar 文件,则该文件真实路径为 /tmp/dinky/resource/file.properties +3. 其访问方式如下: + +```sql +ADD FILE 'rs:/file.properties' +``` + +:::tip 提示 + +1. 如果使用 rs 协议访问, 请注意路径,不要带上 Root 节点 +2. 推荐使用 rs 协议访问, 以便于在 Flink 中支持除 k8s 模式之外的所有模式提交。 +3. 此功能可以覆盖 ADD CUSTOMJAR 功能, 可自由选择使用 + +::: diff --git a/docs/docs/extend/expand_statements/add_jar_statement.md b/docs/docs/extend/expand_statements/add_jar_statement.md index 87cce90bb1..fbfb14f994 100644 --- a/docs/docs/extend/expand_statements/add_jar_statement.md +++ b/docs/docs/extend/expand_statements/add_jar_statement.md @@ -9,7 +9,7 @@ title: ADD CUSTOMJAR 在某些场景下,用户需要将自定义 jar 添加到 classpath,以便于在 SQL 中使用自定义 jar 中的函数。但是 Flink 原生的 ADD JAR 语法 无法在所有 Flink 版本中通用, 因此我们在 Flink SQL 中添加了 ADD CUSTOMJAR 语法,用于将用户 jar 添加到 classpath。 -以达到在 Dinky 支持的所有 Flink 版本都可使用, 且不影响原生 ADD JAR 语法的目的。同时支持全模式提交。 +以达到在 Dinky 支持的所有 Flink 版本都可使用, 且不影响原生 ADD JAR 语法的目的。同时支持除 k8s 模式之外的所有模式提交。 ::: @@ -28,7 +28,7 @@ add CUSTOMJAR 可以选择性的识别添加到服务器,做到环境隔离 ## 实战场景 -> 在 Dinky v1.0.0 版本中,我们支持了`资源管理`,同时扩展了 rs 协议, 使得用户可以通过 rs 协议调用该 jar , 有关 `资源管理rs 协议`的使用请参考 [资源管理](../../user_guide/register_center/resource)。 +> 在 Dinky v1.0.0 版本中,支持了`资源管理`,同时扩展了 rs 协议, 使得用户可以通过 rs 协议调用该 jar , 有关 `资源管理rs 协议`的使用请参考 [资源管理](../../user_guide/register_center/resource)。 > 如果使用 rs 协议访问, 请参考 [资源管理](../../user_guide/register_center/resource) 中的使用方式, 以下示例中,我们使用 rs 协议访问资源中心中的 jar 资源 @@ -45,6 +45,6 @@ ADD CUSTOMJAR 'rs:/app.jar' :::tip 提示 1. 如果使用 rs 协议访问, 请注意路径,不要带上 Root 节点 -2. 推荐使用 rs 协议访问, 以便于在 Flink 全模式任务中使用 +2. 推荐使用 rs 协议访问, 以便于在 Flink 中支持除 k8s 模式之外的所有模式提交。 ::: diff --git a/script/sql/dinky-mysql.sql b/script/sql/dinky-mysql.sql index d5ebafdf92..455d43c8b0 100644 --- a/script/sql/dinky-mysql.sql +++ b/script/sql/dinky-mysql.sql @@ -963,7 +963,6 @@ INSERT INTO dinky_flink_document (id, category, type, subtype, name, description \'sink[1].topic\'=\'cdc\', \'sink[1].brokers\'=\'127.0.0.1:9092\' )', 'All Versions', 0, 1, '2023-10-31 16:17:27', '2023-12-28 00:02:57', null, null); -INSERT INTO dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) VALUES (234, 'Reference', 'FUN_UDF', 'OTHER_FUNCTION', 'ADD JAR', 'ADD JAR', 'ADD JAR ${1:}; -- str path ', 'All Versions', 0, 1, '2023-10-31 16:19:52', '2023-12-28 00:02:02', null, null); INSERT INTO dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) VALUES (235, 'Function', 'Other', 'Other', 'SHOW FRAGMENTS', 'SHOW FRAGMENTS', 'SHOW FRAGMENTS;', 'All Versions', 0, 1, '2023-10-31 16:20:30', '2023-12-28 09:57:55', null, null); INSERT INTO dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) VALUES (236, 'Function', 'Other', 'Other', 'SHOW FRAGMENT var1', 'SHOW FRAGMENT var1', 'SHOW FRAGMENT ${1:};', 'All Versions', 0, 1, '2023-10-31 16:21:23', '2023-12-28 09:57:54', null, null); INSERT INTO dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) VALUES (237, 'Reference', 'SQL_TEMPLATE', 'FlinkCDC', 'EXECUTE CDCSOURCE demo_hudi', 'The entire library is synchronized to hudi', 'EXECUTE CDCSOURCE demo_hudi WITH ( @@ -1137,8 +1136,11 @@ WITH \'sink.path\' = \'hdfs:/tmp/paimon/#{schemaName}.db/#{tableName}\', \'sink.auto-create\' = \'true\', );', 'All Versions', 0, 1, '2023-12-27 16:53:37', '2023-12-28 12:05:20', 1, 1); -INSERT INTO dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) VALUES (248, 'Reference', 'FUN_UDF', 'OTHER_FUNCTION', 'add-customjar', 'add CUSTOMJAR 为 Dinky 扩展语法 功能实现和 add jar 类似 , 推荐使用此方式', '-- add CUSTOMJAR 为 Dinky 扩展语法 功能实现和 add jar 类似 , 推荐使用此方式 -add CUSTOMJAR \'${1:}\';', 'All Versions', 0, 1, '2023-12-28 10:50:17', '2023-12-28 15:49:40', 1, 1); +insert into dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) values (248, 'Variable', 'FUN_UDF', 'OTHER_FUNCTION', 'ADD-CUSTOMJAR', 'add CUSTOMJAR 为 Dinky 扩展语法 功能实现和 add jar 类似 , 推荐使用此方式', '-- add CUSTOMJAR 为 Dinky 扩展语法 功能实现和 add jar 类似 , 推荐使用此方式 +ADD CUSTOMJAR ''${1:}'';', 'All Versions', 0, 1, '2023-12-28 10:50:17', '2024-03-01 17:15:44', 1, 1); +insert into dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) values (249, 'Variable', 'FUN_UDF', 'OTHER_FUNCTION', 'ADD-FILE', 'ADD FILE 为 Dinky 扩展语法 可以向环境中添加依赖jar(与ADD CUSTOMJAR 一致) 还可以添加其他类型的文件 +', '-- ADD FILE 为 Dinky 扩展语法 可以向环境中添加依赖jar(与add customjar 一致) 还可以添加其他类型的文件 +ADD FILE ''${1:}''; -- str path ', 'All Versions', 0, 1, '2024-03-01 17:13:05', '2024-03-01 17:15:55', 1, 1); commit ; -- ---------------------------- diff --git a/script/sql/dinky-pg.sql b/script/sql/dinky-pg.sql index fd7fe0419b..b5bdfcc3b5 100644 --- a/script/sql/dinky-pg.sql +++ b/script/sql/dinky-pg.sql @@ -2090,10 +2090,6 @@ VALUES (233, 'Reference', 'SQL_TEMPLATE', 'FlinkCDC', 'EXECUTE CDCSOURCE mysql2m ''sink[1].topic''=''cdc'', ''sink[1].brokers''=''127.0.0.1:9092'' )', 'All Versions', 0, 1, '2023-10-31 16:17:27.000000', '2023-12-28 00:02:57.000000', null, null); -INSERT INTO public.dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, - enabled, create_time, update_time, creator, updater) -VALUES (234, 'Reference', 'FUN_UDF', 'OTHER_FUNCTION', 'ADD JAR', 'ADD JAR', 'ADD JAR ${1:}; -- str path ', - 'All Versions', 0, 1, '2023-10-31 16:19:52.000000', '2023-12-28 00:02:02.000000', null, null); INSERT INTO public.dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) VALUES (235, 'Function', 'Other', 'Other', 'SHOW FRAGMENTS', 'SHOW FRAGMENTS', 'SHOW FRAGMENTS;', 'All Versions', 0, 1, @@ -2302,11 +2298,11 @@ WITH ''sink.path'' = ''hdfs:/tmp/paimon/#{schemaName}.db/#{tableName}'', ''sink.auto-create'' = ''true'', );', 'All Versions', 0, 1, '2023-12-27 16:53:37.000000', '2023-12-28 12:05:20.000000', 1, 1); -INSERT INTO public.dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, - enabled, create_time, update_time, creator, updater) -VALUES (248, 'Variable', 'SQL_TEMPLATE', 'FlinkSql', 'add-customjar', - 'add CUSTOMJAR 为 Dinky 扩展语法 功能实现和 add jar 类似 , 推荐使用此方式', e'-- add CUSTOMJAR 为 Dinky 扩展语法 功能实现和 add jar 类似 , 推荐使用此方式 -add CUSTOMJAR ''${1:}'';', 'All Versions', 0, 1, '2023-12-28 10:50:17.000000', '2023-12-28 12:05:20.000000', 1, 1); +insert into public.dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) values (248, 'Variable', 'FUN_UDF', 'OTHER_FUNCTION', 'ADD-CUSTOMJAR', 'add CUSTOMJAR 为 Dinky 扩展语法 功能实现和 add jar 类似 , 推荐使用此方式', '-- add CUSTOMJAR 为 Dinky 扩展语法 功能实现和 add jar 类似 , 推荐使用此方式 +ADD CUSTOMJAR ''${1:}'';', 'All Versions', 0, 1, '2023-12-28 10:50:17', '2024-03-01 17:15:44', 1, 1); +insert into public.dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) values (249, 'Variable', 'FUN_UDF', 'OTHER_FUNCTION', 'ADD-FILE', 'ADD FILE 为 Dinky 扩展语法 可以向环境中添加依赖jar(与ADD CUSTOMJAR 一致) 还可以添加其他类型的文件 +', '-- ADD FILE 为 Dinky 扩展语法 可以向环境中添加依赖jar(与add customjar 一致) 还可以添加其他类型的文件 +ADD FILE ''${1:}''; -- str path ', 'All Versions', 0, 1, '2024-03-01 17:13:05', '2024-03-01 17:15:55', 1, 1); -- ---------------------------- diff --git a/script/sql/upgrade/1.0.0_schema/mysql/dinky_dml.sql b/script/sql/upgrade/1.0.0_schema/mysql/dinky_dml.sql index b2b8561b83..baf4cba6d6 100644 --- a/script/sql/upgrade/1.0.0_schema/mysql/dinky_dml.sql +++ b/script/sql/upgrade/1.0.0_schema/mysql/dinky_dml.sql @@ -615,7 +615,6 @@ INSERT INTO dinky_flink_document (id, category, type, subtype, name, description \'sink[1].topic\'=\'cdc\', \'sink[1].brokers\'=\'127.0.0.1:9092\' )', 'All Versions', 0, 1, '2023-10-31 16:17:27', '2023-12-28 00:02:57', null, null); -INSERT INTO dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) VALUES (234, 'Reference', 'FUN_UDF', 'OTHER_FUNCTION', 'ADD JAR', 'ADD JAR', 'ADD JAR ${1:}; -- str path ', 'All Versions', 0, 1, '2023-10-31 16:19:52', '2023-12-28 00:02:02', null, null); INSERT INTO dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) VALUES (235, 'Function', 'Other', 'Other', 'SHOW FRAGMENTS', 'SHOW FRAGMENTS', 'SHOW FRAGMENTS;', 'All Versions', 0, 1, '2023-10-31 16:20:30', '2023-12-28 09:57:55', null, null); INSERT INTO dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) VALUES (236, 'Function', 'Other', 'Other', 'SHOW FRAGMENT var1', 'SHOW FRAGMENT var1', 'SHOW FRAGMENT ${1:};', 'All Versions', 0, 1, '2023-10-31 16:21:23', '2023-12-28 09:57:54', null, null); INSERT INTO dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) VALUES (237, 'Reference', 'SQL_TEMPLATE', 'FlinkCDC', 'EXECUTE CDCSOURCE demo_hudi', 'The entire library is synchronized to hudi', 'EXECUTE CDCSOURCE demo_hudi WITH ( @@ -789,10 +788,11 @@ WITH \'sink.path\' = \'hdfs:/tmp/paimon/#{schemaName}.db/#{tableName}\', \'sink.auto-create\' = \'true\', );', 'All Versions', 0, 1, '2023-12-27 16:53:37', '2023-12-28 12:05:20', 1, 1); -INSERT INTO dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) VALUES (248, 'Reference', 'FUN_UDF', 'OTHER_FUNCTION', 'add-customjar', 'add CUSTOMJAR 为 Dinky 扩展语法 功能实现和 add jar 类似 , 推荐使用此方式', '-- add CUSTOMJAR 为 Dinky 扩展语法 功能实现和 add jar 类似 , 推荐使用此方式 -add CUSTOMJAR \'${1:}\';', 'All Versions', 0, 1, '2023-12-28 10:50:17', '2023-12-28 15:49:40', 1, 1); - - +insert into dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) values (248, 'Variable', 'FUN_UDF', 'OTHER_FUNCTION', 'ADD-CUSTOMJAR', 'add CUSTOMJAR 为 Dinky 扩展语法 功能实现和 add jar 类似 , 推荐使用此方式', '-- add CUSTOMJAR 为 Dinky 扩展语法 功能实现和 add jar 类似 , 推荐使用此方式 +ADD CUSTOMJAR ''${1:}'';', 'All Versions', 0, 1, '2023-12-28 10:50:17', '2024-03-01 17:15:44', 1, 1); +insert into dinky_flink_document (id, category, type, subtype, name, description, fill_value, version, like_num, enabled, create_time, update_time, creator, updater) values (249, 'Variable', 'FUN_UDF', 'OTHER_FUNCTION', 'ADD-FILE', 'ADD FILE 为 Dinky 扩展语法 可以向环境中添加依赖jar(与ADD CUSTOMJAR 一致) 还可以添加其他类型的文件 +', '-- ADD FILE 为 Dinky 扩展语法 可以向环境中添加依赖jar(与add customjar 一致) 还可以添加其他类型的文件 +ADD FILE ''${1:}''; -- str path ', 'All Versions', 0, 1, '2024-03-01 17:13:05', '2024-03-01 17:15:55', 1, 1); -- 修改 dinky_udf_template 表的 enable 字段 不允许为空 默认为 1 alter table dinky_udf_template modify column `enabled` tinyint(1) not null default 1 comment 'is enable, 0:no 1:yes';