Skip to main content

Command Execution

View as Markdown

Cancel a command GA​

POST /api/1.2/commands/cancel

Cancels a currently running command within an execution context.

The command ID is obtained from a prior successful call to execute. Cancellation is asynchronous: this method returns once the request is accepted, and the command moves through the Cancelling status before reaching a terminal one. Poll commandStatus to observe the outcome; a cancelled command ends in the Finished status with an error result that describes the cancellation.

API scopes: command-execution

Request body​

clusterIdstring

ID of the cluster that hosts the execution context.

commandIdstring

ID of the command to cancel, as returned by execute.

contextIdstring

ID of the execution context the command runs in.

Run a command GA​

POST /api/1.2/commands/execute

Runs a cluster command in the given execution context, using the provided language.

If successful, it returns an ID for tracking the status of the command's execution. This method returns as soon as the command is accepted, so poll commandStatus with the returned ID to wait for the command to finish and to read its results.

API scopes: command-execution

Request body​

clusterIdstring

ID of the cluster that hosts the execution context.

contextIdstring

ID of the execution context to run the command in, as returned by Create.

languagestring

Language the command is written in.

Values:

  • python
  • scala
  • sql
  • r
commandstring

Code to run, written in the specified language.

Response​

idstring

ID of the new execution context when returned by Create, or of the submitted command when returned by execute. Pass it to the other methods of this API as contextId or commandId.

Get command info GA​

GET /api/1.2/commands/status

Gets the status of and, if available, the results from a currently executing command.

The command ID is obtained from a prior successful call to execute. Poll this method until the status is one of the terminal values Finished, Error or Cancelled; the results field is populated only once the command has reached a terminal status.

API scopes: command-execution

Parameters​

clusterIdstringRequiredquery

ID of the cluster that hosts the execution context.

Example: 0123-456789-abcdefg1

contextIdstringRequiredquery

ID of the execution context the command runs in.

Example: 3f2a9c1e8b7d4a6f9e0c1b2d3a4f5e6d

commandIdstringRequiredquery

ID of the command, as returned by execute.

Example: 5c8e1d2f3a4b8c9d8e0f1a2b3c4d5e6f

Response​

idstring

ID of the command.

statusstring

Current status of the command. Queued and Running mean the command has not completed yet, and Cancelling means a cancellation is in progress. Finished, Error and Cancelled are terminal: Finished means the command ran to completion, including when the code itself raised an error (reported in results with the error result type), while Error means the execution environment failed, for example because the driver or the context stopped.

Values:

  • Cancelled
  • Cancelling
  • Error
  • Finished
  • Queued
  • Running
resultsobject

Output of the command. It is populated only once the command has reached a terminal status, and its resultType tells which of its other fields are set.

Show child attributesHide child attributes
causestring

Details of an error result, usually the exception message or stack trace.

dataobject

Output of a text result as a string, or the rows of a table result as an array of rows, each an array of column values in the order of schema.

fileNamestring

The image data in one of the following formats:

  1. A Data URL with base64-encoded image data: data:image/{type};base64,{base64-data}. Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...

  2. A FileStore file path for large images: /plots/{filename}.png. Example: /plots/b6a7ad70-fb2c-4353-8aed-3f1e015174a4.png

fileNamesarray of string

List of image data for multiple images. Each element follows the same format as file_name.

isJsonSchemaboolean

true if a JSON schema is returned instead of a string representation of the Hive type.

posint32

internal field used by SDK

resultTypestring

Type of the result, which determines which other fields are set: text puts the output in data, table fills data, schema, truncated and isJsonSchema, image and images fill fileName and fileNames respectively, and error fills cause and summary.

Values:

  • error
  • image
  • images
  • table
  • text
schemaarray of object

Columns of a table result, in the order of the values within each row of data. Each entry has a name, a type and a metadata key.

summarystring

Short description of an error result, such as the exception type and message, when available.

truncatedboolean

Whether a table result was cut off because the command output exceeded the row or byte limit.

Create an execution context GA​

POST /api/1.2/contexts/create

Creates an execution context for running cluster commands.

If successful, this method returns the ID of the new execution context. The context may still be initializing when this method returns, so poll contextStatus until the status is Running before running commands in it. This method and the other methods of this API require the CAN ATTACH TO permission on the cluster.

API scopes: command-execution

Request body​

clusterIdstring

ID of the cluster to create the execution context on. The cluster must be running.

languagestring

Programming language of the execution context.

Values:

  • python
  • scala
  • sql
  • r

Response​

idstring

ID of the new execution context when returned by Create, or of the submitted command when returned by execute. Pass it to the other methods of this API as contextId or commandId.

Delete an execution context GA​

POST /api/1.2/contexts/destroy

Deletes an execution context.

Delete contexts you no longer need, because a cluster can host only a limited number of execution contexts at a time. Deleting a context that no longer exists succeeds, so the call is safe to retry.

API scopes: command-execution

Request body​

clusterIdstringRequired

ID of the cluster that hosts the execution context.

contextIdstringRequired

ID of the execution context to delete, as returned by Create.

Get status GA​

GET /api/1.2/contexts/status

Gets the status for an execution context.

After Create, poll this method until the status is Running or Error. Requests for a context that has been deleted fail with an error instead of returning a status.

API scopes: command-execution

Parameters​

clusterIdstringRequiredquery

ID of the cluster that hosts the execution context.

Example: 0123-456789-abcdefg1

contextIdstringRequiredquery

ID of the execution context, as returned by Create.

Example: 3f2a9c1e8b7d4a6f9e0c1b2d3a4f5e6d

Response​

idstring

ID of the execution context.

statusstring

Current status of the execution context. Pending means the context is still initializing and does not accept commands yet, Running means it is ready, and Error means it failed: running commands may not complete and new commands may be rejected, so create a new context.

Values:

  • Running
  • Pending
  • Error