Update documentation and clients for v1.1.0

Documentation updates: - Fix v0.1.0 → v1.1.0 version numbers in en, ru, fa, zh docs - Add missing Window Functions, Multi-Tenant ERP, Supported Keywords sections to ru, fa, zh baraql.md (~105 lines each) - Expand Turkish and Arabic baraql.md (110 → 268 lines) - Expand Turkish and Arabic installation.md (62 → 307 lines) - Add new Bulgarian documentation files (18 new files) Client updates: - Python: Full async/await rewrite with asyncio, request queueing - Rust: Full async/await rewrite with tokio, async examples - Nim: Update README to v1.1.0 - All clients now support async patterns consistently
2026-05-14 23:05:47 +03:00
parent f7d4961125
commit c55d3080cf
48 changed files with 5792 additions and 544 deletions
@@ -0,0 +1,107 @@
+# API за Бинарен Протокол
+
+Ниско-нивов wire протокол за високопроизводителни клиентски връзки.
+
+## Формат на Съобщенията
+
+Всички съобщения използват big-endian byte order:
+
+```
+┌─────────────┬─────────────┬─────────────┬─────────────────────┐
+│  Kind        │  Length     │  RequestId  │  Payload            │
+│  (4 bytes)   │  (4 bytes)  │  (4 bytes)  │                     │
+│  uint32 BE   │  uint32 BE  │  uint32 BE  │  (Length bytes)     │
+└─────────────┴─────────────┴─────────────┴─────────────────────┘
+```
+
+## Типове Съобщения
+
+### Query (0x01)
+
+```nim
+let msg = makeQueryMessage(requestId, "SELECT * FROM users")
+```
+
+### QueryParams (0x02)
+
+```nim
+let msg = makeQueryParamsMessage(requestId, "SELECT * FROM users WHERE name = ?", params)
+```
+
+### Auth (0x07)
+
+```nim
+let msg = makeAuthMessage(requestId, token)
+```
+
+### Ping (0x09)
+
+```nim
+let msg = makePingMessage(requestId)
+```
+
+### Close (0x0A)
+
+```nim
+let msg = makeCloseMessage(requestId)
+```
+
+## Отговорни Съобщения
+
+### Ready (0x05)
+
+```nim
+let msg = makeReadyMessage(requestId)
+```
+
+### Error (0x06)
+
+```nim
+let msg = makeErrorMessage(requestId, code, message)
+```
+
+### Data (0x81)
+
+```nim
+# Съдържа резултатите от заявката с колони и редове
+```
+
+### Complete (0x82)
+
+```nim
+# Потвърждава завършване на заявката
+```
+
+### Auth_OK (0x83)
+
+```nim
+# Потвърждава успешна автентикация
+```
+
+### Pong (0x84)
+
+```nim
+# Keepalive отговор
+```
+
+## Кодове за Грешки
+
+| Код | Име | Описание |
+|------|-----|----------|
+| 0x00 | OK | Успех |
+| 0x01 | ERROR | Обща грешка |
+| 0x02 | AUTH_REQUIRED | Изисква се автентикация |
+| 0x03 | INVALID_QUERY | Синтактична грешка в заявката |
+| 0x04 | NOT_FOUND | Ресурсът не е намерен |
+
+## Сериализация
+
+```nim
+import barabadb/protocol/wire
+
+# Сериализиране на стойност
+let bytes = serializeValue(Value(kind: vkString, strVal: "test"))
+
+# Десериализиране на стойност
+let value = deserializeValue(bytes)
+```
@@ -0,0 +1,111 @@
+# HTTP/REST API
+
+JSON-базиран REST API за уеб приложения.
+
+## Базов URL
+
+```
+http://localhost:9470
+```
+
+## Endpoints
+
+### GET /health
+
+Health проверка:
+
+```bash
+curl http://localhost:9470/health
+```
+
+### GET /ready
+
+Readiness проверка:
+
+```bash
+curl http://localhost:9470/ready
+```
+
+### POST /query
+
+Изпълнение на BaraQL заявка:
+
+```bash
+curl -X POST http://localhost:9470/api/query \
+  -H "Content-Type: application/json" \
+  -d '{"query": "SELECT * FROM users WHERE age > 18"}'
+```
+
+Отговор:
+```json
+{
+  "columns": ["name", "age"],
+  "rows": [["Alice", 30], ["Bob", 25]],
+  "row_count": 2,
+  "duration_ms": 12
+}
+```
+
+### POST /batch
+
+Групови заявки:
+
+```bash
+curl -X POST http://localhost:9470/api/batch \
+  -H "Content-Type: application/json" \
+  -d '{"queries": ["INSERT users { name := \"Alice\" }", "INSERT users { name := \"Bob\" }"]}'
+```
+
+### GET /schema
+
+Преглед на схемата:
+
+```bash
+curl http://localhost:9470/api/schema
+```
+
+### GET /metrics
+
+Prometheus метрики:
+
+```bash
+curl http://localhost:9470/metrics
+```
+
+### POST /explain
+
+Обяснение на план за изпълнение:
+
+```bash
+curl -X POST http://localhost:9470/api/explain \
+  -H "Content-Type: application/json" \
+  -d '{"query": "SELECT * FROM users WHERE age > 18"}'
+```
+
+### POST /backup
+
+Създаване на backup:
+
+```bash
+curl -X POST http://localhost:9470/api/backup \
+  -H "Content-Type: application/json" \
+  -d '{"destination": "/backup/snapshot.db"}'
+```
+
+## Грешки
+
+```json
+{
+  "error": {
+    "code": "INVALID_QUERY",
+    "message": "Грешка в синтаксиса"
+  }
+}
+```
+
+## Автентикация
+
+```bash
+curl -H "Authorization: Bearer <token>" \
+  http://localhost:9470/api/users
+```
@@ -0,0 +1,127 @@
+# WebSocket API
+
+Full-duplex стрийминг за данни в реално време и push известия.
+
+## Свързване
+
+```
+ws://localhost:9471
+```
+
+## Клиентски Пример
+
+```javascript
+const ws = new WebSocket('ws://localhost:9471');
+
+ws.onopen = () => {
+  console.log('Свързан');
+  ws.send(JSON.stringify({
+    type: 'query',
+    query: 'SELECT * FROM users'
+  }));
+};
+
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  console.log('Получено:', data);
+};
+```
+
+## Формат на Съобщенията
+
+```json
+{
+  "type": "query",
+  "id": "1",
+  "query": "SELECT * FROM users"
+}
+```
+
+## Типове Съобщения
+
+### Заявка (query)
+
+```json
+{
+  "type": "query",
+  "id": "1",
+  "query": "SELECT * FROM users"
+}
+```
+
+### Резултат (result)
+
+```json
+{
+  "type": "result",
+  "id": "1",
+  "columns": ["id", "name"],
+  "rows": [["1", "Alice"], ["2", "Bob"]]
+}
+```
+
+### Грешка (error)
+
+```json
+{
+  "type": "error",
+  "id": "1",
+  "code": "INVALID_QUERY",
+  "message": "Синтактична грешка"
+}
+```
+
+### Абониране (subscribe)
+
+Абониране за промени в таблица:
+
+```json
+{
+  "type": "subscribe",
+  "id": "sub1",
+  "table": "users"
+}
+```
+
+### Известие (notification)
+
+Push известие от сървъра:
+
+```json
+{
+  "type": "notification",
+  "table": "users",
+  "operation": "insert",
+  "data": {"id": 3, "name": "Charlie"}
+}
+```
+
+### Ping/Pong (keepalive)
+
+```json
+{"type": "ping", "id": "ping1"}
+```
+
+Отговор:
+```json
+{"type": "pong", "id": "ping1"}
+```
+
+## JavaScript Клиент
+
+```javascript
+class BaraDBClient {
+  constructor(url) {
+    this.ws = new WebSocket(url);
+    this.pending = new Map();
+  }
+
+  query(sql) {
+    return new Promise((resolve, reject) => {
+      const id = crypto.randomUUID();
+      this.pending.set(id, { resolve, reject });
+      this.ws.send(JSON.stringify({ type: 'query', id, query: sql }));
+    });
+  }
+}
+```
@@ -2,150 +2,125 @@

 ## Преглед

-BaraDB е **мултимодална база данни** написана на Nim, която комбинира документно (KV), графично, векторно, колонно и пълнотекстово търсене в един двигател с обединен език за заявки наречен **BaraQL**.
+BaraDB е **мултимодален database engine**, написан на Nim, който комбинира документно (KV), графово, векторно, колонково и пълнотекстово съхранение в един engine с унифициран език за заявки наречен **BaraQL**.

-## Слоеста Архитектура
+## Слоеве на Архитектурата

 ```
 ┌─────────────────────────────────────────────────────────┐
-│ 1. СЛОЙ ЗА КЛИЕНТИ                                       │
-│    Binary Protocol │ HTTP/REST │ WebSocket │ Embedded    │
+│ 1. КЛИЕНТСКИ СЛОЙ                                        │
+│    Бинарен Протокол │ HTTP/REST │ WebSocket │ Embedded   │
 ├─────────────────────────────────────────────────────────┤
-│ 2. ЗАЯВКИ СЛОЙ (BaraQL)                                  │
+│ 2. QUERY СЛОЙ (BaraQL)                                   │
 │    Lexer → Parser → AST → IR → Optimizer → Codegen      │
 ├─────────────────────────────────────────────────────────┤
-│ 3. ИЗПЪЛНИТЕЛЕН ДВИГАТЕЛ                                  │
-│    Document │ Graph │ Vector │ Columnar │ FTS            │
+│ 3. ИЗПЪЛНИТЕЛЕН ENGINE                                   │
+│    Документен │ Графов │ Векторен │ Колонков │ FTS       │
 ├─────────────────────────────────────────────────────────┤
-│ 4. СЪХРАНЕНИЕ                                             │
+│ 4. СЪХРАНЕНИЕ                                            │
 │    LSM-Tree │ B-Tree │ WAL │ Bloom │ Compaction │ Cache  │
 ├─────────────────────────────────────────────────────────┤
-│ 5. РАЗПРЕДЕЛЕНО                                           │
-│    Raft Consensus │ Sharding │ Replication │ Gossip      │
+│ 5. РАЗПРЕДЕЛЕНИ                                          │
+│    Raft Консенсус │ Шардиране │ Репликация │ Gossip      │
 └─────────────────────────────────────────────────────────┘
 ```

 ## Слой 1: Клиентски Слой

-Множество протоколи за комуникация:
+Множество комуникационни протоколи:

- **Binary Protocol** (`protocol/wire.nim`): Ефективен big-endian бинарен протокол с 16 типа съобщения
- **HTTP/REST** (`core/httpserver.nim`): JSON REST API с мулти-трединг
- **WebSocket** (`core/websocket.nim`): Пълен дуплекс стрийминг
+- **Бинарен Протокол** (`protocol/wire.nim`): Ефективен big-endian бинарен протокол с 16 типа съобщения
+- **HTTP/REST** (`core/httpserver.nim`): JSON-базиран REST API с multi-threading
+- **WebSocket** (`core/websocket.nim`): Full-duplex стрийминг
 - **Embedded** (`storage/lsm.nim`): Директен in-process достъп

-### Управление на Връзките
+### Управление на Връзки

- **Connection Pool** (`protocol/pool.nim`): Мин/макс лимити на връзки
- **Rate Limiting** (`protocol/ratelimit.nim`): Token-bucket лимитиране
- **Authentication** (`protocol/auth.nim`): JWT с HMAC-SHA256
- **TLS/SSL** (`protocol/ssl.nim`): TLS 1.3 с авто-генерирани сертификати
+- **Connection Pool** (`protocol/pool.nim`): Min/max лимити на връзки с idle timeout
+- **Rate Limiting** (`protocol/ratelimit.nim`): Token-bucket глобални и per-client лимити
+- **Автентикация** (`protocol/auth.nim`): JWT с HMAC-SHA256 и достъп на база роли
+- **TLS/SSL** (`protocol/ssl.nim`): TLS 1.3 с автоматично генерирани сертификати

-## Слой 2: Заявки (BaraQL)
+## Слой 2: Query Слой (BaraQL)

-Pipeline-а на BaraQL:
+BaraQL конвейрът:

 1. **Lexer** (`query/lexer.nim`): Токенизира входа в 80+ типа токени
-2. **Parser** (`query/parser.nim`): Рекурсивен descent парсър произвеждащ AST
+2. **Parser** (`query/parser.nim`): Recursive descent parser генериращ AST
 3. **AST** (`query/ast.nim`): 300+ реда покриващи 25+ вида възли
-4. **IR** (`query/ir.nim`): Междинно представяне за планове за изпълнение
-5. **Optimizer** (`query/adaptive.nim`): Адаптивен крос-модален оптимизатор
-6. **Codegen** (`query/codegen.nim`): Транслира IR към операции върху съхранение
+4. **IR** (`query/ir.nim`): Intermediate representation за планове за изпълнение
+5. **Optimizer** (`query/adaptive.nim`): Adaptive cross-modal оптимизация на заявки
+6. **Codegen** (`query/codegen.nim`): Превежда IR към storage операции
 7. **Executor** (`query/executor.nim`): Изпълнява планове с паралелизация

-### Крос-Модално Планиране
+## Слой 3: Изпълнителен Engine

-Оптимизаторът определя реда на изпълнение между двигателите:
+### Документен/KV Engine
+- **LSM-Tree** (`storage/lsm.nim`): Write-оптимизирано съхранение с MemTable, WAL, SSTables
+- **B-Tree Индекс** (`storage/btree.nim`): Подреден индекс за range сканиране с COW

-```
-1. Оценка на селективност за всеки предикат
-2. Най-селективният предикат се изпълнява първи
-3. Bloom филтри за KV търсения
-4. Паралелизация на независими клонове
-```
+### Vector Engine (`vector/`)
+- **HNSW Индекс** (`vector/engine.nim`): Hierarchical Navigable Small World граф
+- **IVF-PQ Индекс** (`vector/engine.nim`): Inverted File Index с Product Quantization
+- **SIMD Операции** (`vector/simd.nim`): AVX2-оптимизирани изчисления на разстояние
+- **Квантуване** (`vector/quant.nim`): Скаларно, продуктово и бинарно квантуване

-## Слой 3: Изпълнителен Двигател
-
-### Document/KV Двигател
- **LSM-Tree** (`storage/lsm.nim`): Оптимизиран за запис с MemTable, WAL, SSTables
- **B-Tree Index** (`storage/btree.nim`): Подреден индекс за диапазони с COW
-
-### Vector Engine
- **HNSW** (`vector/engine.nim`): Иерархичен навигируем малък свят
- **IVF-PQ** (`vector/engine.nim`): Инвертиран файл с продуктово квантуване
- **SIMD** (`vector/simd.nim`): AVX2-оптимизирани изчисления на разстояния
- **Quantization** (`vector/quant.nim`): Скаларно, продуктово и бинарно квантуване
-
-### Graph Engine
- **Списък със съседи** (`graph/engine.nim`): Насочен граф с тегла
+### Graph Engine (`graph/`)
+- **Adjacency List** (`graph/engine.nim`): Насочен граф с тегла на ребрата
 - **Алгоритми** (`graph/engine.nim`): BFS, DFS, Dijkstra, PageRank
 - **Community Detection** (`graph/community.nim`): Louvain алгоритъм
- **Pattern Matching** (`graph/community.nim`): Subgraph isomorphism
- **Cypher Parser** (`graph/cypher.nim`): Cypher-подобни заявки
+- **Pattern Matching** (`graph/community.nim`): Subgraph изоморфизъм
+- **Cypher Parser** (`graph/cypher.nim`): Cypher-подобни графови заявки

-### FTS
- **Инвертиран индекс** (`fts/engine.nim`): Термин-документ индекс
- **Ранжиране** (`fts/engine.nim`): BM25 и TF-IDF
- **Fuzzy Search** (`fts/engine.nim`): Levenshtein разстояние
- **Многоезичен** (`fts/multilang.nim`): Токенизация за EN, BG, DE, FR, RU
+### Full-Text Search (`fts/`)
+- **Inverted Index** (`fts/engine.nim`): Термин-документен индекс
+- **Ранжиране** (`fts/engine.nim`): BM25 и TF-IDF оценяване
+- **Fuzzy Търсене** (`fts/engine.nim`): Съвпадение с Levenshtein разстояние
+- **Многоезичност** (`fts/multilang.nim`): Токенизатори за EN, BG, DE, FR, RU

-### Columnar Engine
- **Колонно съхранение** (`core/columnar.nim`): Аналитични заявки
- **Компресия**: RLE и dictionary encoding
- **SIMD агрегати**: Ускорени агрегатни функции
+### Columnar Engine (`core/columnar.nim`)
+- Колонково съхранение за аналитични заявки
+- RLE и dictionary encoding
+- SIMD-ускорени агрегати

 ## Слой 4: Съхранение

 - **LSM-Tree** (`storage/lsm.nim`): MemTable, WAL, SSTable, Bloom Filter, Compaction
- **Page Cache** (`storage/compaction.nim`): LRU кеш
- **Memory-mapped I/O** (`storage/mmap.nim`): mmap-базиран достъп
- **Recovery** (`storage/recovery.nim`): WAL replay и възстановяване
+- **Page Cache** (`storage/compaction.nim`): LRU кеш с проследяване на hit rate
+- **Memory-mapped I/O** (`storage/mmap.nim`): mmap-базиран достъп до файлове
+- **Recovery** (`storage/recovery.nim`): WAL replay и crash recovery

-### Път на Запис
+## Слой 5: Разпределение

-```
-Client → Protocol → Auth → Parser → AST → IR → Codegen
-  → StorageOp → MVCC Txn → WAL Write → MemTable → Commit
-```
+- **Raft Консенсус** (`core/raft.nim`): Leader election, log репликация
+- **Шардиране** (`core/sharding.nim`): Hash, range и consistent hashing
+- **Репликация** (`core/replication.nim`): Sync, async, semi-sync режими
+- **Gossip Протокол** (`core/gossip.nim`): SWIM-подобно управление на членство
+- **Разпределени Транзакции** (`core/disttxn.nim`): Two-phase commit

-### Път на Четене
-
-```
-Client → Protocol → Auth → Parser → AST → IR → Codegen
-  → StorageOp → MVCC Snapshot → MemTable → SSTable → Result
-```
-
-## Слой 5: Разпределено
-
- **Raft Consensus** (`core/raft.nim`): Лидерско избиране, репликация на логове
- **Sharding** (`core/sharding.nim`): Hash, range и консистентно хеширане
- **Replication** (`core/replication.nim`): Sync, async, semi-sync режими
- **Gossip Protocol** (`core/gossip.nim`): SWIM-подобно управление на членство
- **Distributed Transactions** (`core/disttxn.nim`): Two-phase commit
-
-## Ключови Дизайн Решения
+## Ключови Дизайнерски Решения

 1. **Чист Nim**: Без Cython, Python или Rust зависимости
