Databricks guide

Turn questions into Databricks SQL.

Databricks SQL connects analytical questions to lakehouse tables. A precise catalog, schema and SQL warehouse matter as much as the natural-language prompt.

TTSQL team Updated September 5, 2026

Try TTSQL free

Before connecting Databricks

Provide the Databricks workspace host, token and either the SQL warehouse ID or its HTTP path. TTSQL uses the Databricks SQL Statement Execution HTTP API; it does not connect directly to a notebook or an arbitrary cluster endpoint.

Set the catalog and schema where needed. Confirm that the token identity can use the SQL warehouse and access the selected Unity Catalog objects. The adapter supports schema discovery and query results; its table editor is read-only, so do not assume row editing is available through that interface.

Give the prompt the right dialect and context

Use catalog.schema.table to disambiguate Unity Catalog objects. Backticks quote identifiers that need escaping. The examples use main.analytics.orders; replace all three name parts with your actual objects.

These examples target Databricks SQL. QUALIFY is also available in Databricks Runtime 10.4 LTS and later, but it is not interchangeable with every Apache Spark SQL environment. Confirm the engine rather than assuming a notebook and SQL warehouse have identical syntax support.

Schema used in these examples

customers(id INTEGER PRIMARY KEY, name TEXT, country TEXT); orders(id INTEGER PRIMARY KEY, customer_id INTEGER REFERENCES customers(id), ordered_at TIMESTAMP, status TEXT, total DECIMAL(12,2)). Each order has one customer. total is the order amount in a single reporting currency; paid means recognized revenue in this teaching dataset. Timestamps use UTC. These are example tables, not tables TTSQL creates.

Translate TEXT and TIMESTAMP to equivalent column types for your engine. Use your own database, schema and table qualifiers. Each example states its reporting grain and sorting rule.

Review these Databricks details

An all-history window can shuffle and sort many rows even when it produces one row per customer. Use a date restriction when the question permits it and inspect the SQL warehouse query profile for expensive scans or joins.

Catalog permissions, warehouse access and table freshness are separate from SQL syntax. A valid query against yesterday's materialized data can answer a different question from a query against a current event table.

Generate, review, then choose whether to run

Select the matching database type and confirm your project's schema context before generating. Review the returned SQL against the schema and the metric you intended. A successful connection test does not prove that every table or operation is authorized.

TTSQL's POST /api/v1 endpoint generates SQL and returns executed: false. Query execution is a separate manual Run action in the workspace, subject to the configured connection and policies. The examples below are educational SELECT statements, not live results from your database.

Official Databricks references

Check your engine version and account configuration when adapting a function or connection setting.

Worked SQL examples

Read the sample schema and assumptions alongside each query. Adapt names, dates, and definitions to your own database before running SQL.

01 / Databricks SQL

Turn month buckets into dates

Show paid revenue by calendar month in the configured UTC session, oldest first.

SELECT CAST(date_trunc('MONTH', ordered_at) AS DATE) AS month,
       SUM(total) AS revenue
FROM main.analytics.orders
WHERE status = 'paid'
GROUP BY CAST(date_trunc('MONTH', ordered_at) AS DATE)
ORDER BY month;

date_trunc returns a timestamp; CAST presents the month-start date. The example assumes the session time zone is UTC for TIMESTAMP data. TIMESTAMP_NTZ represents a local date and time instead, so document your real column type and reporting zone.

02 / Databricks SQL

Select the latest event per customer

Show each customer's latest paid order, choosing the highest ID when timestamps tie. Sort by customer ID.

SELECT customer_id, id, total
FROM main.analytics.orders
WHERE status = 'paid'
QUALIFY row_number() OVER (
  PARTITION BY customer_id ORDER BY ordered_at DESC, id DESC
) = 1
ORDER BY customer_id;

QUALIFY applies after row_number is evaluated. Partitioning by customer defines the output grain; the second ordering column makes tied timestamps deterministic. If you need every tied latest event, that is a different requirement from one latest row.

03 / Databricks SQL

Count matching statuses with count_if

For each customer with an order, show paid and cancelled counts. Sort by customer ID.

SELECT customer_id,
       count_if(status = 'paid') AS paid_orders,
       count_if(status = 'cancelled') AS cancelled_orders
FROM main.analytics.orders
GROUP BY customer_id
ORDER BY customer_id;

count_if counts rows whose Boolean expression is true. Other and NULL statuses contribute to neither count. The spelling differs from BigQuery's COUNTIF, which is a useful reason to select the exact database dialect in the project.

Answers before you connect a database.

Does selecting Databricks guarantee a working database connection?

No. SQL generation uses the project dialect and schema, while connection and execution also depend on deployment prerequisites, credentials, network access and database permissions. Complete the prerequisites described in this guide.

Does the TTSQL API execute Databricks queries?

No. POST /api/v1 generates SQL and returns executed: false. Review the query; a separate manual Run action is available in the workspace when the connection and policies allow it.

Bring your next question to TTSQL.

Start with one PostgreSQL project and 20 free requests a day. Explore your data, build a report, or integrate the API.

Start free Contact sales