Workflow blocks
Databricks
Run SQL statements, manage SQL warehouses, and trigger Databricks Jobs
databricks — Run SQL statements, manage SQL warehouses, and trigger Databricks Jobs.
Where it appears
The Databricks block lives in the Integrations group of the Workflow Builder. Connect the Databricks integration before adding it.
Fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
resource | select | Yes | sql | Which Databricks resource to work with. Options: sql, jobs. |
operation | select | Yes | — | Which action to perform on the selected resource. |
statement | code | Yes | — | Read-only SQL only. SELECT, WITH, SHOW, DESCRIBE, DESC, and EXPLAIN are allowed; write operations are blocked. |
warehouseId | text (supports references) | No | — | Override the warehouse configured in the integration credentials. |
catalog | text (supports references) | No | — | Optional Databricks catalog for statement execution. |
schema | text (supports references) | No | — | Optional Databricks schema for statement execution. |
parameters | code | No | — | Optional statement parameters as an array of {name, value, type}. |
rowLimit | text (supports references) | No | — | Optional maximum number of rows returned. |
byteLimit | text (supports references) | No | — | Optional maximum result size in bytes. |
waitTimeoutSeconds | text (supports references) | No | — | Optional server-side wait timeout before the client begins polling. |
jobId | text (supports references) | Yes | — | The numeric ID of an existing Databricks Job to trigger via run-now. |
jobParameters | code | No | — | Optional job-level parameters as a {key: value} map (sent as job_parameters). |
notebookParams | code | No | — | Optional notebook widget values as a {key: value} map (sent as notebook_params). |
idempotencyToken | text (supports references) | No | — | Optional token so a retried trigger does not launch the job twice. |
runId | text (supports references) | Yes | — | The run ID returned by Run Job. |
includeOutput | toggle | No | — | Also fetch run output (notebook result / error) when the run is terminal. |
waitForCompletion | toggle | No | — | Poll the run until it reaches a terminal state before continuing. Fails with a clear error if the run outlives the wait timeout. |
pollIntervalSeconds | text (supports references) | No | — | How often to check the run while waiting (1–60 seconds, default 10). Only used when Wait for Completion is on. |
runWaitTimeoutSeconds | text (supports references) | No | — | Maximum time to wait for the run to finish (10–1800 seconds, default 300). Only used when Wait for Completion is on. |
limit | text (supports references) | No | — | Maximum number of jobs to return (default 25). |
Inputs and outputs
Inputs are the configurable fields above. The block produces these outputs:
Outputs
Reference an output downstream with <Databricks.field>.
| Name | Type | Description |
|---|---|---|
success | boolean | Whether the request succeeded |
warehouses | array | Available Databricks SQL warehouses |
error | string | Error message if failed |
statementId | string | Databricks statement ID |
status | json | Statement execution status |
result | json | Databricks statement result payload |
warehouseCount | number | Number of visible SQL warehouses |
runId | number | The ID of the triggered run |
numberInJob | number | Sequence number of this run within the job |
lifeCycleState | string | Run life-cycle state (e.g. RUNNING, TERMINATED) |
resultState | string | Run result state (e.g. SUCCESS, FAILED) once terminal |
isTerminal | boolean | True when the run has reached a terminal life-cycle state |
stateMessage | string | Human-readable state detail |
runPageUrl | string | URL to the run in the Databricks UI |
output | json | Run output payload when requested. Single-task runs return the task output directly; multi-task runs return { tasks: [{ task_key, run_id, output }] }. |
jobs | array | Available Databricks Jobs |
Example
A minimal configuration for this block:
{
"type": "databricks",
"config": {
"resource": "sql",
"operation": "...",
"statement": "...",
"jobId": "<PreviousStep.field>",
"runId": "<PreviousStep.field>"
}
}Limits and failure modes
- Requires a connected Databricks integration. Calls fail if that integration is disconnected or its authorization has expired.
- Required fields (
resource,operation,statement,jobId,runId) must be set, or the block fails validation before it runs. - On failure the
erroroutput is populated; downstream blocks that reference other outputs may not receive values.