Atlas Metrics
Define, browse, and validate your semantic metrics in one place. Atlas Metrics gives your team a shared catalog of business metrics built on top of your dbt models, with live SQL preview, branch-level diffing, and import tools for existing metric definitions.
Overview
Atlas Metrics lives in the left navigation under Metrics. It reads semantic model definitions committed in your repository and presents them as a browsable catalog. Every metric, dimension, and dataset is visible at a glance with search and filtering.
The catalog shows a stats bar at the top with totals for semantic models, metrics, and dimensions across your project. Type-colored icons in the sidebar (purple for models, blue for dimensions, orange for metrics) make it easy to scan.
When no metric definitions exist yet, the page shows an animated empty state with a glowing emblem and floating chip hints to guide you toward defining your first semantic model.
Catalog Browser
The catalog sidebar lists all semantic models in your project. Expand any model to see its metrics, dimensions, and datasets:
- Semantic models: Top-level groupings that map to your dbt models
- Metrics: Named calculations (revenue, order count, customer LTV) with their expressions
- Dimensions: Grouping and filtering attributes (date, region, status, category)
- Datasets: The underlying tables and relationships
Click any item to open the detail pane on the right.
Detail Pane
The detail pane shows full information about the selected item:
Metric Detail
- Expression: The calculation formula with syntax highlighting
- Source file: Which YAML file defines this metric
- Dimensions: Available grouping dimensions displayed as interactive pills
- Live SQL preview: Compile the metric to real SQL (see below)
Model Detail
- Stats band showing dataset, metric, and relationship counts
- Quick navigation to any child metric or dimension
- Visual summary with type-colored badges
Dimension Detail
- Which dataset and model it belongs to
- Whether it is a time dimension
- Where it is referenced
Live SQL Preview
Select a metric, pick your dimensions, and see the compiled SQL instantly. The preview adapts to your warehouse dialect:
| Dialect | Syntax adaptation |
|---|---|
| Snowflake | DATE_TRUNC('month', col) syntax, schema quoting |
| BigQuery | date_trunc(col, MONTH) syntax, backtick quoting |
| Redshift | Redshift-compatible SQL generation |
| Databricks | Spark SQL dialect support |
| PostgreSQL | Standard PostgreSQL syntax |
| Athena | Presto/Trino SQL dialect |
| StarRocks | MySQL-compatible syntax |
The SQL is compiled on demand. Change your dimension selection or dialect and the preview updates immediately.
Metric Diff (Compare)
Compare metrics between branches to catch breaking changes before they merge:
- Click Compare in the toolbar
- Select the base branch and head branch
- View the diff showing all metric changes
Each change is categorized:
| Severity | Meaning | Examples |
|---|---|---|
| Breaking | Changes that alter query results or remove definitions | Metric removed, expression changed, dimension dropped, dataset source repointed, join keys changed |
| Safe | Additive changes that do not affect existing queries | New metric added, new dimension, new dataset or relationship |
| Info | Cosmetic changes with no query impact | Description updated, label changed, formatting adjustments |
The diff shows before/after values for each change so reviewers can assess impact at a glance. When a PR contains any breaking change, the verdict is Blocked, requiring explicit review before merge.
Metric Gate in Slimmer CI
When Slimmer CI is enabled, the metric diff runs automatically on every pull request. Breaking metric changes block the PR just like a failing build. Results appear in the PR Overview tab and digest comment. See Slimmer CI for details.
Importing Metrics
Atlas Metrics supports importing metric definitions from multiple sources so you can migrate your existing metric layer:
dbt Semantic Models
If your dbt project already uses semantic_models in YAML, import them directly:
- Click Import in the toolbar
- Select the dbt tab
- Choose which semantic models to import
- The definitions are converted and added to your catalog
LookML
Import metric definitions from Looker's LookML files:
- Click Import and select the LookML tab
- Paste or upload your LookML file content
- Measures and dimensions are mapped to the catalog format
Cube
Import from Cube.js schema definitions:
- Click Import and select the Cube tab
- Paste or upload your Cube schema
- Measures and dimensions are converted to the catalog format
Validation
Atlas Metrics validates your semantic model definitions and surfaces issues directly in the catalog:
- Errors: Invalid expressions, missing references, duplicate names
- Warnings: Unused dimensions, potential performance issues
- Info: Style suggestions, documentation gaps (e.g., adding
ai_contextfor better Atlas grounding)
Issues appear inline in the catalog sidebar with severity badges so you can fix problems before they reach production.
Atlas AI Grounding
When Atlas Metrics is enabled, the Atlas AI Co-pilot automatically reads your governed metric definitions. This means:
- Atlas answers are grounded in your actual metric names and expressions
- Questions like "how is revenue calculated?" return your team's governed definition, not a guess
- Suggested SQL uses your metric layer rather than raw table references
- Up to 40 relevant metrics are included in each AI context window
This bridges the gap between your metric catalog and day-to-day development.
How It Fits Together
Atlas Metrics works alongside the other dbdeux features:
- Data Products: Bundle metrics into governed data products with SLAs, ownership, and maturity tracking
- Share Links: Share your metric catalog externally with tokenized links that require no login
- Slimmer CI: Metric diffs run automatically on PRs to catch breaking metric changes before merge
- Atlas AI: Atlas grounds answers in your governed metric definitions for consistent, accurate responses
- Atlas Catalog: Browse documentation for the models behind your metrics in the Atlas Catalog
- Database Explorer: Browse the underlying warehouse tables that your metrics reference
- Scheduling: Scheduled builds ensure your metric catalog stays in sync with the latest code
How It Compares
| Capability | Atlas Metrics | dbt Semantic Layer | Looker / LookML | Spreadsheet metrics |
|---|---|---|---|---|
| Definition format | Git-native YAML in your dbt project | dbt Semantic Layer YAML | LookML files | Scattered formulas |
| Live SQL preview | Instant compiled SQL with dialect switching (7 warehouses) | Requires API call | View SQL in Explore | Not available |
| Branch diffs | Side-by-side metric diff with breaking/safe/info severity | Not available | Git diff only | Not available |
| Import | One-click import from dbt, LookML, and Cube | Native only | Native only | Manual migration |
| Validation | Inline errors, warnings, and info with file locations | CLI validation | IDE validation | None |
| AI grounding | Metrics are automatically used by Atlas AI for accurate answers | Not available | Not available | Not available |
| External sharing | Tokenized share links with no login required | API access only | Requires Looker license | File sharing |