# 02 — Glossary and Graph Signals

Builds on [01-keyword-search](../01-keyword-search/) by adding domain knowledge and relationship-aware ranking.

## What's new

- **GlossaryProvider** — maps business terms ("royalties", "disbursement") to table IDs
- **GraphBuilder** — constructs a relationship graph from foreign key edges
- **DegreeSignal** — a built-in static signal that boosts highly-connected tables

## Key concepts

### Glossary matching

Users search with business language, not table names. A query for "royalties" won't match any table via BM25 alone — but the glossary maps it to `CONTRACT` and `STATEMENT`:

```ts
{
  terms: ["royalties", "royalty", "earnings"],
  targets: ["CONTRACT", "STATEMENT"],
  context: "Royalty calculations flow through contracts and statements",
}
```

The engine uses the glossary in two ways:

1. **Query expansion** — glossary terms inject target IDs as expansion tokens, feeding a second keyword stage
2. **Direct boost** — a glossary match stage boosts target documents directly

### Graph signals

The `GraphBuilder` constructs a directed graph from FK relationships. The engine uses this graph for:

- **DegreeSignal** — tables with more incoming edges (referenced by many others) are likely hub entities. `ACCOUNT` has 3 incoming FKs (from `CONTRACT`, `PAYMENT`, `VENDOR`), so it gets a degree boost.
- **Graph augmentation** — search results include `related` tables (graph neighbors) and `joinPaths` (how to join them)

### RRF fusion

Multiple signals (keyword, glossary, degree) are combined via Reciprocal Rank Fusion:

```
score(doc) = SUM over signals: 1 / (k + rank)
```

This means a document that ranks well across _multiple_ signals outscores one that ranks #1 in just one signal. The constant `k=25` controls how much weight the top ranks get.

## Running

```bash
npx tsx examples/02-glossary-and-signals/main.ts
```

## Expected output

```
Indexed 5 tables
Graph nodes: 5

Query: "royalties" (glossary-boosted)
  0.2237  CONTRACT
  0.1840  STATEMENT
  0.1524  ACCOUNT
  0.1034  PAYMENT
  0.1000  VENDOR
  Related: (none)
  Join paths: 0

Query: "account" (degree-boosted — ACCOUNT has 3 FK references)
  0.1881  ACCOUNT
  0.1827  CONTRACT
  0.1419  PAYMENT
  0.1370  VENDOR
  0.1085  STATEMENT
```