This is an automated email from the ASF dual-hosted git repository.
chengpan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-kyuubi.git
The following commit(s) were added to refs/heads/master by this push:
new 797957629 [KYUUBI #3611][DOCS] Add session resource REST docs
797957629 is described below
commit 797957629d9a07846d68dafc06bf425464a7085a
Author: Luning Wang <[email protected]>
AuthorDate: Wed Oct 19 00:22:07 2022 +0800
[KYUUBI #3611][DOCS] Add session resource REST docs
### _Why are the changes needed?_
Add session resource REST docs in `rest_api.md`
### _How was this patch tested?_
- [ ] Add some test cases that check the changes thoroughly including
negative and positive cases if possible
- [ ] Add screenshots for manual tests if appropriate
- [x] [Run
test](https://kyuubi.apache.org/docs/latest/develop_tools/testing.html#running-tests)
locally before make a pull request
Closes #3642 from deadwind4/session-rest-doc.
Closes #3611
3d8e5e6b [Luning Wang] Fix wrong description
8a1372a5 [Luning Wang] [KYUUBI #3611][DOCS] Add session resource REST docs
Authored-by: Luning Wang <[email protected]>
Signed-off-by: Cheng Pan <[email protected]>
---
docs/client/rest/rest_api.md | 264 ++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 263 insertions(+), 1 deletion(-)
diff --git a/docs/client/rest/rest_api.md b/docs/client/rest/rest_api.md
index e9a40c961..cf0c8643a 100644
--- a/docs/client/rest/rest_api.md
+++ b/docs/client/rest/rest_api.md
@@ -19,6 +19,248 @@
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](#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 |
+|:----------------|:-----------------------------------------|:-------|
+| protocolVersion | The protocol version of Hive CLI service | Int |
+| user | The user name | String |
+| password | The user password | String |
+| ipAddr | The user client IP address | String |
+| configs | The configuration of the session | Map |
+
+#### Response Body
+
+| Name | Description | Type |
+|:-----------|:------------------------------|:-------|
+| identifier | The session handle identifier | 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 |
+
+#### 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 |
+
## Batch Resource
### GET /batches
@@ -58,7 +300,6 @@ Returns all the batches.
| conf | Configuration properties | Map of
key=val |
| args | Command line arguments for the application | List of
Strings |
-
#### Response Body
The created [Batch](#batch) object.
@@ -122,3 +363,24 @@ Gets the local log lines from this batch.
| 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 |
