OPTIONS

该部分的语法主要是设置，修改或者展示 AIR的一些配置项。相关配置项请参考：引擎配置参数。

SHOW OPTIONS

• 语法说明

SHOW [<level> [('<scope_name>')]] VARIABLES
[
    LIKE '<keyword>'
  | WHERE <key> = '<value>' [(AND | OR) ...]
]

• 参数说明

关键字	类型	说明
level	SQL 标识符，选填	默认为 SESSION；支持 GLOBAL、CLUSTER、USER、SESSION
scope_name	字符串，选填	USER 下表示目标用户名，CLUSTER 下表示目标 cluster；查询其他用户的配置需要超级管理员权限

• 使用示例

-- 显示GLOBAL级别的所有配置项；
SHOW GLOBAL VARIABLES; 

--  查找GLOBAL级别的所有time结尾的配置项；
SHOW GLOBAL VARIABLES like '%time'


-- 显示GLOBAL级别的变量名为“wait_timeout”的配置项
show GLOBAL variables where variable_name = 'wait_timeout' 

-- 显示SESSION级别的变量名为“enable.query.rewrite.by.view”的配置项值
show session variables where variable_name = "enable.query.rewrite.by.view"; 

• 返回结果

      Variable Name       | Value | Scope  
--------------------------+-------+--------
 rp.system.case_sensitive | false | GLOBAL 

SET OPTIONS

设置AIR引擎的配置项

• 语法说明

SET [<level> [('<scope_name>')]] "<key>" = <value>;

• 参数说明

关键字	类型	说明
level	SQL 标识符，选填	默认为 SESSION；支持 GLOBAL、CLUSTER、USER、SESSION
scope_name	字符串，选填	USER 下表示目标用户名，CLUSTER 下表示目标 cluster
value	变量的值	数值和布尔值直接书写，字符串使用单引号；使用 DEFAULT 表示显式设置为代码默认值

• 例子

-- 默认设置 SESSION 级别配置项
SET "rp.failures.threshold" = 3;

-- 设置 GLOBAL 级别配置项
SET GLOBAL "rp.failures.threshold" = 3;

-- 设置 SESSION 级别配置项
SET SESSION "rp.failures.threshold" = 3;

-- 设置指定 cluster 范围的配置项
SET CLUSTER('default') "rp.failures.threshold" = 3;

-- 设置当前默认 cluster 范围的配置项
SET CLUSTER "enable.query.rewrite.by.view" = false;

RESET OPTIONS

RESET 删除指定作用域中的显式配置，使参数重新继承低优先级作用域的值。RESET USER 支持 Trino/Presto 和 MySQL 协议；RESET SESSION 仅支持 Trino/Presto 协议。

RESET USER [('<username>')] "<key>";
RESET SESSION "<key>";

语法	说明	权限	支持协议
RESET USER "<key>"	删除当前用户在当前 AIR 引擎环境中的持久化配置，恢复继承 CLUSTER、GLOBAL 或代码默认值	参数必须开放 USER 作用域；普通用户可操作自己的配置	Trino/Presto、MySQL
RESET USER('<username>') "<key>"	删除指定用户的持久化配置	需要超级管理员权限	Trino/Presto、MySQL
RESET SESSION "<key>"	删除当前连接中的 SESSION 配置，恢复继承 USER、CLUSTER、GLOBAL 或代码默认值	当前连接用户	Trino/Presto

RESET GLOBAL、RESET CLUSTER 和 RESET CATALOG 当前不受支持。MySQL 协议也不支持 RESET SESSION。SET ... = DEFAULT 会在对应作用域显式保存代码默认值，并不等同于删除配置；该值仍会覆盖低优先级作用域。

-- 删除当前用户的显式配置
RESET USER "planner.catalog.rules";

-- 超级管理员删除指定用户的显式配置
RESET USER('alice') "planner.catalog.rules";

-- 清除当前连接的临时覆盖值
RESET SESSION "planner.catalog.rules";

用户级配置

USER 配置按引擎认证用户名保存，在同一 AIR 引擎环境内跨连接、跨 cluster 生效。用户名区分大小写。查询参数的优先级为：SQL Hint > SESSION > USER > CLUSTER > GLOBAL > 代码默认值。

普通用户可以查看自己的配置，修改自己的已开放参数；查看或修改其他用户的配置需要超级管理员权限。USER 支持：planner.timeout.millisecond、enable.query.mv.rewrite、enable.query.rewrite.by.view、enable.profile.verbose、enable.planner.timing.log、planner.catalog.rules。

-- 设置当前用户的持久化默认值
SET USER "planner.timeout.millisecond" = 120000;

-- 查看当前用户视角的有效值，Scope 列表示实际来源
SHOW USER VARIABLES LIKE '%timeout%';

-- 超级管理员为指定用户配置
SET USER('alice') "planner.timeout.millisecond" = 120000;
SHOW USER('alice') VARIABLES;

-- 显式采用代码默认值，仍覆盖 CLUSTER/GLOBAL
SET USER "planner.timeout.millisecond" = DEFAULT;

