Databricks Integration Guide

Cloud support and scope

The hostname validator also recognizes Azure and Google Cloud workspace domains. That does not establish end-to-end support on those clouds. Private networking and deployment-specific connectivity require separate verification.

The built-in connector offers seven read-only tools. It does not offer arbitrary SQL, data writes, notebook execution, or job execution. Genie is a separate, optional path that generates and runs read-only SQL within the selected space's data scope.

Before you start

• An ACTAVA organization administrator who can configure connectors and acknowledge agents.
• A Databricks administrator who can create or assign a service principal, manage its workspace entitlements, and grant resource access.
• A Unity Catalog catalog, schema, and approved tables or views.
• A SQL warehouse that the service principal can use. Confirm warehouse availability and billing before testing.
• For Genie, a curated Genie space, access to its underlying data, and the workspace's Managed MCP Servers preview enabled by a workspace administrator.

Use synthetic or otherwise approved non-sensitive data for the first test. Avoid putting personal data, credentials, or sensitive business information in Unity Catalog comments, tags, or Genie instructions.

1. Create the service principal

In Databricks, create a dedicated service principal for the ACTAVA connection and assign it to the intended workspace. Enable the workspace and Databricks SQL access entitlements needed by your workspace configuration.

Create a Databricks OAuth secret for that principal. Record its application/client ID, secret, and expiration in your approved credential manager. The OAuth secret is different from a personal access token. For Azure workspaces, do not substitute a Microsoft Entra secret for a Databricks OAuth secret.

Choose an expiration and rotation process under your organization's credential policy. See Databricks OAuth M2M authentication for the current administration steps.

ACTAVA exchanges the client ID and secret at the workspace's /oidc/v1/token endpoint using the client_credentials grant and all-apis scope. This OAuth scope does not grant data privileges by itself. Databricks resource permissions still determine what the principal can access.

2. Grant only the required access

Grant the service principal CAN USE on the selected SQL warehouse. In Unity Catalog, grant USE CATALOG, USE SCHEMA, and SELECT only on the data needed by the agent.

For example, a Databricks data owner can adapt these statements for an existing approved table. Replace every placeholder before running them in Databricks SQL. The principal value is the service principal's application ID.

GRANT USE CATALOG ON CATALOG `<catalog>` TO `<service-principal-application-id>`;
GRANT USE SCHEMA ON SCHEMA `<catalog>`.`<schema>` TO `<service-principal-application-id>`;
GRANT SELECT ON TABLE `<catalog>`.`<schema>`.`<table>` TO `<service-principal-application-id>`;

For an approved view, grant SELECT on that view instead. Review existing group memberships and inherited privileges too. A dedicated principal can still inherit broader access; the connector's read-only tool set does not remove those upstream privileges.

Every agent run uses this shared principal, regardless of who starts the run. Databricks policies evaluate that principal rather than each ACTAVA end user. Do not use this connection where access must depend on the invoking user's individual row-level permissions. Restrict both the principal's grants and the audience allowed to run the agent.

3. Save and verify the ACTAVA connection

As an ACTAVA organization administrator, open Administration → Connectors → Databricks. In the Setup view, enter the connection fields.

Select Save Credentials, then Verify Connection. Verification checks authentication, a small Unity Catalog request, and SELECT 1 on the configured warehouse. It does not prove access to every target table or to Genie.

After verification succeeds, enable the Databricks connector. Complete the table and Genie checks below before making an agent available to other users. A blank secret field on an existing connection keeps the saved secret; enter a new value to rotate it.

4. Authorize an agent and test table access

Create or choose a draft agent without Databricks tools first. In the Databricks connector's Permissions view, have an organization administrator acknowledge that everyone permitted to run that agent may receive data accessible through the shared service principal. Then edit the agent and add only the required Databricks tools.

Preview and distinct-value tools default to 25 rows and accept limits from 1 to 100. The built-in SQL templates impose a 100-row and 1,000,000-byte response limit, with a 30-second statement wait and cancellation on timeout. These limits bound returned results; a row count or distinct-value query can still scan a large table and consume warehouse compute. They do not define Genie's result limits.

