---
name: lightdash-semantics
description: Add and manage Lightdash semantic layer meta configurations in dbt YAML schema files — dimensions, metrics, labels, groups, joins, formats, and time intervals. Use when adding Lightdash meta to dbt models, configuring the Lightdash semantic layer, setting up metrics or dimensions in schema.yml, or preparing dbt models for Lightdash exploration.
---

# Lightdash Semantic Layer Configuration

Add Lightdash-specific `config.meta` blocks to dbt schema.yml files so models, dimensions, and metrics are properly configured for exploration in Lightdash.

This skill adds **Gemma-specific conventions** on top of the native `developing-in-lightdash` skill, which provides the full Lightdash property reference (all dimension types, metric types, table properties, joins, etc.).

## When to Use

- User asks to "add Lightdash configuration" or "prepare models for Lightdash"
- User wants to define metrics, dimensions, labels, or groups for Lightdash
- User is working in a dbt project and mentions Lightdash semantic layer
- User wants to add joins, formats, or grouping to dbt models for BI consumption

## Important: YAML Syntax Format

Gemma dbt projects use `config.meta` (dbt v1.10+). The native Lightdash skill examples use bare `meta:`. **Do not mix them.**

```yaml
# ✅ Gemma convention             # ❌ Do NOT use in Gemma projects
models:                           models:
  - name: fct_orders                - name: fct_orders
    config:                           meta:
      meta:                             label: "Orders"
        label: "Orders"
```

Always use `config.meta` at both model and column level in Gemma projects.

## Prerequisites

- A dbt project with models and schema.yml files
- Understanding of which models are exposed to end users (typically the `marts/` layer)
- Column data types (from SQL files, warehouse, or `dbt docs generate`)

## Workflow

### Step 1: Identify Target Models

Focus on the **marts** (or reporting/consumption) layer. Base and interim models should remain hidden from Lightdash users.

- Read `dbt_project.yml` to understand the project structure and model directories
- List models in the marts/reporting layer
- Read corresponding schema.yml files and .sql model files

### Step 2: Analyse Existing Schema

For each target model:
- Read the schema.yml to check for existing `config.meta` blocks, descriptions, and tests
- Read the .sql file to understand column data types and relationships
- Identify foreign keys (columns ending in `_key`, `_id`, `_sk`) pointing to dimension tables
- Identify measure columns (revenue, amount, quantity, count, price)
- Identify categorical columns (type, status, category, name)
- Identify date/time columns
- Identify boolean flags (columns starting with `is_`, `has_`, `was_`)

### Step 3: Add Model-Level Meta

For each model, add under `config.meta`:

```yaml
config:
  meta:
    label: "Human-Readable Name"
    group_label: "Sidebar Group"       # e.g., "Finance", "Operations", "Organisation"
    order_fields_by: "index"
```

For fact tables, also add:
- **`joins`** to related dimension tables (use `many-to-one` for fact→dim)
- **Model-level `metrics`** for calculated metrics that reference column-level metrics (e.g., revenue per unit)

### Step 4: Add Column-Level Meta

Apply the Gemma column conventions from `${CLAUDE_SKILL_DIR}/references/gemma-conventions.md`:
- Surrogate/foreign keys → `hidden: true`
- Numeric amounts → hidden dimension + `sum`/`average` metrics with EUR format
- Quantities → `sum` metric with integer format
- Categoricals → string dimension in appropriate group
- Boolean flags → "Flags" group, optional filtered count metrics
- Dates/timestamps → "Date" group
- Text/names → `count_distinct` metric

For the full Lightdash property reference (all options for dimensions, metrics, joins, tables), see the native `developing-in-lightdash` skill.

### Step 5: Type Inference Rules

When SQL types are visible in the model files, map them:

| SQL/Warehouse Type | Lightdash Type |
|---|---|
| `VARCHAR`, `TEXT`, `STRING`, `CHAR` | `string` |
| `INT`, `INTEGER`, `BIGINT`, `SMALLINT` | `number` |
| `FLOAT`, `DOUBLE`, `NUMERIC`, `DECIMAL` | `number` |
| `TIMESTAMP`, `DATETIME`, `TIMESTAMP_NTZ` | `timestamp` |
| `DATE` | `date` |
| `BOOLEAN`, `BOOL` | `boolean` |

When types are not visible, infer from column names:
- `*_at`, `*_timestamp` → `timestamp`
- `*_date`, `*_month`, `*_day` → `date`
- `is_*`, `has_*`, `was_*` → `boolean`
- `*_amount`, `*_revenue`, `*_price`, `*_cost` → `number`
- `*_count`, `*_quantity`, `*_total` → `number`
- `*_name`, `*_type`, `*_status`, `*_category` → `string`
- `*_key`, `*_sk`, `*_id` → `string` (hidden)

## Critical Rules

1. **Never remove existing dbt configuration** — preserve all `data_tests`, `tests`, `description`, `tags`, and other dbt properties
2. **Always use `config.meta`** — this is the dbt v1.10+ format (not bare `meta:`)
3. **Keep base/interim models hidden** — only enrich marts/reporting layer models
4. **Hide raw measures** — set `hidden: true` on dimension for amount/revenue columns, expose via `sum`/`average` metrics instead
5. **Hide surrogate keys** — `_key` and `_sk` columns should be `hidden: true`
6. **Use consistent groups** — follow the grouping conventions in `${CLAUDE_SKILL_DIR}/references/gemma-conventions.md`
7. **Use NULLIF in divisions** — model-level calculated metrics must guard against division by zero: `${metric_a} / NULLIF(${metric_b}, 0)`
8. **Currency format** — use `[$€]#,##0.00` for EUR, `[$USD]#,##0.00` for USD, etc.

## Common Mistakes

| Mistake | Consequence | Prevention |
|---|---|---|
| **Using bare `meta:` instead of `config.meta`** | YAML structure incorrect for dbt v1.10+ projects; Lightdash may not pick up the configuration | Always use `config.meta` at both model and column level |
| **Guessing filter values in metric filters** | Case mismatches (`'Payment'` vs `'payment'`) cause metrics to silently return zero | Use `lightdash sql "SELECT DISTINCT column FROM table LIMIT 50"` to get exact values |
| **Deploying to wrong project** | Overwrites production content | Always run `lightdash config get-project` before deploying |

## References

- Gemma conventions (column patterns, formats, groups): `${CLAUDE_SKILL_DIR}/references/gemma-conventions.md`
- Before/after examples: `${CLAUDE_SKILL_DIR}/references/gemma-examples.md`
- Full Lightdash property reference: see the native `developing-in-lightdash` skill (dimensions, metrics, tables, joins references)