Semantic layer

A semantic layer defines your metrics once, in code, so every answer computes them the same way. Polaris supports the dbt MetricFlow semantic layer. When one is connected, Polaris asks for metrics by name, and MetricFlow writes the SQL.

When to add one

Start without one. Write your metric definitions in RULES.md and run tests. Add a semantic layer when tests show that Polaris computes the same metric in different ways, or when your team already maintains MetricFlow definitions in dbt.

Set it up

1. In your dbt project, run dbt parse. It writes target/semantic_manifest.json.

2. Add a semantic_layer block to pda_config.yaml:

   semantic_layer:
       type: metricflow
       manifest_path: ../dbt/target/semantic_manifest.json
       database: warehouse # optional when the project has one database

3. Install the CLI with the semantic-layer extra (see Install the CLI).

4. Run pda sync -p semantics.

The sync copies the manifest into the project and writes readable docs:

semantics/
├── README.md
├── dimensions.md
└── metrics/
    ├── <metric>.md
    └── ...

No dbt Cloud plan is needed. Polaris compiles the SQL locally with MetricFlow and runs it on the configured database.

How Polaris uses it

The agent reads the metric docs in semantics/, then calls the semantic query tool with:

• metrics: the metric names, for example ["patient_count"].
• group_by: dimensions, for example a time grain or a category.
• where: filters written with MetricFlow templates, such as {{ Dimension('patient__project_id') }} = 'TCGA-KIRC'.
• order_by and a row limit.

The result shows up in the chat like any SQL result, so you can chart and export it.

Choose how strictly to use it

Admins choose a mode in Settings › Agent › Capabilities › Semantic layer:

Mode	What happens
Semantics first (default)	Metric questions go through the semantic layer first. The agent falls back to SQL when the layer cannot answer.
Semantics only	Every database question goes through the semantic layer. SQL only works on Polaris’s local DuckDB, to reshape results and read files.
Don’t use semantics	The definitions stay readable as context, but the agent cannot run semantic queries.

Keep RULES.md lean

When a semantic layer defines your metrics, do not define them again in RULES.md. Add one line that sends the agent to semantics/ instead.