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:

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

A fact query returns rows as they are, so the tables it references must be joinable without multiplying them. If neither of two tables can be reached from the other without traversing a one-to-many relationship against its direction — typically two tables that both reference a third — the extension returns fact query references objects from incompatible table paths. A chain of many-to-one relationships is fine however long it is.