# Gemma Lightdash Conventions

Gemma-specific conventions for configuring Lightdash in dbt projects. For the full Lightdash property reference (all dimension types, metric types, table properties, joins, etc.), see the native `developing-in-lightdash` skill.

---

## YAML Format: `config.meta` (dbt v1.10+)

Gemma dbt projects use the `config.meta` nesting format. The native Lightdash skill uses bare `meta:` — **do not mix them in the same file**.

```yaml
# ✅ Gemma convention (dbt v1.10+)
models:
  - name: fct_orders
    config:
      meta:
        label: "Orders"

# ❌ Do NOT use bare meta: in Gemma projects
models:
  - name: fct_orders
    meta:
      label: "Orders"
```

The same applies at column level: use `columns.[col].config.meta.dimension` and `columns.[col].config.meta.metrics`.

---

## Column Convention Table

Apply these patterns when enriching dbt models for Lightdash:

| Column Pattern | Dimension Config | Metrics | Group |
|---|---|---|---|
| **Surrogate/foreign keys** (`_key`, `_sk`, `_id` used as joins) | `type: string`, `hidden: true` | — | — |
| **Numeric amounts** (revenue, price, cost, amount) | `type: number`, `hidden: true`, EUR format | `sum` + `average` with EUR format | `Revenue` |
| **Quantities/counts** (quantity, count, total) | `type: number` | `sum` with integer format | `Volume` |
| **Categorical strings** (type, status, category) | `type: string` | — | `Product` / `Organisation` |
| **Boolean flags** (`is_*`, `has_*`, `was_*`) | `type: boolean` | Optional: filtered `count` | `Flags` |
| **Date columns** | `type: date` | — | `Date` |
| **Timestamps** (`*_at`, `*_timestamp`) | `type: timestamp` | — | `Date` |
| **Text/name columns** (name, title) | `type: string` | `count_distinct` | Context-dependent |

**Key rules:**
- Hide raw monetary dimensions — users should use aggregated metrics, not raw row values
- Hide surrogate keys — they have no business meaning
- Always add metrics for numeric columns — dimensions alone are rarely useful for numbers

---

## Format Patterns

| Use Case | Format String | Example |
|---|---|---|
| EUR currency | `[$€]#,##0.00` | €1,234.56 |
| EUR label | `[$EUR]#,##0.00` | EUR 1,234.56 |
| USD currency | `[$USD]#,##0.00` | USD 1,234.56 |
| Percentage | `0.00%` | 67.89% |
| Integer count | `#,##0` | 1,234 |
| Compact K | `#,##0,"K"` | 15K |

Default for Gemma projects is EUR (`[$€]#,##0.00`).

---

## Grouping Conventions

Standard sidebar groups used across Gemma projects:

| Group | Use For |
|---|---|
| `Organisation` | Company, entity, department, team names |
| `Product` | Product types, categories, line types |
| `Date` | Date/time dimensions |
| `Revenue` | Revenue and monetary metrics |
| `Volume` | Count and quantity metrics |
| `Pricing` | Unit prices, averages per unit |
| `Flags` | Boolean indicator columns |
| `Identifiers` | IDs that users might need to see (not hidden keys) |
| `Lifecycle` | Churn, retention, first/last dates |
| `Derived` | Model-level calculated metrics |
| `Operations` | Operational status, processing flags |

Use nested groups sparingly (e.g., `["Organisation", "Details"]`) — one level is usually enough.

---

## Dimension Colors

For boolean dimensions with clear good/bad semantics, add color mappings:

```yaml
dimension:
  type: boolean
  label: "Churned"
  groups: ["Lifecycle"]
  colors:
    "true": "#ef4444"     # Red for negative
    "false": "#22c55e"    # Green for positive
```

This ensures consistent colors across all charts where the dimension is pivoted.

---

## Division Safety

Model-level calculated metrics that divide must guard against zero:

```yaml
config:
  meta:
    metrics:
      revenue_per_unit:
        type: number
        sql: "${total_revenue} / NULLIF(${total_quantity}, 0)"
        format: "[$€]#,##0.00"
        groups: ["Derived"]
```

Always use `NULLIF(${denominator}, 0)` — never divide without it.