# @coda/search Examples

Progressive examples from minimal to production-like usage. Each builds on previous concepts — read the READMEs in order for the best experience.

| #   | Example                                              | New concepts                                                        | Embedding? |
| --- | ---------------------------------------------------- | ------------------------------------------------------------------- | ---------- |
| 1   | [Keyword search](01-keyword-search/)                 | SchemaFetcher, DocumentTransformer, BM25                            | No         |
| 2   | [Glossary and signals](02-glossary-and-signals/)     | GlossaryProvider, GraphBuilder, DegreeSignal, graph augmentation    | No         |
| 3   | [Custom signal](03-custom-signal/)                   | HybridSearch.create(), StaticSignal, explain(), RRF fusion          | No         |
| 4   | [Events and lifecycle](04-events-and-lifecycle/)     | EventBus, incremental refresh via diff(), state transitions         | No         |
| 5   | [Filters and pagination](05-filters-and-pagination/) | SearchFilter (include/exclude/predicate), keyset pagination         | No         |
| 6   | [Custom pipeline](06-custom-pipeline/)               | QueryExpander, SearchStage, QuerySignal (pipeline extension points) | No         |
| 7   | [Hybrid search](07-hybrid-search/)                   | EmbeddingProvider, vector + keyword fusion, QuerySignal in action   | Yes (mock) |
| 8   | [Snapshot persistence](08-snapshot-persistence/)     | SnapshotPersistence, warm start, model invalidation                 | Yes (mock) |
| 9   | [Graph signals](09-graph-signals/)                   | AdamicAdarSignal, BetweennessSignal, ColumnDensitySignal            | No         |
| 10  | [Evaluation](10-evaluation/)                         | ndcg, mrr, precisionAtK, recallAtK, RelevanceMap, ablation          | No         |

## Running

```bash
# From packages/search/
npx tsx examples/01-keyword-search/main.ts
npx tsx examples/02-glossary-and-signals/main.ts
npx tsx examples/03-custom-signal/main.ts
npx tsx examples/04-events-and-lifecycle/main.ts
npx tsx examples/05-filters-and-pagination/main.ts
npx tsx examples/06-custom-pipeline/main.ts
npx tsx examples/07-hybrid-search/main.ts
npx tsx examples/08-snapshot-persistence/main.ts
npx tsx examples/09-graph-signals/main.ts
npx tsx examples/10-evaluation/main.ts
```

## Progression

Examples 01-04 use `SearchEngine` (the high-level orchestrator) with keyword-only search. Example 03 switches to `HybridSearch.create()` for direct control over signals. Examples 05-08 add production features: filtering, pipeline customization, vector search, and snapshot caching. Examples 09-10 cover advanced signals and quality measurement.

```
01 keyword → 02 glossary+graph → 03 custom signal → 04 events
                                                          ↓
08 snapshots ← 07 hybrid search ← 06 pipeline ← 05 filters
                                                          ↓
                                    09 graph signals → 10 evaluation
```

## What's not covered here

- **Production EmbeddingProvider**: Examples 07-08 use a mock. Real providers use ONNX Runtime, AWS Bedrock Titan, or similar. See [Getting Started](../docs/getting-started.md#adding-vector-search).
- **Reranking**: Requires a `RerankProvider` (cross-encoder model). See [Cookbook](../docs/cookbook.md#add-a-cross-encoder-reranker).
- **S3 snapshots**: Example 08 uses in-memory storage. See [Engine Lifecycle](../docs/engine.md) for S3 configuration.
- **QuantizedHnswIndex**: 4x memory reduction. See [Cookbook](../docs/cookbook.md#use-quantized-hnsw-for-lower-memory).
- **FuzzyStage**: Typo tolerance. See [Cookbook](../docs/cookbook.md#add-fuzzy-typo-tolerance).