explain_semantic_view()

Table function that shows the SQL generated by a semantic view query without executing the data query. Returns the expanded SQL and the DuckDB query plan as rows of text.

Syntax

SELECT * FROM explain_semantic_view(
    '<view_name>',
    [ dimensions := [ '<dim_name>' [, ...] ] , ]
    [ metrics := [ '<metric_name>' [, ...] ] ]
)

Parameters

Parameters are identical to semantic_view().

Parameter

Type

Description

<view_name>

VARCHAR (positional)

The name of the semantic view to explain.

dimensions

LIST (named)

Optional list of dimension names.

metrics

LIST (named)

Optional list of metric names.

At least one of dimensions or metrics must be specified.

Output

Returns multiple rows, each containing a single VARCHAR column:

Column

Type

Description

explain_output

VARCHAR

One line of the explain output.

The output has three sections:

  1. Header: the view name and requested dimensions/metrics.

  2. Expanded SQL: the SQL query the extension generates, formatted with indentation.

  3. DuckDB Plan: the physical query plan from EXPLAIN.

Examples

SELECT * FROM explain_semantic_view('analytics',
    dimensions := ['customer_name'],
    metrics := ['revenue']
);

Sample output:

-- Semantic View: analytics
-- Dimensions: customer_name
-- Metrics: revenue

-- Expanded SQL:
SELECT
    c.name AS "customer_name",
    sum(o.amount) AS "revenue"
FROM "orders" AS "o"
LEFT JOIN "customers" AS "c" ON "o"."customer_id" = "c"."id"
GROUP BY
    1

-- DuckDB Plan:
┌─────────────────────────────┐
│     HASH_GROUP_BY           │
│   ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─     │
│           ...               │
└─────────────────────────────┘

Tip

Use explain_semantic_view() to verify that the extension generates the SQL you expect, especially when debugging join paths, fact inlining, or role-playing dimension scoped aliases.