KnowForgeREST API v1
师成· 更新于 2026-09-29· 阅读 43 分钟· 0 次阅读Note that: now the api version is v1 and the base uri is /api/v1.
Session Resource
GET /sessions
Get the list of all live sessions
Response Body
| Name | Description | Type |
|---|---|---|
| identifier | The session identifier | String |
| user | The user name that created the session | String |
| ipAddr | The client IP address that created the session | String |
| conf | The configuration of the session | Map |
| createTime | The session that created at this timestamp | Long |
| duration | The interval that last access time subtract created time | Long |
| idleTime | The interval of no operation | Long |
GET /sessions/${sessionHandle}
Get a session event
Response Body
The KyuubiSessionEvent.
GET /sessions/${sessionHandle}/info/${infoType}
Get an information detail of a session
Request Parameters
| Name | Description | Type |
|---|---|---|
| infoType | The id of Hive Thrift GetInfo | Int |
Response Body
| Name | Description | Type |
|---|---|---|
| infoType | The type of session information | String |
| infoValue | The value of session information | String |
GET /sessions/count
Get the current open session count
Response Body
| Name | Description | Type |
|---|---|---|
| openSessionCount | The count of opening session | Int |
GET /sessions/execPool/statistic
Get statistic info of background executors
Response Body
| Name | Description | Type |
|---|---|---|
| execPoolSize | The current number of threads in the pool | Int |
| execPoolActiveCount | The approximate number of threads that are actively executing tasks | Int |
POST /sessions
Create a session
Request Parameters
| Name | Description | Type |
|---|---|---|
| configs | The configuration of the session | Map |
Response Body
| Name | Description | Type |
|---|---|---|
| identifier | The session handle identifier | String |
| kyuubiInstance | The Kyuubi instance that holds the session and to call for the following operations in the session | String |
DELETE /sessions/${sessionHandle}
Close a session.
POST /sessions/${sessionHandle}/operations/statement
Create an operation with EXECUTE_STATEMENT type
Request Body
| Name | Description | Type |
|---|---|---|
| statement | The SQL statement that you execute | String |
| runAsync | The flag indicates whether the query runs synchronously or not | Boolean |
| queryTimeout | The interval of query time out | Long |
| confOverlay | The conf to overlay only for current operation | Map of key=val |
Response Body
| Name | Description | Type |
|---|---|---|
| identifier | The identifier of operation | String |
POST /sessions/${sessionHandle}/operations/typeInfo
Create an operation with GET_TYPE_INFO type
Response Body
| Name | Description | Type |
|---|---|---|
| identifier | The identifier of operation | String |
POST /sessions/${sessionHandle}/operations/catalogs
Create an operation with GET_CATALOGS type
Response Body
| Name | Description | Type |
|---|---|---|
| identifier | The identifier of operation | String |
POST /sessions/${sessionHandle}/operations/schemas
Create an operation with GET_SCHEMAS type
Request Body
| Name | Description | Type |
|---|---|---|
| catalogName | The catalog name | String |
| schemaName | The schema name | String |
Response Body
| Name | Description | Type |
|---|---|---|
| identifier | The identifier of operation | String |
POST /sessions/${sessionHandle}/operations/tables
Request Body
| Name | Description | Type |
|---|---|---|
| catalogName | The catalog name | String |
| schemaName | The schema name | String |
| tableName | The table name | String |
| tableTypes | The type of table, for example: TABLE or VIEW | String |
Response Body
| Name | Description | Type |
|---|---|---|
| identifier | The identifier of operation | String |
POST /sessions/${sessionHandle}/operations/tableTypes
Request Parameters
Response Body
| Name | Description | Type |
|---|---|---|
| identifier | The identifier of operation | String |
POST /sessions/${sessionHandle}/operations/columns
Request Body
| Name | Description | Type |
|---|---|---|
| catalogName | The catalog name | String |
| schemaName | The schema name | String |
| tableName | The table name | String |
| columnName | The column name | String |
Response Body
| Name | Description | Type |
|---|---|---|
| identifier | The identifier of operation | String |
POST /sessions/${sessionHandle}/operations/functions
Request Body
| Name | Description | Type |
|---|---|---|
| catalogName | The catalog name | String |
| schemaName | The schema name | String |
| functionName | The function name | String |
Response Body
| Name | Description | Type |
|---|---|---|
| identifier | The identifier of operation | String |
POST /sessions/${sessionHandle}/operations/primaryKeys
Request Parameters
| Name | Description | Type |
|---|---|---|
| catalogName | The catalog name | String |
| schemaName | The schema name | String |
| tableName | The table name | String |
Response Body
| Name | Description | Type |
|---|---|---|
| identifier | The identifier of operation | String |
POST /sessions/${sessionHandle}/operations/crossReference
| Name | Description | Type |
|---|---|---|
| identifier | The identifier of operation | String |
Request Body
| Name | Description | Type |
|---|---|---|
| primaryCatalog | The primary catalog name | String |
| primarySchema | The primary schema name | String |
| primaryTable | The primary table name | String |
| foreignCatalog | The foreign catalog name | String |
| foreignSchema | The foreign schema name | String |
| foreignTable | The foreign table name | String |
Response Body
| Name | Description | Type |
|---|---|---|
| identifier | The identifier of operation | String |
Operation Resource
GET /operations/${operationHandle}/event
Get the current event of the operation by the specified operation handle.
Response Body
The KyuubiOperationEvent.
PUT /operations/${operationHandle}
Perform an action to the pending or running operation.
Request Body
Name Description Type
action The action that is performed to the operation. Currently, supported actions are 'cancel' and 'close'.
- Cancel: to cancel the operation, which means the operation and its corresponding background task will be stopped, and its state will be switched to CANCELED. A CANCELED operation's status can still be fetched by client requests.
- Close: to close the operation, which means the operation and its corresponding background task will be stopped, and its state will be switched to CLOSED. A CLOSED operation's status will be removed on the server side and can not be fetched anymore.
String
GET /operations/${operationHandle}/resultsetmetadata
Get the result set schema of the operation by the specified operation handle.
Response Body
| Name | Description | Type |
|---|---|---|
| columns | The descriptions of columns | List of ColumnDesc |
GET /operations/${operationHandle}/log
Get a list of operation log lines of the running operation by the specified operation handle.
Request Parameters
| Name | Description | Type |
|---|---|---|
| maxrows | The max row that are pulled each time | Int |
Response Body
| Name | Description | Type |
|---|---|---|
| logRowSet | The set of log set | List of Strings |
| rowCount | The count of log row set | Int |
GET /operations/${operationHandle}/rowset
Get the operation result as a list of rows by the specified operation handle.
Request Parameters
| Name | Description | Type |
|---|---|---|
| maxrows | The max rows that are pulled each time | Int |
| fetchorientation | The orientation of fetch, for example FETCH_NEXT, FETCH_PRIOR, FETCH_FIRST, FETCH_LAST, FETCH_RELATIVE, FETCH_ABSOLUTE | String |
Response Body
| Name | Description | Type |
|---|---|---|
| rows | The list of rows | List of Rows |
| rowCount | The count of rows | Int |
Batch Resource
GET /batches
Returns all the batches.
Request Parameters
Name Description Type
batchType The batch type, such as spark/flink, if no batchType is specified,
return all types String
batchState The valid batch state can be one of the following:
PENDING, RUNNING, FINISHED, ERROR, CANCELED String
batchUser The user name that created the batch String
createTime Return the batch that created after this timestamp Long
endTime Return the batch that ended before this timestamp Long
from The start index to fetch batches Int
size Number of batches to fetch, 100 by default Int
Response Body
| Name | Description | Type |
|---|---|---|
| from | The start index of fetched batches | Int |
| total | Number of batches fetched | Int |
| batches | Batch List | List |
POST /batches
Create a new batch.
Request Body
- Media type:
application-json - JSON structure:
| Name | Description | Type |
|---|---|---|
| batchType | The batch type, such as Spark, Flink | String |
| resource | The resource containing the application to execute | Path (required) |
| className | Application main class | String(required) |
| name | The name of this batch. | String |
| conf | Configuration properties | Map of key=val |
| args | Command line arguments for the application | List of Strings |
Response Body
The created Batch object.
POST /batches (with uploading resource)
Create a new batch with uploading resource file.
Example of using curl command to send POST request to /v1/batches in multipart-formdata media type with uploading resource file from local path.
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"'Request Body
- Media type:
multipart-formdata - Request body structure in multiparts:
| Name | Description | Media Type |
|---|---|---|
| batchRequest | The batch request in JSON format as request body requried in POST /batches | application/json |
| resourceFile | The resource to upload and execute, which will be cached on server and cleaned up after execution | File |
Response Body
The created Batch object.
GET /batches/${batchId}
Returns the batch information.
Response Body
The Batch.
DELETE /batches/${batchId}
Kill the batch if it is still running.
Response Body
| Name | Description | Type |
|---|---|---|
| success | Whether killed the batch successfully | Boolean |
| msg | The kill batch message | String |
GET /batches/${batchId}/localLog
Gets the local log lines from this batch.
Request Parameters
| Name | Description | Type |
|---|---|---|
| from | Offset | Int |
| size | Max number of log lines to return, 100 by default | Int |
Response Body
| Name | Description | Type |
|---|---|---|
| logRowSet | The log lines | List of Strings |
| rowCount | The log row count | Int |
Admin Resource
POST /admin/refresh/hadoop_conf
Refresh the Hadoop configurations of the Kyuubi server.
POST /admin/refresh/user_defaults_conf
Refresh the user defaults configs with key in format in the form of ___{username}___.{config key} from default property file.
POST /admin/refresh/kubernetes_conf
Refresh the kubernetes configs with key prefixed with kyuubi.kubernetes from default property file.
It is helpful if you need to support multiple kubernetes contexts and namespaces, see KYUUBI devlive-community/knowforge#4843.
DELETE /admin/engine
Delete the specified engine.
Request Parameters
| Name | Description | Type |
|---|---|---|
| type | the engine type | String(optional) |
| sharelevel | the engine share level | String(optional) |
| subdomain | the engine subdomain | String(optional) |
| proxyUser | the proxy user to impersonate | String(optional) |
| hive.server2.proxy.user | the proxy user to impersonate | String(optional) |
proxyUser is an alternative to hive.server2.proxy.user, and the current behavior is consistent with hive.server2.proxy.user. When both parameters are set, proxyUser takes precedence.
GET /admin/engine
Get a list of satisfied engines.
Request Parameters
| Name | Description | Type |
|---|---|---|
| type | the engine type | String(optional) |
| sharelevel | the engine share level | String(optional) |
| subdomain | the engine subdomain | String(optional) |
| proxyUser | the proxy user to impersonate | String(optional) |
| hive.server2.proxy.user | the proxy user to impersonate | String(optional) |
proxyUser is an alternative to hive.server2.proxy.user, and the current behavior is consistent with hive.server2.proxy.user. When both parameters are set, proxyUser takes precedence.
Response Body
The Engine List.
REST Objects
Batch
| Name | Description | Type |
|---|---|---|
| id | The batch id | String |
| user | The user created the batch | String |
| batchType | The batch type | String |
| name | The batch name | String |
| appStartTime | The batch application start time | Long |
| appId | The batch application Id | String |
| appUrl | The batch application tracking url | String |
| appState | The batch application state | String |
| appDiagnostic | The batch application diagnostic | String |
| kyuubiInstance | The kyuubi instance that created the batch | String |
| state | The kyuubi batch operation state | String |
| createTime | The batch create time | Long |
| endTime | The batch end time, if it has not been terminated, the value is 0 | Long |
KyuubiSessionEvent
| Name | Description | Type |
|---|---|---|
| sessionId | The session id | String |
| clientVersion | The client version | Int |
| sessionType | The session type | String |
| sessionName | The session name, if user not specify it, we use empty string instead | String |
| user | The session user name | String |
| clientIP | The client ip address | String |
| serverIP | A unique Kyuubi server id, e.g. kyuubi server ip address and port, it is useful if has multi-instance Kyuubi Server | String |
| conf | The session config | Map |
| startTime | The session create time | Long |
| remoteSessionId | The remote engine session id | String |
| engineId | The engine id. For engine on yarn, it is applicationId | String |
| openedTime | The session opened time | Long |
| endTime | The session end time | Long |
| totalOperations | How many queries and meta calls | Int |
| exception | The session exception, such as the exception that occur when opening session | Throwable |
| eventType | The type of session event | String |
KyuubiOperationEvent
| Name | Description | Type |
|---|---|---|
| statementId | The unique identifier of a single operation | String |
| remoteId | The unique identifier of a single operation at engine side | String |
| statement | The sql that you execute | String |
| shouldRunAsync | The flag indicating whether the query runs synchronously or not | Boolean |
| state | The current operation state | String |
| eventTime | The time when the event created & logged | Long |
| createTime | The time for changing to the current operation state | Long |
| startTime | The time the query start to time of this operation | Long |
| completeTime | Time time the query ends | Long |
| exception | Caught exception if have | Throwable |
| sessionId | The identifier of the parent session | String |
| sessionUser | The authenticated client user | String |
ColumnDesc
| Name | Description | Type |
|---|---|---|
| columnName | The name of the column | String |
| dataType | The type descriptor for this column | String |
| columnIndex | The index of this column in the schema | Int |
| precision | The precision of the column | Int |
| scale | The scale of the column | Int |
| comment | The comment of the column | String |
Row
| Name | Description | Type |
|---|---|---|
| fields | The fields of row | List of Fields |
Field
| Name | Description | Type |
|---|---|---|
| dataType | The type of column | String |
| value | The value of column | Object |
Engine
| Name | Description | Type |
|---|---|---|
| version | The version of the Kyuubi server that creates this engine instance | String |
| user | The user created the engine | String |
| engineType | The engine type | String |
| sharelevel | The engine share level | String |
| subdomain | The engine subdomain | String |
| instance | host:port for the engine node | String |
| namespace | The namespace used to expose the engine to KyuubiServers | String |
评论
登录后参与评论