Command Execution
Cancel a command GA
POST
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
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.
pythonscalasqlr
- 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
contextIdorcommandId.
Get command info GA
GET
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.
- contextIdstringRequiredquery
ID of the execution context the command runs in.
- commandIdstringRequiredquery
ID of the command, as returned by execute.
Response
- idstring
ID of the command.
- statusstring
Current status of the command.
QueuedandRunningmean the command has not completed yet, andCancellingmeans a cancellation is in progress.Finished,ErrorandCancelledare terminal:Finishedmeans the command ran to completion, including when the code itself raised an error (reported inresultswith theerrorresult type), whileErrormeans the execution environment failed, for example because the driver or the context stopped.CancelledCancellingErrorFinishedQueuedRunning
- resultsobject
Output of the command. It is populated only once the command has reached a terminal status, and its
resultTypetells which of its other fields are set.Show child attributesHide child attributes
- causestring
Details of an
errorresult, usually the exception message or stack trace.
- dataobject
Output of a
textresult as a string, or the rows of atableresult as an array of rows, each an array of column values in the order ofschema.
- fileNamestring
The image data in one of the following formats:
-
A Data URL with base64-encoded image data:
data:image/{type};base64,{base64-data}. Example:data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA... -
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:
textputs the output indata,tablefillsdata,schema,truncatedandisJsonSchema,imageandimagesfillfileNameandfileNamesrespectively, anderrorfillscauseandsummary.errorimageimagestabletext
- schemaarray of object
Columns of a
tableresult, in the order of the values within each row ofdata. Each entry has aname, atypeand ametadatakey.
- summarystring
Short description of an
errorresult, such as the exception type and message, when available.
- truncatedboolean
Whether a
tableresult was cut off because the command output exceeded the row or byte limit.
Create an execution context GA
POST
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.
pythonscalasqlr
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
contextIdorcommandId.
Delete an execution context GA
POST
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
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.
- contextIdstringRequiredquery
ID of the execution context, as returned by Create.
Response
- idstring
ID of the execution context.
- statusstring
Current status of the execution context.
Pendingmeans the context is still initializing and does not accept commands yet,Runningmeans it is ready, andErrormeans it failed: running commands may not complete and new commands may be rejected, so create a new context.RunningPendingError