REST API v1 · Apache Kyuubi 1.9.1 简体中文

请注意：当前 api 版本为 v1，基础 URI 为 /api/v1。

会话资源

GET /sessions

获取所有存活会话的列表

响应体

名称	描述	类型
identifier	会话标识符	String
user	创建会话的用户名	String
ipAddr	创建会话的客户端 IP 地址	String
conf	会话的配置	Map
createTime	会话创建的时间戳	Long
duration	最后访问时间减去创建时间的时间间隔	Long
idleTime	空闲（无操作）的时间间隔	Long

GET /sessions/${sessionHandle}

获取一个会话事件

响应体

KyuubiSessionEvent。

GET /sessions/${sessionHandle}/info/${infoType}

获取会话的某项信息详情

请求参数

名称	描述	类型
infoType	Hive Thrift GetInfo 的 ID	Int

响应体

名称	描述	类型
infoType	会话信息的类型	String
infoValue	会话信息的值	String

GET /sessions/count

获取当前已打开的会话数量

响应体

名称	描述	类型
openSessionCount	已打开会话的数量	Int

GET /sessions/execPool/statistic

获取后台执行器的统计信息

响应体

名称	描述	类型
execPoolSize	线程池中当前的线程数量	Int
execPoolActiveCount	正在活跃执行任务的线程的大致数量	Int

POST /sessions

创建一个会话

请求参数

名称	描述	类型
configs	会话的配置	Map

响应体

名称	说明	类型
identifier	会话句柄标识符	String
kyuubiInstance	持有该会话、并在会话中执行后续操作时需要调用的 Kyuubi 实例	String

DELETE /sessions/${sessionHandle}

关闭一个会话。

POST /sessions/${sessionHandle}/operations/statement

创建一个类型为 EXECUTE_STATEMENT 的操作

请求体

名称	说明	类型
statement	要执行的 SQL 语句	String
runAsync	指示查询是同步执行还是异步执行的标志	Boolean
queryTimeout	查询超时的时间间隔	Long
confOverlay	仅针对当前操作生效的配置覆盖	Map of key=val

响应体

名称	说明	类型
identifier	操作的标识符	String

POST /sessions/${sessionHandle}/operations/typeInfo

创建一个类型为 GET_TYPE_INFO 的操作

响应体

名称	说明	类型
identifier	操作的标识符	String

POST /sessions/${sessionHandle}/operations/catalogs

创建一个类型为 GET_CATALOGS 的操作

响应体

名称	说明	类型
identifier	操作的标识符	String

POST /sessions/${sessionHandle}/operations/schemas

创建一个类型为 GET_SCHEMAS 的操作

请求体

名称	说明	类型
catalogName	catalog 名称	String
schemaName	schema 名称	String

响应体

名称	说明	类型
identifier	操作的标识符	String

POST /sessions/${sessionHandle}/operations/tables

请求体

名称	说明	类型
catalogName	catalog 名称	String
schemaName	schema 名称	String
tableName	表名	String
tableTypes	表的类型，例如：TABLE 或 VIEW	String

响应体

名称	描述	类型
identifier	操作的标识符	String

POST /sessions/${sessionHandle}/operations/tableTypes

请求参数

响应体

名称	描述	类型
identifier	操作的标识符	String

POST /sessions/${sessionHandle}/operations/columns

请求体

名称	描述	类型
catalogName	目录名称	String
schemaName	模式名称	String
tableName	表名称	String
columnName	列名称	String

响应体

名称	描述	类型
identifier	操作的标识符	String

POST /sessions/${sessionHandle}/operations/functions

请求体

名称	描述	类型
catalogName	目录名称	String
schemaName	模式名称	String
functionName	函数名称	String

响应体

名称	描述	类型
identifier	操作的标识符	String

POST /sessions/${sessionHandle}/operations/primaryKeys

请求参数

名称	描述	类型
catalogName	目录名称	String
schemaName	模式名称	String
tableName	表名称	String

响应体

名称	描述	类型
identifier	操作的标识符	String

POST /sessions/${sessionHandle}/operations/crossReference

名称	描述	类型
identifier	操作的标识符	String

请求体

名称	描述	类型
primaryCatalog	主目录名称	String
primarySchema	主模式名称	String
primaryTable	主表名称	String
foreignCatalog	外部目录名称	String
foreignSchema	外部模式名称	String
foreignTable	外部表名称	String

响应体

名称	描述	类型
identifier	操作的标识符	String

