Skip to content

SQL Query ​

Purpose: a multi-tab SQL workbench over the nodes in your project (/projects/<id>/sql-query). Queries run on DDL's warehouse — a PostgreSQL engine, so the errors you see are real PostgreSQL errors — and a saved query becomes a pipeline node, which is how SQL joins the ETL DAG.

The SQL Query pageFresh SQL Query page: Nodes / History panel on the left, a Query 1 tab, the Run and Save buttons, and an empty editor.


Page tour ​

AreaWhat it holds
Side panel tabsNodes (what you can query) and History (what you ran)
Node searchPlaceholder Search Dataset; Ctrl+K focuses it
Node listOne entry per project node; expand it to list its columns
Per-node ⋮ menuView Data — writes and runs a correct query for you
Query tabsQuery 1, Query 2, … — + adds a tab, ✕ closes one
Editor headerRun and Save
Code editorAce editor with a LINE / COLUMN indicator
Result tabsData, Details, Logs (plus Refresh Log inside Logs)

The Nodes panelThe Nodes tab lists the project's queryable nodes — the only "schema tree" the workbench has.


Write and run a query ​

  1. Click into the editor and type your statement.

A typed queryAn aggregate query typed into the editor; the cursor indicator tracks LINE / COLUMN.

  1. Click Run.

ResultsThe result grid opens under the Data tab.

  1. Read the outcome:

Data tabData tab of a smoke-test query: three columns, one row, and a 1 ROW / 3 COLUMN footer.

Details tabDetails tab: Query ID · Total Size · Started At · Status · Duration for the run you just made.

TabUse it for
DataThe rows. Footer states N ROW / N COLUMN
DetailsQuery ID, result size, start time, status, duration — quote the Query ID when you ask for help
LogsThe technical log, including full tracebacks for failed runs; Refresh Log re-reads it

Logs is where failures are explained

A red Status in Details plus a traceback in Logs is usually enough to self-diagnose. The same log is mirrored in Monitoring, where you can also share it as a deep link.


The one rule: table names are back-quoted node names ​

DDL resolves a table only as the node name wrapped in backticks (`), not as a PostgreSQL schema-qualified relation. Four variants of the same query, run in the same project:

What you writeWhat happens
SELECT * from `demo_orders` LIMIT 25✅ Works — 6 rows / 5 columns
SELECT … FROM demo_orders … (bare name)❌ psycopg2.errors.UndefinedTable: relation "demo_orders" does not exist
SELECT * FROM "demo_orders" LIMIT 5 (double quotes)❌ same error
SELECT * FROM ddl.demo_orders LIMIT 5 (schema-qualified)❌ relation "ddl.demo_orders" does not exist

Working example — the statement DDL itself generates:

sql
SELECT * from `demo_orders` LIMIT 25

Aggregate version, same rule:

sql
SELECT customer, SUM(amount) AS total
FROM `demo_orders`
GROUP BY customer
ORDER BY total DESC

Failure mode 1: double-quoted nameDouble quotes are not enough — the run fails with relation "demo_orders" does not exist even though the node exists.

Failure mode 2: schema-qualified namePrefixing a schema (ddl.demo_orders) fails the same way: relation "ddl.demo_orders" does not exist.

Backticks, not double quotes, not schema.table

This is the single most common cause of "the table doesn't exist" in DDL. The node does exist — you are addressing it in a way the resolver does not accept. Use backticks, or better, let DDL write the name for you with View Data.

The reliable way to get the identifier right

Expand the node in the Nodes panel → ⋮ → View Data. DDL inserts the correct backticked statement in a new tab and runs it. Copy from there when you write your own queries.


Browse data without writing SQL ​

  1. In the Nodes panel, expand a node to see its columns.

Node expanded with columnsExpanding demo_orders lists its five columns — the quickest type check before you write a query.

  1. Click the node's ⋮ and choose View Data.

Per-node menuThe node menu with View Data .

  1. A new tab opens, pre-filled and already run.

Generated query in a new tabQuery 2 contains SELECT * from `demo_orders` LIMIT 25 — note the backticks.

Generated query result6 ROW / 5 COLUMN: order_id, customer, region, amount, order_date.


Reuse a run from History ​

The History tab lists your previous executions as cards, each headed by the query UUID and its timestamp.

History tabEvery run, newest first. The UUID matches the Query ID shown in the Details tab and in Monitoring.

TIP

Copy a UUID from History into a bug report or a chat message: support and your own teammates can find the exact run in Monitoring with it.


Save a query as a node ​

Save turns the current statement into a pipeline node, making it part of the DAG — upstream nodes, lineage, schedules and all.

Save as node modal"Save this query as a node" with a single Node Name field and Cancel / Save .

  1. Make sure the query runs cleanly first (it will be re-executed by the pipeline).
  2. Click Save, give the node a name that follows your naming convention, confirm with Save.
  3. The node appears on the canvas; use Sync to refresh it. See Pipelines (ETL).

The node name you choose here becomes a table name

Downstream queries must reference it in backticks. Rename later and every query that used the old name breaks.


What the SQL workbench does not do ​

Knowing these limits saves you from hunting for a button that isn't there:

  • No result export. There is no Download CSV / Export results control on the Data tab. To get data out, save the query as a node and use Transfer or Dump Data.
  • No charts from the result grid. Charts and Dashboards are separate project tabs — see Charts & Dashboards.
  • No autocomplete or schema tree beyond the Nodes panel, and no SQL formatting button.
  • No result pagination for a LIMIT 25 result — you get the rows the query returned.
  • The LINE indicator is cosmetic. It can read LINE: 0 on a single-line query.
  • No "Ask AI" control in the editor. Selecting text or right-clicking offers nothing AI-related unless your deployment has the assistant configured — see AI & MCP integration.

Troubleshooting ​

Error / symptomCauseFix
relation "…" does not existTable name not written as a back-quoted node nameUse `node_name` or View Data
relation "schema.node" does not existSchema-qualified names are not supportedDrop the prefix
Query runs but returns 0 rowsNode not synced yet, or filter too tightSync now the node, then re-run
Column not foundType or name differs from what you assumedExpand the node in Nodes to read real column names
Long traceback in LogsReal PostgreSQL error from the warehouseRead the last line — it names the failing expression

Next: Schedules · Related: Pipelines (ETL), Monitoring, AI & MCP integration

Delman Data Lab — user guide for the DDL web application at ddl.delman.io.