-2. **Обединено Съхранение**: Един двигател за KV, граф, вектор, FTS и колонно
-3. **Вграден Режим**: Работи като библиотека или сървър
-4. **Бинарен Протокол**: Ефективен wire протокол
+2. **Унифицирано Съхранение**: Един engine обработва KV, graph, vector, FTS и columnar
+3. **Embedded Режим**: Може да работи като библиотека или сървър
+4. **Бинарен Протокол**: Персонализиран ефективен wire протокол
 5. **MVCC**: Multi-version concurrency control
-6. **Schema-First**: Строго типизирана система с наследяване
-7. **Крос-Модал**: Един език за заявки през всички модели данни
-8. **Формално Верифициран**: Разпределените алгоритми са специфицирани в TLA+ и проверени с TLC
+6. **Schema-First**: Силно типизирана система от схеми с наследяване
+7. **Cross-Modal**: Един език за заявки за всички модели на данни
+8. **Формално Верифициран**: Основните разпределени алгоритми са специфицирани в TLA+ и проверени с TLC

 ## Статистика на Модулите

 | Категория | Модули | Редове Код | Предназначение |
 |-----------|--------|------------|----------------|
-| Core | 16 | ~4,200 | Сървър, протоколи, транзакции, разпределено |
+| Core | 16 | ~4,200 | Сървър, протоколи, транзакции, разпределени |
 | Storage | 7 | ~3,100 | LSM, B-Tree, WAL, bloom, compaction, mmap |
-| Query | 7 | ~2,800 | Lexer, parser, AST, IR, оптимизатор, codegen, executor |
+| Query | 7 | ~2,800 | Lexer, parser, AST, IR, optimizer, codegen, executor |
 | Vector | 3 | ~1,200 | HNSW, IVF-PQ, квантуване, SIMD |
-| Graph | 3 | ~1,000 | Списък със съседи, алгоритми, community detection |
-| FTS | 2 | ~900 | Инвертиран индекс, BM25, fuzzy, многоезичен |
+| Graph | 3 | ~1,000 | Adjacency list, алгоритми, community detection |
+| FTS | 2 | ~900 | Inverted index, BM25, fuzzy, многоезичност |
 | Protocol | 7 | ~2,400 | Wire, HTTP, WebSocket, pool, auth, rate limit, SSL |
 | Schema | 1 | ~600 | Типове, връзки, наследяване, миграции |
-| Client | 2 | ~800 | Nim binary client, file helpers |
-| CLI | 1 | ~400 | Интерактивна BaraQL конзола |
+| Client | 2 | ~800 | Nim бинарен клиент, файлови помощници |
+| CLI | 1 | ~400 | Интерактивна BaraQL обвивка |
 | **Общо** | **49** | **~14,100** | |
@@ -0,0 +1,198 @@
+# Backup и Възстановяване
+
+## Online Snapshots
+
+BaraDB поддържа online snapshots без спиране на сървъра. Snapshot-ът заснема консистентен изглед към момент във времето чрез MVCC.
+
+### Създаване на Snapshot
+
+```nim
+import barabadb/core/backup
+
+var bm = newBackupManager()
+bm.createSnapshot("/backup/baradb_2025-01-15")
+```
+
+### Чрез CLI
+
+```bash
+./build/baradadb --snapshot --output=/backup/snapshot.db
+```
+
+### Чрез HTTP API
+
+```bash
+curl -X POST http://localhost:9470/api/backup \
+  -H "Content-Type: application/json" \
+  -d '{"destination": "/backup/snapshot.db"}'
+```
+
+### Автоматизирани Backups
+
+Използвайте cron за планирани backups:
+
+```bash
+# Ежедневен snapshot в 2 сутринта
+0 2 * * * /usr/local/bin/baradadb --snapshot --output=/backup/baradb_$(date +\%Y\%m\%d).db
+
+# Запазване на последните 7 дни
+find /backup -name "baradb_*.db" -mtime +7 -delete
+```
+
+## Point-in-Time Recovery (PITR)
+
+BaraDB използва Write-Ahead Log (WAL) за възстановяване до момент във времето.
+
+### WAL Архивиране
+
+Включете непрекъснато WAL архивиране:
+
+```bash
+BARADB_WAL_ARCHIVE_DIR=/backup/wal \
+BARADB_WAL_ARCHIVE_INTERVAL_MS=60000 \
+./build/baradadb
+```
+
+### Възстановяване от Checkpoint + WAL
+
+```bash
+# Възстановяване от snapshot
+./build/baradadb --recover \
+  --checkpoint=/backup/snapshot.db \
+  --wal-dir=/backup/wal
+
+# Възстановяване до конкретен LSN
+./build/baradadb --recover \
+  --checkpoint=/backup/snapshot.db \
+  --wal-dir=/backup/wal \
+  --target-lsn=15420
+
+# Възстановяване до конкретно време
+./build/baradadb --recover \
+  --checkpoint=/backup/snapshot.db \
+  --wal-dir=/backup/wal \
+  --target-time="2025-01-15T10:30:00Z"
+```
+
+### Възстановяване чрез SQL
+
+Можете също да възстановявате директно чрез BaraQL:
+
+```sql
+RECOVER TO TIMESTAMP '2026-05-07T12:00:00';
+```
+
+### Инкрементални Backups
+
+Инкременталните backups копират само променени SSTables:
+
+```bash
+./build/baradadb --backup-incremental \
+  --last-backup=/backup/previous \
+  --output=/backup/incremental_$(date +%Y%m%d)
+```
+
+## Репликация като Backup
+
+За непрекъсната защита използвайте streaming репликация:
+
+### Primary
+
+```bash
+BARADB_REPLICATION_ENABLED=true \
+BARADB_REPLICATION_MODE=async \
+./build/baradadb
+```
+
+### Replica
+
+```bash
+BARADB_REPLICATION_ENABLED=true \
+BARADB_REPLICATION_PRIMARY=primary:9472 \
+./build/baradadb
+```
+
+## Disaster Recovery
+
+### Процедури за Възстановяване
+
+#### Сценарий 1: Повреда на Единичен Файл
+
+```bash
+# Идентифициране на повреден SSTable от логовете
+# Възстановяване на конкретен SSTable от backup
+cp /backup/sstables/000012.sst ./data/sstables/
+
+# Възстановяване на индекса
+./build/baradadb --rebuild-index
+```
+
+#### Сценарий 2: Пълна Загуба на Данни
+
+```bash
+# 1. Възстановяване на последния snapshot
+cp /backup/snapshot.db ./data/
+
+# 2. Преиграване на WAL
+./build/baradadb --recover --wal-dir=/backup/wal
+
+# 3. Проверка
+curl http://localhost:9470/health
+```
+
+#### Сценарий 3: Отказ на Възел в Клъстер
+
+```bash
+# За Raft клъстери, просто стартирайте нов възел
+BARADB_RAFT_NODE_ID=newnode \
+BARADB_RAFT_PEERS=node1:9001,node2:9001 \
+./build/baradadb
+
+# Новият възел ще навакса чрез Raft log репликация
+```
+
+## Верификация на Backup
+
+Винаги проверявайте backups:
+
+```bash
+# Възстановяване във временна директория
+./build/baradadb --recover \
+  --checkpoint=/backup/snapshot.db \
+  --data-dir=/tmp/verify_data
+
+# Проверка на консистентност
+curl http://localhost:9470/api/admin/check
+```
+
+## Изисквания за Съхранение
+
+| Тип Backup | Размер | Честота | Задържане |
+|------------|--------|---------|-----------|
+| Пълен snapshot | ~1× размер на данните | Ежедневно | 7 дни |
+| Инкрементален | ~0.1× размер на данните | На всеки час | 24 часа |
+| WAL архив | ~0.05× размер на данните / ден | Непрекъснато | 30 дни |
+
+## Най-добри Практики
+
+1. **Тествайте възстановяването редовно** — Backup, който не може да бъде възстановен, е безполезен
+2. **Съхранявайте backups извън локацията** — Използвайте S3, GCS или Azure Blob
+3. **Криптирайте backups** — Използвайте `gpg` или криптиране на ниво ОС
+4. **Мониторирайте backup задачите** — Алармирайте при неуспешни backups
+5. **Документирайте RTO/RPO** — Знайте целите си за време и точка на възстановяване
+
+### Качване на Backup в Облак
+
+```bash
+# Качване в S3
+aws s3 cp /backup/snapshot.db s3://my-bucket/baradb/
+
+# Качване в GCS
+gsutil cp /backup/snapshot.db gs://my-bucket/baradb/
+
+# Качване в Azure
+az storage blob upload \
+  --container-name backups \
+  --file /backup/snapshot.db \
+  --name baradb/snapshot.db
+```
@@ -2,39 +2,160 @@

 BaraQL е SQL-съвместим език за заявки с разширения за графи, вектори и документи.

+## Типове Данни
+
+| Тип | Описание | Пример |
+|------|----------|--------|
+| `null` | Null стойност | `null` |
+| `bool` | Булев | `true`, `false` |
+| `int8` | 8-битов signed integer | `127` |
+| `int16` | 16-битов signed integer | `32767` |
+| `int32` | 32-битов signed integer | `2147483647` |
+| `int64` | 64-битов signed integer | `9223372036854775807` |
+| `float32` | 32-битов float | `3.14` |
+| `float64` | 64-битов float | `3.14159265359` |
+| `str` | UTF-8 низ | `'hello'` |
+| `bytes` | Сурови байтове | `0xDEADBEEF` |
+| `array<T>` | Хомогенен масив | `[1, 2, 3]` |
+| `vector` | Float32 вектор | `[0.1, 0.2, 0.3]` |
+| `vector(n)` | Float32 вектор с фиксирана размерност (SQL) | `VECTOR(768)` |
+| `object` | Ключ-стойност обект | `{"a": 1}` |
+| `datetime` | ISO 8601 времеви печат | `'2025-01-15T10:30:00Z'` |
+| `uuid` | UUID v4 | `'550e8400-e29b-41d4-a716-446655440000'` |
+| `json` | JSON документ | `{"key": "value"}` |
+| `jsonb` | Бинарен JSON (валидиран) | `{"key": "value"}` |
+
 ## Основни Заявки

 ### SELECT

 ```sql
-SELECT name, age FROM users WHERE age > 18 ORDER BY name LIMIT 10;
+-- Всички колони
+SELECT * FROM users;
+
+-- Конкретни колони
+SELECT name, age FROM users;
+
+-- Псевдоними
+SELECT name AS full_name, age AS years FROM users;
+
+-- DISTINCT
+SELECT DISTINCT department FROM employees;
+
+-- LIMIT и OFFSET
+SELECT * FROM users LIMIT 10 OFFSET 20;
+```
+
+### WHERE
+
+```sql
+-- Оператори за сравнение
+SELECT * FROM users WHERE age > 18;
+SELECT * FROM users WHERE age >= 18 AND age <= 65;
+SELECT * FROM users WHERE name = 'Alice';
+SELECT * FROM users WHERE name != 'Bob';
+
+-- Диапазон
+SELECT * FROM users WHERE age BETWEEN 18 AND 65;
+
+-- Принадлежност към множество
+SELECT * FROM users WHERE department IN ('Engineering', 'Sales');
+
+-- Търсене по шаблон
+SELECT * FROM users WHERE name LIKE 'A%';
+SELECT * FROM users WHERE name ILIKE 'alice';  -- Case-insensitive
+
+-- NULL проверки
+SELECT * FROM users WHERE email IS NOT NULL;
+
+-- Логически оператори
+SELECT * FROM users WHERE age > 18 AND (department = 'Engineering' OR department = 'Sales');
+```
+
+### ORDER BY
+
+```sql
+-- Възходящ (по подразбиране)
+SELECT * FROM users ORDER BY age;
+
+-- Низходящ
+SELECT * FROM users ORDER BY age DESC;
+
+-- Множество колони
+SELECT * FROM users ORDER BY department ASC, age DESC;
 ```

 ### INSERT

 ```sql
+-- Един ред
 INSERT users { name := 'Alice', age := 30 };
+
+-- С явен тип
+INSERT User { name := 'Alice', age := 30 };
+
+-- Множество редове
+INSERT users {
+  { name := 'Alice', age := 30 },
+  { name := 'Bob', age := 25 }
+};
 ```

 ### UPDATE

 ```sql
+-- Обнови всички редове
+UPDATE users SET status = 'active';
+
+-- Условно обновяване
 UPDATE users SET age = 31 WHERE name = 'Alice';
+
+-- Обновяване на няколко колони
+UPDATE users SET age = 32, status = 'premium' WHERE name = 'Alice';
 ```

 ### DELETE

 ```sql
-DELETE FROM users WHERE name = 'Bob';
+-- Изтрий всички редове
+DELETE FROM users;
+
+-- Условно изтриване
+DELETE FROM users WHERE age < 18;
 ```

 ## Агрегати и Групиране

+### Агрегатни Функции
+
+| Функция | Описание |
+|----------|-----------|
+| `count(*)` | Брой на всички редове |
+| `count(column)` | Брой на не-NULL стойности |
+| `sum(column)` | Сума на стойностите |
+| `avg(column)` | Средно аритметично |
+| `min(column)` | Минимална стойност |
+| `max(column)` | Максимална стойност |
+| `stddev(column)` | Стандартно отклонение |
+| `variance(column)` | Дисперсия |
+
+### GROUP BY
+
 ```sql
-SELECT department, count(*), avg(salary)
+SELECT department, count(*) as emp_count, avg(salary) as avg_salary
+FROM employees
+GROUP BY department;
+
+-- С HAVING
+SELECT department, count(*) as emp_count
 FROM employees
 GROUP BY department
 HAVING count(*) > 5;
+
+-- Множествено групиране
+SELECT department, role, count(*), avg(salary)
+FROM employees
+GROUP BY department, role;
 ```

 ## JOINs
@@ -49,15 +170,85 @@ INNER JOIN orders o ON u.id = o.user_id;
 SELECT u.name, o.total
 FROM users u
 LEFT JOIN orders o ON u.id = o.user_id;
+
+-- RIGHT JOIN
+SELECT u.name, o.total
+FROM users u
+RIGHT JOIN orders o ON u.id = o.user_id;
+
+-- FULL JOIN
+SELECT u.name, o.total
+FROM users u
+FULL JOIN orders o ON u.id = o.user_id;
+
+-- CROSS JOIN
+SELECT u.name, p.name
+FROM users u
+CROSS JOIN products p;
+
+-- Множество JOINs
+SELECT u.name, o.id, p.name
+FROM orders o
+JOIN users u ON o.user_id = u.id
+JOIN products p ON o.product_id = p.id;
+
+-- Self JOIN
+SELECT e.name, m.name as manager
+FROM employees e
+JOIN employees m ON e.manager_id = m.id;
 ```

 ## CTEs (Common Table Expressions)

 ```sql
+-- Единичен CTE
 WITH active_users AS (
  SELECT * FROM users WHERE active = true
 )
 SELECT * FROM active_users;
+
+-- Множество CTEs
+WITH
+  recent AS (
+    SELECT * FROM orders WHERE date > '2025-01-01'
+  ),
+  totals AS (
+    SELECT user_id, sum(amount) as total FROM recent GROUP BY user_id
+  )
+SELECT u.name, t.total
+FROM users u
+JOIN totals t ON u.id = t.user_id;
+
+-- Рекурсивен CTE
+WITH RECURSIVE subordinates AS (
+  SELECT id, name, manager_id FROM employees WHERE name = 'CEO'
+  UNION ALL
+  SELECT e.id, e.name, e.manager_id
+  FROM employees e
+  JOIN subordinates s ON e.manager_id = s.id
+)
+SELECT * FROM subordinates;
+```
+
+## Подзаявки
+
+```sql
+-- Подзаявка в SELECT
+SELECT name, (SELECT count(*) FROM orders WHERE user_id = u.id) as order_count
+FROM users u;
+
+-- Подзаявка в FROM
+SELECT * FROM (SELECT id, name FROM users WHERE active = true) AS active;
+
+-- Подзаявка в WHERE (IN)
+SELECT name FROM users WHERE id IN (SELECT user_id FROM orders);
+
+-- Подзаявка в WHERE (EXISTS)
+SELECT name FROM users WHERE EXISTS (SELECT 1 FROM orders WHERE orders.user_id = users.id);
+
+-- Корелирана подзаявка
+SELECT name FROM users u
+WHERE age > (SELECT avg(age) FROM users WHERE department = u.department);
 ```

 ## CASE Изрази
@@ -65,54 +256,114 @@ SELECT * FROM active_users;
 ```sql
 SELECT name,
  CASE
-    WHEN age < 18 THEN 'minor'
+    WHEN age < 13 THEN 'child'
+    WHEN age < 20 THEN 'teenager'
    WHEN age < 65 THEN 'adult'
    ELSE 'senior'
  END AS category
 FROM users;
+
+-- Прост CASE
+SELECT name,
+  CASE department
+    WHEN 'Engineering' THEN 'Tech'
+    WHEN 'Sales' THEN 'Revenue'
+    ELSE 'Other'
+  END AS division
+FROM employees;
 ```

-## Схема
+## Set Операции
+
+```sql
+-- UNION (различни)
+SELECT name FROM customers
+UNION
+SELECT name FROM suppliers;
+
+-- UNION ALL (с дубликати)
+SELECT name FROM customers
+UNION ALL
+SELECT name FROM suppliers;
+
+-- INTERSECT
+SELECT name FROM customers
+INTERSECT
+SELECT name FROM suppliers;
+
+-- EXCEPT
+SELECT name FROM customers
+EXCEPT
+SELECT name FROM suppliers;
+```
+
+## Дефиниране на Схема
+
+### CREATE TYPE

 ```sql
 CREATE TYPE Person {
  name: str,
  age: int32
 };
-```

-## Векторно Търсене
-
-```sql
-INSERT articles {
-  title := 'Nim Programming',
-  embedding := [0.1, 0.2, 0.3, ...]
+-- Със задължителни полета
+CREATE TYPE User {
+  email: str REQUIRED,
+  name: str,
+  age: int32,
+  created_at: datetime DEFAULT now()
 };

-SELECT title FROM articles
-ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, ...])
-LIMIT 5;
+-- С връзки
+CREATE TYPE Movie {
+  title: str,
+  year: int32,
+  director: Person
+};
+
+-- С изчислими свойства
+CREATE TYPE Employee {
+  name: str,
+  base_salary: float64,
+  bonus: float64,
+  total_compensation: float64 COMPUTED (base_salary + bonus)
+};
 ```

-## Графични Шаблони
+### Наследяване

 ```sql
-MATCH (p:Person)-[:KNOWS]->(friend:Person)
-WHERE p.name = 'Alice'
-RETURN friend.name;
+CREATE TYPE Animal {
+  name: str
+};
+
+CREATE TYPE Dog EXTENDING Animal {
+  breed: str
+};
+
+CREATE TYPE Cat EXTENDING Animal {
+  indoor: bool
+};
 ```

-## Пълнотекстово Търсене
+### Индекси

 ```sql
