Run a Jupyter Notebook

POST /api/v1.2/commands

Use this API to run a Jupyter notebook. You can view the command’s status, result, or cancel a command using the corresponding Command API that are used for other types of command.

Required Role

The following users can make this API call:

  • Users who belong to the system-user or system-admin group.

  • Users who belong to a group associated with a role that allows update on Jupyter Notebook and directory. See Managing Groups and Managing Roles for more information.

Parameters

Note

Parameters marked in bold below are mandatory. Others are optional and have default values.

Parameter

Description

path

Path including name of the Jupyter notebook to be run with extension (.ipynb).

label

Label of the cluster on which the Jupyter notebook should be run. If this parameter is not specified then label = “default” is used.

command_type

Type of command to be executed. For Jupyter notebook, the command type is JupyterNotebookCommand.

arguments

Valid JSON to be sent to the notebook. Specify the parameters in notebooks and pass the parameter value using the JSON format. key is the parameter’s name and value is the parameter’s value.

Supported types in parameters are string, integer, float, and boolean.

upload_to_source

Specifies if the original notebook should be updated after execution. Default value is true.

Request API Syntax

Here is the Request API syntax for running a Jupyter notebook.

curl  -i -X POST -H "X-AUTH-TOKEN: <auth_token>" -H "Content-Type: application/json" -H "Accept: application/json" \
-d '{"path":"<Path>/<Name>", "command_type":"JupyterNotebookCommand",  "label":"<ClusterLabel>", "arguments": {"key1":"value1", "key2":"value2", ..., "keyN":"valueN"}}' \
 "https://api.qubole.com/api/v1.2/commands"

Note

The above syntax uses https://api.qubole.com as the endpoint. Qubole provides other endpoints to access QDS that are described in Supported Qubole Endpoints on Different Cloud Providers.

Sample API Request

curl  -i -X POST -H "X-AUTH-TOKEN: $AUTH_TOKEN" -H "Content-Type: application/json" -H "Accept: application/json" \
-d '{"path":"Users/[email protected]/note1.ipynb", "command_type":"JupyterNotebookCommand",  "label":"spark-cluster-1", "arguments": {"name":"xyz", "age":"20"}}' \
 "https://api.qubole.com/api/v1.2/commands"

Known Limitation

If there is a warning in one of the cells when this API is run, the notebook stops executing at that cell. As a workaround, to skip the warning and continue execution, add raises-exception in that cell’s metadata field by performing the following steps:

  1. Select the cell that shows the warning.

  2. Click on the Tools icon on the left side bar.

  3. Click Advanced Tools.

  4. Add raises-exception in the Cell Metadata tags field.

  5. Re-run the API.