> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/databricks.md). # Databricks Query a Databricks workspace for data analytics and machine learning. * Knowledge base source ### Connectors Choose the connector that matches your authentication method. The options below use the names shown in StackAI. | Connector | Authentication | | ------------------- | --------------------- | | Databricks | Personal Access Token | | Databricks (OAuth2) | OAuth sign-in | #### Databricks Connect to Databricks workspace for data analytics, machine learning, and data processing. Requires a Personal Access Token (PAT) from your Databricks workspace. **Set up in Databricks** 1. In your Databricks workspace, click your username in the top bar and open Settings, then Developer. 2. Next to Access tokens, click Manage, then Generate new token; give it a name and lifetime and generate it. 3. Copy the personal access token immediately, since it is shown only once, and note your workspace URL (and SQL warehouse / HTTP path if required). **Set up in StackAI** 1. Open **Settings → Connections**, add a connection, and select **Databricks**. 2. Enter the credentials and connection details in the fields below. 3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it. **Connection fields** | StackAI field | Required | What to enter | | --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Workspace URL | Yes | Your Databricks workspace URL (e.g., ). [Provider instructions](https://docs.databricks.com/workspace/workspace-details.html). | | Personal Access Token | Yes | Databricks PAT from User Settings > Access Tokens. Generate it for a user or service principal with read-only Unity Catalog grants on the target objects: GRANT USE CATALOG ON CATALOG main TO `stackai_ro`; GRANT USE SCHEMA ON SCHEMA main.default TO `stackai_ro`; GRANT SELECT ON SCHEMA main.default TO `stackai_ro`;. [Provider instructions](https://docs.databricks.com/dev-tools/api/latest/authentication.html#personal-access-tokens). | | Catalog (Optional) | Optional / as applicable | Unity Catalog catalog name (e.g., hive\_metastore). Leave empty to use default. | | Schema (Optional) | Optional / as applicable | Schema name within the catalog (e.g., default). Leave empty to use default. | **Provider documentation:** [Setup reference](https://docs.databricks.com/aws/en/dev-tools/auth/pat). #### Databricks (OAuth2) Connect to Databricks workspace using OAuth2 authentication. Supports secure, token-based access to your Databricks data and SQL warehouses. **Set up in Databricks** 1. Use a Databricks account with access to the records and operations that your workflow needs. 2. If your organization restricts application access or user consent, have its administrator approve the connection before you sign in. **Set up in StackAI** 1. Open **Settings → Connections**, add a connection, and select **Databricks (OAuth2)**. 2. Complete the fields marked for use before sign-in. 3. Select **Connect**, sign in to the provider account, and review the requested access. Complete authorization to return to StackAI. 4. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it. **Connection fields** | StackAI field | Required | What to enter | | -------------- | -------- | --------------------------------------------------------------- | | Workspace Host | Yes | Your Databricks workspace URL. Complete this before signing in. | **Provider documentation:** [Setup reference](https://docs.databricks.com/aws/en/dev-tools/auth/). #### Verify the connection Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action. If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change. #### Detailed setup guides * [Connect Databricks](/integrations/catalog/databricks/connect-databricks.md) ## Use an action 1. Add the required **Databricks** action to the workflow. 2. Select a connection when the action requests one. 3. Complete the required fields. Use the reference picker when a value comes from another workflow step. 4. Run the workflow and inspect the action’s output. Check the result before using it in a later step. ### Actions #### Query Databricks Query a Databricks workspace with a SQL query **Inputs** | Field | Type | Required | Description | | ----- | ------ | -------- | ----------------------------------------------------------------- | | Query | string | Yes | SQL query to execute against the Databricks warehouse. Default: . | **Outputs** | Field | Type | Description | | --------- | ----------- | ---------------------------------------------------- | | Query | string | The SQL query that was executed. | | Results | dict\_array | Results of the Databricks query. | | Truncated | boolean | True if the result set was truncated by the row cap. | #### Insert Row into Databricks Insert a single row into a Databricks table from JSON data. **Inputs** | Field | Type | Required | Description | | --------------- | ------ | -------- | --------------------------------------------------------- | | Table | string | Yes | Fully-qualified or unqualified table name to insert into. | | Row Data (JSON) | string | Yes | JSON object of column→value pairs. | **Outputs** | Field | Type | Description | | ------------- | ------- | -------------------------------------------------- | | Success | boolean | Whether the insert succeeded. | | Message | string | Status message from the insert. | | SQL Statement | string | The parameterized SQL statement that was executed. | #### Update Rows in Databricks Update rows in a Databricks table. WHERE clause is required. **Inputs** | Field | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------ | | Table | string | Yes | Fully-qualified or unqualified table name to update. | | SET Data (JSON) | string | Yes | JSON object of column→new-value pairs. | | WHERE Clause | string | Yes | SQL WHERE clause (required) — scopes which rows are updated. | **Outputs** | Field | Type | Description | | ------------- | ------- | -------------------------------------------------- | | Success | boolean | Whether the update succeeded. | | Message | string | Status message from the update. | | SQL Statement | string | The parameterized SQL statement that was executed. | #### Delete Rows from Databricks Delete rows from a Databricks table. WHERE clause is required. **Inputs** | Field | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------------ | | Table | string | Yes | Fully-qualified or unqualified table name to delete from. | | WHERE Clause | string | Yes | SQL WHERE clause (required) — scopes which rows are deleted. | **Outputs** | Field | Type | Description | | ------------- | ------- | ------------------------------------ | | Success | boolean | Whether the delete succeeded. | | Message | string | Status message from the delete. | | SQL Statement | string | The SQL statement that was executed. | #### Merge into Databricks MERGE rows into a Databricks table. Supports simple upsert (default) or full MERGE semantics including conditional updates, deletes on match, and full-sync via 'delete when not matched by source'. **Inputs** | Field | Type | Required | Description | | ------------------------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Target Table | string | Yes | Target table to merge into. | | Source Rows (JSON) | string | No | JSON array of row objects to merge. Provide this OR source\_query, not both. | | Source Query | string | No | SQL SELECT that produces source rows. Use when the source is another table. | | Match On Columns | string | Yes | JSON array of column names used to join target and source. | | When Matched | select (string) | No | Action when a source row matches a target row. Available values: Update all columns, Update specific columns, Delete matched rows, Do nothing. | | When Matched Condition (optional) | string | No | Optional extra predicate for the WHEN MATCHED branch. | | Columns to Update (JSON array) | string | No | Required when When Matched = Update specific columns. | | When Not Matched | select (string) | No | Action when a source row has no matching target row. Available values: Insert all columns, Insert specific columns, Do nothing. | | When Not Matched Condition (optional) | string | No | Optional extra predicate for the WHEN NOT MATCHED branch. | | Columns to Insert (JSON array) | string | No | Required when When Not Matched = Insert specific columns. | | When Not Matched By Source | select (string) | No | Action for target rows that have no matching source row. Enables full-sync semantics when set to Delete. Available values: Do nothing, Delete target rows missing from source. | **Outputs** | Field | Type | Description | | ------------- | ------- | -------------------------------------- | | Success | boolean | Whether the merge succeeded. | | Message | string | Status message from the merge. | | SQL Statement | string | The MERGE statement that was executed. | #### Create Table in Databricks Create a table in Databricks from a JSON schema definition. **Inputs** | Field | Type | Required | Description | | -------------------- | ------- | -------- | -------------------------------------------------------------- | | Table | string | Yes | Fully-qualified or unqualified table name to create. | | Columns (JSON array) | string | Yes | JSON array of column definitions. | | IF NOT EXISTS | boolean | No | Skip creation if the table already exists. | | USING (optional) | string | No | Optional storage format (e.g. DELTA, PARQUET). Default: DELTA. | **Outputs** | Field | Type | Description | | ------------- | ------- | ------------------------------------- | | Success | boolean | Whether the table creation succeeded. | | Message | string | Status message from the create. | | SQL Statement | string | The DDL statement that was executed. | #### Create Schema in Databricks Create a schema (database) in Databricks. **Inputs** | Field | Type | Required | Description | | --------------------------- | ------- | -------- | --------------------------------------------------------- | | Schema Name | string | Yes | Schema to create. Accepts `schema` or `catalog.schema`. | | Comment (optional) | string | No | Optional human-readable description. | | IF NOT EXISTS | boolean | No | Skip creation if the schema already exists. | | Managed Location (optional) | string | No | Optional storage location (Unity Catalog managed tables). | **Outputs** | Field | Type | Description | | ------------- | ------- | -------------------------------------- | | Success | boolean | Whether the schema creation succeeded. | | Message | string | Status message from the create. | | SQL Statement | string | The DDL statement that was executed. | #### Create Catalog in Databricks Create a Unity Catalog catalog in Databricks. **Inputs** | Field | Type | Required | Description | | --------------------------- | ------- | -------- | -------------------------------------------------- | | Catalog Name | string | Yes | Catalog name to create (Unity Catalog). | | Comment (optional) | string | No | Optional human-readable description. | | IF NOT EXISTS | boolean | No | Skip creation if the catalog already exists. | | Managed Location (optional) | string | No | Optional root storage location for managed tables. | **Outputs** | Field | Type | Description | | ------------- | ------- | --------------------------------------- | | Success | boolean | Whether the catalog creation succeeded. | | Message | string | Status message from the create. | | SQL Statement | string | The DDL statement that was executed. | #### Create View in Databricks Create a view in Databricks from a SELECT query. **Inputs** | Field | Type | Required | Description | | ------------------ | ------- | -------- | --------------------------------------------------- | | View | string | Yes | Fully-qualified or unqualified view name to create. | | SELECT Query | string | Yes | The SELECT query that defines the view. | | OR REPLACE | boolean | No | Replace the view if it exists. | | IF NOT EXISTS | boolean | No | Skip creation if the view already exists. | | Comment (optional) | string | No | Optional human-readable description. | **Outputs** | Field | Type | Description | | ------------- | ------- | ------------------------------------ | | Success | boolean | Whether the view creation succeeded. | | Message | string | Status message from the create. | | SQL Statement | string | The DDL statement that was executed. | ### Important behavior If an operation is denied, check the connection’s granted permissions and the account’s access in the provider. Reauthorize the connection when it needs additional permissions. Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data. The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.stackai.com/integrations/catalog/databricks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.