功能介绍
Kyuubi 是一款分布式、多租户的 Spark SQL 网关服务，可作为 EMR 集群统一的 Spark 访问入口。用户无需登录集群节点手工执行 spark-submit，即可通过标准 JDBC 或 REST 方式访问集群内的 Spark 引擎。
腾讯云 EMR 各集群类型（EMR on CVM、EMR on TKE）均支持部署 Kyuubi 服务。Kyuubi 对外暴露两类入口：
10009（Thrift/JDBC）：用于交互式 Spark SQL 访问。
10099（REST）：用于批作业的提交与管理。
Kyuubi 收到请求后会按需拉起 Spark 引擎（Driver），再由 Driver 申请计算资源（Executor）。在容器化部署形态（如 EMR on TKE）下，上述引擎与计算资源以 Pod 形式动态调度，用户无需关心底层细节；在基于云服务器的部署形态（如 EMR on CVM）下，引擎与计算资源由 YARN 等资源调度框架统一管理。
本文为您介绍在 EMR 集群中通过 Kyuubi 连接并使用 Spark 引擎的操作方法与实践教程。
总体架构与变量约定
Kyuubi 对外提供的两类入口如下表所示：
入口 | 端口 | 协议 | 典型用途 |
Kyuubi Thrift Server | 10009 | HiveServer2 Thrift (JDBC) | 交互式 Spark SQL、BI 工具、beeline |
Kyuubi REST Server | 10099 | HTTP REST | PySpark / Scala 批作业提交、状态查询、日志查看 |
本文所有命令中的地址均以变量形式给出，使用前请先在客户端机器上导入以下环境变量：
# Kyuubi 实例外部访问地址（替换为实际集群的 Kyuubi 访问地址）export KYUUBI_HOST=10.16.32.39# Thrift/JDBC 端口（交互式 Spark SQL）export KYUUBI_THRIFT_PORT=10009# REST 端口（批作业提交与管理）export KYUUBI_REST_PORT=10099# 提交用户export KYUUBI_USER=root
Spark SQL 交互式访问（JDBC / beeline）
下载 Kyuubi 客户端二进制包
在任意可访问 Kyuubi 地址的机器上下载并解压：
wget https://www.apache.si/kyuubi/kyuubi-1.7.3/apache-kyuubi-1.7.3-bin.tgztar -zxvf apache-kyuubi-1.7.3-bin.tgz
说明：
客户端机器只需具备 JRE 环境，无需安装 Spark，也无需是集群节点。
通过 beeline 进入 Spark SQL 控制台
1. 执行以下命令，通过 beeline 连接 Kyuubi Thrift Server：
./apache-kyuubi-1.7.3-bin/bin/beeline \\-u "jdbc:hive2://${KYUUBI_HOST}:${KYUUBI_THRIFT_PORT}/default;#kyuubi.engine.share.level=CONNECTION" \\-n ${KYUUBI_USER}
2. 连接成功后即进入 Spark SQL 的交互式控制台，可直接执行 DDL / DML：
show databases;use default;show tables;select count(*) from your_table;
参数说明与实践教程
各连接参数的含义及使用建议如下表所示：
参数 | 含义 | 建议 |
jdbc:hive2://${KYUUBI_HOST}:${KYUUBI_THRIFT_PORT}/default | Kyuubi Thrift 地址与默认库 | 端口固定 10009，default 可替换为业务库 |
#kyuubi.engine.share.level=CONNECTION | 引擎共享级别 | 见下方说明 |
-n ${KYUUBI_USER} | 提交用户名 | 与集群侧 OS 用户 / 权限体系（Ranger、LDAP）保持一致 |
engine.share.level 取值建议
CONNECTION：每个连接独占一个 Spark 引擎，连接关闭即回收。适合调试、临时查询、需要独立资源隔离的场景（本文示例采用该模式）。
USER（默认）：同一用户的多个连接复用一个引擎，省去重复启动开销，适合日常多次查询。
GROUP / SERVER：更大范围复用，适合大量轻量查询、追求秒级响应的多租户场景。
其他实践建议
1. URL 中 # 之后的参数会透传给引擎，可叠加 Spark 配置，例如：
jdbc:hive2://${KYUUBI_HOST}:${KYUUBI_THRIFT_PORT}/default;#kyuubi.engine.share.level=CONNECTION;spark.executor.memory=8g;spark.executor.instances=10
2. 首次连接会触发 Spark Driver 冷启动，通常需要数十秒；若长期卡住，优先排查镜像拉取、资源配额（Quota）与调度是否正常。
3. -n 指定的用户名必须在引擎侧存在（涉及 Hadoop group mapping、Ranger 鉴权），否则会出现权限或用户不存在类报错。
4. BI / 第三方工具（DBeaver、Tableau 等）使用同一个 JDBC URL 即可接入，驱动选择 Hive JDBC。
PySpark 批作业提交与管理（REST API）
Kyuubi REST Server（10099）提供 Batch 接口，适合将 PySpark 脚本作为一次性作业提交，无需保持长连接。
提交作业
执行以下命令提交批作业：
curl -X POST http://${KYUUBI_HOST}:${KYUUBI_REST_PORT}/api/v1/batches \\-H 'Content-Type: application/json' \\-d '{"batchType":"PYSPARK","resource":"cosn://xxx/hello.py"}'
请求字段说明如下表所示：
字段 | 说明 |
batchType | 作业类型，PySpark 作业填 PYSPARK，Scala/Java Jar 填 SPARK |
resource | 作业主文件路径，推荐使用对象存储路径（cosn:// / s3a://），保证所有引擎节点均可访问 |
说明：
提交成功后接口会返回一个 batch id（UUID 形式），后续所有状态查询、日志查看都依赖该 id，务必记录下来。
查询作业状态
使用提交请求返回的 id 查询作业状态：
export BATCH_ID=75a87c64-4294-4072-ab91-96c95e685d29curl http://${KYUUBI_HOST}:${KYUUBI_REST_PORT}/api/v1/batches/${BATCH_ID}
返回体中包含作业状态（如 PENDING / RUNNING / FINISHED / ERROR）、提交用户、引擎信息等，可用于脚本轮询或调度系统对接。
查看作业日志
使用提交请求返回的 id，在 EMR 控制台 → Kyuubi 服务页面 查看该次提交的日志，用于定位作业失败原因（依赖缺失、路径不可达、资源不足等）。
批作业实践建议
1. 主文件与依赖统一放对象存储：hello.py 及其依赖（--py-files 打包的 zip/egg）均放在 COS 上，避免因本地路径不可见导致 Driver 启动失败。
2. 保存 batch id：id 是作业的唯一句柄，建议提交后立即持久化到调度系统或日志中。
3. 轮询而非死等：调度系统对接时用固定间隔轮询状态接口，遇到 ERROR 立即拉取控制台日志。
4. 资源参数随请求传入：可在请求体中携带 conf 字段下发 Spark 配置（executor 数量、内存、shuffle 分区等），避免依赖服务端默认值。
5. shuffle 分区与并行度匹配：spark.sql.shuffle.partitions 应与实际可用 executor 核数量级匹配，过大会造成大量小任务与调度开销。