-- 删除当前用户的显式配置，恢复继承 CLUSTER/GLOBAL
RESET USER "planner.timeout.millisecond";
RESET USER('alice') "planner.timeout.millisecond";

修改后无需重新连接，后续语句读取最新 USER 配置；正在执行的 SQL 保持语句开始时的 USER 配置快照。内部调度与智能物化任务不自动继承管理员的个人配置。通过引擎账号删除接口删除用户时，会清理该用户的 USER 配置。

修改用户配置不会修改当前连接的 SESSION 参数。若 SESSION 中已显式设置同名参数，需要执行 RESET SESSION "<key>" 清除 SESSION 配置，才能看到 USER 的有效值。USER 参数不用于强制资源限额，因为 SESSION 和 SQL Hint 仍可覆盖它。

按用户与 catalog 设置执行计划模式

planner.catalog.rules 是 JSON 数组，默认 []。每条规则必须包含 clusterId、catalog 和 mode，同一 cluster/catalog 不允许重复。USER 配置跨 cluster 生效，因此需要显式指定 cluster ID。catalog 使用元数据中的名称。

-- 为 alice 在指定 cluster 的 mysql_sales catalog 上启用规则
SET USER('alice') "planner.catalog.rules" = '[
  {"clusterId":"<cluster-id>","catalog":"mysql_sales","mode":"FULL_MATERIALIZATION_OR_PUSHDOWN"}
]';

SHOW USER('alice') VARIABLES LIKE 'planner.catalog.rules';

-- 当前连接临时禁用规则；不改变 USER 配置
SET SESSION "planner.catalog.rules" = '[]';

-- 清除当前连接的临时覆盖值，重新使用 USER 配置
RESET SESSION "planner.catalog.rules";

-- 删除用户显式配置，恢复继承
RESET USER('alice') "planner.catalog.rules";

支持两种模式：

模式	行为
AUTO	沿用现有物化改写、下推与引擎选择策略
FULL_MATERIALIZATION_OR_PUSHDOWN	查询底表全部属于规则指定的 catalog 时，当前优化结果的所有 Scan 都命中物化则使用该计划；否则关闭物化改写重新规划，要求查询整体可下推

同源按视图展开前的原始依赖解析到底表后判断，跨 schema 可以；跨 catalog 不触发规则。依赖缺失或循环、无法确认原始底表归属时不匹配规则。规则列表沿用 SQL Hint > SESSION > USER > CLUSTER > GLOBAL 优先级，高优先级整体替换列表，不按 catalog 合并。

全下推计划既可以直接通过源端引擎执行，也可以由 Spark 通过 temp view/RDD 下推执行，规则不改变已有引擎选择逻辑。如果当前计划未全命中物化，重新规划后又无法整体下推，则查询失败；请检查查询中的算子支持情况、dialect.query.jdbc.pushdown 及 catalog 的下推配置。

此模式不额外搜索所有可能的全物化候选，不承诺多个投影之间具有相同刷新时间。重规划临时关闭的 query.enable.default.raw 和 enable.query.mv.rewrite 会自动恢复，后续语句不受影响。EXPLAIN 的 Catalog Plan Rule 信息说明选用的路径，Profile 的 Catalog Pushdown Replan 阶段记录重规划耗时。

用户配置 HTTP 接口

请求使用现有引擎认证机制与 User-Name、Cluster-Id 请求头。User-Name 表示调用者，路径中的用户名表示配置目标；权限在服务端校验。Cluster-Id 用于解析继承值，不改变 USER 配置的跨 cluster 范围。

方法	路径	说明
GET	/v1/option/user/{user}	返回用户视角的全部有效配置，包含 scope 来源
GET	/v1/option/user/{user}/overrides	仅返回该用户显式配置，保留等于代码默认值的记录
PUT	/v1/option/user/{user}/{name}	设置用户配置，请求体为 {"value":"120000"}
DELETE	/v1/option/user/{user}/{name}	删除显式配置，恢复继承

接口统一返回 TardisResponse。GET 成功时 success 为 true，data 为 Option 数组，包含 name、type、value、scope、scopeId 等字段。PUT/DELETE 成功时 success 为 true、data 为 null；无权限、参数不支持 USER、值类型或范围不合法时，success 为 false，并返回 errorCode、errorMessage，不写入配置。旧 /v1/option/get/USER/...、set/USER/...、delete/USER/... 接口也可操作当前用户。

USER 配置使用跨节点失效事件同步。写入节点立即失效本地缓存，其他节点接收事件后更新；事件漏收时，单项读取缓存最长 60 秒过期。发布时需先升级所有引擎节点及读取 Option 枚举的客户端，再开放 USER 写入，避免旧版本无法解析新增作用域。

设置单条SQL执行生效的配置项

 /*+ options ("rp.failures.threshold" = 3, "dialect.query.jdbc.pushdown" = false) */ 
explain select * from zs_mysql_test.tpcds.call_center;

[警告]注意：引擎层任何参数的修改都需要特别谨慎，不恰当的参数修改有可能导致整个引擎宕机，极端情况会导致引擎无法启动，进而无法恢复到修改前的状态。修改前请跟技术支持同学确认参数的配置和参数值的正确性。