layout: page title: Livy Docs - REST API tagline: REST API

{% include JB/setup %}

REST API

GET /sessions

Returns all the active interactive sessions.

Request Parameters

Response Body

POST /sessions

Creates a new interactive Scala, Python, or R shell in the cluster.

Request Body

1: Starting with version 0.5.0-incubating this field is not required. To be compatible with previous versions users can still specify this with spark, pyspark or sparkr, implying that the submitted code snippet is the corresponding kind.

Response Body

The created Session.

GET /sessions/{sessionId}

Returns the session information.

Response Body

The Session.

GET /sessions/{sessionId}/state

Returns the state of session

Response

DELETE /sessions/{sessionId}

Kills the Session job.

GET /sessions/{sessionId}/log

Gets the log lines from this session.

Request Parameters

Response Body

GET /sessions/{sessionId}/statements

Returns all the statements in a session.

Response Body

POST /sessions/{sessionId}/statements

Runs a statement in a session.

Request Body

2: If session kind is not specified or the submitted code is not the kind specified in session creation, this field should be filled with correct kind. Otherwise Livy will use kind specified in session creation as the default code kind.

Response Body

The statement object.

GET /sessions/{sessionId}/statements/{statementId}

Returns a specified statement in a session.

Response Body

The statement object.

POST /sessions/{sessionId}/statements/{statementId}/cancel

Cancel the specified statement in this session.

Response Body

POST /sessions/{sessionId}/completion

Runs a statement in a session.

Request Body

Response Body

GET /batches

Returns all the active batch sessions.

Request Parameters

Response Body

POST /batches

Creates a new batch session.

Request Body

Response Body

The created Batch object.

GET /batches/{batchId}

Returns the batch session information.

Response Body

The Batch.

GET /batches/{batchId}/state

Returns the state of batch session

Response

DELETE /batches/{batchId}

Kills the Batch job.

GET /batches/{batchId}/log

Gets the log lines from this batch.

Request Parameters

Response Body

REST Objects

Session

A session represents an interactive shell.

Session State

Session Kind

Starting with version 0.5.0-incubating, each session can support all four Scala, Python and R interpreters with newly added SQL interpreter. The kind field in session creation is no longer required, instead users should specify code kind (spark, pyspark, sparkr or sql) during statement submission.

To be compatible with previous versions, users can still specify kind in session creation, while ignoring kind in statement submission. Livy will then use this session kind as default kind for all the submitted statements.

If users want to submit code other than default kind specified in session creation, users need to specify code kind (spark, pyspark, sparkr or sql) during statement submission.

pyspark

To change the Python executable the session uses, Livy reads the path from environment variable PYSPARK_PYTHON (Same as pyspark).

Starting with version 0.5.0-incubating, session kind “pyspark3” is removed, instead users require to set PYSPARK_PYTHON to python3 executable.

Like pyspark, if Livy is running in local mode, just set the environment variable. If the session is running in yarn-cluster mode, please set spark.yarn.appMasterEnv.PYSPARK_PYTHON in SparkConf so the environment variable is passed to the driver.

Statement

A statement represents the result of an execution statement.

Statement State

Statement Output

Batch

Proxy User - doAs support

If superuser support is configured, Livy supports the doAs query parameter to specify the user to impersonate. The doAs query parameter can be used on any supported REST endpoint described above to perform the action as the specified user. If both doAs and proxyUser are specified during session or batch creation, the doAs parameter takes precedence.