操作资源

GET /operations/${operationHandle}/event

通过指定的操作句柄获取该操作的当前事件。

响应体

KyuubiOperationEvent。

PUT /operations/${operationHandle}

对处于待执行或运行中的操作执行一个动作。

请求体

名称描述类型

action 对该操作执行的动作。目前支持的动作有 'cancel' 和 'close'。

Cancel：取消该操作，即操作及其对应的后台任务将被停止，其状态将切换为 CANCELED。处于 CANCELED 状态的操作仍可通过客户端请求获取其状态。
Close：关闭该操作，即操作及其对应的后台任务将被停止，其状态将切换为 CLOSED。处于 CLOSED 状态的操作将在服务端被移除，且无法再获取。

String

GET /operations/${operationHandle}/resultsetmetadata

通过指定的操作句柄获取该操作的结果集 schema。

响应体

名称	描述	类型
columns	各列的描述	ColumnDesc 列表

GET /operations/${operationHandle}/log

通过指定的操作句柄获取运行中操作的日志行列表。

请求参数

名称	描述	类型
maxrows	每次拉取的最大行数	Int

响应体

名称	描述	类型
logRowSet	日志集合	字符串列表
rowCount	日志行数	Int

GET /operations/${operationHandle}/rowset

通过指定的操作句柄以行列表的形式获取操作结果。

请求参数

名称	描述	类型
maxrows	每次拉取的最大行数	Int
fetchorientation	拉取方向，例如 FETCH_NEXT、FETCH_PRIOR、FETCH_FIRST、FETCH_LAST、FETCH_RELATIVE、FETCH_ABSOLUTE	String

响应体

名称	描述	类型
rows	行的列表	行列表
rowCount	行数	Int

批处理资源

GET /batches

返回所有的批处理。

请求参数

名称描述类型

batchType 批处理类型，例如 spark/flink，如果未指定 batchType，将返回所有类型 String

batchState 有效的批次状态可以是以下之一：
PENDING、RUNNING、FINISHED、ERROR、CANCELED String

batchUser 创建该批次的用户名 String

createTime 返回在此时间戳之后创建的批次 Long

endTime 返回在此时间戳之前结束的批次 Long

from 获取批次的起始索引 Int

size 获取的批次数量，默认为 100 Int

响应体

名称	描述	类型
from	获取批次的起始索引	Int
total	获取的批次总数	Int
batches	Batch 列表	List

POST /batches

创建一个新的批次。

请求体

媒体类型：application-json
JSON 结构：

名称	描述	类型
batchType	批次类型，例如 Spark、Flink	String
resource	包含要执行的应用程序的资源文件路径	Path（必填）
className	应用程序主类	String（必填）
name	该批次的名称	String
conf	配置属性	key=val 的 Map
args	应用程序的命令行参数	字符串 List

响应体

创建的 Batch 对象。

POST /batches（上传资源）

通过上传资源文件创建一个新的批次。

以下是使用 curl 命令以 multipart-formdata 媒体类型向 /v1/batches 发送 POST 请求，并从本地路径上传资源文件的示例。

curl --location --request POST 'http://localhost:10099/api/v1/batches' \
--form 'batchRequest="{\"batchType\":\"SPARK\",\"className\":\"org.apache.spark.examples.SparkPi\",\"name\":\"Spark Pi\"}";type=application/json' \
--form 'resourceFile=@"/local_path/example.jar"'

请求体

媒体类型：multipart-formdata
请求体以多部分（multipart）形式组织：

名称	描述	媒体类型
batchRequest	POST /batches 所需的 JSON 格式批处理请求作为请求体	application/json
resourceFile	需要上传并执行的资源，它将在服务端被缓存，并在执行完成后清理	File

响应体

已创建的 Batch 对象。

GET /batches/${batchId}

返回批处理信息。

响应体

Batch 对象。

DELETE /batches/${batchId}

如果批处理仍在运行，则终止该批处理。

响应体

名称	描述	类型
success	是否成功终止了批处理	Boolean
msg	终止批处理的消息	String

GET /batches/${batchId}/localLog

获取该批处理的本地日志行。

请求参数

名称	描述	类型
from	偏移量	Int
size	返回的最大日志行数，默认为 100	Int

响应体

名称	描述	类型
logRowSet	日志行	字符串列表
rowCount	日志行数	Int

管理资源

POST /admin/refresh/hadoop_conf

刷新 Kyuubi 服务端的 Hadoop 配置。

