Skip to main content

SQL nodes

A SQL node defines its data source as a SQL query rather than a raw table. Use it for derived tables, CTEs, and complex joins you want to encapsulate.

Example​

node: daily_revenue
label: Daily Revenue
sql: |
  SELECT
    DATE_TRUNC('day', payment_date) AS day,
    SUM(amount) AS revenue,
    COUNT(*) AS payment_count
  FROM public.payment
  GROUP BY 1

attributes:
  - name: day
    type: date
    is_date: true

metrics:
  - name: revenue
    label: Daily Revenue
    sql: SUM(revenue)
    type: currency

  - name: payment_count
    label: Payments
    sql: SUM(payment_count)
    type: integer

When to use SQL nodes​

  • You need a pre-aggregated table for performance
  • You want to encapsulate complex business logic
  • Your source data comes from a view or CTE, not a raw table
  • You need to combine columns from multiple tables before exposing them as attributes

Limitations​

  • SQL nodes cannot be used as join targets from other nodes (use table nodes for that)
  • The SQL is executed as a subquery, so avoid ORDER BY at the top level