Add comprehensive documentation with i18n support (EN/BG)

- Add docs/ folder with English (en/) and Bulgarian (bg/) documentation - Create index.md with language switching and links - English docs: installation, quickstart, architecture, baraql, storage, schema, lsm, btree, vector, graph, fts, columnar, transactions, distributed, protocol, udf, api-binary, api-http, api-websocket - Bulgarian docs: installation, quickstart, architecture, baraql, schema, lsm, btree, vector, graph, fts, transactions, distributed - Update README license to BSD 3-Clause - Add LICENSE file with BSD 3-Clause text
2026-05-06 16:51:14 +03:00
parent f9f77b3a18
commit e1bae0c7a0
34 changed files with 2370 additions and 1 deletions
@@ -0,0 +1,78 @@
+# BaraDB Архитектура
+
+## Преглед
+
+BaraDB е **мултимодална база данни** написана на Nim, която комбинира документно (KV), графично, векторно, колонно и пълнотекстово търсене в един двигател с обединен език за заявки наречен **BaraQL**.
+
+## Слоеста Архитектура
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 1. СЛОЙ ЗА КЛИЕНТИ                                       │
+│    Binary Protocol │ HTTP/REST │ WebSocket │ Embedded    │
+├─────────────────────────────────────────────────────────┤
+│ 2. ЗАЯВКИ СЛОЙ (BaraQL)                                 │
+│    Lexer → Parser → AST → IR → Optimizer → Codegen     │
+├─────────────────────────────────────────────────────────┤
+│ 3. ИЗПЪЛНИТЕЛЕН ДВИГАТЕЛ                                  │
+│    Document │ Graph │ Vector │ Columnar │ FTS           │
+├─────────────────────────────────────────────────────────┤
+│ 4. СЪХРАНЕНИЕ                                            │
+│    LSM-Tree │ B-Tree │ WAL │ Bloom │ Compaction │ Cache │
+├─────────────────────────────────────────────────────────┤
+│ 5. РАЗПРЕДЕЛЕНО                                          │
+│    Raft Consensus │ Sharding │ Replication │ Gossip    │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Слой 1: Клиентски Слой
+
+Множество протоколи за комуникация:
+
+- **Binary Protocol**: Ефективен протокол с 16 типа съобщения
+- **HTTP/REST**: JSON-basiran REST API
+- **WebSocket**: Пълен дуплекс стрийминг
+- **Embedded**: Директен достъп в процеса
+
+## Слой 2: Заявки (BaraQL)
+
+Pipeline-а на BaraQL:
+
+1. **Lexer**: Токенизира входа в 80+ типа токени
+2. **Parser**: Рекурсивен descent парсър произвеждащ AST
+3. **AST**: 300+ реда покриващи 25+ вида възли
+4. **IR**: Междинно представяне за планове за изпълнение
+5. **Optimizer/Codegen**: Транслира IR към операции върху съхранение
+
+## Слой 3: Изпълнителен Двигател
+
+### Document/KV Двигател
+- **LSM-Tree**: Оптимизиран за запис
+- **B-Tree Index**: Подреден индекс за диапазони
+
+### Vector Engine
+- **HNSW**: Иерархичен навигируем малък свят
+- **IVF-PQ**: Инвертиран файл с продуктово квантуване
+- **SIMD**: Ускорени разстояния
+
+### Graph Engine
+- **Списък със съседи**: Насочен граф с тегла
+- **Алгоритми**: BFS, DFS, Dijkstra, PageRank, Louvain
+
+### FTS
+- **Инвертиран индекс**: Термин-документ индекс
+- **Ранжиране**: BM25 и TF-IDF
+- **Многоезичен**: Токенизация за EN, BG, DE, FR, RU
+
+## Слой 4: Съхранение
+
+- **LSM-Tree**: MemTable, WAL, SSTable, Bloom Filter, Compaction
+- **Page Cache**: LRU кеш
+- **Memory-mapped I/O**: mmap-базиран достъп
+
+## Слой 5: Разпределено
+
+- **Raft Consensus**: Лидерско избиране, репликация на логове
+- **Sharding**: Hash, range и консистентно хеширане
+- **Replication**: Sync, async, semi-sync режими
+- **Gossip Protocol**: Управление на членство
@@ -0,0 +1,110 @@
+# BaraQL - Референция на Езика
+
+BaraQL е SQL-съвместим език за заявки с разширения за графи, вектори и документи.
+
+## Основни Заявки
+
+### SELECT
+
+```sql
+SELECT name, age FROM users WHERE age > 18 ORDER BY name LIMIT 10;
+```
+
+### INSERT
+
+```sql
+INSERT users { name := 'Alice', age := 30 };
+```
+
+### UPDATE
+
+```sql
+UPDATE users SET age = 31 WHERE name = 'Alice';
+```
+
+### DELETE
+
+```sql
+DELETE FROM users WHERE name = 'Bob';
+```
+
+## Агрегати и Групиране
+
+```sql
+SELECT department, count(*), avg(salary)
+FROM employees
+GROUP BY department
+HAVING count(*) > 5;
+```
+
+## JOINs
+
+```sql
+-- INNER JOIN
+SELECT u.name, o.total
+FROM users u
+INNER JOIN orders o ON u.id = o.user_id;
+
+-- LEFT JOIN
+SELECT u.name, o.total
+FROM users u
+LEFT JOIN orders o ON u.id = o.user_id;
+```
+
+## CTEs (Common Table Expressions)
+
+```sql
+WITH active_users AS (
+  SELECT * FROM users WHERE active = true
+)
+SELECT * FROM active_users;
+```
+
+## CASE Изрази
+
+```sql
+SELECT name,
+  CASE
+    WHEN age < 18 THEN 'minor'
+    WHEN age < 65 THEN 'adult'
+    ELSE 'senior'
+  END AS category
+FROM users;
+```
+
+## Схема
+
+```sql
+CREATE TYPE Person {
+  name: str,
+  age: int32
+};
+```
+
+## Векторно Търсене
+
+```sql
+INSERT articles {
+  title := 'Nim Programming',
+  embedding := [0.1, 0.2, 0.3, ...]
+};
+
+SELECT title FROM articles
+ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, ...])
+LIMIT 5;
+```
+
+## Графични Шаблони
+
+```sql
+MATCH (p:Person)-[:KNOWS]->(friend:Person)
+WHERE p.name = 'Alice'
+RETURN friend.name;
+```
+
+## Пълнотекстово Търсене
+
+```sql
+SELECT * FROM articles
+WHERE MATCH(title, body) AGAINST('database programming');
+```
@@ -0,0 +1,22 @@
+# B-Tree Индекс
+
+Подредена индексна структура за ефективни диапазонни заявки.
+
+## Употреба
+
+```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")
+```
+
+## Функции
+
+- Подредени ключ-стойност двойки
+- Диапазонни заявки (BETWEEN, >, <, >=, <=)
+- Префиксни сканирания
+- Конфигурируем размер на страницата
@@ -0,0 +1,37 @@
+# Разпределена Система
+
+Поддръжка за разпределено внедряване с Raft консенсус, шардиране и репликация.
+
+## Raft Консенсус
+
+```nim
+import barabadb/core/raft
+
+var cluster = newRaftCluster()
+cluster.addNode("node1")
+cluster.addNode("node2")
+cluster.addNode("node3")
+
+let n1 = cluster.nodes["n1"]
+n1.becomeLeader()
+```
+
+## Шардиране
+
+```nim
+import barabadb/core/sharding
+
+var router = newShardRouter(ShardConfig(numShards: 4, replicas: 2))
+router.rebalance(@["node1", "node2", "node3"])
+let shard = router.getShard("user_123")
+```
+
+## Репликация
+
+```nim
+import barabadb/core/replication
+
+var rm = newReplicationManager(rmSync)
+rm.addReplica(newReplica("r1", "10.0.0.1", 5432))
+rm.connectReplica("r1")
+```
@@ -0,0 +1,35 @@
+# Пълнотекстово Търсене
+
+Инвертиран индекс с BM25 и TF-IDF ранжиране.
+
+## Употреба
+
+```nim
+import barabadb/fts/engine
+
+var idx = newInvertedIndex()
+idx.addDocument(1, "Nim е бърз език за програмиране")
+idx.addDocument(2, "Python е популярен за data science")
+
+let results = idx.search("език програмиране")
+let tfidf = idx.searchTfidf("език")
+let fuzzy = idx.fuzzySearch("програмиране", maxDistance = 2)
+```
+
+## Методи за Ранжиране
+
+### BM25
+
+Най-добрият алгоритъм за съвпадение
+
+### TF-IDF
+
+Term Frequency-Inverse Document Frequency
+
+## Търсене
+
+| Тип | Описание |
+|-----|----------|
+| Fuzzy | Толерантност към правописни грешки |
+| Wildcard | Префикс, суфикс, и инфикс заместващи символи |
+| Regex | Регулярни изрази |
@@ -0,0 +1,28 @@
+# Graph Engine
+
+Съхранение със списък от съседи и вградени алгоритми.
+
+## Употреба
+
+```nim
+import barabadb/graph/engine
+
+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 bfs = g.bfs(alice)
+let path = g.shortestPath(alice, bob)
+let ranks = g.pageRank()
+```
+
+## Алгоритми
+
+| Алгоритъм | Описание |
+|-----------|----------|
+| `bfs` | breadth-first обхождане |
+| `dfs` | depth-first обхождане |
+| `dijkstra` | Най-кратък път с тегла |
+| `pageRank` | Ранг на възел |
+| `louvain` | Откриване на общности |
@@ -0,0 +1,96 @@
+# BaraDB - Ръководство за Инсталация
+
+## Изисквания
+
+- **Nim Компилатор** >= 2.0.0
+- **Операционна система**: Linux, macOS, Windows
+
+## Инсталиране на Nim
+
+### Linux/macOS
+
+```bash
+curl https://nim-lang.org/choosenim/init.sh -sSf | sh
+```
+
+Или чрез пакетен мениджър:
+
+```bash
+# Ubuntu/Debian
+apt-get install nim
+
+# macOS
+brew install nim
+```
+
+### Windows
+
+Изтеглете инсталатора от [nim-lang.org](https://nim-lang.org/install.html) или използвайте winget:
+
+```powershell
+winget install nim
+```
+
+## Компилиране на BaraDB
+
+### Клониране на Репозиторито
+
+```bash
+git clone https://github.com/katehonz/barabaDB.git
+cd barabaDB
+```
+
+### Компилиране
+
+```bash
+# Debug компилация
+nim c -o:build/baradadb src/baradadb.nim
+
+# Release компилация (оптимизирана)
+nim c -d:release -o:build/baradadb src/baradadb.nim
+```
+
+### Стартиране на Тестове
+
+```bash
+nim c --path:src -r tests/test_all.nim
+```
+
+### Стартиране на Бенчмаркове
+
+```bash
+nim c -d:release -r benchmarks/bench_all.nim
+```
+
+## Опции за Инсталация
+
+### Docker
+
+```bash
+docker pull barabadb/barabadb
+docker run -it barabadb/barabadb
+```
+
+### Вградено Използване
+
+Добавете към вашия `.nimble` файл:
+
+```nim
+requires "barabadb >= 1.0.0"
+```
+
+След това импортнете в кода:
+
+```nim
+import barabadb
+
+var db = newLSMTree("./data")
+db.put("key1", cast[seq[byte]]("value1"))
+db.close()
+```
+
+## Следващи Стъпки
+
+- [Бързо Стартиране](bg/quickstart.md)
+- [Архитектура](bg/architecture.md)
+- [BaraQL Заявки](bg/baraql.md)
@@ -0,0 +1,25 @@
+# LSM-Tree Съхранение
+
+Основният двигател за съхранение използващ Log-Structured Merge-Tree архитектура.
+
+## Употреба
+
+```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**: Сортирани таблици на диска
+- **Bloom Filter**: Бързи негативни проверки
+- **Compaction**: Сливане на SSTables
+- **Page Cache**: LRU кеш
@@ -0,0 +1,117 @@
+# BaraDB - Бързо Стартиране
+
+## Стартиране на Сървъра
+
+След компилация, стартирайте сървъра:
+
+```bash
+./build/baradadb
+```
+
+Сървърът ще стартира на `localhost:8080` по подразбиране.
+
+## Свързване чрез CLI
+
+BaraDB включва интерактивна конзола:
+
+```bash
+./build/baradadb --shell
+```
+
+## Основни Операции
+
+### Създаване на Схема
+
+```sql
+CREATE TYPE Person {
+  name: str,
+  age: int32
+};
+
+CREATE TYPE Movie {
+  title: str,
+  year: int32,
+  director: Person
+};
+```
+
+### Вмъкване на Данни
+
+```sql
+INSERT Person { name := 'Alice', age := 30 };
+INSERT Person { name := 'Bob', age := 25 };
+```
+
+### Заявки
+
+```sql
+SELECT name, age FROM Person WHERE age > 18;
+```
+
+### Обновяване
+
+```sql
+UPDATE Person SET age = 31 WHERE name = 'Alice';
+```
+
+### Изтриване
+
+```sql
+DELETE FROM Person WHERE name = 'Bob';
+```
+
+## Разширени Заявки
+
+### JOIN
+
+```sql
+SELECT u.name, o.total
+FROM users u
+INNER JOIN orders o ON u.id = o.user_id;
+```
+
+### Агрегати
+
+```sql
+SELECT department, count(*), avg(salary)
+FROM employees
+GROUP BY department
+HAVING count(*) > 5;
+```
+
+### CTEs
+
+```sql
+WITH active_users AS (
+  SELECT * FROM users WHERE active = true
+)
+SELECT * FROM active_users;
+```
+
+## Търсене на Вектори
+
+```sql
+-- Вмъкване с вектор
+INSERT vectors { id := 1, embedding := [0.1, 0.2, 0.3] };
+
+-- Търсене на подобни
+SELECT * FROM vectors ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3]) LIMIT 10;
+```
+
+## HTTP/REST API
+
+```bash
+# GET заявка
+curl http://localhost:8080/api/users
+
+# POST заявка
+curl -X POST http://localhost:8080/api/users \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Alice", "age": 30}'
+```
+
+## Следващи Стъпки
+
+- [BaraQL Референция](bg/baraql.md)
+- [Схема](bg/schema.md)
+- [Архитектура](bg/architecture.md)
@@ -0,0 +1,40 @@
+# Схема на BaraDB
+
+BaraDB използва схема с типове, наследяване и автоматични миграции.
+
+## Дефиниране на Типове
+
+```nim
+import barabadb/schema/schema
+
+var s = newSchema()
+
+let person = newType("Person")
+person.addProperty("name", "str", required = true)
+person.addProperty("age", "int32")
+s.addType("default", person)
+```
+
+## Наследяване на Типове
+
+```nim
+let employee = newType("Employee")
+employee.setBases(@["Person"])
+employee.addProperty("department", "str")
+s.addType("default", employee)
+
+let resolved = s.resolveInheritance(employee)
+```
+
+## Типове Полета
+
+| Тип | Описание |
+|-----|---------|
+| `str` | Низ |
+| `int32` | 32-битово цяло число |
+| `int64` | 64-битово цяло число |
+| `float32` | 32-битов float |
+| `float64` | 64-битов float |
+| `bool` | Булева стойност |
+| `datetime` | Дата/час |
+| `bytes` | Двоични данни |
@@ -0,0 +1,27 @@
+# Транзакции & MVCC
+
+Multi-Version Concurrency Control със snapshot изолация.
+
+## Употреба
+
+```nim
+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"))
+
+tm.savepoint(txn)
+discard tm.rollbackToSavepoint(txn)
+
+discard tm.commit(txn)
+```
+
+## Изолация
+
+BaraDB използва **snapshot isolation**:
+- Читателите не блокират писатели
+- Писателите не блокират читатели
+- Всяка транзакция вижда консистентен моментна снимка
@@ -0,0 +1,41 @@
+# Vector Търсене
+
+HNSW и IVF-PQ индекси за търсене на прилика.
+
+## Употреба
+
+```nim
+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)
+```
+
+## Индекс Типове
+
+### HNSW
+
+Иерархичен навигируем малък свят:
+
+```nim
+var hnsw = newHNSWIndex(dimensions = 128, m = 16)
+```
+
+### IVF-PQ
+
+Инвертиран файл с продуктово квантуване:
+
+```nim
+var ivfpq = newIVFPQIndex(dimensions = 128, numCentroids = 256)
+```
+
+## Метрики за Разстояние
+
+| Метрика | Описание |
+|---------|----------|
+| `cosine` | Косинусова прилика |
+| `euclidean` | L2 разстояние |
+| `dotproduct` | Скаларно произведение |
+| `manhattan` | L1 разстояние |