POST /admin/refresh/user_defaults_conf

从默认属性文件中刷新键格式为 ___{username}___.{config key} 的用户默认配置。

POST /admin/refresh/kubernetes_conf

从默认属性文件中刷新键以 kyuubi.kubernetes 为前缀的 Kubernetes 配置。

当你需要支持多个 Kubernetes 上下文和命名空间时，该功能会很有用，参见 KYUUBI devlive-community/knowforge#4843。

DELETE /admin/engine

删除指定的引擎。

请求参数

名称	说明	类型
type	引擎类型	String(可选)
sharelevel	引擎共享级别	String(可选)
subdomain	引擎子域	String(可选)
proxyUser	要模拟的代理用户	String(可选)
hive.server2.proxy.user	要模拟的代理用户	String(可选)

proxyUser 是 hive.server2.proxy.user 的替代参数，当前行为与 hive.server2.proxy.user 一致。当两个参数同时设置时，以 proxyUser 为准。

GET /admin/engine

获取满足条件的引擎列表。

请求参数

名称	说明	类型
type	引擎类型	String(可选)
sharelevel	引擎共享级别	String(可选)
subdomain	引擎子域	String(可选)
proxyUser	要模拟的代理用户	String(可选)
hive.server2.proxy.user	要模拟的代理用户	String(可选)

proxyUser 是 hive.server2.proxy.user 的替代参数，当前行为与 hive.server2.proxy.user 一致。当两个参数同时设置时，以 proxyUser 为准。

响应体

Engine 列表。

REST 对象

Batch

名称	描述	类型
id	批处理 ID	String
user	创建该批处理的用户	String
batchType	批处理类型	String
name	批处理名称	String
appStartTime	批处理应用启动时间	Long
appId	批处理应用 Id	String
appUrl	批处理应用的追踪 URL	String
appState	批处理应用状态	String
appDiagnostic	批处理应用诊断信息	String
kyuubiInstance	创建该批处理的 Kyuubi 实例	String
state	Kyuubi 批处理操作状态	String
createTime	批处理创建时间	Long
endTime	批处理结束时间，若尚未终止，则值为 0	Long

KyuubiSessionEvent

名称	描述	类型
sessionId	会话 ID	String
clientVersion	客户端版本	Int
sessionType	会话类型	String
sessionName	会话名称，如果用户未指定，则使用空字符串	String
user	会话用户名	String
clientIP	客户端 IP 地址	String
serverIP	唯一的 Kyuubi 服务器 ID，例如 Kyuubi 服务器的 IP 地址和端口；当存在多实例 Kyuubi Server 时非常有用	String
conf	会话配置	Map
startTime	会话创建时间	Long
remoteSessionId	远程引擎会话 ID	String
engineId	引擎 ID。对于运行在 YARN 上的引擎，即为 applicationId	String
openedTime	会话打开时间	Long
endTime	会话结束时间	Long
totalOperations	查询和元数据调用的总次数	Int
exception	会话异常，例如打开会话时发生的异常	Throwable
eventType	会话事件类型	String

KyuubiOperationEvent

名称	说明	类型
statementId	单个操作的唯一标识符	String
remoteId	单个操作在引擎侧的唯一标识符	String
statement	你所执行的 SQL	String
shouldRunAsync	指示查询是同步运行还是异步运行的标志	Boolean
state	当前操作状态	String
eventTime	事件创建并记录的时间	Long
createTime	转换为当前操作状态的时间	Long
startTime	查询开始的时间	Long
completeTime	查询结束的时间	Long
exception	捕获到的异常（如有）	Throwable
sessionId	父会话的标识符	String
sessionUser	已认证的客户端用户	String

ColumnDesc

名称	说明	类型
columnName	列的名称	String
dataType	该列的类型描述符	String
columnIndex	该列在 schema 中的索引	Int
precision	列的精度	Int
scale	列的小数位数	Int
comment	列的注释	String

Row

名称	说明	类型
fields	行中的字段	字段列表

Field

名称	说明	类型
dataType	列的类型	String
value	列的值	Object

Engine

名称	描述	类型
version	创建该引擎实例的 Kyuubi 服务器版本	String
user	创建该引擎的用户	String
engineType	引擎类型	String
sharelevel	引擎共享级别	String
subdomain	引擎子域	String
instance	引擎节点的 host:port	String
namespace	用于将引擎暴露给 KyuubiServer 的命名空间	String