---
alwaysApply: false
description: "Graphit: Consult when starting a dashboard build. The Knowledge Base contains reusable metrics, dimensions, rules, and table schemas that ensure consistent formulas across dashboards."
globs: []
---

# KB Exploration

Consult when starting a dashboard build. The Knowledge Base contains reusable metrics, dimensions, rules, and table schemas that ensure consistent formulas across dashboards.

## KB-First Discovery

Before writing raw SQL with inline aggregations or column references:

1. Understand organization: `graphit kb list domains` shows business-area groupings (MARKETING, PRODUCT, FINANCE, etc.)
2. List what exists: `graphit kb list metrics`, `graphit kb list dimensions`, `graphit kb list rules`
3. If a KB metric matches the user's request, use its formula: `graphit kb get metric REVENUE`
4. If no match exists, consider whether to build the dashboard from raw columns or suggest KB asset creation first
5. Explore relationships: `graphit kb explore metric REVENUE` shows which tables and dimensions connect to a metric

## Metric vs Dimension

| Property | Metric | Dimension |
|---|---|---|
| Formula | Aggregation required (SUM, COUNT, AVG, MIN, MAX) | Row-level only (no aggregates) |
| Table scope | Can reference multiple tables | Exactly one table |
| Purpose | Measures - what you count/sum | Grouping axes - how you slice |
| Example | `SUM(ORDERS.AMOUNT)` | `DATE_TRUNC('month', EVENTS.EVENT_TS)` |
| Invalid | `ORDERS.AMOUNT` (no aggregate) | `SUM(EVENTS.DURATION)` (has aggregate) |

## Naming Conventions

All KB assets use UPPER_SNAKE_CASE. The names are auto-sanitized:

| Pattern | Example | Use when |
|---|---|---|
| `TOTAL_*` | `TOTAL_REVENUE`, `TOTAL_ORDERS` | Sum aggregations |
| `AVG_*` | `AVG_ORDER_VALUE` | Average metrics |
| `COUNT_*` | `COUNT_ACTIVE_USERS` | Count metrics |
| `*_RATE` | `CONVERSION_RATE`, `CHURN_RATE` | Ratios/percentages |

> `*_RATE`/ratio columns are usually 0-1 fractions. To chart them as a percent, multiply by 100 in SQL (`* 100.0`) - `"percent"` format appends `%` without scaling.

## When to Suggest KB Asset Creation

| Signal | Propose |
|---|---|
| User requests a business metric with no KB match | Metric - reusable formula |
| User groups by a derived expression | Dimension - consistent grouping |
| User describes a business rule ("active = logged in within 30d") | Rule - applied to future queries |
| User uses a business term not in KB | Synonym - maps colloquial to defined |

## Formula Syntax

Metrics require `TABLE.COLUMN` references with UPPERCASE naming:

```sql
-- Valid metric formulas
SUM(ORDERS.AMOUNT)
COUNT(DISTINCT EVENTS.USER_ID) WHERE EVENTS.EVENT_TS >= DATEADD(day, -30, CURRENT_DATE)
SUM(ORDERS.REVENUE) / NULLIF(SUM(ORDERS.COST), 0)

-- Valid dimension formulas (no aggregates)
EVENTS.PLATFORM
DATE_TRUNC('month', EVENTS.EVENT_TS)
CASE WHEN USERS.AGE >= 18 THEN 'adult' ELSE 'minor' END
```

Conditionals use CASE WHEN (not FILTER WHERE - Snowflake doesn't support it). Always guard division with NULLIF.

For deeper coverage, consult: `kb-graph-structure.md` (graph model), `kb-awareness.md` (KB-first planning), `kb-explanation.md` (structural Q&A), `parameterized-metrics.md` (metric templates), `kb-traversal.md` (graph queries), `kb-actions.md` (full CRUD).