The built-in SQL tools accept catalog, schema, table, and column names made of letters, digits, and underscores, up to 255 characters per part. Objects with other characters in their names may be discoverable but cannot be queried through these templates. Use approved compatible views if needed.

In the agent's test view, ask it to inspect an approved table, count its rows, preview a few rows, and list values from a non-sensitive column. Include the fully qualified table name and explicitly request the Databricks tools. Compare the result with a direct Databricks query under the same service principal. Check the recorded tool calls as well as the final prose.

5. Enable Genie analytics

Databricks documentation may call a Genie space a Genie Agent. ACTAVA's configuration still asks for a Genie space ID and connects to the space-scoped MCP endpoint.

1. Create or select a curated Genie space in the same workspace. Include only the approved tables or views and review its instructions and sample queries.
2. Grant the ACTAVA service principal CAN RUN on that space and the underlying data permissions required by Genie, including warehouse access. A space grant alone does not grant table access.
3. Have a Databricks workspace administrator enable Managed MCP Servers on the workspace's Previews page. This is a workspace-wide public preview setting.
4. Copy the space ID from the Genie settings. In ACTAVA's Databricks Setup view, enter it, select Save Credentials, then enable Genie for agents.
5. Open the MCP Store, find Databricks Genie, and refresh its tools. In the already acknowledged draft agent, select the discovered query and polling tools. Their names include the space ID. Merely selecting a server does not select its tools.
6. Ask a question over the space's approved data. If the query is still running, let the agent use the polling tool to finish. Verify its answer against Databricks and open the Powered by Genie reference to confirm that it points to the intended space.

ACTAVA configures the MCP connection at https://<workspace-host>/api/2.0/mcp/genie/<genie-space-id>. The current connector uses the same M2M principal. The Databricks Genie MCP service is read-only and does not carry conversation history between tool calls. See the Databricks Genie MCP documentation for current preview prerequisites and limitations.

After changing the workspace or space ID, refresh the MCP tool catalog and replace the agent's old space-specific tool selections. Review existing agent acknowledgements against the new data scope before running those agents again.

6. Confirm the connection end to end

Use a small synthetic table with a known row count and one simple aggregate. Keep the expected answer outside the agent's prompt so the test measures actual retrieval.

Run these checks after credential rotation, changes to grants, a warehouse or workspace change, or changes to the Genie space. A successful connection check alone is not an end-to-end test.

Data handling and access review

ACTAVA sends tool requests and Genie questions to Databricks. Metadata, query results, and Genie answers return to ACTAVA for the agent to use in its response and can appear in conversations and run records. Review the deployment's retention, model-provider routing, and access settings before allowing sensitive data.

The connector is an on-demand query path, not a Databricks data replication or indexing setup. Do not treat that distinction as a zero-retention guarantee. Review Unity Catalog comments, tags, and Genie content as data that may be returned with a request. Confirm any required restrictions on their storage or indexing with ACTAVA before production use.

Use the organization's approved data and security policies to decide which tables, views, columns, and agent audiences are appropriate. Scope access in Databricks rather than relying on the default catalog or instructions in an agent prompt.

Rotate credentials or disconnect

Create a replacement Databricks OAuth secret before the current secret expires. Save it in ACTAVA, verify the connection, and repeat the SQL and Genie tests. Revoke the old secret in Databricks after confirming the replacement works. If your deployment uses multiple workers, confirm the rotation has propagated before considering the change complete.

Turn off Genie for agents to disable the Genie path while keeping built-in Databricks tools available. Turn off the Databricks connector or revoke an agent's acknowledgement to stop its authorized connector access. Do not assume a toggle cancels work already submitted to Databricks.

Use Disconnect to remove the saved ACTAVA connection configuration. Disconnection does not revoke the OAuth secret, delete the service principal, or remove its Databricks grants. A Databricks administrator must revoke credentials and grants separately when retiring the integration.

Troubleshooting

For help, contact ACTAVA support. Share the failing step, approximate time, and a redacted error category. Do not send secrets, access tokens, or sensitive query results.