docs: add multi-language documentation (ru, fa, zh, tr, ar)
This commit is contained in:
@@ -0,0 +1,197 @@
|
||||
# Архитектура BaraDB
|
||||
|
||||
## Обзор
|
||||
|
||||
BaraDB — это **мультимодальный движок баз данных** на языке Nim, объединяющий документное (KV), графовое, векторное, колоночное хранилище и полнотекстовый поиск в едином движке с унифицированным языком запросов **BaraQL**.
|
||||
|
||||
## Слоёвая архитектура
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ 1. СЛОЙ КЛИЕНТА │
|
||||
│ Бинарный протокол │ HTTP/REST │ WebSocket │ Встраивание│
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ 2. СЛОЙ ЗАПРОСОВ (BaraQL) │
|
||||
│ Лексер → Парсер → AST → IR → Оптимизатор → Кодоген │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ 3. ДВИЖОК ВЫПОЛНЕНИЯ │
|
||||
│ Документы │ Граф │ Векторы │ Колоночный │ FTS │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ 4. ХРАНИЛИЩЕ │
|
||||
│ LSM-Tree │ B-Tree │ WAL │ Bloom │ Компактификация │ Cache│
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ 5. РАСПРЕДЕЛЁННОСТЬ │
|
||||
│ Raft │ Шардирование │ Репликация │ Gossip │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Слой 1: Клиентский слой
|
||||
|
||||
Несколько протоколов связи:
|
||||
|
||||
- **Бинарный протокол** (`protocol/wire.nim`): Эффективный бинарный протокол в big-endian с 16 типами сообщений
|
||||
- **HTTP/REST** (`core/httpserver.nim`): JSON-based REST API с многопоточностью
|
||||
- **WebSocket** (`core/websocket.nim`): Полнодуплексная потоковая передача
|
||||
- **Встраиваемый режим** (`storage/lsm.nim`): Прямой доступ внутри процесса
|
||||
|
||||
### Управление соединениями
|
||||
|
||||
- **Пул соединений** (`protocol/pool.nim`): Мин/макс лимиты соединений с таймаутом простоя
|
||||
- **Ограничение скорости** (`protocol/ratelimit.nim`): Token-bucket глобальные и пери-клиент лимиты
|
||||
- **Аутентификация** (`protocol/auth.nim`): JWT с HMAC-SHA256 и ролевой доступ
|
||||
- **TLS/SSL** (`protocol/ssl.nim`): TLS 1.3 с автогенерируемыми сертификатами
|
||||
|
||||
## Слой 2: Слой запросов (BaraQL)
|
||||
|
||||
Конвейер BaraQL:
|
||||
|
||||
1. **Лексер** (`query/lexer.nim`): Токенизация входных данных в 80+ типов токенов
|
||||
2. **Парсер** (`query/parser.nim`): Рекурсивный нисходящий парсер, создающий AST
|
||||
3. **AST** (`query/ast.nim`): 300+ строк, покрывающих 25+ видов узлов
|
||||
4. **IR** (`query/ir.nim`): Промежуточное представление для планов выполнения
|
||||
5. **Оптимизатор** (`query/adaptive.nim`): Адаптивная кросс-модальная оптимизация запросов
|
||||
6. **Кодоген** (`query/codegen.nim`): Трансляция IR в операции хранилища
|
||||
7. **Исполнитель** (`query/executor.nim`): Выполнение планов с параллелизацией
|
||||
|
||||
### Кросс-модальное планирование
|
||||
|
||||
Оптимизатор (`query/adaptive.nim`) определяет порядок выполнения между движками:
|
||||
|
||||
```
|
||||
1. Оценить селективность каждого предиката
|
||||
2. Направить наиболее селективный предикат в его движок первым
|
||||
3. Использовать bloom-фильтры для KV поисков
|
||||
4. Параллелизовать независимые ветви
|
||||
5. Потоковая передача результатов для избежания материализации
|
||||
```
|
||||
|
||||
## Слой 3: Движок выполнения
|
||||
|
||||
### Документный/KV движок
|
||||
- **LSM-Tree** (`storage/lsm.nim`): Хранилище с оптимизацией записи с MemTable, WAL, SSTables
|
||||
- **B-Tree индекс** (`storage/btree.nim`): Упорядоченный индекс для диапазонных сканирований с COW
|
||||
|
||||
### Векторный движок (`vector/`)
|
||||
- **HNSW индекс** (`vector/engine.nim`): Иерархический навигируемый граф малого мира
|
||||
- **IVF-PQ индекс** (`vector/engine.nim`): Инвертированный файловый индекс с продуктовым квантованием
|
||||
- **SIMD операции** (`vector/simd.nim`): AVX2-оптимизированные вычисления расстояний
|
||||
- **Квантование** (`vector/quant.nim`): Скалярное, продуктовое и бинарное квантование
|
||||
|
||||
### Графовый движок (`graph/`)
|
||||
- **Список смежности** (`graph/engine.nim`): Граф с рёберными весами
|
||||
- **Алгоритмы** (`graph/engine.nim`): BFS, DFS, Dijkstra, PageRank
|
||||
- **Обнаружение сообществ** (`graph/community.nim`): Алгоритм Louvain
|
||||
- **Сопоставление шаблонов** (`graph/community.nim`): Изоморфизм подграфов
|
||||
- **Cypher парсер** (`graph/cypher.nim`): Cypher-подобные графовые запросы
|
||||
|
||||
### Полнотекстовый поиск (`fts/`)
|
||||
- **Инвертированный индекс** (`fts/engine.nim`): Терм-документ индекс
|
||||
- **Ранжирование** (`fts/engine.nim`): BM25 и TF-IDF scoring
|
||||
- **Нечёткий поиск** (`fts/engine.nim`): Сопоставление по расстоянию Левенштейна
|
||||
- **Многоязычность** (`fts/multilang.nim`): Токенизаторы для EN, BG, DE, FR, RU
|
||||
|
||||
### Колоночный движок (`core/columnar.nim`)
|
||||
- Поколоночное хранение для аналитических запросов
|
||||
- RLE и словарное кодирование
|
||||
- SIMD-ускоренные агрегаты
|
||||
|
||||
## Слой 4: Хранилище
|
||||
|
||||
- **LSM-Tree** (`storage/lsm.nim`): MemTable, WAL, SSTable, Bloom Filter, Компактификация
|
||||
- **Page Cache** (`storage/compaction.nim`): LRU кэш с отслеживанием hit rate
|
||||
- **Memory-mapped I/O** (`storage/mmap.nim`): mmap-based доступ к файлам
|
||||
- **Восстановление** (`storage/recovery.nim`): WAL replay и восстановление после сбоев
|
||||
|
||||
### Путь записи
|
||||
|
||||
```
|
||||
Клиент → Протокол → Auth → Парсер → AST → IR → Кодоген
|
||||
→ StorageOp → MVCC Txn → WAL Write → MemTable → Commit
|
||||
```
|
||||
|
||||
### Путь чтения
|
||||
|
||||
```
|
||||
Клиент → Протокол → Auth → Парсер → AST → IR → Кодоген
|
||||
→ StorageOp → MVCC Snapshot → MemTable → SSTable → Result
|
||||
```
|
||||
|
||||
## Слой 5: Распределённость
|
||||
|
||||
- **Raft Consensus** (`core/raft.nim`): Лидер-выборы, репликация лога
|
||||
- **Шардирование** (`core/sharding.nim`): Hash, range и consistent hashing
|
||||
- **Репликация** (`core/replication.nim`): Sync, async, semi-sync режимы
|
||||
- **Gossip протокол** (`core/gossip.nim`): SWIM-like управление членством
|
||||
- **Распределённые транзакции** (`core/disttxn.nim`): Two-phase commit
|
||||
|
||||
## Ключевые архитектурные решения
|
||||
|
||||
1. **Чистый Nim**: Без Cython, Python или Rust зависимостей
|
||||
2. **Унифицированное хранилище**: Один движок для KV, графов, векторов, FTS и колоночного
|
||||
3. **Встраиваемый режим**: Может работать как библиотека или сервер
|
||||
4. **Бинарный протокол**: Кастомный эффективный wire протокол
|
||||
5. **MVCC**: Многоверсионное управление параллелизмом
|
||||
6. **Схема-первый**: Строго типизированная система схем с наследованием
|
||||
7. **Кросс-модальность**: Единый язык запросов для всех моделей данных
|
||||
8. **Формальная верификация**: Основные распределённые алгоритмы специфицированы в TLA+ и проверены с TLC
|
||||
|
||||
## Статистика по модулям
|
||||
|
||||
| Категория | Модули | Строк кода | Назначение |
|
||||
|----------|---------|------------|------------|
|
||||
| Core | 16 | ~4,200 | Сервер, протоколы, транзакции, распределённость |
|
||||
| Storage | 7 | ~3,100 | LSM, B-Tree, WAL, bloom, компактификация, mmap |
|
||||
| Query | 7 | ~2,800 | Лексер, парсер, AST, IR, оптимизатор, кодоген, исполнитель |
|
||||
| Vector | 3 | ~1,200 | HNSW, IVF-PQ, квантование, SIMD |
|
||||
| Graph | 3 | ~1,000 | Список смежности, алгоритмы, обнаружение сообществ |
|
||||
| FTS | 2 | ~900 | Инвертированный индекс, BM25, нечёткий, многоязычный |
|
||||
| Protocol | 7 | ~2,400 | Wire, HTTP, WebSocket, пул, auth, rate limit, SSL |
|
||||
| Schema | 1 | ~600 | Типы, связи, наследование, миграции |
|
||||
| Client | 2 | ~800 | Nim binary клиент, файловые хелперы |
|
||||
| CLI | 1 | ~400 | Интерактивная BaraQL оболочка |
|
||||
| **Всего** | **49** | **~14,100** | |
|
||||
|
||||
## Диаграммы потока данных
|
||||
|
||||
### Простой запрос
|
||||
|
||||
```
|
||||
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
|
||||
│ Client │───→│ Lexer │───→│ Parser │───→│ IR │───→│ Codegen│
|
||||
└────────┘ └────────┘ └────────┘ └────────┘ └───┬────┘
|
||||
│
|
||||
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
|
||||
│ Result │←───│ Format │←───│ Execute│←───│ Storage│←──────┘
|
||||
└────────┘ └────────┘ └────────┘ └────────┘
|
||||
```
|
||||
|
||||
### Кросс-модальный запрос
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ Parser │
|
||||
└──────┬──────┘
|
||||
│
|
||||
┌──────▼──────┐
|
||||
│ Adaptive │
|
||||
│ Optimizer │
|
||||
└──────┬──────┘
|
||||
│
|
||||
┌───────────────┼───────────────┐
|
||||
│ │ │
|
||||
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
|
||||
│ Vector │ │ Graph │ │ FTS │
|
||||
│ Engine │ │ Engine │ │ Engine │
|
||||
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
|
||||
│ │ │
|
||||
└───────────────┼───────────────┘
|
||||
│
|
||||
┌──────▼──────┐
|
||||
│ Join │
|
||||
│ & Sort │
|
||||
└──────┬──────┘
|
||||
│
|
||||
┌──────▼──────┐
|
||||
│ Result │
|
||||
└─────────────┘
|
||||
```
|
||||
Reference in New Issue
Block a user