-- Създаване на FTS индекс
-CREATE INDEX idx_fts ON articles(body) USING FTS;
-
-- Търсене с BM25 ранжиране
-SELECT * FROM articles WHERE body @@ 'database programming';
+CREATE INDEX idx_users_name ON users(name);
+CREATE UNIQUE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_users_age ON users(age) USING btree;
+CREATE INDEX idx_vectors ON items(embedding) USING hnsw;
 ```

-## JSON Оператори
+### DROP
+
+```sql
+DROP TYPE User;
+DROP INDEX idx_users_name;
+```
+
+### JSON Оператори за Път

 ```sql
 -- Извличане на JSON поле като JSON
@@ -122,16 +373,292 @@ SELECT data->'name' FROM users;
 SELECT data->>'name' FROM users;
 ```

-## Set Операции
+### Пълнотекстово Търсене (SQL)

 ```sql
-SELECT name FROM customers
-UNION ALL
-SELECT name FROM suppliers;
+-- Създаване на FTS индекс с BM25
+CREATE INDEX idx_fts ON articles(body) USING FTS;
+
+-- Търсене с BM25 ранжиране
+SELECT * FROM articles WHERE body @@ 'machine learning';
 ```

-## Възстановяване до Момент във Времето
+### Възстановяване до Момент във Времето

 ```sql
 RECOVER TO TIMESTAMP '2026-05-07T12:00:00';
