入门指南

本页介绍如何在笔记本电脑上用大约 3~5 分钟快速开始使用 Kyuubi。

环境要求

对于快速开始部署，我们需要准备以下内容：

• 一个用于连接服务器并提交查询的客户端。这里我们使用 kyuubi beeline 进行演示。
• 一个用于服务客户端并管理引擎的服务器。
• 一个用于实例化查询执行环境的引擎。这里我们使用 Spark 进行演示。

这些核心组件都是基于 JVM 的应用。因此，需要预先安装 JRE，并为每个组件正确设置 JAVA_HOME。

组件

角色

版本

备注

Java

JRE

8/11/17

官方基于 JDK8 发布

Kyuubi

网关 引擎库 Beeline

1.9.1

• Kyuubi Server
• Kyuubi Engine
• Kyuubi Hive Beeline

Spark

引擎

3.1 到 3.5，4.0

一份 Spark 发行版

Flink

引擎

1.16 到 1.19

一份 Flink 发行版

Trino

引擎

不适用

一个可通过 trino-client v411 访问的 Trino 集群

Doris

引擎

不适用

一个 Doris 集群

Hive

引擎 元数据存储

• 2.1-cdh6/2.3/3.1
• 不适用

• 一份 Hive 发行版
• 一个可选的外部元数据存储，其版本由引擎决定

Zookeeper

高可用（HA）

>=3.4.x

磁盘

存储

不适用

不适用

上表中列出的其他内部或外部部件可以单独使用，也可以组合使用。例如，你可以使用 Kyuubi、Spark 和 Flink 构建一个流式数据仓库；然后使用 Zookeeper 开启负载均衡以实现高可用；数据可以存储在 Hive、Apache Iceberg 或其他 DBMS 中。

在下文中，我们只使用 Kyuubi 和 Spark。

安装

注意

以下说明基于二进制发行版。如果你从源码发行版开始，请参阅构建 kyuubi 页面。

安装 Kyuubi

官方发行版（二进制版和源码版）都归档在下载页面上。请下载最新的稳定版本开始使用。

要安装 Kyuubi，你需要解压该 tarball。例如，

$ tar zxf apache-kyuubi-1.9.1-bin.tgz

├── LICENSE
├── NOTICE
├── RELEASE
├── beeline-jars
├── bin
├── charts
│   └── kyuubi
├── conf
|   ├── kyuubi-defaults.conf.template
│   ├── kyuubi-env.sh.template
│   └── log4j2.xml.template
├── db-scripts
│   ├── mysql
│   ├── postgresql
│   └── sqlite
├── docker
│   ├── Dockerfile
│   └── playground
├── externals
│  └── engines
├── jars
├── licenses
├── logs
├── pid
├── web-ui
└── work

从上到下依次为：

• LICENSE：我们声明遵循的 APACHE LICENSE，VERSION 2.0。
• RELEASE：该安装包的构建信息。
• NOTICE：Apache Kyuubi 社区就其项目及依赖项发布的声明。
• bin：Kyuubi 服务的入口，其中 kyuubi 为启动脚本。
• conf：Kyuubi Server 本身以及通过引擎创建会话时所使用的全部默认配置。
• externals - engines：包含我们所支持的各类 SQL 引擎。
• licenses：随附的一批许可证文件。
• jars：Kyuubi 服务所需的依赖包。
• logs：Kyuubi 服务的日志存放位置。
• pid：存放 Kuuubi 服务实例的 PID 文件。
• work：所有派生出的子进程（即 SQL 引擎）的工作目录的根目录。

安装 Spark

官方发行版（二进制包和源码包）归档在 spark 下载页面。请下载最新的稳定版本以开始使用。

Note

目前，Kyuubi 是基于 Spark 3 和 Scala 2.12 编译并预构建的。如果你使用 Spark 2 或使用不受支持的 Scala 版本的 Spark，很可能会遇到运行时异常。

要安装 Spark，你需要解压 tar 包。例如：

$ tar zxf spark-3.4.2-bin-hadoop3.tgz

配置

kyuubi-env.sh 文件用于为 Kyuubi 服务器进程及其创建的引擎进程设置系统环境变量。

kyuubi-defaults.conf 文件用于为 Kyuubi 服务器进程及其创建的引擎进程设置系统属性。

这两个文件在 conf 目录下都各有一个模板文件供你参考。以下是使用 Spark 快速启动所需参数的示例。

• JAVA_HOME

$ echo 'export JAVA_HOME=/path/to/java' >> conf/kyuubi-env.sh

• SPARK_HOME

$ echo 'export SPARK_HOME=/path/to/spark' >> conf/kyuubi-env.sh

启动 Kyuubi

$ bin/kyuubi start

如果上述脚本运行成功，它会将服务器实例的 PID 存储到 pid/kyuubi-<username>-org.apache.kyuubi.server.KyuubiServer.pid 中。你可以从日志文件 logs/kyuubi-<username>-org.apache.kyuubi.server.KyuubiServer-<hostname>.out 中获取 JDBC 连接 URL。

例如：

Starting and exposing JDBC connection at: jdbc:hive2://localhost:10009/

如果出现问题，你同样可以在日志文件中找到一些线索。

注意

此外，它也可以在前台运行，日志及其他输出将写入 stdout/stderr。如果使用 supervisord 等监控系统，应当同时捕获这两个输出流。

bin/kyuubi run

操作客户端

Kyuubi 提供了 beeline 客户端，可提供与 Apache Hive 使用场景相似的体验。

打开连接

请将以下 JDBC URL 中的主机和端口替换为服务器启动步骤中获取的实际值。下面的示例为名为 apache 的用户打开一个会话。

$ bin/beeline -u 'jdbc:hive2://localhost:10009/' -n apache

:::note
使用 --help 显示 beeline 工具的用法指南。
:::

$ bin/beeline --help

执行语句

成功连接服务器后，你可以在 beeline 控制台中运行 SQL 查询。例如，

> SHOW DATABASES;

你会在 beeline 控制台中看到一大屏操作日志和一个结果表。

omitted logs
+------------+
| namespace  |
+------------+
| default    |
+------------+
1 row selected (0.2 seconds)

启动引擎

引擎由服务端自动启动，无需最终用户干预。

如果在上述场景中使用同一用户创建另一个连接，引擎将被复用。你可能会注意到，此时建立连接所花费的时间比上一次短得多。

如果使用不同的用户创建新连接，则会启动另一个引擎。

$ bin/beeline -u 'jdbc:hive2://localhost:10009/' -n kentyao

这可能会根据你所设置的引擎共享级别而有所不同。

关闭连接

通过执行 !quit 来关闭 beeline 与 Kyuubi server 之间的会话，例如，

> !quit
Closing: 0: jdbc:hive2://localhost:10009/

停止引擎

引擎由服务器根据引擎生命周期自动停止，最终用户无需关心。连接的终止并不一定意味着引擎的终止，这取决于引擎共享级别与引擎生命周期两方面。

停止 Kyuubi

在 $KYUUBI_HOME 目录下执行以下命令即可停止 Kyuubi：

$ bin/kyuubi stop

随后，你会看到 Kyuubi 服务端挥手向你告别。

Kyuubi 服务端会立即停止，而引擎仍会继续存活一段时间。

如果你在引擎自行终止之前再次启动 Kyuubi，它将会重新连接到新创建的引擎。