---
title: "Semantic Index"
type: concept
tags: [index, code-intelligence, navigation]
last_updated: 2026-04-20
---

## Definition
Semantic Index（语义索引）是存储代码符号定义、引用关系和悬停文档的持久化数据结构，支持快速代码导航和文档查询。

## Navigation Index Format (nav.index.jsonl)
```jsonl
{"symId":"sym:AppController","def":{"uri":"file:///src/app.php","l":10,"c":6},"refs":[
  {"uri":"file:///src/routes.php","l":5,"c":10}
],"hover":{"contents":{"kind":"markdown","value":"```php\nclass AppController extends BaseController\n```"}}}
```

## Index Schema
| Field | Description |
|-------|-------------|
| symId | 符号唯一标识符，格式：`sym:<name>` |
| def | 定义位置（文件 URI + 行号 + 列号） |
| refs | 引用位置数组 |
| hover | 悬停文档内容（Markdown 格式） |

## Storage Backends
- **JSONL**：流式写入，适合大规模索引
- **SQLite**：支持快速随机访问和复杂查询
- **LSIF**：Language Server Index Format，用于预计算数据导入/导出

## Performance Requirements
- 定义查找：<20ms（缓存），<60ms（未缓存）
- 支持 100k+ 符号规模
- 增量更新，不重建整个索引

## Connections
- [[graphd]] ← 维护 ← [[Semantic Index]]
- [[LSIF (Language Server Index Format)]] ← 导入/导出 ← [[Semantic Index]]