-```
+```
+
+## Векторно Търсене (SQL)
+
+### Създаване на Векторни Колони
+
+```sql
+CREATE TABLE items (
+  id INT PRIMARY KEY,
+  embedding VECTOR(768)
+);
+```
+
+### Вмъкване на Вектори
+
+```sql
+INSERT INTO items (id, embedding) VALUES (1, '[0.1, 0.2, 0.3, 0.4]');
+```
+
+### Функции за Разстояние
+
+```sql
+-- Косинусово разстояние (0 = идентични, 2 = противоположни)
+SELECT id, cosine_distance(embedding, '[0.1, 0.2, 0.3, 0.4]') AS dist
+FROM items;
+
+-- Евклидово / L2 разстояние
+SELECT id, euclidean_distance(embedding, '[0.1, 0.2, 0.3, 0.4]') AS dist
+FROM items;
+
+-- L2 разстояние с <-> оператор
+SELECT id, embedding <-> '[0.1, 0.2, 0.3, 0.4]' AS dist
+FROM items;
+
+-- Скаларно произведение (отрицателно dot product)
+SELECT id, inner_product(embedding, '[0.1, 0.2, 0.3, 0.4]') AS dist
+FROM items;
+
+-- Манхатън / L1 разстояние
+SELECT id, l1_distance(embedding, '[0.1, 0.2, 0.3, 0.4]') AS dist
+FROM items;
+```
+
+### Търсене на Най-близки Съседи
+
+```sql
+-- Топ-10 най-близки съседи по косинусово разстояние
+SELECT id FROM items
+ORDER BY cosine_distance(embedding, '[0.1, 0.2, 0.3, 0.4]') ASC
+LIMIT 10;
+
+-- Топ-5 най-близки съседи по евклидово разстояние
+SELECT id FROM items
+ORDER BY embedding <-> '[0.1, 0.2, 0.3, 0.4]'
+LIMIT 5;
+
+-- С филтър по метаданни
+SELECT id FROM items
+WHERE category = 'tech'
+ORDER BY cosine_distance(embedding, '[0.1, 0.2, 0.3, 0.4]')
+LIMIT 5;
+```
+
+### Векторни Индекси
+
+```sql
+-- Създаване на HNSW индекс за приблизително търсене на най-близки съседи
+CREATE INDEX idx_items_vec ON items(embedding) USING hnsw;
+
+-- Поддържани индекс методи: hnsw, ivfpq
+```
+
+## Графични Шаблони
+
+```sql
+-- Намиране на приятели на Alice
+MATCH (p:Person)-[:KNOWS]->(friend:Person)
+WHERE p.name = 'Alice'
+RETURN friend.name;
+
+-- Намиране на най-кратък път
+MATCH path = shortestPath((a:Person)-[:KNOWS*1..5]->(b:Person))
+WHERE a.name = 'Alice' AND b.name = 'Bob'
+RETURN path;
+
+-- Намиране на всички връзки
+MATCH (p:Person)-[r]->(other)
+WHERE p.name = 'Alice'
+RETURN type(r), other.name;
+
+-- Множество преходи
+MATCH (a:Person)-[:KNOWS]->(b:Person)-[:KNOWS]->(c:Person)
+WHERE a.name = 'Alice'
+RETURN c.name;
+
+-- С агрегати
+MATCH (p:Person)-[:KNOWS]->(friend)
+RETURN p.name, count(friend) as friend_count
+ORDER BY friend_count DESC;
+```
+
+## Пълнотекстово Търсене
+
+```sql
+-- Основно търсене
+SELECT * FROM articles
+WHERE MATCH(title, body) AGAINST('database programming');
+
+-- С релевантност
+SELECT title, relevance()
+FROM articles
+WHERE MATCH(title, body) AGAINST('Nim language')
+ORDER BY relevance() DESC;
+
+-- Булев режим
+SELECT * FROM articles
+WHERE MATCH(title, body) AGAINST('+Nim -Python' IN BOOLEAN MODE);
+
+-- Fuzzy търсене
+SELECT * FROM articles
+WHERE MATCH(title) AGAINST('programing' WITH FUZZINESS 2);
+```
+
+## Транзакции
+
+```sql
+BEGIN;
+INSERT users { name := 'Alice', age := 30 };
+INSERT orders { user_id := last_insert_id(), total := 100 };
+COMMIT;
+
+-- С savepoint
+BEGIN;
+INSERT users { name := 'Bob', age := 25 };
+SAVEPOINT sp1;
+INSERT orders { user_id := last_insert_id(), total := 200 };
+-- Грешка, връщане до savepoint
+ROLLBACK TO sp1;
+COMMIT;
+```
+
+## Потребителски Функции (UDF)
+
+```sql
+-- Регистриране на UDF
+CREATE FUNCTION greet(name str) -> str {
+  RETURN 'Hello, ' || name || '!';
+};
+
+-- Използване
+SELECT greet(name) FROM users;
+
+-- Вградени функции
+SELECT abs(-5), sqrt(16), lower('HELLO'), len('test');
+```
+
+## Подсказки за Заявки (Query Hints)
+
+```sql
+-- Форсиране на индекс
+SELECT /*+ USE_INDEX(idx_users_age) */ * FROM users WHERE age > 18;
+
+-- Форсиране на приблизително векторно търсене
+SELECT /*+ APPROXIMATE */ * FROM vectors
+ORDER BY cosine_distance(embedding, [...])
+LIMIT 10;
+
+-- Паралелно изпълнение
+SELECT /*+ PARALLEL(4) */ * FROM large_table;
+```
+
+## Window Функции
+
+```sql
+-- Функции за ранжиране
+SELECT
+  name,
+  department,
+  ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) AS rn,
+  RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS r,
+  DENSE_RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS dr
+FROM employees;
+
+-- Стойностни функции
+SELECT
+  name,
+  salary,
+  LAG(salary, 1, 0) OVER (ORDER BY salary) AS prev_salary,
+  LEAD(salary, 1, 0) OVER (ORDER BY salary) AS next_salary,
+  FIRST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS cheapest,
+  LAST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS most_expensive
+FROM employees;
+
+-- Функции за разпределение
+SELECT name, NTILE(4) OVER (ORDER BY salary) AS quartile FROM employees;
+```
+
+### Рамкови Спецификации
+
+```sql
+-- ROWS рамка
+SUM(salary) OVER (
+  PARTITION BY department
+  ORDER BY hire_date
+  ROWS BETWEEN 1 PRECEDING AND CURRENT ROW
+)
+
+-- RANGE рамка
+SUM(salary) OVER (
+  PARTITION BY department
+  ORDER BY hire_date
+  RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
+)
+```
+
+## Multi-Tenant ERP
+
+BaraDB поддържа множество компании (тенанти) в една инстанция чрез **Row-Level Security (RLS)** и **сесийни променливи**.
+
+### Сесийни Променливи
+
+```sql
+SET app.tenant_id = 'company-123';
+SELECT current_setting('app.tenant_id') AS tenant;
+```
+
+### Текущ Потребител / Роля
+
+```sql
+SELECT current_user AS me, current_role AS my_role;
+```
+
+### RLS Изолация на Тенанти
+
+```sql
+-- Включване на RLS за таблица
+ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;
+
+-- Създаване на политика за филтриране по тенант
+CREATE POLICY tenant_isolation ON invoices
+  FOR SELECT USING (tenant_id = current_setting('app.tenant_id'));
+
+-- Всяка сесия вижда само своите данни
+SET app.tenant_id = 'company-a';
+SELECT * FROM invoices;  -- само редове на company-a
+```
+
+### Защо Multi-Tenant?
+
+- **Една инстанция, много тенанти** — няма нужда от 100 отделни бази данни
+- **JSONB документи** — гъвкаво съхранение без схема, лесно добавяне на полета за всеки тенант
+- **RLS гарантира изолация** — базата данни налага границите между тенанти, не само приложението
+
+## Поддържани Ключови Думи
+
+| Категория | Ключови думи |
+|-----------|-------------|
+| DQL | SELECT, FROM, WHERE, ORDER BY, GROUP BY, HAVING, LIMIT, OFFSET, DISTINCT |
+| DML | INSERT, UPDATE, DELETE, SET, VALUES |
+| DDL | CREATE TYPE, DROP TYPE, CREATE INDEX, DROP INDEX, ALTER TYPE |
+| Join | INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN, ON |
+| Set | UNION, UNION ALL, INTERSECT, EXCEPT |
+| CTEs | WITH, RECURSIVE, AS |
+| Case | CASE, WHEN, THEN, ELSE, END |
+| Транзакции | BEGIN, COMMIT, ROLLBACK, SAVEPOINT |
+| Графи | MATCH, RETURN, WHERE, shortestPath, type |
+| FTS | MATCH, AGAINST, relevance, IN BOOLEAN MODE, WITH FUZZINESS |
+| Вектори | cosine_distance, euclidean_distance, inner_product, l1_distance, l2_distance, <-> |
+| JSON | ->, ->> |
+| FTS | @@ (BM25 съвпадение) |
+| Recovery | RECOVER TO TIMESTAMP |
+| Функции | count, sum, avg, min, max, stddev, variance, abs, sqrt, lower, upper, len, trim, substr, now, last_insert_id, current_setting |
+| Сесийни | SET, current_setting, current_user, current_role |
+| Window | OVER, PARTITION BY, ROWS, RANGE, UNBOUNDED PRECEDING, CURRENT ROW, FOLLOWING |
+| Window Функции | ROW_NUMBER, RANK, DENSE_RANK, LEAD, LAG, FIRST_VALUE, LAST_VALUE, NTILE |
@@ -0,0 +1,223 @@
+# Списък с Промени (Changelog)
+
+Всички забележителни промени в BaraDB са документирани в този файл.
+
+## [Unreleased] — SQL:2023 Стабилизация
+
+### Поправки
+
+- **GROUPING SETS изпълнение** — `lowerSelect` вече създава `irpkGroupBy` когато `selGroupingSetsKind != gskNone`, дори ако `selGroupBy` е празен. Преди това заявки като `GROUP BY GROUPING SETS ((dept), ())` напълно заобикаляха grouping executor-a.
+- **FTS CREATE INDEX docId несъответствие** — `CREATE INDEX ... USING FTS` вече изчислява `docId` като хеш на `tableName.$key`, консистентно с DML операциите (`INSERT`/`UPDATE`/`DELETE`). Преди това създаването на индекс използваше последователни ID-та (0, 1, 2...), което причиняваше `@@` заявките никога да не намират индексирани документи.
+- **Тестова изолация (всички сюити)** — Всички извиквания на `newLSMTree("")` са заменени с уникални временни директории за всеки сюит. Елиминира проблеми с натрупване на WAL и нестабилни тестове от споделено състояние между тестове.
+- **Window frame parser** — `parseFrameBoundary` вече не консумира `tkRow` след `tkCurrent` неправилно (използваше `tkRows`). Също така е поправен конфликт на ключовата дума `tkRow` с парсването на `ENABLE ROW LEVEL SECURITY`.
+- **ORDER BY + SELECT проекция** — `lowerSelect` вече поставя `irpkSort` преди `irpkProject`, което позволява `ORDER BY` по колони, които не присъстват в `SELECT` списъка.
+- **UNPIVOT изпълнение** — Проверено и поправено липсващо тестово покритие за UNPIVOT трансформация.
+
+### Добавки
+
+- **JSON оператори** — `@>` (съдържа), `<@` (съдържа се в), `?` (има ключ), `?|` (има някой от), `?&` (има всички) вече се поддържат в lexer, parser и executor.
+- **Window frame изпълнение** — `ROWS BETWEEN X PRECEDING AND Y FOLLOWING` / `CURRENT ROW` граници на рамката вече се спазват от `FIRST_VALUE` и `LAST_VALUE`.
+- **Сесийни променливи** — `SET var_name = value` и `current_setting('var_name')` за ключ/стойност съхранение на ниво връзка.
+- **Текущ потребител/роля** — `current_user` и `current_role` SQL ключови думи връщат потребителя и ролята на автентикираната сесия.
+- **Auth-executor мост** — Сървърът и HTTP сървърът вече попълват `ExecutionContext.currentUser` и `ExecutionContext.currentRole` след JWT/SCRAM автентикация.
+- **Multi-tenant RLS** — Row-Level Security политиките вече могат да реферират `current_user`, `current_role` и `current_setting('app.tenant_id')` за изолация на данни по тенант.
+
+## [1.1.0] — 2026-05-13
+
+### Добавки
+
+- **Client SDKs v1.1.0** — Пълнофункционални клиенти за всички езици:
+  - JavaScript: TypeScript дефиниции, package.json, примери, unit и integration тестове
+  - Python: Преструктуриран като пакет (`baradb/` с `__init__.py` и `core.py`), pyproject.toml, примери, тестове (query builder, wire protocol, integration)
+  - Nim: Примери, integration тестове, README
+  - Rust: Примери, integration тестове, подобрен Cargo.toml
+- **SCRAM-SHA-256 Автентикация** — RFC 7677 съвместима автентикация с PBKDF2 + HMAC + SHA-256 + nonce/salt генериране
+- **HTTP SCRAM Endpoints** — `/auth/scram/start` + `/auth/scram/finish` в HTTP сървъра
+- **Docker Compose Тестова Конфигурация** — `docker-compose.test.yml` за тестови среди
+- **CI/CD Clients Pipeline** — `.github/workflows/clients-ci.yml` за автоматизирано тестване на клиенти
+
+### Поправки
+
+- **Query Executor** — Унарен минус (`irNeg`) вече работи коректно в SELECT и WHERE клаузи
+- **Distributed Transactions** — Rollback след commit опит вече не нарушава атомарността
+- **Sharding** — Протокол за миграция на данни с TCP + `scanAll` на LSM
+- **Raft** — Поправено изчисление на мнозинство за четен брой нодове
+- **MVCC** — Прекъснатите транзакции вече не стават видими
+- **LSM-Tree** — Поправена загуба на данни при презаписване на immutable memtable; поправено сортиране на SSTable търсене
+- **Auth** — JWT подписът е променен на HMAC-SHA256 (вече не е тривиално forgeable); валидация на токен изтичане (`exp`/`nbf`/`iat`); сравнението на подписи вече е constant-time
+- **Recovery** — `summary()` вече не мутира базата данни
+- **Wire Protocol** — 64MB лимит + bounds проверки + max дълбочина за предотвратяване на OOM/DoS
+- **SQL Injection** — `exprToSql` вече escape-ва единични кавички
+- **ReDoS** — `irLike`/`irILike` вече escape-ват regex метасимволи
+- **Graph** — `addEdge` вече проверява съществуването на възел
+- **Vector** — Валидация на несъответствие на размерности + HNSW заключване
+- **FTS** — UTF-8 токенизацията вече използва runes вместо байтове
+- **Build** — `nim.cfg` добавя `-d:ssl`, така че `nimble build` работи без флагове; `--threads:on` добавен към всички CI команди
+
+### Промени
+
+- **Версията е вдигната до 1.1.0** във всички компоненти (сървър, Docker изображения, клиенти, CLI)
+- **README** — Версионният badge е обновен; всички feature таблици вече реферират v1.1.0
+- **TLA+ Формална Верификация** — Добавени `crossmodal.tla`, `backup.tla`, `recovery.tla`; symmetry reduction във всички 9 спецификации
+- **Чист build** — 0 компилаторни предупреждения на Nim 2.2.10
+
+## [0.1.0] — 2025-01-15
+
+### Добавки
+
+- **Ядро за Съхранение**
+  - LSM-Tree с MemTable, WAL, SSTables и size-tiered compaction
+  - B-Tree подреден индекс с range сканиране и MVCC copy-on-write
+  - Bloom филтри за ефективно пропускане на SSTable
+  - Memory-mapped I/O за SSTable четене
+  - LRU page cache с проследяване на hit rate
+
+- **Query Engine (BaraQL)**
+  - SQL-съвместим lexer с 80+ типа токени
+  - Recursive descent parser генериращ AST с 25+ вида възли
+  - Intermediate representation (IR) за планове за изпълнение
+  - Code generator превеждащ IR към storage операции
+  - Adaptive query optimizer с cross-modal планиране
+  - Query executor с паралелизация
+
+- **BaraQL Езикови Възможности**
+  - SELECT, INSERT, UPDATE, DELETE
+  - WHERE, ORDER BY, LIMIT, OFFSET
+  - GROUP BY, HAVING, агрегатни функции (count, sum, avg, min, max)
+  - INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN
+  - CTEs (Common Table Expressions) с WITH
+  - Подзаявки (EXISTS, IN, корелирани)
+  - CASE изрази
+  - UNION, INTERSECT, EXCEPT
+  - Дефиниране на схема: CREATE TYPE, DROP TYPE
+
+- **Vector Engine**
+  - HNSW индекс за приблизително търсене на най-близки съседи
+  - IVF-PQ индекс за мащабно векторно търсене
+  - SIMD-оптимизирани функции за разстояние (cosine, L2, dot product, Manhattan)
+  - Квантуване: scalar 8-bit/4-bit, product quantization, binary
+  - Филтриране по метаданни при векторно търсене
+
+- **Graph Engine**
+  - Adjacency list съхранение за насочени графи с тегла
+  - BFS и DFS обхождане
+  - Dijkstra най-кратък път
+  - PageRank важност на възли
+  - Louvain community detection
+  - Subgraph pattern matching
+  - Cypher-подобен graph query parser
+
+- **Full-Text Search**
+  - Inverted index с term-document mapping
+  - BM25 алгоритъм за ранжиране
+  - TF-IDF оценяване
+  - Fuzzy търсене с Levenshtein разстояние
+  - Wildcard/regex търсене
+  - Многоезични токенизатори (английски, български, немски, френски, руски)
+
+- **Columnar Storage**
+  - Колонково съхранение за аналитични заявки
+  - RLE (Run-Length Encoding) компресия
+  - Dictionary encoding за колони с ниска кардиналност
+  - SIMD-ускорени агрегати
+
+- **Транзакции**
+  - MVCC (Multi-Version Concurrency Control) със snapshot изолация
+  - Deadlock детекция чрез wait-for граф
+  - Write-ahead log за устойчивост
+  - Savepoints и частичен rollback
+
+- **Протоколен Слой**
+  - Бинарен wire протокол с 16 типа съобщения
+  - HTTP/REST JSON API
+  - WebSocket стрийминг
+  - Connection pooling
+  - JWT-базирана автентикация
+  - Token-bucket rate limiting
+  - TLS/SSL с автоматично генерирани сертификати
+
+- **Система за Схеми**
+  - Силна типова система с 17 нативни типа
+  - Наследяване на типове с multi-base поддръжка
+  - Property links между типове
+  - Schema diffing и миграции
+  - Изчислими свойства
+
+- **Разпределени Системи**
+  - Raft консенсус (leader election, log replication)
+  - Hash, range и consistent-hash шардиране
+  - Sync/async/semi-sync репликация
+  - Gossip протокол за управление на членство
+  - Two-phase commit за разпределени транзакции
+
+- **Cross-Modal Заявки**
+  - Унифициран език за заявки през всички storage двигатели
+  - Cross-engine predicate pushdown
+  - Оптимизирани планове за изпълнение за multi-modal заявки
+
+- **Backup & Recovery**
+  - Online snapshots без прекъсване
+  - Point-in-time recovery чрез WAL replay
+  - Инкрементални backups
+
+- **Client SDKs**
+  - JavaScript/TypeScript клиент с бинарен протокол
+  - Python клиент със sync и async API
+  - Nim embedded режим и клиентска библиотека
+  - Rust клиент (async)
+
+- **Операции**
+  - Интерактивен CLI shell (BaraQL REPL)
+  - Структурирано логване (JSON и текстови формати)
+  - Prometheus-съвместим metrics endpoint
+  - Health и readiness проби
+  - CPU/memory profiling endpoints
+
+- **Docker Поддръжка**
+  - Multi-stage Dockerfile (Alpine Linux)
+  - Docker Compose конфигурация
+  - Health checks
+
+### Производителност
+
+- LSM-Tree: 580K записа/s, 720K четения/s
+- B-Tree: 1.2M вмъквания/s, 1.5M търсения/s
+- Vector SIMD: 850K косинусови разстояния/s (dim=768)
+- FTS: 320K документи/s индексиране, 28K заявки/s BM25
+- Graph: 2.5M възела/s вмъкване, 12K BFS обхождания/s
+- Бинарен протокол: 380K заявки/s (100 конкурентни връзки)
+
+### Тестове
+
+- 262 теста в 56 тестови сюита
+- 100% успеваемост
+
+## [Unreleased]
+
+### Добавки
+
+- **Vector SQL Integration** — Пълна поддръжка на векторно търсене на SQL ниво:
+  - `VECTOR(n)` тип колона в `CREATE TABLE` с валидация на размерност
+  - `CREATE INDEX ... USING hnsw` / `USING ivfpq` за приблизителни nearest neighbor индекси
+  - SQL функции за разстояние: `cosine_distance()`, `euclidean_distance()`, `inner_product()`, `l1_distance()`, `l2_distance()`
+  - `<->` nearest-neighbor оператор (евклидово разстояние)
+  - `ORDER BY` поддръжка за изрази с векторно разстояние, включително колони извън `SELECT`
+  - Автоматична поддръжка на HNSW индекс при `INSERT` и `UPDATE`
+- **Advanced SQL Engine** — Window функции, MERGE/UPSERT, LATERAL JOIN, PIVOT/UNPIVOT, SQL/PGQ Property Graph, Разширени агрегати (ARRAY_AGG, STRING_AGG, FILTER, GROUPING SETS/ROLLUP/CUBE)
+- **JavaScript Client — TCP Request Queue** — Вътрешна `_requestQueue` + `_requestLock` за безопасни конкурентни заявки. Множество паралелни извиквания на `query()` / `execute()` / `ping()` вече не размесват бинарни frame-ове по връзката.
+
+### Поправки
+
+- **Query Executor — Ескейпване на Стойности** — `execInsert` вече правилно ескейпва запетаи и знаци за равенство в стойностите на колоните, поправяйки корупция на съхранението за векторни литерали като `[1.0, 2.0, 3.0]`
+- **Query Planner — ORDER BY Проекция** — `irpkSort` вече се поставя преди `irpkProject` в IR плана, позволявайки на `ORDER BY` да реферира колони, които не са селектирани
+- **Wire Protocol — Big-Endian Float Сериализация** — `FLOAT32`/`FLOAT64` и float стойностите във вектори вече се сериализират в big-endian byte order, съвпадайки с `readFloatBE()` / `readDoubleBE()` на клиента и осигурявайки междуплатформена числова точност.
+- **Gossip Protocol — Async UDP Socket** — Заменен синхронният `newSocket` + блокиращ `recvFrom` с `newAsyncSocket` + `await recvFrom`, предотвратявайки замръзване на async event loop-а до пристигане на UDP пакет.
+
+### Планирани
+
+- Query plan caching
+- Materialized views
+- Геопространствен индекс
+- Time-series оптимизации
+- CDC (Change Data Capture) стрийминг
+- Федеративни заявки между BaraDB инстанции
@@ -0,0 +1,285 @@
+# Client SDKs
+
+BaraDB предоставя официални клиентски библиотеки за JavaScript/TypeScript, Python, Nim и Rust.
+
+## JavaScript / TypeScript
+
+### Инсталация
+
+```bash
+npm install baradb
+# или
+yarn add baradb
+```
+
+### Основна Употреба
+
+```typescript
+import { Client } from 'baradb';
+
+const client = new Client('localhost', 9472);
+await client.connect();
+
+// Проста заявка
+const result = await client.query('SELECT name, age FROM users WHERE age > 18');
+console.log(result.rows);
+
+// Параметризирана заявка
+const result2 = await client.query(
+  'SELECT * FROM users WHERE name = ?',
+  ['Alice']
+);
+
+// Batch вмъкване
+await client.batch([
+  "INSERT users { name := 'Alice', age := 30 }",
+  "INSERT users { name := 'Bob', age := 25 }",
+]);
+
+// Транзакции
+await client.begin();
+await client.query("INSERT orders { total := 100 }");
+await client.query("UPDATE users SET balance = balance - 100 WHERE name = 'Alice'");
+await client.commit();
+
+await client.close();
+```
+
+### Конкурентни Заявки
+
+JavaScript клиентът автоматично сериализира конкурентни заявки през една TCP връзка чрез вътрешна опашка. Можете безопасно да изпращате множество паралелни операции — техните бинарни frame-ове няма да се размесят:
+
+```typescript
+const [users, orders, stats] = await Promise.all([
+  client.query('SELECT * FROM users'),
+  client.query('SELECT * FROM orders'),
+  client.query('SELECT count(*) FROM visits')
+]);
+```
+
+### WebSocket Стрийминг
+
+```typescript
+import { WebSocketClient } from 'baradb/ws';
+
+const ws = new WebSocketClient('ws://localhost:9471');
+ws.onMessage = (data) => console.log(data);
+await ws.connect();
+await ws.send('SUBSCRIBE updates');
+```
+
+## Python
+
+### Инсталация
+
+```bash
+pip install baradb
+```
+
+### Основна Употреба
+
+```python
+from baradb import Client
+
+client = Client("localhost", 9472)
+client.connect()
+
+# Проста заявка
+result = client.query("SELECT name, age FROM users WHERE age > 18")
+for row in result:
+    print(row["name"], row["age"])
+
+# Параметризирана заявка
+result = client.query(
+    "SELECT * FROM users WHERE name = ?",
+    ["Alice"]
+)
+
+# Batch операции
+client.batch([
+    "INSERT users { name := 'Alice', age := 30 }",
+    "INSERT users { name := 'Bob', age := 25 }",
+])
+
+# Context manager (автоматично затваряне)
+with Client("localhost", 9472) as c:
+    result = c.query("SELECT count(*) FROM users")
+    print(result[0]["count"])
+```
+
+### Async Клиент
+
+```python
+import asyncio
+from baradb import AsyncClient
+
+async def main():
+    client = AsyncClient("localhost", 9472)
+    await client.connect()
+    result = await client.query("SELECT * FROM users")
+    print(result.rows)
+    await client.close()
+
+asyncio.run(main())
+```
+
+## Nim (Вграден Режим)
+
+### Добавяне на Зависимост
+
+```nim
+# Във вашия .nimble файл
+requires "barabadb >= 1.1.0"
+```
+
+### Вградена Употреба
+
+```nim
+import barabadb/storage/lsm
+import barabadb/storage/btree
+import barabadb/vector/engine
+import barabadb/graph/engine
+
+# Key-Value store
+var db = newLSMTree("./data")
+db.put("user:1", cast[seq[byte]]("Alice"))
+let (found, value) = db.get("user:1")
+db.close()
+
+# B-Tree индекс
+var btree = newBTreeIndex[string, int]()
+btree.insert("Alice", 30)
+let ages = btree.get("Alice")
+
+# Векторно търсене
+var idx = newHNSWIndex(dimensions = 128)
+idx.insert(1, @[0.1'f32, 0.2, 0.3], {"category": "A"}.toTable)
+let results = idx.search(@[0.1'f32, 0.2, 0.3], k = 10)
+
+# Графи
+var g = newGraph()
+let alice = g.addNode("Person", {"name": "Alice"}.toTable)
+let bob = g.addNode("Person", {"name": "Bob"}.toTable)
+discard g.addEdge(alice, bob, "knows")
+let path = g.shortestPath(alice, bob)
+```
+
+### Клиентска Библиотека
+
+```nim
+import barabadb/client/client
+
+var c = newBaraClient("localhost", 9472)
+c.connect()
+let result = c.query("SELECT name FROM users")
+for row in result.rows:
+  echo row["name"]
+c.close()
+```
+
+## Rust
+
+### Добавяне на Зависимост
+
+```toml
+[dependencies]
+baradb = "0.1"
+tokio = { version = "1", features = ["full"] }
+```
+
+### Основна Употреба
+
+```rust
+use baradb::Client;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut client = Client::connect("localhost:9472").await?;
+
+    let result = client
+        .query("SELECT name, age FROM users WHERE age > 18")
+        .await?;
+
+    for row in result.rows {
+        println!("{} is {} years old", row["name"], row["age"]);
+    }
+
+    client.close().await?;
+    Ok(())
+}
+```
+
+## HTTP/REST (Езиково Независим)
+
+Всички езици могат да използват HTTP/REST API директно:
+
+```bash
+# Заявка
+curl -X POST http://localhost:9470/api/query \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"query": "SELECT * FROM users WHERE age > 18"}'
+
+# Вмъкване
+curl -X POST http://localhost:9470/api/query \
+  -H "Content-Type: application/json" \
+  -d '{"query": "INSERT users { name := \"Alice\", age := 30 }"}'
+
+# Схема
+curl http://localhost:9470/api/schema
+
+# Health
+curl http://localhost:9470/health
+
+# Метрики
+curl http://localhost:9470/metrics
+```
+
+## Connection Pooling
+
+Всички официални клиенти поддържат connection pooling:
+
+### JavaScript
+
+```typescript
+import { Pool } from 'baradb';
+
+const pool = new Pool({
+  host: 'localhost',
+  port: 9472,
+  min: 5,
+  max: 50,
+  idleTimeout: 30000,
+});
+
+const client = await pool.acquire();
+try {
+  const result = await client.query('SELECT 1');
+} finally {
+  pool.release(client);
+}
+```
+
+### Python
+
+```python
+from baradb import Pool
+
+pool = Pool("localhost", 9472, min_size=5, max_size=50)
+with pool.connection() as conn:
+    result = conn.query("SELECT 1")
+```
+
+## Съответствие на Типове Данни
+
+| BaraDB Тип | JavaScript | Python | Nim | Rust |
+|------------|------------|--------|-----|------|
+| `null` | `null` | `None` | `nil` | `Option::None` |
+| `bool` | `boolean` | `bool` | `bool` | `bool` |
+| `int8/16/32/64` | `number` | `int` | `int` | `i8/i16/i32/i64` |
+| `float32/64` | `number` | `float` | `float32/float64` | `f32/f64` |
+| `str` | `string` | `str` | `string` | `String` |
+| `bytes` | `Uint8Array` | `bytes` | `seq[byte]` | `Vec<u8>` |
+| `array` | `Array` | `list` | `seq` | `Vec` |
+| `object` | `Object` | `dict` | `Table` | `HashMap` |
+| `vector` | `Float32Array` | `list[float]` | `seq[float32]` | `Vec<f32>` |
@@ -0,0 +1,58 @@
+# Колонково Съхранение (Columnar)
+
+Колонково-ориентирано съхранение за аналитични заявки и агрегации.
+
+## Употреба
+
+```nim
+import barabadb/core/columnar
+
+var batch = newColumnBatch()
+var ageCol = batch.addInt64Col("age")
+var nameCol = batch.addStringCol("name")
+
+ageCol.appendInt64(25)
+nameCol.appendString("Alice")
+```
+
+## Агрегации
+
+```nim
+echo ageCol.sumInt64()
+echo ageCol.avgInt64()
+echo ageCol.minInt64()
+echo ageCol.maxInt64()
+echo ageCol.count()
+```
+
+## Кодиране
+
+### RLE (Run-Length Encoding)
+
+```nim
+let rle = rleEncode(@[1'i64, 1, 1, 2, 2, 3])
+```
+
+### Dictionary Encoding
+
+```nim
+let dict = dictEncode(@["apple", "banana", "apple"])
+```
+
+## Типове Колони
+
+| Тип | Описание |
+|------|----------|
+| `int32` | 32-битов integer |
+| `int64` | 64-битов integer |
+| `float32` | 32-битов float |
+| `float64` | 64-битов float |
+| `string` | Низ с променлива дължина |
+| `bool` | Булев |
+
+## Случаи на Употреба
+
+- OLAP натоварвания
+- Мащабни агрегации
+- Data warehousing
+- Анализ на времеви редове
@@ -0,0 +1,218 @@
+# Конфигурационна Референция
+
+BaraDB може да се конфигурира чрез **променливи на средата**, **конфигурационен файл** или **командно-редови флагове**.
+
+## Ред на Приоритет
+
+1. Командно-редови флагове (най-висок приоритет)
+2. Променливи на средата
+3. Конфигурационен файл (`baradb.conf` или `baradb.json`)
+4. Вградени стойности по подразбиране (най-нисък приоритет)
+
+## Променливи на Средата
+
+### Мрежа
+
+| Променлива | По подр. | Описание |
+|------------|----------|----------|
+| `BARADB_ADDRESS` | `127.0.0.1` | Адрес за свързване |
+| `BARADB_PORT` | `9472` | TCP бинарен протокол порт |
+| `BARADB_HTTP_PORT` | `9470` | HTTP/REST API порт |
+| `BARADB_WS_PORT` | `9471` | WebSocket порт |
+
+### Съхранение
+
+| Променлива | По подр. | Описание |
+|------------|----------|----------|
+| `BARADB_DATA_DIR` | `./data` | Път до директория за данни |
+| `BARADB_MEMTABLE_SIZE_MB` | `64` | Размер на MemTable в MB |
+| `BARADB_CACHE_SIZE_MB` | `256` | Размер на page cache в MB |
+| `BARADB_WAL_SYNC_INTERVAL_MS` | `0` | Интервал за WAL fsync (0 = всеки запис) |
+| `BARADB_COMPACTION_INTERVAL_MS` | `60000` | Интервал за фонов compaction |
+| `BARADB_BLOOM_BITS_PER_KEY` | `10` | Bloom филтър битове за ключ |
+
+### TLS/SSL
+
+| Променлива | По подр. | Описание |
+|------------|----------|----------|
+| `BARADB_TLS_ENABLED` | `false` | Включване на TLS |
+| `BARADB_CERT_FILE` | — | Път до TLS сертификат |
+| `BARADB_KEY_FILE` | — | Път до TLS частен ключ |
+
+### Сигурност
+
+| Променлива | По подр. | Описание |
+|------------|----------|----------|
+| `BARADB_AUTH_ENABLED` | `false` | Включване на автентикация |
+| `BARADB_JWT_SECRET` | — | JWT подписващ secret |
+| `BARADB_RATE_LIMIT_GLOBAL` | `10000` | Глобални заявки в секунда |
+| `BARADB_RATE_LIMIT_PER_CLIENT` | `1000` | Заявки в секунда за клиент |
+
+### Логване
+
+| Променлива | По подр. | Описание |
+|------------|----------|----------|
+| `BARADB_LOG_LEVEL` | `info` | Ниво на логване: debug, info, warn, error |
+| `BARADB_LOG_FILE` | — | Път до лог файл (stdout ако е празен) |
+| `BARADB_LOG_FORMAT` | `json` | Формат на лога: json, text |
+
+### Vector Engine
+
+| Променлива | По подр. | Описание |
+|------------|----------|----------|
+| `BARADB_VECTOR_M` | `16` | HNSW `M` параметър |
+| `BARADB_VECTOR_EF_CONSTRUCTION` | `200` | HNSW `efConstruction` |
+| `BARADB_VECTOR_EF_SEARCH` | `64` | HNSW `efSearch` |
+
+### Graph Engine
+
+| Променлива | По подр. | Описание |
+|------------|----------|----------|
+| `BARADB_GRAPH_PAGE_RANK_ITERATIONS` | `20` | Брой итерации на PageRank |
+| `BARADB_GRAPH_PAGE_RANK_DAMPING` | `0.85` | PageRank damping фактор |
+| `BARADB_GRAPH_LOUVAIN_RESOLUTION` | `1.0` | Louvain резолюционен параметър |
+
+### Разпределени
+
+| Променлива | По подр. | Описание |
+|------------|----------|----------|
+| `BARADB_RAFT_NODE_ID` | — | Уникално ID на възел в клъстер |
+| `BARADB_RAFT_PEERS` | — | Списък с адреси на peer-ове, разделени със запетая |
+| `BARADB_RAFT_PORT` | `9001` | Raft вътрешен комуникационен порт |
+| `BARADB_SHARD_COUNT` | `1` | Брой шардове |
+| `BARADB_REPLICATION_FACTOR` | `1` | Фактор на репликация |
+| `BARADB_SEED_NODES` | — | Gossip seed възли (host:port, разделени със запетая) |
+
+## Конфигурационен Файл
+
+### baradb.conf (INI-подобен)
+
+```ini
+[server]
+address = "0.0.0.0"
+port = 9472
+http_port = 9470
+ws_port = 9471
+
+[storage]
+data_dir = "/var/lib/baradb"
+memtable_size_mb = 256
+cache_size_mb = 512
+wal_sync_interval_ms = 10
+compaction_interval_ms = 30000
+
+[tls]
+enabled = true
+cert_file = "/etc/baradb/server.crt"
+key_file = "/etc/baradb/server.key"
+
+[auth]
+enabled = true
+jwt_secret = "change-me-in-production"
+rate_limit_global = 10000
+rate_limit_per_client = 1000
+
+[logging]
+level = "info"
+format = "json"
+file = "/var/log/baradb/baradb.log"
+
+[vector]
+m = 16
+ef_construction = 200
+ef_search = 64
+
+[cluster]
+raft_node_id = "node1"
+raft_peers = "node2:9001,node3:9001"
+```
+
+### baradb.json
+
+```json
+{
+  "server": {
+    "address": "0.0.0.0",
+    "port": 9472,
+    "http_port": 9470,
+    "ws_port": 9471
+  },
+  "storage": {
+    "data_dir": "/var/lib/baradb",
+    "memtable_size_mb": 256,
+    "cache_size_mb": 512
+  },
+  "tls": {
+    "enabled": true,
+    "cert_file": "/etc/baradb/server.crt",
+    "key_file": "/etc/baradb/server.key"
+  }
+}
+```
+
+## Командно-редови Флагове
+
+```bash
+./build/baradadb --help
+```
+
+```
+BaraDB v1.1.0 — Multimodal Database Engine
+
+Употреба:
+  baradadb [опции]
+
+Опции:
+  -c, --config <файл>        Път до конфигурационен файл
+  -p, --port <порт>          TCP бинарен порт (по подр.: 9472)
+  --http-port <порт>         HTTP порт (по подр.: 9470)
+  --ws-port <порт>           WebSocket порт (по подр.: 9471)
+  -d, --data-dir <дир>       Директория за данни (по подр.: ./data)
+  --tls-cert <файл>          TLS сертификатен файл
+  --tls-key <файл>           TLS файл с частен ключ
+  --log-level <ниво>         Ниво на логване: debug, info, warn, error
+  --log-file <файл>          Път до лог файл
+  --shell                    Стартиране на интерактивна обвивка
+  --version                  Показване на версия
+  --recover                  Изпълнение на WAL възстановяване
+  --checkpoint <файл>        Checkpoint за възстановяване
+  -h, --help                 Показване на тази помощ
+```
+
+## Примерни Конфигурации
+
+### Разработка
+
+```bash
+./build/baradadb \
+  --log-level debug \
+  --data-dir ./dev_data
+```
+
+### Продукционен Единичен Възел
+
+```bash
+BARADB_TLS_ENABLED=true \
+BARADB_CERT_FILE=/etc/baradb/server.crt \
+BARADB_KEY_FILE=/etc/baradb/server.key \
+BARADB_AUTH_ENABLED=true \
+BARADB_JWT_SECRET="$(openssl rand -hex 32)" \
+BARADB_LOG_LEVEL=warn \
+BARADB_LOG_FILE=/var/log/baradb/baradb.log \
+BARADB_MEMTABLE_SIZE_MB=256 \
+BARADB_CACHE_SIZE_MB=1024 \
+./build/baradadb
+```
+
+### Продукционен Клъстер (3 възела)
+
+```bash
+# Възел 1
+BARADB_ADDRESS=0.0.0.0 \
+BARADB_PORT=9472 \
+BARADB_RAFT_NODE_ID=node1 \
+BARADB_RAFT_PEERS=node2:9001,node3:9001 \
+BARADB_SHARD_COUNT=4 \
+BARADB_REPLICATION_FACTOR=2 \
+./build/baradadb
+```
@@ -0,0 +1,101 @@
+# Cross-Modal Заявки
+
+Уникалната способност на BaraDB да изпълнява заявки, обхващащи множество storage двигатели в една унифицирана BaraQL заявка.
+
+## Преглед
+
+Традиционните бази данни изискват отделни заявки и join-ове на ниво приложение при работа с различни модели на данни. Cross-modal query planner-ът на BaraDB оптимизира изпълнението през:
+
+- **Документи/KV** (LSM-Tree) — структурирани записи
+- **Графи** (Adjacency List) — връзки
+- **Вектори** (HNSW/IVF-PQ) — търсене на прилика
+- **Пълен текст** (Inverted Index) — текстово търсене
+- **Колонково** — аналитични агрегати
+
+## Примери за Заявки
+
+### Векторно + Пълнотекстово (Семантично + Ключово Търсене)
+
+```sql
+SELECT title, score
+FROM articles
+WHERE MATCH(body) AGAINST('machine learning')
+ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, ...])
+LIMIT 10;
+```
+
+### Графово + Векторно (Социални Препоръки)
+
+```sql
+MATCH (u:User)-[:KNOWS]->(friend:User)
+WHERE u.name = 'Alice'
+ORDER BY cosine_distance(friend.taste_vector, u.taste_vector)
+RETURN friend.name, friend.age;
+```
+
+### Документно + Графово (Обогатяване на Същности)
+
+```sql
+SELECT o.id, o.total, c.name,
+       (SELECT count(*) FROM orders WHERE customer_id = c.id) as order_count
+FROM orders o
+MATCH (c:Customer)-[:PLACED]->(o)
+WHERE o.date > '2025-01-01';
+```
+
+## Cross-Modal Engine API
+
+```nim
+import barabadb/core/crossmodal
+
+var engine = newCrossModalEngine("/tmp/baradb")
+
+# Документни операции
+engine.put("key1", cast[seq[byte]]("value1"))
+let (found, val) = engine.get("key1")
+
+# Векторни операции
+engine.insertVector(1, @[1.0'f32, 0.0'f32, ...], {"cat": "A"}.toTable)
+let results = engine.searchVector(@[1.0'f32, 0.1'f32, ...], 2)
+
+# Графови операции
+let n1 = engine.addNode("Person")
+let n2 = engine.addNode("Person")
+discard engine.addEdge(n1, n2, "knows")
+let traversal = engine.traverseGraph(n1, "bfs")
+
+# FTS операции
+engine.indexText(1, "Nim programming language")
+let ftsResults = engine.searchText("programming")
+
+# Хибридно търсене
+var query = newCrossModalQuery(qmHybrid)
+query.vector = @[1.0'f32, 0.0'f32]
+query.searchQuery = "fast"
+query.vecWeight = 1.0
+query.ftsWeight = 1.0
+let hybridResult = engine.hybridSearch(query)
+```
+
+## 2PC Транзакции
+
+Cross-modal engine-ът поддържа two-phase commit за атомарни операции през множество storage системи:
+
+```nim
+var txn = newTPCTransaction(1)
+txn.addParticipant("storage")
+txn.addParticipant("vector")
+txn.addParticipant("graph")
+
+txn.prepare()   # Всички участници потвърждават, че могат да комитнат
+txn.commit()    # Атомарен commit през всички участници
+```
+
+## Формална Верификация
+
+Cross-modal консистентността е формално специфицирана в TLA+:
+
+- **Спецификация:** `formal-verification/crossmodal.tla`
+- **Проверени свойства:**
+  - `MetadataVectorConsistency` — insertVector обновява метаданни за филтрирано търсене
+  - `CrossModalAtomicity` — всички участници комитват или всички абортират
@@ -0,0 +1,250 @@
+# Ръководство за Внедряване (Deployment)
+
+## Docker
+
+За пълно ръководство за Docker deployment вижте [Docker Guide](docker.md).
+
+### Бърз старт
+
+```bash
+docker build -t baradb:latest .
+docker compose up -d
+```
+
+### Docker Compose файлове
+
+| Файл | Назначение |
+|------|-----------|
+| `docker-compose.yml` | Development |
+| `docker-compose.prod.yml` | Production |
+| `docker-compose.override.yml` | Dev override (автоматично) |
+| `docker-compose.test.yml` | Тестова среда |
+
+### Production
+
+```bash
+docker compose -f docker-compose.prod.yml up -d
+```
+
+### Docker Swarm
+
+```bash
+docker stack deploy -c docker-compose.prod.yml baradb
+```
+
+## systemd Услуга
+
+Създайте `/etc/systemd/system/baradb.service`:
+
+```ini
+[Unit]
+Description=BaraDB Multimodal Database
+After=network.target
+
+[Service]
+Type=simple
+User=baradb
+Group=baradb
+WorkingDirectory=/var/lib/baradb
+ExecStart=/usr/local/bin/baradadb
+Restart=always
+RestartSec=5
+
+Environment=BARADB_PORT=9472
+Environment=BARADB_HTTP_PORT=9470
+Environment=BARADB_DATA_DIR=/var/lib/baradb/data
+Environment=BARADB_LOG_LEVEL=info
+
+# Подсилване на сигурността
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/baradb/data
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Активиране и стартиране:
+
+```bash
+sudo useradd -r -s /bin/false baradb
+sudo mkdir -p /var/lib/baradb/data
+sudo chown -R baradb:baradb /var/lib/baradb
+sudo cp build/baradadb /usr/local/bin/
+sudo systemctl daemon-reload
+sudo systemctl enable --now baradb
+```
+
+## Kubernetes
+
+### StatefulSet
+
+```yaml
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: baradb
+spec:
+  serviceName: baradb
+  replicas: 3
+  selector:
+    matchLabels:
+      app: baradb
+  template:
+    metadata:
+      labels:
+        app: baradb
+    spec:
+      containers:
+      - name: baradb
+        image: baradb:latest
+        ports:
+        - containerPort: 9472
+          name: binary
+        - containerPort: 9470
+          name: http
+        - containerPort: 9471
+          name: websocket
+        env:
+        - name: BARADB_DATA_DIR
+          value: /data
+        - name: BARADB_RAFT_NODE_ID
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.name
+        volumeMounts:
+        - name: data
+          mountPath: /data
+  volumeClaimTemplates:
+  - metadata:
+      name: data
+    spec:
+      accessModes: ["ReadWriteOnce"]
+      resources:
+        requests:
+          storage: 100Gi
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: baradb
+spec:
+  selector:
+    app: baradb
+  ports:
+  - port: 9472
+    name: binary
+  - port: 9470
+    name: http
+  - port: 9471
+    name: websocket
+  clusterIP: None
+```
+
+## Reverse Proxy (nginx)
+
+```nginx
+upstream baradb_http {
+    server 127.0.0.1:9470;
+}
+
+upstream baradb_ws {
+    server 127.0.0.1:9471;
+}
+
+server {
+    listen 80;
+    server_name db.example.com;
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name db.example.com;
+
+    ssl_certificate /etc/letsencrypt/live/db.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/db.example.com/privkey.pem;
+
+    location /api/ {
+        proxy_pass http://baradb_http/;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    location /ws/ {
+        proxy_pass http://baradb_ws/;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+## Висока Достъпност (High Availability)
+
+### 3-Възел Raft Клъстер
+
+```bash
+# Възел 1
+BARADB_RAFT_NODE_ID=node1 \
+BARADB_RAFT_PEERS=node2:9001,node3:9001 \
+./build/baradadb
+
+# Възел 2
+BARADB_RAFT_NODE_ID=node2 \
+BARADB_RAFT_PEERS=node1:9001,node3:9001 \
+./build/baradadb
+
+# Възел 3
+BARADB_RAFT_NODE_ID=node3 \
+BARADB_RAFT_PEERS=node1:9001,node2:9001 \
+./build/baradadb
+```
+
+## Облачно Внедряване
+
+### AWS EC2
+
+Препоръчителна инстанция: `m6i.2xlarge` (8 vCPU, 32 GB RAM)
+
+```bash
+# User data скрипт
+#!/bin/bash
+apt-get update
+apt-get install -y nim
+wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-amd64
+chmod +x baradadb-linux-amd64
+mv baradadb-linux-amd64 /usr/local/bin/baradadb
+
+mkdir -p /data/baradb
+cat > /etc/systemd/system/baradb.service << 'EOF'
+[Unit]
+Description=BaraDB
+After=network.target
+[Service]
+ExecStart=/usr/local/bin/baradadb
+Environment=BARADB_DATA_DIR=/data/baradb
+Restart=always
+[Install]
+WantedBy=multi-user.target
+EOF
+
+systemctl daemon-reload
+systemctl enable --now baradb
+```
+
+### GCP Cloud Run (само HTTP)
+
+```bash
+gcloud run deploy baradb \
+  --image gcr.io/PROJECT/baradb \
+  --port 9470 \
+  --memory 4Gi \
+  --cpu 2 \
+  --max-instances 10
+```
@@ -1,9 +1,11 @@
 # Разпределена Система

-Поддръжка за разпределено внедряване с Raft консенсус, шардиране и репликация.
+BaraDB поддържа разпределено внедряване с Raft консенсус, шардиране, репликация и gossip протокол.

 ## Raft Консенсус

+Leader election и log репликация:
+
 ```nim
 import barabadb/core/raft

@@ -13,19 +15,35 @@ cluster.addNode("node2")
 cluster.addNode("node3")

 let n1 = cluster.nodes["n1"]
+n1.becomeCandidate()
 n1.becomeLeader()
+let entry = n1.appendLog("SET key1 value1")
 ```

 ## Шардиране

+Разпределение на данни между възли:
+
 ```nim
 import barabadb/core/sharding

-var router = newShardRouter(ShardConfig(numShards: 4, replicas: 2))
+var router = newShardRouter(ShardConfig(
+  numShards: 4,
+  replicas: 2,
+  strategy: ssHash
+))
 router.rebalance(@["node1", "node2", "node3"])
 let shard = router.getShard("user_123")
 ```

+### Стратегии за Шардиране
+
+| Стратегия | Описание |
+|-----------|----------|
+| `ssHash` | Хеш-базирано шардиране |
+| `ssRange` | Range-базирано шардиране |
+| `ssConsistent` | Consistent hashing |
+
 ## Репликация

 ```nim
@@ -34,11 +52,46 @@ import barabadb/core/replication
 var rm = newReplicationManager(rmSync)
 rm.addReplica(newReplica("r1", "10.0.0.1", 9472))
 rm.connectReplica("r1")
+let lsn = rm.writeLsn(@[1'u8, 2, 3])
+rm.ackLsn("r1", lsn)
+```
+
+### Режими на Репликация
+
+| Режим | Описание |
+|--------|----------|
+| `rmSync` | Синхронна репликация |
+| `rmAsync` | Асинхронна репликация |
+| `rmSemiSync` | Полу-синхронна репликация |
+
+## Gossip Протокол
+
+Управление на членство и детекция на откази:
+
+```nim
+import barabadb/core/gossip
+
+var g = newGossipProtocol("node1", "localhost", 9472, gossipPort = 9572)
+g.join(newGossipNode("node2", "10.0.0.2", 9472))
+```
+
+## Разпределени Транзакции
+
+Two-phase commit между възли:
+
+```nim
+import barabadb/core/disttxn
+
+var tm = newDistTxnManager()
+let txn = tm.beginTransaction("node1")
+txn.addParticipant("node2", "10.0.0.2", 9472)
+txn.prepare()
+txn.commit()
 ```

 ## Формална Верификация

-Разпределените алгоритми са формално специфицирани в TLA+ и проверени с TLC:
+Основните разпределени алгоритми са формално специфицирани в TLA+ и проверени с TLC:

 - **Raft Консенсус** — `formal-verification/raft.tla`
  - Проверено: ElectionSafety, StateMachineSafety
@@ -47,11 +100,11 @@ rm.connectReplica("r1")
 - **Репликация** — `formal-verification/replication.tla`
  - Проверено: MonotonicLsn, AcksRemovePending

-Пускане на TLC:
+Пускане на TLC локално:

 ```bash
 cd formal-verification
 java -cp tla2tools.jar tlc2.TLC -config models/raft.cfg raft.tla
 java -cp tla2tools.jar tlc2.TLC -config models/twopc.cfg twopc.tla
 java -cp tla2tools.jar tlc2.TLC -config models/replication.cfg replication.tla
-```
+```
@@ -0,0 +1,183 @@
+# Docker Deployment Ръководство
+
+Това ръководство описва как да използвате BaraDB с Docker и Docker Compose.
+
+## Бърз старт
+
+```bash
+# Клониране на репото
+git clone https://github.com/katehonz/barabaDB.git
+cd barabaDB
+
+# Build на образа
+docker build -t baradb:latest .
+
+# Стартиране с Docker Compose
+docker compose up -d
+
+# Проверка на статуса
+docker compose ps
+docker compose logs -f
+```
+
+## Файлове
+
+| Файл | Описание |
+|------|----------|
+| `Dockerfile` | Мулти-stage production build |
+| `docker-compose.yml` | Development конфигурация |
+| `docker-compose.prod.yml` | Production конфигурация |
+| `docker-compose.override.yml` | Development override (автоматично се зарежда) |
+| `docker-compose.test.yml` | Тестова конфигурация |
+| `docker-entrypoint.sh` | Entrypoint скрипт за инициализация |
+| `.dockerignore` | Файлове, които да не се копират в образа |
+
+## Създаване на образ
+
+```bash
+# Стандартен build
+docker build -t baradb:latest .
+
+# С конкретна версия
+docker build -t baradb:1.1.0 .
+```
+
+## Стартиране
+
+### Development (docker compose)
+
+```bash
+# Стартиране на заден план
+docker compose up -d
+
+# Спиране
+docker compose down
+
+# Спиране и изтриване на volumes (ВНИМАНИЕ — изтрива данните!)
+docker compose down -v
+
+# Преглед на логове
+docker compose logs -f
+```
+
+### Production (docker compose)
+
+```bash
+# Стартиране с production конфигурация
+docker compose -f docker-compose.prod.yml up -d
+
+# Проверка на healthcheck
+docker compose -f docker-compose.prod.yml ps
+```
+
+### Ръчно (docker run)
+
+```bash
+docker run -d \
+  --name baradb \
+  -p 9472:9472 \
+  -p 9470:9470 \
+  -p 9471:9471 \
+  -v baradb_data:/data \
+  -e BARADB_LOG_LEVEL=info \
+  baradb:latest
+```
+
+## Портове
+
+| Порт | Описание |
+|------|----------|
+| `9472` | Binary wire протокол |
+| `9470` | HTTP/REST API |
+| `9471` | WebSocket |
+
+## Променливи на Средата
+
+| Променлива | Стойност по подразбиране | Описание |
+|------------|--------------------------|----------|
+| `BARADB_ADDRESS` | `0.0.0.0` | Адрес за слушане |
+| `BARADB_PORT` | `9472` | Binary протокол порт |
+| `BARADB_HTTP_PORT` | `9470` | HTTP порт |
+| `BARADB_WS_PORT` | `9471` | WebSocket порт |
+| `BARADB_DATA_DIR` | `/data` | Директория за данни |
+| `BARADB_LOG_LEVEL` | `info` | Ниво на логове |
+
+## Volumes
+
+| Път в контейнера | Описание |
+|------------------|----------|
+| `/data` | Основна директория за базата данни |
+| `/data/server/wal` | Write-ahead log |
+| `/data/server/sstables` | SSTable файлове |
+
+## Production Checklist
+
+- [ ] Създайте TLS сертификати в `./certs/`
+- [ ] Задайте силен `BARADB_JWT_SECRET`
+- [ ] Настройте firewall правила
+- [ ] Конфигурирайте регулярни backups
+- [ ] Проверете resource limits
+- [ ] Настройте мониторинг (healthcheck, logs)
+
+## TLS в Docker
+
+1. Създайте сертификати:
+```bash
+mkdir -p certs
+openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+  -keyout certs/server.key -out certs/server.crt
+```
+
+2. Активирайте в `docker-compose.prod.yml`:
+```yaml
+environment:
+  - BARADB_TLS_ENABLED=true
+  - BARADB_CERT_FILE=/certs/server.crt
+  - BARADB_KEY_FILE=/certs/server.key
+volumes:
+  - ./certs:/certs:ro
+```
+
+## Backup в Docker
+
+```bash
+# Ръчен backup
+docker exec baradb baradadb --snapshot --output=/backup/snapshot.db
+
+# Списък на backups
+ls /backup/
+
+# Възстановяване
+docker exec baradb baradadb --recover --checkpoint=/backup/snapshot.db
+```
+
+## Troubleshooting
+
+### Контейнерът не стартира
+
+```bash
+# Проверка на логове
+docker compose logs -f baradb
+
+# Проверка на статус
+docker compose ps
+```
+
+### Няма връзка с базата
+
+```bash
+# Проверка дали портовете са експозвани
+docker port baradb
+
+# Проверка отвътре
+docker exec baradb wget -qO- http://localhost:9470/health
+```
+
+### Permission denied на /data
+
+Entrypoint скриптът автоматично създава директориите и задава правилните permissions. Ако имате проблем:
+
+```bash
+docker exec baradb ls -la /data
+docker exec baradb chown -R baradb:baradb /data
+```
@@ -1,6 +1,6 @@
-# Пълнотекстово Търсене
+# Full-Text Search Engine

-Инвертиран индекс с BM25 и TF-IDF ранжиране.
+Inverted индекс с BM25 и TF-IDF ранжиране за текстово търсене.

 ## Употреба

@@ -8,28 +8,80 @@
 import barabadb/fts/engine

 var idx = newInvertedIndex()
-idx.addDocument(1, "Nim е бърз език за програмиране")
-idx.addDocument(2, "Python е популярен за data science")
+idx.addDocument(1, "Nim is a fast programming language")
+idx.addDocument(2, "Python is popular for data science")

-let results = idx.search("език програмиране")
-let tfidf = idx.searchTfidf("език")
-let fuzzy = idx.fuzzySearch("програмиране", maxDistance = 2)
+# BM25 търсене
+let results = idx.search("programming language")
+
+# TF-IDF търсене
+let tfidf = idx.searchTfidf("programming language")
+
+# Fuzzy търсене (толеранс на печатни грешки)
+let fuzzy = idx.fuzzySearch("programing", maxDistance = 2)
+
+# Wildcard търсене
+let wild = idx.regexSearch("prog*")
 ```

 ## Методи за Ранжиране

 ### BM25

-Най-добрият алгоритъм за съвпадение
+Best matching алгоритъм за ранжиране:
+
+```nim
+let bm25 = idx.searchBM25("query terms")
+```

 ### TF-IDF

-Term Frequency-Inverse Document Frequency
+Term Frequency-Inverse Document Frequency:

-## Търсене
+```nim
+let tfidf = idx.searchTfidf("query terms")
+```

-| Тип | Описание |
-|-----|----------|
-| Fuzzy | Толерантност към правописни грешки |
-| Wildcard | Префикс, суфикс, и инфикс заместващи символи |
-| Regex | Регулярни изрази |
+## Функции за Търсене
+
+| Функция | Описание |
+|---------|----------|
+| Fuzzy търсене | Levenshtein distance толеранс |
+| Wildcard | Префиксни, суфиксни и инфиксни wildcards |
+| Regex | Регулярни изрази |
+| Фразово търсене | Точно съвпадение на фраза |
+| Булево | AND, OR, NOT оператори |
+
+## SQL Интерфейс
+
+Пълнотекстовото търсене е достъпно и директно в BaraQL:
+
+```sql
+-- Създаване на таблица с текстова колона
+CREATE TABLE articles (id INT PRIMARY KEY, title TEXT, body TEXT);
+
+-- Създаване на FTS индекс
+CREATE INDEX idx_fts ON articles(body) USING FTS;
+
+-- Търсене с оператора @@ (BM25 ранжиране)
+SELECT * FROM articles WHERE body @@ 'machine learning';
+
+-- Търсене с множество термини
+SELECT * FROM articles WHERE body @@ 'quick brown fox';
+```
+
+## Многоезична Поддръжка
+
+```nim
+import barabadb/fts/multilang
+
+# Поддържани езици: EN, BG, DE, FR, RU
+var tokenizer = newTokenizer("bg")  # Български
+let tokens = tokenizer.tokenize("Търсене в пълен текст")
+```
+
+Функции за всеки език:
+- Токенизация
+- Stop думи
+- Стеминг
+- Детекция на език
@@ -15,6 +15,7 @@
 | macOS | x86_64 | ✅ Пълна поддръжка |
 | macOS | ARM64 (Apple Silicon) | ✅ Пълна поддръжка |
 | Windows | x86_64 | ✅ Поддръжка |
+| FreeBSD | x86_64 | 🟡 Тествано от общността |

 ## Инсталиране на Nim

@@ -48,10 +49,13 @@ sudo port install nim
 ### Windows

 ```powershell
-# Winget
+# С choosenim
+curl.exe -A "MSYS2_$(uname -m)" -L https://nim-lang.org/choosenim/init.ps1 | powershell -
+
+# С winget
 winget install nim

-# Scoop
+# С scoop
 scoop install nim
 ```

@@ -79,10 +83,16 @@ sudo pacman -S openssl

 ### macOS

+OpenSSL е включен в системата. Ако е необходимо:
+
 ```bash
 brew install openssl
 ```

+### Windows
+
+OpenSSL е включен в Nim Windows дистрибуцията. За ръчни компилации, изтеглете от [slproweb.com](https://slproweb.com/products/Win32OpenSSL.html).
+
 ## Компилиране на BaraDB

 ### Клониране на Репозиторито
@@ -103,26 +113,29 @@ nimble install -d -y
 #### Debug Компилация

 ```bash
-nim c -d:ssl -o:build/baradadb src/baradadb.nim
+nim c -d:ssl --threads:on -o:build/baradadb src/baradadb.nim
 ```

 #### Release Компилация (Препоръчителна)

 ```bash
-nim c -d:ssl -d:release --opt:speed -o:build/baradadb src/baradadb.nim
+nim c -d:ssl --threads:on -d:release --opt:speed -o:build/baradadb src/baradadb.nim
 ```

-#### Използване на Nimble
+#### Използване на Nimble Tasks

 ```bash
+# Debug компилация
 nimble build_debug
+
+# Release компилация
 nimble build_release
 ```

 #### Минимален Размер

 ```bash
-nim c -d:ssl -d:release --opt:size -o:build/baradadb src/baradadb.nim
+nim c -d:ssl --threads:on -d:release --opt:size -o:build/baradadb src/baradadb.nim
 strip build/baradadb
 ```

@@ -130,17 +143,31 @@ strip build/baradadb

 ```bash
 ./build/baradadb --version
-# Очакван резултат: BaraDB v0.1.0 — Multimodal Database Engine
+# Очакван резултат: BaraDB v1.1.0 — Multimodal Database Engine
 ```

 ## Стартиране на Тестове

-```bash
-# Всички тестове (262 теста, 56 сюита)
-nim c -d:ssl -r tests/test_all.nim
+### Всички Тестове

-# Бенчмаркове
-nim c -d:ssl -d:release -r benchmarks/bench_all.nim
+```bash
+nim c --path:src -d:ssl --threads:on -r tests/test_all.nim
+```
+
+### Специфични Тестови Сюити
+
+```bash
+# Storage тестове
+nim c --path:src -d:ssl --threads:on -r tests/test_all.nim
+
+# Stress тестове
+nim c --path:src -d:ssl --threads:on -d:release -r tests/stress_test.nim
+```
+
+### Бенчмаркове
+
+```bash
+nim c --path:src -d:ssl --threads:on -d:release -r benchmarks/bench_all.nim
 ```

 ## Опции за Инсталация
@@ -148,16 +175,46 @@ nim c -d:ssl -d:release -r benchmarks/bench_all.nim
 ### Системна Инсталация

 ```bash
+# Компилиране на release binary
 nimble build_release
+
+# Инсталиране в /usr/local/bin
 sudo cp build/baradadb /usr/local/bin/
 sudo chmod +x /usr/local/bin/baradadb
+
+# Създаване на директория за данни
 sudo mkdir -p /var/lib/baradb
+sudo chmod 755 /var/lib/baradb
+```
+
+### Предварително Компилиран Binary
+
+Изтеглете най-новата версия за вашата платформа:
+
+```bash
+# Linux x86_64
+wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-amd64
+chmod +x baradadb-linux-amd64
+mv baradadb-linux-amd64 /usr/local/bin/baradadb
+
+# Linux ARM64
+wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-arm64
+chmod +x baradadb-linux-arm64
+mv baradadb-linux-arm64 /usr/local/bin/baradadb
+
+# macOS
+wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-darwin-amd64
+chmod +x baradadb-darwin-amd64
+mv baradadb-darwin-amd64 /usr/local/bin/baradadb
 ```

 ### Docker

 ```bash
+# Изтегляне на официален образ
 docker pull barabadb/barabadb:latest
+
+# Стартиране
 docker run -d \
  -p 9472:9472 \
  -p 9470:9470 \
@@ -172,12 +229,16 @@ docker run -d \
 docker-compose up -d
 ```

-### Вградено Използване
+### Вградено Използване (Nim Проекти)
+
+Добавете към вашия `.nimble` файл:

 ```nim
-requires "barabadb >= 0.1.0"
+requires "barabadb >= 1.1.0"
 ```

+Използване в кода:
+
 ```nim
 import barabadb/storage/lsm

@@ -193,16 +254,52 @@ db.close()
 # Стартиране на сървъра
 ./build/baradadb

-# Тестване на HTTP API
+# Очакван изход:
+# BaraDB v1.1.0 — Multimodal Database Engine
+# BaraDB TCP listening on 127.0.0.1:9472
+
+# Тестване с HTTP API
 curl http://localhost:9470/health

-# Интерактивна конзола
+# Интерактивна обвивка
 ./build/baradadb --shell
 ```

+## Отстраняване на Проблеми с Инсталацията
+
+### "cannot open file: hunos"
+
+```bash
+nimble install -d -y
+```
+
+### "BaraDB requires SSL support"
+
+Винаги компилирайте с `-d:ssl`:
+
+```bash
+nim c -d:ssl --threads:on -o:build/baradadb src/baradadb.nim
+```
+
+### Бавна компилация
+
+Използвайте паралелна компилация:
+
+```bash
+nim c -d:ssl --threads:on -d:release --parallelBuild:4 -o:build/baradadb src/baradadb.nim
+```
+
+### Голям размер на binary-то
+
+Използвайте оптимизация на размера:
+
+```bash
+nim c -d:ssl --threads:on -d:release --opt:size --passL:-s -o:build/baradadb src/baradadb.nim
+```
+
 ## Следващи Стъпки

- [Бързо Стартиране](bg/quickstart.md)
- [Конфигурация](en/configuration.md)
- [Архитектура](bg/architecture.md)
- [BaraQL Заявки](bg/baraql.md)
+- [Бърз Старт](quickstart.md)
+- [Конфигурационна Референция](configuration.md)
+- [Преглед на Архитектурата](architecture.md)
+- [BaraQL Език за Заявки](baraql.md)
@@ -1,6 +1,29 @@
-# LSM-Tree Съхранение
+# LSM-Tree Storage Engine

-Основният двигател за съхранение използващ Log-Structured Merge-Tree архитектура.
+Основният storage engine в BaraDB, използващ Log-Structured Merge-Tree архитектура.
+
+## Архитектура
+
+```
+┌─────────────────────────────────────────────┐
+│                   Записи                     │
+│       (добавяне към WAL + MemTable)          │
+└─────────────────────────────────────────────┘
+                       │
+                       ▼
+┌─────────────────────────────────────────────┐
+│                  MemTable                    │
+│         (в-памет сортиран буфер)              │
+└─────────────────────────────────────────────┘
+                       │
+              (при запълване, flush към SSTable)
+                       │
+                       ▼
+┌─────────────────────────────────────────────┐
+│                  SSTable                     │
+│    (сортирана string table на диска)          │
+└─────────────────────────────────────────────┘
+```

 ## Употреба

@@ -9,17 +32,33 @@ import barabadb/storage/lsm

 var db = newLSMTree("./data")

+# Запис
 db.put("key1", cast[seq[byte]]("value1"))
+
+# Четене
 let (found, value) = db.get("key1")

+# Изтриване
+db.delete("key1")
+
 db.close()
 ```

-## Компоненти
+## Възможности

- **MemTable**: Сортиран буфер в паметта
- **WAL**: Write-ahead log за трайност
- **SSTable**: Сортирани таблици на диска
- **Bloom Filter**: Бързи негативни проверки
- **Compaction**: Сливане на SSTables
- **Page Cache**: LRU кеш
+- **Write-оптимизиран**: Append-only лог структура
+- **Устойчивост**: Write-ahead log (WAL) осигурява crash recovery
+- **Bloom Филтър**: Бързи негативни проверки
+- **Compaction**: Size-tiered стратегия слива SSTables
+- **Page Cache**: LRU кеш за често достъпвани страници
+
+## Конфигурация
+
+```nim
+var db = newLSMTree(
+  path = "./data",
+  memTableSize = 64 * 1024 * 1024,  # 64MB
+  walEnabled = true,
+  bloomFpRate = 0.01
+)
+```
@@ -0,0 +1,202 @@
+# Мониторинг и Наблюдаемост
+
+## Health Checks
+
+### HTTP Health Endpoint
+
+```bash
+curl http://localhost:9470/health
+```
+
+Отговор:
+
+```json
+{
+  "status": "healthy",
+  "version": "1.1.0",
+  "uptime_seconds": 86400,
+  "checks": {
+    "storage": "ok",
+    "memory": "ok",
+    "connections": "ok"
+  }
+}
+```
+
+### Readiness Probe
+
+```bash
+curl http://localhost:9470/ready
+```
+
+Връща `200 OK` когато сървърът е готов да приема трафик, `503` по време на стартиране.
+
+## Метрики
+
+### Prometheus-Съвместими Метрики
+
+```bash
+curl http://localhost:9470/metrics
+```
+
+Примерен изход:
+
+```
+# HELP baradb_queries_total Общ брой изпълнени заявки
+# TYPE baradb_queries_total counter
+baradb_queries_total 152340
+
+# HELP baradb_queries_duration_seconds Хистограма на времетраене на заявки
+# TYPE baradb_queries_duration_seconds histogram
+baradb_queries_duration_seconds_bucket{le="0.001"} 45000
+baradb_queries_duration_seconds_bucket{le="0.01"} 120000
+baradb_queries_duration_seconds_bucket{le="0.1"} 148000
+
+# HELP baradb_storage_lsm_size_bytes Общ размер на LSM-Tree
+# TYPE baradb_storage_lsm_size_bytes gauge
+baradb_storage_lsm_size_bytes 2147483648
+
+# HELP baradb_cache_hit_rate Page cache hit rate
+# TYPE baradb_cache_hit_rate gauge
+baradb_cache_hit_rate 0.94
+
+# HELP baradb_active_connections Активни клиентски връзки
+# TYPE baradb_active_connections gauge
+baradb_active_connections 42
+```
+
+### JSON Метрики
+
+```bash
+curl http://localhost:9470/metrics?format=json
+```
+
+## Логване
+
+### Нива на Логване
+
+| Ниво | Описание |
+|------|----------|
+| `debug` | Детайлни вътрешни операции |
+| `info` | Нормални операции |
+| `warn` | Възстановими проблеми |
+| `error` | Грешки, изискващи внимание |
+
+### Структурирани JSON Логове
+
+```bash
+BARADB_LOG_LEVEL=info \
+BARADB_LOG_FORMAT=json \
+BARADB_LOG_FILE=/var/log/baradb/baradb.log \
+./build/baradadb
+```
+
+Примерен лог запис:
+
+```json
+{
+  "timestamp": "2025-01-15T10:30:00.123Z",
+  "level": "info",
+  "component": "server",
+  "message": "Query executed",
+  "query": "SELECT * FROM users",
+  "duration_ms": 12,
+  "client_ip": "10.0.0.15"
+}
+```
+
+### Текстов Формат
+
+```bash
+BARADB_LOG_FORMAT=text ./build/baradadb
+```
+
+## Правила за Алармиране
+
+### Prometheus AlertManager
+
+```yaml
+groups:
+  - name: baradb
+    rules:
+      - alert: BaraDBHighErrorRate
+        expr: rate(baradb_errors_total[5m]) > 0.1
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: "Висок процент грешки в BaraDB"
+
+      - alert: BaraDBLowCacheHitRate
+        expr: baradb_cache_hit_rate < 0.8
+        for: 10m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Cache hit rate под 80%"
+
+      - alert: BaraDBHighConnections
+        expr: baradb_active_connections > 800
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Голям брой връзки към BaraDB"
+
+      - alert: BaraDBDown
+        expr: up{job="baradb"} == 0
+        for: 1m
+        labels:
+          severity: critical
+        annotations:
+          summary: "BaraDB инстанцията не работи"
+```
+
+## Разпределен Мониторинг
+
+### Клъстерни Метрики
+
+За Raft клъстери, мониторирайте:
+
+```bash
+curl http://node1:9470/metrics/cluster
+```
+
+```json
+{
+  "cluster_id": "baradb-cluster-1",
+  "nodes": [
+    {"id": "node1", "role": "leader", "health": "healthy"},
+    {"id": "node2", "role": "follower", "health": "healthy"},
+    {"id": "node3", "role": "follower", "health": "healthy"}
+  ],
+  "raft_log_index": 15420,
+  "raft_commit_index": 15420,
+  "shards": 4,
+  "replication_lag_ms": 5
+}
+```
+
+## Профилиране на Производителност
+
+### Вграден CPU Profiler
+
+```bash
+curl -X POST http://localhost:9470/debug/pprof/cpu?seconds=30 > cpu.prof
+```
+
+### Memory Profiler
+
+```bash
+curl http://localhost:9470/debug/pprof/heap > heap.prof
+```
+
+## Отстраняване на Проблеми с Метрики
+
+| Симптом | Метрика | Действие |
+|---------|--------|----------|
+| Бавни заявки | `baradb_queries_duration_seconds` | Проверете cache hit rate, добавете индекси |
+| Висока памет | `process_resident_memory_bytes` | Намалете memtable/cache размери |
+| Растящо съхранение | `baradb_storage_lsm_size_bytes` | Пуснете ръчен compaction |
+| Грешки при връзка | `baradb_active_connections` | Увеличете connection pool или добавете възли |
+| Репликационно закъснение | `baradb_replication_lag_ms` | Проверете мрежата, увеличете ресурсите |
@@ -0,0 +1,125 @@
+# Ръководство за Производителност
+
+## Методология на Бенчмарковете
+
+Всички бенчмаркове са проведени с:
+- **Компилатор**: Nim 2.2.0 с `-d:release --opt:speed`
+- **CPU**: AMD Ryzen 9 5900X (12 ядра / 24 нишки)
+- **Памет**: 64 GB DDR4-3600
+- **Диск**: Samsung 980 Pro NVMe SSD
+- **ОС**: Ubuntu 24.04 LTS
+
+Пускане на пълния бенчмарк сюит:
+
+```bash
+nim c -d:ssl -d:release -r benchmarks/bench_all.nim
+```
+
+## Storage Engine Бенчмаркове
+
+### LSM-Tree Key-Value
+
+| Метрика | Стойност |
+|---------|----------|
+| Пропускателна способност при запис | ~580,000 ops/s |
+| Пропускателна способност при четене | ~720,000 ops/s |
+| Средна латентност при запис | 1.7 µs |
+| Средна латентност при четене | 1.4 µs |
+
+LSM-Tree използва 64MB MemTable, WAL fsync при всеки запис и size-tiered compaction с 6 нива.
+
+### B-Tree Индекс
+
+| Метрика | Стойност |
+|---------|----------|
+| Пропускателна способност при вмъкване | ~1,200,000 ops/s |
+| Пропускателна способност при точково търсене | ~1,500,000 ops/s |
+| Range scan (1000 ключа) | ~0.3 ms |
+
+## Vector Engine Бенчмаркове
+
+### HNSW Индекс
+
+| Метрика | Стойност |
+|---------|----------|
+| Вмъкване (dim=128) | ~45,000 вектора/s |
+| Търсене топ-10 (dim=128, n=10K) | ~2 ms |
+| Търсене топ-10 (dim=128, n=100K) | ~8 ms |
+
+### SIMD Функции за Разстояние
+
+| Операция | dim=128 | dim=768 | dim=1536 |
+|----------|---------|---------|----------|
+| Косинусово разстояние | 4.2M/s | 850K/s | 420K/s |
+| L2 (Евклидово) | 4.5M/s | 920K/s | 450K/s |
+| Скаларно произведение | 4.8M/s | 980K/s | 480K/s |
+
+## Full-Text Search Бенчмаркове
+
+| Метрика | Стойност |
+|---------|----------|
+| Индексиране | ~320,000 документа/s |
+| BM25 търсене | ~28,000 заявки/s |
+| Fuzzy търсене (distance=2) | ~850 заявки/s |
+
+## Graph Engine Бенчмаркове
+
+| Операция | Пропускателна способност |
+|----------|--------------------------|
+| Добавяне на възел | ~2.5M ops/s |
+| Добавяне на ребро | ~1.8M ops/s |
+| BFS (1K възела, 5K ребра) | ~12K обхождания/s |
+| Dijkstra най-кратък път | ~120 µs |
+| PageRank (10 итерации) | ~450 графа/s |
+
+## Протоколни Бенчмаркове
+
+| Протокол | Връзки | Заявки/s | Латентност p99 |
+|----------|--------|----------|----------------|
+| Бинарен (localhost) | 1 | 45,000 | 0.4 ms |
+| Бинарен (localhost) | 100 | 380,000 | 1.2 ms |
+| HTTP/REST | 1 | 12,000 | 2.1 ms |
+| HTTP/REST | 100 | 95,000 | 5.8 ms |
+| WebSocket | 1 | 18,000 | 1.8 ms |
+
+## Вертикален Мащабинг
+
+| Ядра | LSM Запис | LSM Четене | Векторно Търсене |
+|------|-----------|------------|-------------------|
+| 1 | 580K | 720K | 2.0 ms |
+| 4 | 1.9M | 2.6M | 1.1 ms |
+| 8 | 3.4M | 4.8M | 0.7 ms |
+| 16 | 5.8M | 7.2M | 0.5 ms |
+
+## Ръководство за Настройка
+
+### За Write-Heavy Натоварвания
+
+```bash
+export BARADB_MEMTABLE_SIZE_MB=256
+export BARADB_WAL_SYNC_INTERVAL_MS=10
+export BARADB_COMPACTION_INTERVAL_MS=30000
+```
+
+### За Read-Heavy Натоварвания
+
+```bash
+export BARADB_CACHE_SIZE_MB=1024
+export BARADB_BLOOM_BITS_PER_KEY=10
+export BARADB_COMPACTION_INTERVAL_MS=120000
+```
+
+### За Векторно Търсене
+
+```bash
+export BARADB_VECTOR_EF_CONSTRUCTION=200
+export BARADB_VECTOR_EF_SEARCH=128
+export BARADB_VECTOR_M=32
+```
+
+### За Графова Аналитика
+
+```bash
+export BARADB_GRAPH_PAGE_RANK_ITERATIONS=20
+export BARADB_GRAPH_LOUVAIN_RESOLUTION=1.0
+```
@@ -0,0 +1,373 @@
+# Протоколна Референция
+
+BaraDB поддържа множество протоколи за клиентска комуникация:
+- **Бинарен Wire Протокол** — високопроизводителен, ниска латентност
+- **HTTP/REST API** — езиково-независим, лесен за дебъгване
+- **WebSocket** — стрийминг и pub/sub
+
+---
+
+## Бинарен Wire Протокол
+
+Бинарният протокол използва big-endian кодиране за всички многобайтови стойности.
+
+### Жизнен Цикъл на Връзката
+
+```
+Клиент                          Сървър
+  |                               |
+  |─── TCP свързване ───────────>|
+  |<── TLS ръкостискане (опц.) ──|
+  |─── Auth съобщение ──────────>|
+  |<── Auth_OK / Грешка ─────────|
+  |─── Query съобщение ─────────>|
+  |<── Data / Complete / Error ──|
+  |─── Close съобщение ─────────>|
+  |<── TCP затваряне ────────────|
+```
+
+### Формат на Съобщенията
+
+Всяко съобщение започва с 12-байтов хедър:
+
+```
+┌─────────────┬─────────────┬─────────────┬─────────────────────┐
+│  Kind        │  Length     │  RequestId  │  Payload            │
+│  (4 bytes)   │  (4 bytes)  │  (4 bytes)  │                     │
+│  uint32 BE   │  uint32 BE  │  uint32 BE  │  (Length bytes)     │
+└─────────────┴─────────────┴─────────────┴─────────────────────┘
+```
+
+### Типове Съобщения
+
+| Тип | ID | Посока | Описание |
+|------|----|--------|----------|
+| Query | 0x01 | К→С | Изпълни заявка |
+| QueryParams | 0x02 | К→С | Параметризирана заявка |
+| Auth | 0x07 | К→С | Заявка за автентикация |
+| Ping | 0x09 | К→С | Keepalive ping |
+| Close | 0x0A | К→С | Затваряне на връзка |
+| Data | 0x81 | С→К | Резултат от заявка |
+| Complete | 0x82 | С→К | Заявката е завършена |
+| Auth_OK | 0x83 | С→К | Успешна автентикация |
+| Pong | 0x84 | С→К | Keepalive отговор |
+| Error | 0x06 | С→К | Грешка |
+
+### Query Съобщение Payload
+
+```
+┌───────────────────┬────────────────────────────┐
+│ Query String      │                            │
+│ (променлива)      │                            │
+│ UTF-8             │                            │
+└───────────────────┴────────────────────────────┘
+```
+
+### Data Съобщение Payload
+
+```
+┌──────────────┬─────────────────────────────────────────────┐
+│ Брой Колони  │ Дефиниции на Колони + Данни от Редове        │
+│ (4 bytes)    │                                             │
+│ uint32 BE    │                                             │
+└──────────────┴─────────────────────────────────────────────┘
+```
+
+### Типове Полета
+
+| Тип | ID | Размер | Описание |
+|------|----|--------|----------|
+| NULL | 0x00 | 0 | NULL стойност |
+| BOOL | 0x01 | 1 | true/false |
+| INT8 | 0x02 | 1 | Signed 8-bit integer |
+| INT16 | 0x03 | 2 | Signed 16-bit integer |
+| INT32 | 0x04 | 4 | Signed 32-bit integer |
+| INT64 | 0x05 | 8 | Signed 64-bit integer |
+| FLOAT32 | 0x06 | 4 | IEEE 754 единична точност (big-endian) |
+| FLOAT64 | 0x07 | 8 | IEEE 754 двойна точност (big-endian) |
+| STRING | 0x08 | променлив | UTF-8 низ (4-байтов префикс за дължина) |
+| BYTES | 0x09 | променлив | Сурови байтове (4-байтов префикс за дължина) |
+| ARRAY | 0x0A | променлив | Масив от стойности |
+| OBJECT | 0x0B | променлив | Ключ-стойност обект |
+| VECTOR | 0x0C | променлив | Float32 масив (4-байтов префикс, big-endian floats) |
+
+### Error Съобщение Payload
+
+```
+┌──────────────┬──────────────┬────────────────────────────┐
+│ Код Грешка   │ Дълж. Съобщ. │ Съобщение за Грешка        │
+│ (4 bytes)    │ (4 bytes)    │ (Дълж. Съобщ. bytes)      │
+│ uint32 BE    │ uint32 BE    │ UTF-8                      │
+└──────────────┴──────────────┴────────────────────────────┘
+```
+
+---
+
+## HTTP/REST API
+
+Базов URL: `http://localhost:9470/api/v1`
+
+### Endpoints
+
+#### Health
+
+```http
+GET /health
+```
+
+Отговор:
+```json
+{
+  "status": "healthy",
+  "version": "1.1.0",
+  "uptime_seconds": 86400
+}
+```
+
+#### Ready
+
+```http
+GET /ready
+```
+
+Връща `200` когато е готов, `503` при стартиране.
+
+#### Query
+
+```http
+POST /query
+Content-Type: application/json
+Authorization: Bearer <token>
+
+{
+  "query": "SELECT name, age FROM users WHERE age > 18",
+  "params": [],
+  "format": "json"
+}
+```
+
+Отговор:
+```json
+{
+  "columns": ["name", "age"],
+  "rows": [
+    ["Alice", 30],
+    ["Bob", 25]
+  ],
+  "row_count": 2,
+  "duration_ms": 12
+}
+```
+
+#### Batch
+
+```http
+POST /batch
+Content-Type: application/json
+
+{
+  "queries": [
+    "INSERT users { name := 'Alice', age := 30 }",
+    "INSERT users { name := 'Bob', age := 25 }"
+  ]
+}
+```
+
+Отговор:
+```json
+{
+  "results": [
+    {"status": "ok", "affected_rows": 1},
+    {"status": "ok", "affected_rows": 1}
+  ]
+}
+```
+
+#### Schema
+
+```http
+GET /schema
+```
+
+#### Metrics
+
+```http
+GET /metrics
+```
+
+Prometheus-съвместими метрики. Виж [Ръководство за Мониторинг](monitoring.md).
+
+#### Explain
+
+```http
+POST /explain
+Content-Type: application/json
+
+{
+  "query": "SELECT * FROM users WHERE age > 18"
+}
+```
+
+Отговор:
+```json
+{
+  "plan": "IndexScan",
+  "index": "idx_users_age",
+  "estimated_rows": 42,
+  "cost": 120
+}
+```
+
+#### Backup
+
+```http
+POST /backup
+Content-Type: application/json
+
+{
+  "destination": "/backup/snapshot.db"
+}
+```
+
+#### Административни Операции
+
+```http
+POST /admin/compact
+POST /admin/rebalance
+POST /admin/check
+```
+
+### HTTP Статус Кодове
+
+| Код | Значение |
+|------|----------|
+| 200 | Успех |
+| 400 | Лоша заявка (синтактична грешка) |
+| 401 | Неоторизиран (изисква се auth) |
+| 403 | Забранен (недостатъчни права) |
+| 404 | Не е намерен (таблица/тип не съществува) |
+| 429 | Твърде много заявки (rate limited) |
+| 500 | Вътрешна сървърна грешка |
+| 503 | Услугата е недостъпна (стартира) |
+
+---
+
+## WebSocket Протокол
+
+URL: `ws://localhost:9471`
+
+### Формат на Frame
+
+WebSocket текстови frame-ове съдържат JSON съобщения:
+
+```json
+{
+  "id": 1,
+  "type": "query",
+  "query": "SELECT * FROM users"
+}
+```
+
+### Типове Съобщения
+
+| Тип | Посока | Описание |
+|------|--------|----------|
+| `query` | К→С | Изпълни заявка |
+| `subscribe` | К→С | Абониране за промени |
+| `unsubscribe` | К→С | Отписване |
+| `ping` | К→С | Keepalive |
+| `result` | С→К | Резултат от заявка |
+| `notification` | С→К | Известие за промяна |
+| `error` | С→К | Грешка |
+| `pong` | С→К | Keepalive отговор |
+
+### Pub/Sub Пример
+
+```javascript
+const ws = new WebSocket('ws://localhost:9471');
+
+ws.onopen = () => {
+  // Абониране за промени в таблица
+  ws.send(JSON.stringify({
+    id: 1,
+    type: 'subscribe',
+    table: 'users'
+  }));
+};
+
+ws.onmessage = (event) => {
+  const msg = JSON.parse(event.data);
+  if (msg.type === 'notification') {
+    console.log('Промяна:', msg.operation, msg.data);
+  }
+};
+```
+
+### Стрийминг Заявки
+
+```javascript
+ws.send(JSON.stringify({
+  id: 2,
+  type: 'query',
+  query: 'SELECT * FROM logs ORDER BY timestamp',
+  streaming: true
+}));
+
+// Сървърът изпраща множество result frame-ове
+// Последният frame има {"complete": true}
+```
+
+---
+
+## Nim API Примери
+
+### Бинарен Протокол
+
+```nim
+import barabadb/protocol/wire
+
+let msg = makeQueryMessage(1, "SELECT * FROM users")
+let ready = makeReadyMessage(1)
+let error = makeErrorMessage(1, 42, "Syntax error")
+```
+
+### Connection Pool
+
+```nim
+import barabadb/protocol/pool
+
+var pool = newConnectionPool(
+  minConnections = 5,
+  maxConnections = 100,
+  idleTimeout = 30000
+)
+let conn = pool.acquire()
+# Използване на връзка...
+pool.release(conn)
+```
+
+### Автентикация
+
+```nim
+import barabadb/protocol/auth
+
+var am = newAuthManager("secret-key")
+let token = am.createToken(JWTClaims(sub: "user1", role: "admin"))
+let result = am.validateCredentials(
+  AuthCredentials(authMethod: amToken, payload: token)
+)
+```
+
+### Rate Limiting
+
+```nim
+import barabadb/protocol/ratelimit
+
+var rl = newRateLimiter(
+  rlaTokenBucket,
+  globalRate = 10000,
+  perClientRate = 1000
+)
+if rl.allowRequest("client-123"):
+  echo "Заявката е разрешена"
+```
@@ -0,0 +1,210 @@
+# Ръководство за Сигурност
+
+## TLS/SSL Криптиране
+
+BaraDB поддържа TLS 1.3 за всички протоколи (бинарен, HTTP, WebSocket). Ако не е предоставен сертификат, сървърът автоматично генерира self-signed сертификат при стартиране за криптиране без конфигурация.
+
+### Използване на Персонализирани Сертификати
+
+```bash
+# Предоставяне на съществуващи сертификати
+BARADB_TLS_ENABLED=true \
+BARADB_CERT_FILE=/etc/baradb/server.crt \
+BARADB_KEY_FILE=/etc/baradb/server.key \
+./build/baradadb
+```
+
+### Генериране на Self-Signed Сертификати
+
+```bash
+openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt \
+  -days 365 -nodes -subj "/CN=localhost"
+```
+
+### Let's Encrypt (Продукция)
+
+Използвайте certbot и насочете BaraDB към генерираните файлове:
+
+```bash
+sudo certbot certonly --standalone -d db.example.com
+
+BARADB_CERT_FILE=/etc/letsencrypt/live/db.example.com/fullchain.pem \
+BARADB_KEY_FILE=/etc/letsencrypt/live/db.example.com/privkey.pem \
+./build/baradadb
+```
+
+### TLS от Страна на Клиента
+
+```python
+from baradb import Client
+
+client = Client("localhost", 9472, tls=True, tls_verify=True)
+client.connect()
+```
+
+## Автентикация
+
+### JWT-Базирана Автентикация
+
+BaraDB използва JWT (JSON Web Tokens) с HMAC-SHA256 подписване.
+
+#### Включване на Автентикация
+
+```bash
+BARADB_AUTH_ENABLED=true \
+BARADB_JWT_SECRET="$(openssl rand -hex 32)" \
+./build/baradadb
+```
+
+#### Създаване на Токени
+
+```nim
+import barabadb/protocol/auth
+
+var am = newAuthManager("your-secret-key")
+let token = am.createToken(JWTClaims(
+  sub: "user1",
+  role: "admin",
+  exp: getTime() + 24.hours
+))
+```
+
+#### Контрол на Достъп на База Роли
+
+| Роля | Права |
+|------|-------|
+| `admin` | Пълен достъп |
+| `write` | Четене + запис |
+| `read` | Само четене |
+| `monitor` | Само метрики и health |
+
+#### Използване на Токени
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  http://localhost:9470/api/query \
+  -d '{"query": "SELECT * FROM users"}'
+```
+
+```python
+from baradb import Client
+
+client = Client("localhost", 9472)
+client.connect()
+client.authenticate("eyJhbGciOiJIUzI1NiIs...")
+```
+
+### Многофакторна Автентикация (MFA)
+
+```nim
+import barabadb/protocol/auth
+
+var am = newAuthManager("secret-key")
+# TOTP-базирана MFA
+let mfaCode = am.generateTOTP("user1")
+let valid = am.validateTOTP("user1", mfaCode)
+```
+
+## Rate Limiting
+
+Token-bucket rate limiting предотвратява злоупотреби:
+
+```nim
+import barabadb/protocol/ratelimit
+
+var rl = newRateLimiter(
+  rlaTokenBucket,
+  globalRate = 10000,      # 10K заявки/s глобално
+  perClientRate = 1000,    # 1K заявки/s на IP/токен
+  burstSize = 100          # Разрешаване на 100 заявки burst
+)
+
+if not rl.allowRequest("client-ip"):
+  return error("Лимитът на заявки е надвишен")
+```
+
+## Мрежова Сигурност
+
+### Адрес за Свързване
+
+По подразбиране BaraDB се свързва към `127.0.0.1` (само localhost). За продукция:
+
+```bash
+# Свързване към всички интерфейси (зад защитна стена или reverse proxy)
+BARADB_ADDRESS=0.0.0.0 ./build/baradadb
+
+# Свързване към конкретен вътрешен интерфейс
+BARADB_ADDRESS=10.0.0.5 ./build/baradadb
+```
+
+### Правила на Защитната Стена
+
+```bash
+# Разрешаване само на сървъри на приложения
+sudo ufw allow from 10.0.0.0/8 to any port 9472
+sudo ufw allow from 10.0.0.0/8 to any port 9470
+
+# Блокиране на външен достъп до портове за управление
+sudo ufw deny 9471  # WebSocket (само вътрешна употреба)
+```
+
+## Криптиране на Данни в Покой
+
+### Криптиране на Ниво ОС
+
+Използвайте LUKS за пълно дисково криптиране:
+
+```bash
+cryptsetup luksFormat /dev/nvme0n1p2
+cryptsetup open /dev/nvme0n1p2 baradb-crypt
+mkfs.ext4 /dev/mapper/baradb-crypt
+mount /dev/mapper/baradb-crypt /var/lib/baradb
+```
+
+### Криптиране на Ниво Приложение
+
+BaraDB поддържа прозрачно криптиране на SSTable файлове:
+
+```bash
+BARADB_STORAGE_ENCRYPTION_KEY="$(openssl rand -hex 32)" \
+./build/baradadb
+```
+
+## Одитно Логване
+
+Всички заявки и административни действия се логват:
+
+```json
+{
+  "timestamp": "2025-01-15T10:30:00Z",
+  "level": "info",
+  "event": "query_executed",
+  "client_ip": "10.0.0.15",
+  "user": "app_user",
+  "query": "SELECT * FROM users WHERE id = ?",
+  "duration_ms": 12,
+  "rows_returned": 1
+}
+```
+
+Включване на одитно логване:
+
+```bash
+BARADB_LOG_LEVEL=info \
+BARADB_LOG_FORMAT=json \
+BARADB_LOG_FILE=/var/log/baradb/audit.log \
+./build/baradadb
+```
+
+## Чеклист за Сигурност
+
+- [ ] Сменете JWT secret по подразбиране
+- [ ] Включете TLS с валидни сертификати
+- [ ] Свържете се към конкретни интерфейси
+- [ ] Включете автентикация в продукция
+- [ ] Конфигурирайте rate limiting
+- [ ] Включете одитно логване
+- [ ] Криптирайте данните в покой (LUKS или на ниво приложение)
+- [ ] Стартирайте BaraDB като non-root потребител
+- [ ] Поддържайте рестриктивни правила на защитната стена
+- [ ] Ротирайте JWT secret-и редовно
@@ -0,0 +1,78 @@
+# Storage Engines
+
+BaraDB предоставя множество storage двигатели, оптимизирани за различни модели на достъп.
+
+## LSM-Tree (Key-Value)
+
+Основният storage engine с write-оптимизирана append-only лог структура.
+
+### Употреба
+
+```nim
+import barabadb/storage/lsm
+
+var db = newLSMTree("./data")
+db.put("key1", cast[seq[byte]]("value1"))
+let (found, value) = db.get("key1")
+db.close()
+```
+
+### Компоненти
+
+- **MemTable**: В-памет сортиран буфер
+- **WAL**: Write-ahead log за устойчивост
+- **SSTable**: Сортирани string таблици на диска
+- **Bloom Filter**: Вероятностна проверка за принадлежност
+- **Compaction**: Size-tiered стратегия с управление на нива
+- **Page Cache**: LRU кеш с проследяване на hit rate
+
+## B-Tree Индекс
+
+Подреден индекс за range сканиране и точково търсене.
+
+### Употреба
+
+```nim
+import barabadb/storage/btree
+
+var btree = newBTreeIndex[string, string]()
+btree.insert("key1", "value1")
+let values = btree.get("key1")
+let range = btree.scan("key_a", "key_z")
+```
+
+## Write-Ahead Log (WAL)
+
+Осигурява устойчивост на операциите за запис.
+
+```nim
+import barabadb/storage/wal
+
+var wal = newWAL("./wal")
+wal.append("txn1", "SET key1 value1")
+wal.flush()
+```
+
+## Bloom Filter
+
+Вероятностна структура от данни за бързи негативни проверки.
+
+```nim
+import barabadb/storage/bloom
+
+var filter = newBloomFilter(10000, 0.01)
+filter.add("key1")
+if filter.mightContain("key1"):
+  echo "евентуално съществува"
+```
+
+## Memory-mapped I/O
+
+Ефективен достъп до файлове чрез mmap.
+
+```nim
+import barabadb/storage/mmap
+
+var mapped = mmapFile("./data/file.dat")
+let data = mapped.read(0, 100)
+```
@@ -1,6 +1,6 @@
-# Транзакции & MVCC
+# Транзакции и MVCC

-Multi-Version Concurrency Control със snapshot изолация.
+MVCC (Multi-Version Concurrency Control) със snapshot изолация и deadlock детекция.

 ## Употреба

@@ -10,21 +10,55 @@ import barabadb/core/mvcc
 var tm = newTxnManager()
 let txn = tm.beginTxn()

+# Операции за запис
 discard tm.write(txn, "key1", cast[seq[byte]]("value1"))
 discard tm.write(txn, "key2", cast[seq[byte]]("value2"))

+# Savepoint
 tm.savepoint(txn)
-discard tm.rollbackToSavepoint(txn)
+discard tm.write(txn, "key3", cast[seq[byte]]("value3"))
+discard tm.rollbackToSavepoint(txn)  # отмяна на key3

+# Commit
 discard tm.commit(txn)
 ```

-## Изолация
+## Изолация на Транзакции

-BaraDB използва **snapshot isolation**:
- Читателите не блокират писатели
- Писателите не блокират читатели
- Всяка транзакция вижда консистентен моментна снимка
+BaraDB използва **snapshot изолация**:
+- Четящите не блокират пишещите
+- Пишещите не блокират четящите
+- Всяка транзакция вижда консистентен snapshot
+
+## Deadlock Детекция
+
+```nim
+import barabadb/core/deadlock
+
+var detector = newDeadlockDetector()
+if detector.detectCycle(txn1, txn2):
+  echo "Открит deadlock!"
+```
+
+## Write-Ahead Log
+
+```nim
+import barabadb/storage/wal
+
+var wal = newWAL("./wal")
+wal.append(txnId, "SET key value")
+wal.flush()
+```
+
+## Savepoints
+
+Вложени savepoints на транзакции:
+
+```nim
+tm.savepoint(txn, "sp1")
+# ... операции ...
+tm.rollbackToSavepoint(txn, "sp1")
+```

 ## Формална Верификация

@@ -32,13 +66,13 @@ MVCC / Snapshot Isolation протоколът е формално специф

 - **Спецификация:** `formal-verification/mvcc.tla`
 - **Проверени свойства:**
-  - `NoDirtyReads` — транзакциите никога не четат неcommit-нати данни
+  - `NoDirtyReads` — транзакциите никога не четат некомитнати данни
  - `ReadOwnWrites` — транзакциите винаги виждат собствените си записи
-  - `WriteWriteConflict` — first-committer-wins
+  - `WriteWriteConflict` — first-committer-wins (няма две комитнати транзакции да пишат един и същ ключ)

-Пускане на TLC:
+Пускане на TLC локално:

 ```bash
 cd formal-verification
 java -cp tla2tools.jar tlc2.TLC -config models/mvcc.cfg mvcc.tla
-```
+```
@@ -0,0 +1,164 @@
+# Ръководство за Отстраняване на Проблеми
+
+## Проблеми с Инсталацията
+
+### Nim не е намерен
+
+```
+nim: command not found
+```
+
+**Решение:**
+
+```bash
+# Linux/macOS
+curl https://nim-lang.org/choosenim/init.sh -sSf | sh
+
+# Добавяне към PATH
+echo 'export PATH=$HOME/.nimble/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### SSL Грешка при Компилация
+
+```
+Error: BaraDB requires SSL support. Compile with -d:ssl
+```
+
+**Решение:** Винаги компилирайте с `-d:ssl`:
+
+```bash
+nim c -d:ssl -d:release -o:build/baradadb src/baradadb.nim
+```
+
+### Липсващи Зависимости
+
+```
+Error: cannot open file: hunos
+```
+
+**Решение:**
+
+```bash
+nimble install -d -y
+```
+
+## Проблеми по Време на Изпълнение
+
+### Портът е Зает
+
+```
+Error: unhandled exception: Address already in use [OSError]
+```
+
+**Решение 1:** Сменете порта:
+
+```bash
+BARADB_PORT=5433 ./build/baradadb
+```
+
+**Решение 2:** Убийте съществуващия процес:
+
+```bash
+lsof -ti:9472 | xargs kill -9
+```
+
+### Permission Denied на Директория с Данни
+
+```
+Error: Permission denied: ./data
+```
+
+**Решение:**
+
+```bash
+mkdir -p ./data
+chmod 755 ./data
+# или използвайте друга директория
+BARADB_DATA_DIR=/tmp/baradb ./build/baradadb
+```
+
+## Storage Проблеми
+
+### Бавни Заявки
+
+1. Проверете cache hit rate:
+```bash
+curl http://localhost:9470/metrics | grep cache_hit_rate
+```
+
+2. Пуснете ръчен compaction:
+```bash
+curl -X POST http://localhost:9470/admin/compact
+```
+
+3. Проверете броя на SSTables:
+```bash
+curl http://localhost:9470/metrics | grep sstables
+```
+
+### Растящо Дисково Пространство
+
+```bash
+# Проверете размера на директорията с данни
+du -sh ./data
+
+# Проверете WAL размера
+du -sh ./data/server/wal
+
+# Пуснете ръчен compaction за освобождаване на място
+curl -X POST http://localhost:9470/admin/compact
+```
+
+## Проблеми с Автентикация
+
+### Грешка при Верификация на JWT
+
+```json
+{"error": {"code": "AUTH_REQUIRED", "message": "Authentication required"}}
+```
+
+**Решение:** Уверете се, че изпращате правилния токен:
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  http://localhost:9470/api/query \
+  -d '{"query": "SELECT 1"}'
+```
+
+## Разпределени Проблеми
+
+### Възел не се Присъединява към Клъстер
+
+1. Проверете мрежовата свързаност между възлите
+2. Проверете gossip порта (raft порт + 100)
+3. Проверете логовете за грешки при gossip
+
+### Репликационно Закъснение
+
+```bash
+# Проверете replication lag
+curl http://localhost:9470/metrics/cluster | jq .replication_lag_ms
+```
+
+## Често Задавани Въпроси
+
+### Как да нулирам напълно базата данни?
+
+```bash
+# Спрете сървъра
+# Изтрийте директорията с данни
+rm -rf ./data
+# Стартирайте отново — нова празна база ще бъде създадена
+./build/baradadb
+```
+
+### Как да мигрирам от друга база данни?
+
+BaraDB поддържа импорт чрез JSON и CSV:
+
+```bash
+curl -X POST http://localhost:9470/api/import \
+  -H "Content-Type: application/json" \
+  -d '{"table": "users", "format": "json", "data": [...]}'
+```
@@ -0,0 +1,55 @@
+# Потребителски Функции (UDF)
+
+Разширете BaraQL с персонализирани функции.
+
+## Употреба
+
+```nim
+import barabadb/query/udf
+
+var reg = newUDFRegistry()
+
+# Регистриране на стандартна библиотека
+reg.registerStdlib()  # abs, sqrt, pow, lower, upper, len, trim, substr, toString, toInt
+
+# Персонализирана функция
+reg.register("greet", @[UDFParam(name: "name", typeName: "str")],
+  "str", proc(args: seq[Value]): Value =
+    return Value(kind: vkString, strVal: "Hello, " & args[0].strVal & "!"))
+```
+
+## Функции от Стандартната Библиотека
+
+| Функция | Описание | Пример |
+|----------|----------|--------|
+| `abs(n)` | Абсолютна стойност | `abs(-5)` → 5 |
+| `sqrt(n)` | Квадратен корен | `sqrt(16)` → 4 |
+| `pow(n, e)` | Степенуване | `pow(2, 3)` → 8 |
+| `lower(s)` | Малки букви | `lower('ABC')` → 'abc' |
+| `upper(s)` | Главни букви | `upper('abc')` → 'ABC' |
+| `len(s)` | Дължина | `len('hello')` → 5 |
+| `trim(s)` | Премахване на интервали | `trim(' hello ')` → 'hello' |
+| `substr(s, start, len)` | Подниз | `substr('hello', 0, 3)` → 'hel' |
+| `toString(n)` | Конвертиране в низ | `toString(123)` → '123' |
+| `toInt(s)` | Конвертиране в integer | `toInt('123')` → 123 |
+
+## Регистриране на Функции
+
+```nim
+reg.register(
+  name: "my_function",
+  params: @[
+    UDFParam(name: "arg1", typeName: "str"),
+    UDFParam(name: "arg2", typeName: "int32")
+  ],
+  returnType: "str",
+  body: proc(args: seq[Value]): Value =
+    result = Value(kind: vkString, strVal: "")
+)
+```
+
+## Използване на UDF в Заявки
+
+```sql
+SELECT greet(name) FROM users;
+```
@@ -1,8 +1,89 @@
-# Vector Търсене
+# Vector Search Engine

-HNSW и IVF-PQ индекси за търсене на прилика.
+Нативни HNSW и IVF-PQ индекси за търсене на прилика с пълна SQL интеграция.

-## Употреба
+## SQL Употреба
+
+### Създаване на Векторни Колони
+
+```sql
+CREATE TABLE items (
+  id INT PRIMARY KEY,
+  embedding VECTOR(768)
+);
+```
+
+Типът `VECTOR(n)` съхранява float32 масиви с фиксирана размерност `n`.
+
+### Вмъкване на Вектори
+
+```sql
+INSERT INTO items (id, embedding) VALUES (1, '[0.1, 0.2, 0.3, ...]');
+```
+
+### Функции за Векторно Разстояние
+
+```sql
+-- Косинусово разстояние (0 = идентични, 1 = ортогонални)
+SELECT id, cosine_distance(embedding, '[0.1, 0.2, 0.3]') AS dist
+FROM items;
+
+-- Евклидово / L2 разстояние
+SELECT id, euclidean_distance(embedding, '[0.1, 0.2, 0.3]') AS dist
+FROM items;
+
+-- L2 разстояние с <-> оператор
+SELECT id, embedding <-> '[0.1, 0.2, 0.3]' AS dist
+FROM items;
+
+-- Скаларно произведение (отрицателно dot product за минимизация)
+SELECT id, inner_product(embedding, '[0.1, 0.2, 0.3]') AS dist
+FROM items;
+
+-- Манхатън / L1 разстояние
+SELECT id, l1_distance(embedding, '[0.1, 0.2, 0.3]') AS dist
+FROM items;
+```
+
+### Търсене на Най-близки Съседи
+
+```sql
+-- Топ-10 най-близки съседи по косинусово разстояние
+SELECT id FROM items
+ORDER BY cosine_distance(embedding, '[0.1, 0.2, 0.3]') ASC
+LIMIT 10;
+
+-- Топ-5 най-близки съседи по евклидово разстояние
+SELECT id FROM items
+ORDER BY embedding <-> '[0.1, 0.2, 0.3]'
+LIMIT 5;
+```
+
+### Векторни Индекси
+
+```sql
+-- Създаване на HNSW индекс за приблизително търсене на най-близки съседи
+CREATE INDEX idx_items_vec ON items(embedding) USING hnsw;
+
+-- Индексът се поддържа автоматично при INSERT и UPDATE
+```
+
+Поддържани индекс методи:
+- `USING hnsw` — Hierarchical Navigable Small World (по подразбиране: косинусова метрика)
+- `USING ivfpq` — Inverted File с Product Quantization
+
+### Валидация на Размерност
+
+BaraDB валидира размерностите на векторите при вмъкване:
+
+```sql
+-- Това ще даде грешка: очаквани 768 размерности, но подадени 3
+INSERT INTO items (id, embedding) VALUES (2, '[1.0, 2.0, 3.0]');
+```
+
+## Нативно Nim API
+
+За вградена или високопроизводителна употреба използвайте нативното Nim API директно:

 ```nim
 import barabadb/vector/engine
@@ -10,32 +91,67 @@ import barabadb/vector/engine
 var idx = newHNSWIndex(dimensions = 128)
 idx.insert(1, @[1.0'f32, 0.0'f32, ...], {"category": "A"}.toTable)

+# Търсене
 let results = idx.search(queryVector, k = 10)
+
+# С филтриране по метаданни
+let filtered = idx.searchWithFilter(queryVector, k = 10,
+  filter = proc(meta: Table[string, string]): bool =
+    return meta.getOrDefault("category") == "A")
 ```

-## Индекс Типове
+## Типове Индекси

 ### HNSW

-Иерархичен навигируем малък свят:
+Иерархичен навигируем малък свят за приблизително търсене на най-близки съседи.

 ```nim
-var hnsw = newHNSWIndex(dimensions = 128, m = 16)
+var hnsw = newHNSWIndex(
+  dimensions = 128,
+  m = 16,                # връзки на слой
+  efConstruction = 200,  # ширина на търсене при изграждане
+  efSearch = 100         # ширина на търсене при заявка
+)
 ```

 ### IVF-PQ

-Инвертиран файл с продуктово квантуване:
+Inverted File Index с продуктово квантуване за компресия.

 ```nim
-var ivfpq = newIVFPQIndex(dimensions = 128, numCentroids = 256)
+var ivfpq = newIVFPQIndex(
+  dimensions = 128,
+  numCentroids = 256,
+  subQuantizers = 8
+)
 ```

 ## Метрики за Разстояние

-| Метрика | Описание |
-|---------|----------|
-| `cosine` | Косинусова прилика |
-| `euclidean` | L2 разстояние |
-| `dotproduct` | Скаларно произведение |
-| `manhattan` | L1 разстояние |
+| Метрика | SQL Функция | Описание |
+|---------|-------------|----------|
+| `cosine` | `cosine_distance(a, b)` | Косинусова dissimilarity (1 - similarity) |
+| `euclidean` | `euclidean_distance(a, b)` / `<->` | L2 разстояние |
+| `dotproduct` | `inner_product(a, b)` | Отрицателно скаларно произведение |
+| `manhattan` | `l1_distance(a, b)` | L1 разстояние |
+
+## Квантуване
+
+```nim
+import barabadb/vector/quant
+
+# Скаларно квантуване
+let scalar = scalarQuantize(data, bits = 8)
+
+# Продуктово квантуване
+let pq = productQuantize(data, subVectors = 8, bits = 8)
+```
+
+## SIMD Ускорение
+
+```nim
+import barabadb/vector/simd
+
+let dist = simdCosineDistance(vec1, vec2)
+```