REST API v1
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 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 #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 |