SQL node
The SQL node runs a DuckDB query against the upstream rows in-memory. Upstream rows are exposed as a virtual table named rows. The result set becomes the downstream stream.
When to use
- The transformation is naturally a SQL query (
SELECT customer_id, COUNT(*) FROM rows GROUP BY customer_id HAVING COUNT(*) > 3). - You want to join rows against a DuckDB-native format (Parquet, CSV) without opening a DB connection.
- The query is complex enough that a chain of Transform + Filter + Compute would be harder to read than one SQL statement.
Ports
| Port | Direction | Kind | Notes |
|---|---|---|---|
in | in | data | Rows exposed as the rows table. |
out | out | data | The query result set. |
error | out | control | Fires on SQL parse or execution errors. |
notify | out | control | Notification policy port. |
Configuration
- Query. The DuckDB SQL.
rowsis the virtual table; you can also referenceread_parquet(...),read_csv_auto(...), and other DuckDB scan functions if the runtime has access. - Output shape. Inferred from the query. When the downstream node has a declared schema, the SQL node's output is validated against it and the run stops on a mismatch.
Configure Action walkthrough
- Editor is Monaco with DuckDB IntelliSense — table names, column names, and function catalog are all completion sources.
- Live preview: the modal fetches a small sample and executes the query in-process so the user sees the shape before Save.
Runtime behaviour
- The upstream rows are materialized into a DuckDB table for the query. For large rowsets this incurs a memory cost — the chunker doesn't stream through the SQL node.
- Query timeout is set on the runtime config (
DLR_DUCKDB_QUERY_TIMEOUT_MS).
Failure modes
- Parse error. Caught at Save time via the modal's IntelliSense diagnostics.
- Runtime error. The DuckDB error surface (missing column, division by zero) lands on the
errorport. - OOM. For very large upstreams the SQL node can materialize more than the runtime allows. Pre-Filter to keep the input smaller, or use Compute for the group-by shape instead.