帮你快速理解、总结文档立即下载
文档中心>流计算 Oceanus>操作指南>变量管理

变量管理

最近更新时间：2026-10-19 10:22:08
本文档已由 AI 辅助审校
我的收藏

本页目录：

用户可以在变量管理中新建变量，之后就可以在 SQL 作业中使用变量。SQL 作业的变量替换分为两种模式，表级替换模式和全 SQL 替换模式。
表级替换模式是指 SQL 作业的临时表和元数据表中的 WITH 语句中，对等号右侧的值执行变量替换，全 SQL 替换模式是指用户可以在 SQL 作业全局中使用变量，两种模式使用上略有不同，详见下文 变量替换模式。

新建变量

登录 流计算 Oceanus 控制台，选择进入目标工作空间，在作业管理中，创建 SQL 作业，可参考 创建 SQL 作业 ，切换到开发调试，在左侧的变量管理界面操作变量。变量的值支持两种设置方式：手动自定义输入，或引用自定义凭据。




自定义值

在变量管理功能界面中，选择右上角的新建，在弹窗中填写变量信息，然后单击确定。



自定义凭据

当作业中需要使用数据库账号密码等敏感信息时，为避免其以明文形式出现在代码或变量定义中，可使用自定义凭据功能。具体流程为：先创建自定义凭据，再在创建变量时选择已有的自定义凭据进行关联；作业开发时直接引用该变量即可。这样便可有效避免敏感信息明文暴露的问题。
说明：
自定义凭据需要在凭据管理系统（SSM）产品中创建，详细操作请参见文档创建凭据，或者点击此处前往新建。
凭据管理系统（SSM）为独立的产品服务，使用自定义凭据将产生相应费用，详见凭据管理系统的计费概述。
SSM 地域：默认为用户当前所在地域。若目标凭据不在当前地域，可重新选择其所属地域。
凭据名称：在凭据管理系统（SSM）中已定义的凭据名称。
凭据版本：凭据支持多版本管理，请根据实际需求选择对应版本。

注意：
自定义凭据一旦被作业引用，请勿随意删除。若删除仍在使用中的凭据，将导致关联作业运行失败。如需删除，请先确认该凭据未被任何作业引用。



变量替换模式

变量替换支持两种模式，表级替换模式和全 SQL 替换模式。

表级替换模式

在表级替换模式下，系统仅在表的 WITH 语句中，对等号右侧的值执行变量替换。若在 SQL 体其它位置出现变量，可能会导致所有变量都无法识别。
变量语法
${变量名称}
${变量名称:默认值}
${变量名称}:默认值 （此种语法表级替换模式，全 SQL 变量替换模式不支持）
注意
${变量名称}:默认值 此种语法表级替换模式，全 SQL 变量替换模式不支持。

全 SQL 替换模式

全 SQL 变量与表变量不同，表变量仅作用于数据表的 WITH 参数中，而全 SQL 变量可以在 SQL 编辑器中的任意位置使用，包括 DDL 语句、DML 语句中的字段名、表名、参数值等。
变量语法
${变量名称}
${变量名称:默认值}
注意
变量名称分隔符用下划线 _ 。推荐使用${变量名称}这种语法。



变量使用

表级替换

数据表中引用变量

在库表引用功能界面中，选择右上角的新建 > 数据表，在弹窗中选择 Catalog 和 Database，然后单击下一步，进入选择创建元表的方式，可使用模板、自定义、云资源。如果选择自定义或者云资源，则需输入相应的连接信息。在 WITH 参数中设置表变量并点击完成。




引用多个全局变量

注意：
引用多个变量，可以使用${变量名称}或${变量名称:默认值}样式进行拼接。


SQL 作业引用全局变量

在 SQL 作业中可以直接引用全局变量，单击表变量替换，右侧会显示操作菜单，单击引用全局变量，最后单击提交。



系统变量

将以下变量替换为真实的 job_id 和 cluster_id
${SYSTEM_VARIABLE_JOB_SERIAL_ID}:xx
${SYSTEM_VARIABLE_CLUSTER_SERIAL_ID}:xx




全 SQL 替换

在 SQL 中引用变量

在 SQL 编辑器中，直接使用 ${变量名称} 语法引用。变量会在作业保存/发布时被替换为实际值。
SET pipeline.operator-chaining = ${chaining_enabled};

CREATE TABLE source (
    id INT,
    name STRING
) WITH (
    'connector' = 'datagen',
    'rows-per-second' = '${rows_per_second}'
);

INSERT INTO sink SELECT * FROM source;

变量替换

全 SQL 替换模式下进行变量替换，可以设置自定义值，或者引用全局变量，也支持设置为系统变量。



动态表达式变量

全 SQL 替换变量支持动态表达式，变量值会在作业保存/发布时动态计算。
-- 使用日期工具获取当天日期
CREATE TABLE sink (
    id INT,
    dt STRING
) WITH (
    'connector' = 'filesystem',
    'path' = '/data/${dateUtil.today()}'
);

-- 使用 UUID 工具生成唯一标识
INSERT INTO sink SELECT id, '${IdUtil.simpleUUID()}' FROM source;
当前注册的工具类及常用方法如下（完整 API 请参考 Hutool 5.8.25 文档）：
工具类前缀
对应 Hutool 类
dateUtil
cn.hutool.core.date.DateUtil
idUtil
cn.hutool.core.util.IdUtil
randomUtil
cn.hutool.core.util.RandomUtil
strUtil
cn.hutool.core.util.StrUtil
注意：
仅上述 4 个工具类前缀在白名单中，使用其他前缀的表达式会被跳过，保持原样输出。

中国站