跳转至

NATIVE QUERY

概述

NATIVE QUERY 用于把一条 SQL 原样透传给指定的底层查询引擎执行，AIR 不做任何解析、校验、方言转换或物化改写。适用于：

  • 使用底层引擎（Spark / StarRocks）特有的语法或函数，AIR 标准 SQL 不支持。
  • 临时调试，或绕过 AIR 的 planner / 物化路径直接验证某条 SQL。
  • 规避特定方言转换问题。

语法

NATIVE QUERY ON <catalog>[.<queue>] '<raw_sql>' [;]
  • <catalog>：必填，内置固定的两个 catalog 名：
    • air_spark —— 路由到当前集群中类型为 KYUUBI_SPARK 的查询计算单元（Compute Unit）。
    • air_sr —— 路由到当前集群中类型为 STARROCKS 的查询计算单元。
  • <queue>：可选。当集群中存在多个同类型 ComputeUnit 时，用 <catalog>.<queue> 指定 queue 名；省略时按优先级取默认 queue 中优先级最高的 ComputeUnit（行为与 getClusterDefaultQueryEngine 一致）。
  • <raw_sql>：底层引擎原生 SQL，必须用单引号字符串字面量包裹。内部出现的单引号按 ANSI SQL 风格用 ''（两个连续单引号）转义。
  • 末尾分号可选。

之所以强制用单引号字符串字面量，是因为 AIR 的 SQL 解析器是 Presto 方言，双引号是标识符引用符号；底层引擎（Spark/StarRocks/MySQL/...）的原生 SQL 中可能含有双引号、反引号等任意字符，必须放在字符串字面量里才能被原样透传，避免 AIR 的解析器误读。

行为说明

  • 不解析、不重写、不优化：AIR 仅识别 NATIVE QUERY ON <catalog>[.<queue>] '...' 外壳，提取出原生 SQL 后逐字节下发到目标引擎。
  • 结果列与类型自动推断：直接来自底层引擎的 ResultSetMetaData，AIR 不做映射。
  • 错误透传：底层引擎抛出的异常（如 Spark 的 TABLE_OR_VIEW_NOT_FOUND、StarRocks 的语法错误等）会原样返回到客户端，便于排查。
  • 取消与状态查询：复用 AIR 现有的 SQL Job 取消、状态查询、observer 通知机制；客户端无需做任何特殊处理。
  • 审计：作业信息中会标记 nativeQuery=true，并把 executionEngine 设置为实际下发的引擎类型（KYUUBI_SPARK / STARROCKS），便于事后审计与追溯。
  • SQL 范围：完全透传，DQL / DML / DDL 均可下发，不做语句类型限制；能否成功执行由底层引擎决定。

示例

1. Spark 基本查询

NATIVE QUERY ON air_spark 'SELECT 1';

返回：

1
1

2. StarRocks 基本查询

NATIVE QUERY ON air_sr 'SELECT now()';

返回：

now()
2026-04-29 14:11:54.000

3. 含有单引号的字符串字面量

通过 '' 转义内部单引号：

NATIVE QUERY ON air_spark 'SELECT * FROM events WHERE day = ''2026-04-29''';

实际下发到 Spark 的 SQL 为：

SELECT * FROM events WHERE day = '2026-04-29'

4. 指定 queue

当集群存在多个 KYUUBI_SPARK ComputeUnit 时：

NATIVE QUERY ON air_spark.fast 'SELECT count(*) FROM big_table';

会路由到 queueName = "fast" 的 ComputeUnit。

5. 写操作（DML）

NATIVE QUERY ON air_sr 'INSERT INTO t1 VALUES (1, ''abc'')';

6. 使用底层引擎特有语法

例如 Spark 的反引号标识符、Hive 风格的 hint：

NATIVE QUERY ON air_spark 'SELECT /*+ BROADCAST(s) */ b.* FROM `db`.`big` b JOIN `db`.`small` s ON b.k = s.k';

错误案例

表不存在

NATIVE QUERY ON air_spark 'SELECT * FROM no_such_tbl_xyz_404';

返回错误（节选）：

ERROR_CODE=[851970] QUERY_ENGINE_SQL_EXECUTION_ERROR -
org.apache.kyuubi.KyuubiSQLException:
[TABLE_OR_VIEW_NOT_FOUND] The table or view `no_such_tbl_xyz_404` cannot be found ...

底层引擎的报错信息会原样返回。

未知 catalog

NATIVE QUERY ON air_unknown 'SELECT 1';

返回错误：Unknown native catalog: 'air_unknown'. Supported: [air_spark, air_sr]。

集群中缺少对应类型的 ComputeUnit

如果当前集群没有配置 KYUUBI_SPARK 类型的查询 ComputeUnit，NATIVE QUERY ON air_spark ... 会返回：

Native catalog 'air_spark' requires a KYUUBI_SPARK query compute unit
in cluster '<cluster_id>', but none was found.

注意事项

  • 不进入 AIR 物化加速路径：原生 SQL 直接打到底层引擎，不会被 AIR 的物化视图改写命中。如果需要享受加速，请使用普通的 AIR SQL。
  • 不做表级权限校验：因为 SQL 不解析，AIR 无法识别 SQL 中的表，因此不会按表做权限校验。建议仅在受控场景或可信用户范围内开放此语法。
  • 结果集大小受 JDBC 配置约束：复用 AbstractJDBCQueryEngine 的 maxRowsFromJdbcServer / maxFetchSizeFromJdbcServer 配置。
  • air_spark / air_sr 是保留 catalog 名：与 AIR 元数据中的真实 catalog 名同名时，本语法仍会优先路由到内置引擎而不是用户的 catalog。