Databricks

Connect a Databricks SQL warehouse and ask questions about your lakehouse tables in plain English.

Before you start

You’ll need:

• A Databricks SQL warehouse and its connection details.
• A personal access token.
• Admin rights in your Terno workspace, to see the option to add a datasource.

Connect Databricks

1. Click Add Data Connectors, open the Datasources tab, and choose Databricks.
2. Choose Standard Setup or Connection URI at the top of the form.
3. Leave Start exploring my database ticked (it’s on by default). Right after connecting, Terno opens a background chat that explores the database and learns its tables, joins, and metrics. You’ll find it in your chat history and can open it any time.
4. Enter a Display Name and an optional Description, then fill in the fields below.
5. Click Add Connection. Terno tests the connection before saving it. If the test fails, you’ll see what went wrong, and nothing is saved.

Connection fields

Display Name required

A name for this connection, such as Production DB or Sales warehouse. It can be up to 40 characters and must be unique.

Description optional

A short note on what the data is about, such as Orders, customers, and payments for our online store. Up to 1024 characters. Terno uses it to understand when to use this source.

Standard Setup

SERVER_HOSTNAME required

Your workspace host, without https://, such as dbc-1234abcd-5678.cloud.databricks.com.

HTTP_PATH required

In Databricks, open SQL Warehouses, choose your warehouse, and copy the HTTP path from Connection details, such as /sql/1.0/warehouses/abc123.

ACCESS_TOKEN required

A personal access token. Create one under User Settings → Developer → Access tokens.

CATALOG optional

The Unity Catalog catalog to use, such as main.

SCHEMA optional

The schema to use, such as sales.

Connection URI

databricks://token:<personal_access_token>@<server_hostname>?http_path=<http_path>&catalog=<catalog>&schema=<schema>

Create a read-only user

Create the token for a user or service principal that only has read access, for example:

GRANT USE CATALOG ON CATALOG main TO `terno@yourcompany.com`;
GRANT USE SCHEMA ON SCHEMA main.sales TO `terno@yourcompany.com`;
GRANT SELECT ON SCHEMA main.sales TO `terno@yourcompany.com`;

The user also needs Can use permission on the SQL warehouse.

After you connect

Terno reads your tables, columns, primary keys, foreign keys, and row counts. You’ll get a DataSource Ready notification when it’s done, and the new source appears in the sidebar’s Data Connectors panel. Expand it to see its tables.

Ask questions

Start a chat and ask in plain English, for example:

• “Which 10 customers spent the most this year?”
• “What’s the average order value by month?”
• “Show a chart of new sign-ups per week this quarter.”

Terno writes the SQL for Databricks, runs it, and replies with tables, charts, and an explanation. You don’t need to know SQL.

Security

• Credentials are encrypted at rest and used only to connect to your database.
• The AI never sees your password or connection string.
• SQLShield allows only a single read-only SELECT per query. Inserts, updates, deletes, and schema changes are blocked.
• Admins can hide tables, columns, and rows from groups of users. See Access control.

Troubleshooting

Connection timed out, or Terno can’t reach the server

• Check the host and port.
• Make sure the database accepts connections from outside your network, and that no firewall or security group blocks it.
• Use a real hostname or IP address. localhost and 127.0.0.1 point to Terno’s own servers, not yours.
• Check the database is running.

Authentication failed

• Check the username and password. Watch for extra spaces when pasting.
• Make sure the user is allowed to log in to this database.
• If you used a Connection URI, special characters in the password (like @, /, :) must be URL-encoded.

The database does not exist

Check the spelling of the database name. It’s the database inside the server, not the server name.

Terno can’t find my tables

• Make sure the user has SELECT permission on the tables.
• Check you connected to the right database, catalog, and schema, and that the SQL warehouse is running.
• An admin may have hidden some tables. See Access control.

See Connection errors for the full list of messages.

Best practices

• Use a read-only user created just for Terno, with access to only the data you want to analyse.
• Try a staging or replica database first before connecting production.
• Add a description and table descriptions so Terno picks the right tables. See Add context.
• Watch database load when asking for large, unfiltered results on production systems.
• Work with your database administrator on network access and permissions.