How to Query Facts Directly¶

This guide shows how to query facts as row-level columns using the facts parameter in semantic_view(). Unlike metrics, fact queries return individual rows without aggregation.

Prerequisites:

A semantic view with a FACTS clause (see How to Use FACTS for Reusable Row-Level Logic)
Familiarity with semantic_view() queries

Query Facts¶

Pass fact names in the facts parameter to retrieve them as row-level columns:

SELECT * FROM semantic_view('analytics',
    facts := ['net_price', 'tax_amount']
);

Each row in the result contains the computed fact values – no aggregation is applied. This is equivalent to a SELECT with the fact expressions inlined.

Combine Facts with Dimensions¶

Add dimensions alongside facts. The dimensions appear as columns but do not trigger GROUP BY – the output remains row-level:

SELECT * FROM semantic_view('analytics',
    dimensions := ['region'],
    facts := ['net_price']
);

This returns one row per source row, with region and net_price columns.

Mutual Exclusion with Metrics¶

Warning

Facts and metrics cannot be combined in the same query.

-- This fails:
SELECT * FROM semantic_view('analytics',
    facts := ['net_price'],
    metrics := ['total_revenue']
);

semantic view 'analytics': cannot combine facts and metrics in the same query.
Use facts := [...] OR metrics := [...], not both.

To get both row-level facts and aggregated metrics, run two separate queries.

Wildcard Selection for Facts¶

Use alias.* to select all public facts for a table alias:

SELECT * FROM semantic_view('analytics',
    facts := ['li.*']
);

Private facts are excluded from wildcard expansion. See How to Use Wildcard Selection for details.

Verify with explain_semantic_view()¶

Use explain_semantic_view() to see the expanded SQL and query plan for a fact query:

SELECT * FROM explain_semantic_view('analytics',
    facts := ['net_price', 'tax_amount']
);

You can also use DESCRIBE SEMANTIC VIEW to inspect FACT entries and their expressions.

Troubleshooting¶

Unknown fact name: The fact name must match a fact declared in the FACTS clause. The error message lists available facts and suggests close matches.
Private fact cannot be queried: Facts marked PRIVATE cannot be queried directly. They can only be referenced in metric expressions. Remove the PRIVATE keyword to make a fact queryable.
Incompatible table paths: If a fact query combines facts and dimensions from tables that are not on the same root-to-leaf path in the relationship tree, the extension returns an error: fact query references objects from incompatible table paths.