baraba/Baradb
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: remove non-English/Bulgarian language docs, fix links

Browse Source 
Remove ar, de, fa, ru, tr, zh documentation folders.
Update docs/index.md and docs/bg/index.md to only list en/bg.
Update README badge from 7 to 2 languages.
Update changelog entry for Bulgarian docs.
This commit is contained in:
dimgigov
2026-05-21 09:44:17 +03:00
parent 372e5cf627
commit a526a3aef9
196 changed files with 6 additions and 20632 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+3 -3
View File
@@ -5,12 +5,12 @@
**A multimodal database engine written in Nim — 100% native, zero dependencies.**
[![Version](https://img.shields.io/badge/version-1.1.6-blue.svg)](baradadb.nimble)
[![Documentation](https://img.shields.io/badge/docs-7_languages-blue.svg)](docs/index.md)
[![Documentation](https://img.shields.io/badge/docs-2_languages-blue.svg)](docs/index.md)
[![Stars](https://img.shields.io/github/stars/katehonz/barabaDB?style=social)](https://github.com/katehonz/barabaDB)
## Documentation
📖 **[Read the documentation in your language](docs/index.md)** — English, Български, Русский, فارسی, 中文, Türkçe, العربية
📖 **[Read the documentation in your language](docs/index.md)** — English, Български
BaraDB combines document, graph, vector, columnar, and full-text search storage
in a single engine with a unified query language (BaraQL). It compiles to a
@@ -112,7 +112,7 @@ nimble bench
## BaraQL — Query Language
BaraQL is SQL-compatible with extensions for graph, vector, and document queries.
BaraQL implements partial SQL:2023 coverage with extensions for graph, vector, and document queries.
### Basic Queries
docs/ar/api-binary.md
-62
View File
@@ -1,62 +0,0 @@
# API البروتوكول الثنائي
بروتوكول سلكي منخفض المستوى لاتصالات العميل عالية الأداء.
## تنسيق الرسالة
جميع الرسائل تستخدم ترتيب big-endian:
```
┌────────┬────────┬────────┬────────┬─────────────┐
│ Length │ Type │ Seq │ Status │ Payload │
│ 4 bytes│ 1 byte │ 2 bytes│ 1 byte │ N bytes │
└────────┴────────┴────────┴────────┴─────────────┘
```
## أنواع الرسائل
### Query (0x01)
```nim
let msg = makeQueryMessage(seq, "SELECT * FROM users")
```
### Insert (0x02)
```nim
let msg = makeInsertMessage(seq, "users", data)
```
### Update (0x03)
```nim
let msg = makeUpdateMessage(seq, "users", updates, where)
```
### Delete (0x04)
```nim
let msg = makeDeleteMessage(seq, "users", where)
```
### Ready (0x05)
```nim
let msg = makeReadyMessage(seq)
```
### Error (0x06)
```nim
let msg = makeErrorMessage(seq, code, message)
```
## رموز الاستجابة
| الرمز | الاسم | الوصف |
|-------|-------|-------|
| 0x00 | OK | نجاح |
| 0x01 | ERROR | خطأ عام |
| 0x02 | AUTH_REQUIRED | مطلوب مصادقة |
| 0x03 | INVALID_QUERY | خطأ في بناء الجملة |
| 0x04 | NOT_FOUND | المورد غير موجود |
docs/ar/api-http.md
-62
View File
@@ -1,62 +0,0 @@
# API HTTP/REST
API REST مبني على JSON لتطبيقات الويب.
## Base URL
```
http://localhost:9470/api
```
## نقاط النهاية
### GET /api/users
قائمة جميع المستخدمين:
```bash
curl http://localhost:9470/api/users
```
### GET /api/users/:id
الحصول على المستخدم بالـ ID:
```bash
curl http://localhost:9470/api/users/1
```
### POST /api/users
إنشاء مستخدم:
```bash
curl -X POST http://localhost:9470/api/users \
-d '{"Name": "Charlie", "age": 35}'
```
### PUT /api/users/:id
تحديث مستخدم:
```bash
curl -X PUT http://localhost:9470/api/users/1 \
-d '{"Name": "Alice", "age": 31}'
```
### DELETE /api/users/:id
حذف مستخدم:
```bash
curl -X DELETE http://localhost:9470/api/users/1
```
## نقطة نهاية الاستعلام
تنفيذ استعلامات BaraQL عبر HTTP:
```bash
curl -X POST http://localhost:9470/api/query \
-d '{"sql": "SELECT * FROM users WHERE age > 18"}'
```
docs/ar/api-websocket.md
-78
View File
@@ -1,78 +0,0 @@
# API WebSocket
دفق كامل للاتجاهين لتغذية البيانات في الوقت الفعلي والإشعارات.
## الاتصال
```
ws://localhost:9471/ws
```
## مثال العميل
```javascript
const ws = new WebSocket('ws://localhost:9471/ws');
ws.onopen = () => {
ws.send(JSON.stringify({
type: 'query',
sql: 'SELECT * FROM users'
}));
};
ws.onmessage = (event) => {
console.log('Received:', JSON.parse(event.data));
};
```
## تنسيق الرسالة
```json
{
"type": "query",
"id": "uuid",
"sql": "SELECT * FROM users"
}
```
## أنواع الرسائل
### طلب الاستعلام
```json
{
"type": "query",
"id": "123",
"sql": "SELECT * FROM users"
}
```
### استجابة الاستعلام
```json
{
"type": "result",
"id": "123",
"data": [{"id": 1, "name": "Alice"}]
}
```
### الاشتراك
```json
{
"type": "subscribe",
"table": "users"
}
```
### إشعار
```json
{
"type": "push",
"table": "users",
"action": "insert",
"data": {"id": 3, "name": "Charlie"}
}
```
docs/ar/architecture.md
-102
View File
@@ -1,102 +0,0 @@
# بنية BaraDB
## نظرة عامة
BaraDB هو **محرك قاعدة بيانات متعدد الأنماط** مكتوب بـ Nim يجمع بين تخزين المستندات (KV) والرسم البياني والمتجهي والعمودي والبحث النصي الكامل في محرك واحد مع لغة استعلام موحدة **BaraQL**.
## البنية الطبقية
```
┌─────────────────────────────────────────────────────────┐
│ 1. طبقة العميل │
│ البروتوكول الثنائي │ HTTP/REST │ WebSocket │ مضمن │
├─────────────────────────────────────────────────────────┤
│ 2. طبقة الاستعلام (BaraQL) │
│ المحلل اللغوي → المحلل → AST → IR → المحسن → توليد الكود│
├─────────────────────────────────────────────────────────┤
│ 3. محركات التنفيذ │
│ المستندات │ الرسم البياني │ المتجه │ العمودي │ FTS │
├─────────────────────────────────────────────────────────┤
│ 4. التخزين │
│ LSM-Tree │ B-Tree │ WAL │ Bloom │ الضغط │ الذاكرة المؤقتة│
├─────────────────────────────────────────────────────────┤
│ 5. الموزع │
│ توافق Raft │ التجزئة │ النسخ │ Gossip │
└─────────────────────────────────────────────────────────┘
```
## الطبقة 1: طبقة العميل
- **البروتوكول الثنائي**: بروتوكول ثنائي فعال big-endian
- **HTTP/REST**: واجهة REST مبنية على JSON
- **WebSocket**: دفق ثنائي الاتجاه كامل
- **المدمج**: وصول مباشر داخل العملية
## الطبقة 2: طبقة الاستعلام (BaraQL)
1. **المحلل اللغوي** (`query/lexer.nim`): أكثر من 80 نوع رمز
2. **المحلل** (`query/parser.nim`): محلل تنازلي تكراري
3. **AST** (`query/ast.nim`): أكثر من 25 نوع عقدة
4. **IR** (`query/ir.nim`): تمثيل وسيط
5. **المحسن** (`query/adaptive.nim`): تحسين عبر الأنماط
6. **توليد الكود** (`query/codegen.nim`): ترجمة إلى عمليات التخزين
7. **المنفذ** (`query/executor.nim`): تنفيذ متوازي
## الطبقة 3: محركات التنفيذ
### محرك المستندات/KV
- **LSM-Tree** (`storage/lsm.nim`): MemTable، WAL، SSTables
### المحرك المتجهي (`vector/`)
- **فهرس HNSW** (`vector/engine.nim`): رسم بياني صغير قابل للملاحة هرمي
- **فهرس IVF-PQ**: ملف مقلوب مع تكميم المنتج
- **عمليات SIMD** (`vector/simd.nim`): محسّن بـ AVX2
### محرك الرسم البياني (`graph/`)
- BFS، DFS، Dijkstra، PageRank
- **Louvain**: كشف المجتمع
### البحث النصي الكامل (`fts/`)
- الفهرس المقلوب، BM25، TF-IDF
- **متعدد اللغات**: tokenizers لـ EN، BG، DE، FR، RU
## الطبقة 4: التخزين
- **LSM-Tree**: MemTable، WAL، SSTable، Bloom Filter
- **ذاكرة الصفحة**: ذاكرة مؤقتة LRU
- **I/O المعينة**: وصول قائم على mmap
- **الاستعادة**: إعادة تشغيل WAL
## الطبقة 5: الموزع
- **توافق Raft** (`core/raft.nim`): انتخاب القائد، نسخ السجل
- **التجزئة** (`core/sharding.nim`): hash، range، تجزئة متسقة
- **النسخ** (`core/replication.nim`): متزامن، غير متزامن، شبه متزامن
- **بروتوكول Gossip** (`core/gossip.nim`): مثل SWIM
## قرارات التصميم الرئيسية
1. **Nim نقي**: بدون تبعيات Cython أو Python أو Rust
2. **تخزين موحد**: محرك واحد لـ KV والرسم البياني والمتجة وFTS والعمودي
3. **الوضع المدمج**: يمكن تشغيله كمكتبة أو خادم
4. **البروتوكول الثنائي**: بروتوكول سلكي فعال مخصص
5. **MVCC**: تحكم في التزامن متعدد الإصدارات
6. **المخطط أولاً**: نظام مخطط مكتوب بشدة مع الوراثة
7. **عبر الأنماط**: لغة استعلام واحدة عبر جميع نماذج البيانات
8. **التحقق الرسمي**: الخوارزميات الموزعة الأساسية محددة في TLA+ ومتحقق منها مع TLC
## إحصائيات الوحدات
| الفئة | الوحدات | أسطر الكود | الغرض |
|-------|---------|------------|-------|
| Core | 16 | ~4,200 | الخادم، البروتوكولات، المعاملات، الموزع |
| Storage | 7 | ~3,100 | LSM، B-Tree، WAL، bloom، الضغط، mmap |
| Query | 7 | ~2,800 | المحلل اللغوي، المحلل، AST، IR، المحسن، توليد الكود |
| Vector | 3 | ~1,200 | HNSW، IVF-PQ، التكميم، SIMD |
| Graph | 3 | ~1,000 | قائمة الجوار، الخوارزميات، كشف المجتمع |
| FTS | 2 | ~900 | الفهرس المقلوب، BM25، غامض، متعدد اللغات |
| Protocol | 7 | ~2,400 | Wire، HTTP، WebSocket، pool، auth، حد السعر، SSL |
| Schema | 1 | ~600 | الأنواع، الروابط، الوراثة |
| Client | 2 | ~800 | عميل Nim الثنائي |
| CLI | 1 | ~400 | صدفة BaraQL التفاعلية |
| **المجموع** | **49** | **~14,100** | |
docs/ar/backup.md
-82
View File
@@ -1,82 +0,0 @@
# النسخ الاحتياطي والاستعادة
## لقطات عبر الإنترنت
تدعم BaraDB اللقطات عبر الإنترنت دون إيقاف الخادم.
### إنشاء لقطة
```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 \
-d '{"destination": "/backup/snapshot.db"}'
```
### النسخ الاحتياطي التلقائي
```bash
0 2 * * * /usr/local/bin/baradadb --snapshot --output=/backup/baradb_$(date +\%Y\%m\%d).db
find /backup -name "baradb_*.db" -mtime +7 -delete
```
## استعادة نقطة في الوقت (PITR)
### الاستعادة من اللقطة + WAL
```bash
./build/baradadb --recover \
--checkpoint=/backup/snapshot.db \
--wal-dir=/backup/wal
```
### الاستعادة عبر SQL
```sql
RECOVER TO TIMESTAMP '2026-05-07T12:00:00';
```
## سيناريوهات استعادة الكوارث
### السيناريو 1: تلف الملف
```bash
cp /backup/sstables/000012.sst ./data/sstables/
./build/baradadb --rebuild-index
```
### السيناريو 2: فقدان البيانات الكامل
```bash
cp /backup/snapshot.db ./data/
./build/baradadb --recover --wal-dir=/backup/wal
```
### السيناريو 3: فشل عقدة الكتلة
```bash
BARADB_RAFT_NODE_ID=newnode \
BARADB_RAFT_PEERS=node1:9001,node2:9001 \
./build/baradadb
```
## أفضل الممارسات
1. اختبار الاستعادة بانتظام
2. تخزين النسخ الاحتياطية خارج الموقع
3. تشفير النسخ الاحتياطية
4. مراقبة مهام النسخ الاحتياطي
5. توثيق RTO/RPO
docs/ar/baraql.md
-268
View File
@@ -1,268 +0,0 @@
# مرجع لغة استعلام BaraQL
BaraQL هي لغة استعلام متوافقة مع SQL مع امتدادات لعمليات الرسم البياني والمتجة والمستندات.
## أنواع البيانات
| النوع | الوصف | مثال |
|-------|-------|------|
| `null` | قيمة فارغة | `null` |
| `bool` | منطقي | `true`, `false` |
| `int8` | عدد صحيح 8 بت | `127` |
| `int16` | عدد صحيح 16 بت | `32767` |
| `int32` | عدد صحيح 32 بت | `2147483647` |
| `int64` | عدد صحيح 64 بت | `9223372036854775807` |
| `float32` | فاصلة عائمة 32 بت | `3.14` |
| `float64` | فاصلة عائمة 64 بت | `3.14159265359` |
| `str` | سلسلة UTF-8 | `'hello'` |
| `vector` | متجه float32 | `[0.1, 0.2, 0.3]` |
| `datetime` | طابع زمني ISO 8601 | `'2025-01-15T10:30:00Z'` |
| `uuid` | UUID v4 | `'550e8400-e29b-41d4-a716-446655440000'` |
## الاستعلامات الأساسية
### SELECT
```sql
SELECT * FROM users;
SELECT name, age FROM users;
SELECT name AS full_name FROM users;
SELECT * FROM users LIMIT 10 OFFSET 20;
```
### WHERE
```sql
SELECT * FROM users WHERE age > 18;
SELECT * FROM users WHERE age BETWEEN 18 AND 65;
SELECT * FROM users WHERE department IN ('Engineering', 'Sales');
SELECT * FROM users WHERE name LIKE 'A%';
```
### 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';
```
## JOIN
```sql
SELECT u.name, o.total
FROM users u
INNER JOIN orders o ON u.id = o.user_id;
```
## CTE (تعبيرات الجدول المشترك)
```sql
WITH active_users AS (
SELECT * FROM users WHERE active = true
)
SELECT * FROM active_users;
```
## البحث المتجهي
```sql
INSERT articles { title := 'Nim Programming', embedding := [0.1, 0.2, 0.3, 0.4] };
SELECT title FROM articles
ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4])
LIMIT 5;
```
## أنماط الرسم البياني
```sql
MATCH (p:Person)-[:KNOWS]->(friend:Person)
WHERE p.name = 'Alice'
RETURN friend.name;
```
## المعاملات
```sql
BEGIN;
INSERT users { name := 'Alice', age := 30 };
INSERT orders { user_id := last_insert_id(), total := 100 };
COMMIT;
-- مع نقطة حفظ
BEGIN;
INSERT users { name := 'Bob', age := 25 };
SAVEPOINT sp1;
INSERT orders { user_id := last_insert_id(), total := 200 };
-- خطأ، التراجع إلى نقطة الحفظ
ROLLBACK TO sp1;
COMMIT;
```
## البحث النصي الكامل
```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);
-- البحث الضبابي
SELECT * FROM articles
WHERE MATCH(title) AGAINST('programing' WITH FUZZINESS 2);
```
## الدوال المحددة من المستخدم
```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');
```
## تلميحات الاستعلام
```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;
```
## دوال النوافذ
```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
)
```
## ERP متعدد المستأجرين
يدعم BaraDB تشغيل عدة شركات (مستأجرين) في مثيل قاعدة بيانات واحد، باستخدام **أمان مستوى الصف (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 فقط
```
### لماذا متعدد المستأجرين؟
- **مثيل واحد، مستأجرون كثيرون** — لا حاجة لتشغيل 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 |
| Transaction | BEGIN, COMMIT, ROLLBACK, SAVEPOINT |
| Graph | MATCH, RETURN, WHERE, shortestPath, type |
| FTS | MATCH, AGAINST, relevance, IN BOOLEAN MODE, WITH FUZZINESS |
| Vector | cosine_distance, euclidean_distance, inner_product, l1_distance, l2_distance, <-> |
| JSON | ->, ->> |
| FTS | @@ (تطابق BM25) |
| Recovery | RECOVER TO TIMESTAMP |
| Functions | count, sum, avg, min, max, stddev, variance, abs, sqrt, lower, upper, len, trim, substr, now, last_insert_id, current_setting |
| Session | SET, current_setting, current_user, current_role |
| Window | OVER, PARTITION BY, ROWS, RANGE, UNBOUNDED PRECEDING, CURRENT ROW, FOLLOWING |
| Window Functions | ROW_NUMBER, RANK, DENSE_RANK, LEAD, LAG, FIRST_VALUE, LAST_VALUE, NTILE |
docs/ar/btree.md
-26
View File
@@ -1,26 +0,0 @@
# فهرس B-Tree
هيكل فهرس مرتب للبحث النطاقي والنقطة الفعال.
## الاستخدام
```nim
import barabadb/storage/btree
var btree = newBTreeIndex[string, string]()
btree.insert("key1", "value1")
btree.insert("key2", "value2")
let values = btree.get("key1")
let range = btree.scan("key_a", "key_z")
btree.delete("key1")
```
## الميزات
- تخزين مفاتي-قيم مرتب
- استعلامات النطاق (BETWEEN, >, <, >=, <=)
- المسح بالبادئة
- حجم الصفحة القابل للتكوين
- دعم المكرر
docs/ar/changelog.md
-76
View File
@@ -1,76 +0,0 @@
# سجل التغييرات
## [0.1.0] — 2025-01-15
### المضاف
- **محركات التخزين الأساسية**
- LSM-Tree مع MemTable و WAL و SSTables و size-tiered compaction
- فهرس B-Tree مرتب مع المسح النطاقي و MVCC copy-on-write
- فلاتر Bloom
- I/O المعينة بالذاكرة
- ذاكرة صفحة LRU
- **محرك الاستعلام (BaraQL)**
- lexer متوافق مع SQL مع 80+ نوع رمز
- parser تنازلي تكراري ينتج AST مع 25+ نوع عقدة
- تمثيل وسيط (IR)
- محسن استعلام تكيفي مع تخطيط عبر الأنماط
- منفذ استعلام مع 병렬화
- **ميزات لغة BaraQL**
- SELECT و INSERT و UPDATE و DELETE
- WHERE و ORDER BY و LIMIT و OFFSET
- GROUP BY و HAVING ودوال التجميع
- INNER JOIN و LEFT JOIN و RIGHT JOIN و FULL JOIN و CROSS JOIN
- CTEs مع WITH
- الاستعلامات الفرعية
- تعبيرات CASE
- UNION و INTERSECT و EXCEPT
- **محرك المتجهات**
- فهرس HNSW
- فهرس IVF-PQ
- دوال المسافة المحسنة بـ SIMD
- التكميم: 8-bit/4-bit القياسي والمنتج والثنائي
- **محرك الرسم البياني**
- تخزين قائمة المجاورة
- BFS و DFS للعبور
- Dijkstra لأقصر مسار
- PageRank
- Louvain لكشف المجتمع
- محلل استعلامات Cypher
- **البحث النصي الكامل**
- الفهرس المقلوب
- ترتيب BM25
- TF-IDF
- البحث الغامض
- tokenizers متعدد اللغات
- **البروتوكولات**
- بروتوكول Wire الثنائي مع 16 نوع رسالة
- API HTTP/REST JSON
- WebSocket للدفق
- تجميع الاتصالات
- مصادقة JWT
- TLS/SSL
- **الأنظمة الموزعة**
- توافق Raft
- تجزئة hash و range و consistent-hash
- نسخ متزامن/غير متزامن/شبه متزامن
- بروتوكول Gossip
- commit على مرحلتين
### الأداء
- LSM-Tree: 580K كتابة/ثانية، 720K قراءة/ثانية
- B-Tree: 1.2M إدراج/ثانية، 1.5M بحث/ثانية
- Vector SIMD: 850K مسافة جيب التمام/ثانية (dim=768)
### الاختبارات
- 262 اختبار عبر 56 مجموعة اختبار
- 100% معدل النجاح
docs/ar/clients.md
-66
View File
@@ -1,66 +0,0 @@
# حزم العملاء
توفر BaraDB مكتبات العملاء الرسمية لـ JavaScript/TypeScript و Python و Nim و Rust.
## JavaScript / TypeScript
### التثبيت
```bash
npm install 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');
```
## 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")
```
## Nim (الوضع المدمج)
```nim
import barabadb/storage/lsm
var db = newLSMTree("./data")
db.put("key", cast[seq[byte]]("value"))
let (found, val) = db.get("key")
db.close()
```
## Rust
```rust
use baradb::Client;
let mut client = Client::connect("localhost:9472").await?;
```
## HTTP/REST
```bash
curl -X POST http://localhost:9470/api/query \
-d '{"query": "SELECT * FROM users"}'
```
docs/ar/columnar.md
-50
View File
@@ -1,50 +0,0 @@
# التخزين العمودي
تخزين موجهة للأعمدة للاستعلامات التحليلية والتجميعات.
## الاستخدام
```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()
```
## الترميز
### RLE
```nim
let rle = rleEncode(@[1'i64, 1, 1, 2, 2, 3])
```
### Dictionary
```nim
let dict = dictEncode(@["apple", "banana", "apple"])
```
## أنواع الأعمدة
| النوع | الوصف |
|-------|-------|
| `int32` | عدد صحيح 32 بت |
| `int64` | عدد صحيح 64 بت |
| `float32` | فاصلة عائمة 32 بت |
| `float64` | فاصلة عائمة 64 بت |
| `string` | سلسلة متغيرة الطول |
| `bool` | منطقي |
docs/ar/configuration.md
-96
View File
@@ -1,96 +0,0 @@
# مرجع التكوين
يمكن تكوين BaraDB عبر **متغيرات البيئة** أو **ملف التكوين** أو **علامات سطر الأوامر**.
## ترتيب الأولوية
1. علامات سطر الأوامر (الأعلى)
2. متغيرات البيئة
3. ملف التكوين (`baradb.conf` أو `baradb.json`)
4. الإعدادات الافتراضية (الأدنى)
## متغيرات البيئة
### الشبكة
| المتغير | الافتراضي | الوصف |
|---------|-----------|-------|
| `BARADB_ADDRESS` | `127.0.0.1` | عنوان الربط |
| `BARADB_PORT` | `9472` | منفذ البروتوكول الثنائي |
| `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` | حجم ذاكرة الصفحة (MB) |
### TLS/SSL
| المتغير | الافتراضي | الوصف |
|---------|-----------|-------|
| `BARADB_TLS_ENABLED` | `false` | تمكين TLS |
| `BARADB_CERT_FILE` | — | مسار شهادة TLS |
| `BARADB_KEY_FILE` | — | مسار مفتاح TLS الخاص |
### الأمان
| المتغير | الافتراضي | الوصف |
|---------|-----------|-------|
| `BARADB_AUTH_ENABLED` | `false` | تمكين المصادقة |
| `BARADB_JWT_SECRET` | — | سر توقيع JWT |
| `BARADB_RATE_LIMIT_GLOBAL` | `10000` | طلبات/ثانية عامة |
| `BARADB_RATE_LIMIT_PER_CLIENT` | `1000` | طلبات/ثانية لكل عميل |
## ملف التكوين
### baradb.conf
```ini
[server]
address = "0.0.0.0"
port = 9472
http_port = 9470
[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"
[auth]
enabled = true
jwt_secret = "change-me-in-production"
```
## علامات سطر الأوامر
```bash
./build/baradadb --help
```
## أمثلة التكوين
### التطوير
```bash
./build/baradadb --log-level debug --data-dir ./dev_data
```
### الإنتاج - عقدة واحدة
```bash
BARADB_TLS_ENABLED=true \
BARADB_AUTH_ENABLED=true \
BARADB_JWT_SECRET="$(openssl rand -hex 32)" \
BARADB_MEMTABLE_SIZE_MB=256 \
BARADB_CACHE_SIZE_MB=1024 \
./build/baradadb
```
docs/ar/crossmodal.md
-48
View File
@@ -1,48 +0,0 @@
# الاستعلامات عبر الأنماط
القدرة الفريدة لـ BaraDB هي تنفيذ استعلامات تمتد عبر محركات تخزين متعددة في بيان BaraQL موحد واحد.
## نظرة عامة
- **مستند/KV** (LSM-Tree) — السجلات المهيكلة
- **رسم بياني** (قائمة المجاورة) — العلاقات
- **متجهي** (HNSW/IVF-PQ) — بحث التشابه
- **نص كامل** (الفهرس المقلوب) — البحث النصي
- **عمودي** — التجميعات التحليلية
## أنماط الاستعلام
### متجه + نص كامل
```sql
SELECT title FROM articles
WHERE MATCH(body) AGAINST('machine learning')
ORDER BY cosine_distance(embedding, [...])
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;
```
## التحسين
### مخطط استعلام عبر الأنماط
1. العامل الأكثر انتقائية أولاً
2. دفع المسندات إلى كل محرك
3. استخدام فلاتر Bloom لعمليات KV
4. 병렬화 الفروع المستقلة
## الأداء
| نوع الاستعلام | التأخير (10K صف) |
|---------------|------------------|
| FTS + Vector | 15 ms |
| Graph + Vector | 25 ms |
| FTS + Aggregate | 12 ms |
docs/ar/deployment.md
-68
View File
@@ -1,68 +0,0 @@
# دليل النشر
## Docker
### البداية السريعة
```bash
docker build -t baradb:latest .
docker compose up -d
docker compose ps
```
### ملفات Docker Compose
| الملف | الغرض |
|-------|-------|
| `docker-compose.yml` | التطوير |
| `docker-compose.prod.yml` | الإنتاج |
## المنافذ
| المنفذ | الوصف |
|--------|-------|
| `9472` | بروتوكول Wire الثنائي |
| `9470` | HTTP/REST API |
| `9471` | WebSocket |
## متغيرات البيئة
| المتغير | الافتراضي | الوصف |
|---------|-----------|-------|
| `BARADB_ADDRESS` | `0.0.0.0` | عنوان الاستماع |
| `BARADB_PORT` | `9472` | منفذ البروتوكول الثنائي |
| `BARADB_HTTP_PORT` | `9470` | منفذ HTTP |
| `BARADB_DATA_DIR` | `/data` | دليل البيانات |
## المجلدات
| المسار | الوصف |
|--------|-------|
| `/data` | دليل البيانات الرئيسي |
| `/data/server/wal` | سجل write-ahead |
| `/data/server/sstables` | ملفات SSTable |
## قائمة التحقق للإنتاج
- [ ] إنشاء شهادات TLS في `./certs/`
- [ ] تعيين `BARADB_JWT_SECRET` قوي
- [ ] تكوين قواعد جدار الحماية
- [ ] تكوين النسخ الاحتياطي المنتظم
- [ ] التحقق من حدود الموارد
- [ ] تكوين المراقبة
## TLS في Docker
```bash
mkdir -p certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout certs/server.key -out certs/server.crt
```
## النسخ الاحتياطي في Docker
```bash
docker exec baradb /app/backup backup --data-dir=/data
docker exec baradb /app/backup list
docker exec baradb /app/backup restore --input=backup_xxx.tar.gz
```
docs/ar/distributed.md
-73
View File
@@ -1,73 +0,0 @@
# الأنظمة الموزعة
تدعم BaraDB النشر الموزع مع توافق 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.becomeCandidate()
n1.becomeLeader()
```
## التجزئة
```nim
import barabadb/core/sharding
var router = newShardRouter(ShardConfig(
numShards: 4,
replicas: 2,
strategy: ssHash
))
```
### استراتيجيات التجزئة
| الاستراتيجية | الوصف |
|-------------|-------|
| `ssHash` | تجزئة قائمة على hash |
| `ssRange` | تجزئة قائمة على النطاق |
| `ssConsistent` | تجزئة متسقة |
## النسخ
```nim
import barabadb/core/replication
var rm = newReplicationManager(rmSync)
rm.addReplica(newReplica("r1", "10.0.0.1", 9472))
```
### أوضاع النسخ
| الوضع | الوصف |
|-------|-------|
| `rmSync` | نسخ متزامن |
| `rmAsync` | نسخ غير متزامن |
| `rmSemiSync` | نسخ شبه متزامن |
## المعاملات الموزعة
الالتزام على مرحلتين:
```nim
import barabadb/core/disttxn
var dt = newDistributedTxn()
dt.prepare(@["node1", "node2"])
dt.commit()
```
## التحقق الرسمي
تم تحديد الخوارزميات الموزعة الأساسية في TLA+ والتحقق منها.
docs/ar/docker.md
-78
View File
@@ -1,78 +0,0 @@
# دليل نشر Docker
## البداية السريعة
```bash
git clone https://codeberg.org/baraba/baradb
cd barabaDB
docker build -t baradb:latest .
docker compose up -d
docker compose ps
docker compose logs -f
```
## الملفات
| الملف | الوصف |
|-------|-------|
| `Dockerfile` | بناء multi-stage للإنتاج |
| `docker-compose.yml` | تكوين التطوير |
| `docker-compose.prod.yml` | تكوين الإنتاج |
## بناء الصورة
```bash
docker build -t baradb:latest .
```
## التشغيل
### التطوير
```bash
docker compose up -d
docker compose down
```
### الإنتاج
```bash
docker compose -f docker-compose.prod.yml up -d
```
## المنافذ
| المنفذ | الوصف |
|--------|-------|
| `9472` | بروتوكول Wire الثنائي |
| `9470` | HTTP/REST API |
| `9471` | WebSocket |
## متغيرات البيئة
| المتغير | الافتراضي | الوصف |
|---------|-----------|-------|
| `BARADB_ADDRESS` | `0.0.0.0` | عنوان الاستماع |
| `BARADB_PORT` | `9472` | منفذ البروتوكول الثنائي |
| `BARADB_HTTP_PORT` | `9470` | منفذ HTTP |
| `BARADB_DATA_DIR` | `/data` | دليل البيانات |
## المجلدات
| المسار | الوصف |
|--------|-------|
| `/data` | دليل البيانات الرئيسي |
| `/data/server/wal` | سجل write-ahead |
| `/data/server/sstables` | ملفات SSTable |
## قائمة التحقق للإنتاج
- [ ] إنشاء شهادات TLS في `./certs/`
- [ ] تعيين `BARADB_JWT_SECRET` قوي
- [ ] تكوين قواعد جدار الحماية
- [ ] تكوين النسخ الاحتياطي المنتظم
- [ ] التحقق من حدود الموارد
- [ ] تكوين المراقبة
docs/ar/fts.md
-47
View File
@@ -1,47 +0,0 @@
# محرك البحث النصي الكامل
فهرس مقلوب مع ترتيب BM25 و TF-IDF للبحث النصي.
## الاستخدام
```nim
import barabadb/fts/engine
var idx = newInvertedIndex()
idx.addDocument(1, "Nim is a fast programming language")
idx.addDocument(2, "Python is popular for data science")
let results = idx.search("programming language")
let fuzzy = idx.fuzzySearch("programing", maxDistance = 2)
```
## طرق الترتيب
### BM25
```nim
let bm25 = idx.searchBM25("query terms")
```
### TF-IDF
```nim
let tfidf = idx.searchTfidf("query terms")
```
## ميزات البحث
| الميزة | الوصف |
|---------|-------|
| Fuzzy search | تساهل مسافة Levenshtein |
| Wildcard | بادئة، لاحقة،wildcard中间 |
| Regex | أنماط التعبير العادي |
| Phrase search | تطابق عبارة تامة |
| Boolean | عوامل AND, OR, NOT |
## واجهة SQL
```sql
CREATE INDEX idx_fts ON articles(body) USING FTS;
SELECT * FROM articles WHERE body @@ 'machine learning';
```
docs/ar/graph.md
-42
View File
@@ -1,42 +0,0 @@
# محرك الرسم البياني
تخزين قائمة المجاورة مع خوارزميات مدمجة للعبور والتحليل.
## الاستخدام
```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` | عبور بالعرض |
| `dfs` | عبور بالعمق |
| `dijkstra` | أقصر مسار موزون |
| `pageRank` | ترتيب أهمية العقدة |
| `louvain` | كشف المجتمع |
| `patternMatch` | تماثل الرسم الفرعي |
## استعلام Cypher
```nim
import barabadb/graph/cypher
var engine = newCypherEngine(g)
let results = engine.execute("""
MATCH (p:Person)-[:KNOWS]->(friend:Person)
WHERE p.name = 'Alice'
RETURN friend.name
""")
```
docs/ar/index.md
-59
View File
@@ -1,59 +0,0 @@
# توثيق BaraDB (العربية)
**محرك قاعدة بيانات متعدد الأنماط مكتوب بـ Nim — 100% أصلي، بدون تبعيات.**
## روابط سريعة
> **ملاحظة:** التوثيق العربي قيد التطوير. يرجى الرجوع إلى [النسخة الإنجليزية](../en/) للمعلومات الكاملة.
### البدء
- [التثبيت](../en/installation.md)
- [البداية السريعة](../en/quickstart.md)
- [نظرة عامة على البنية](../en/architecture.md)
- [مرجع التكوين](../en/configuration.md)
- [دليل النشر](../en/deployment.md)
### المفاهيم الأساسية
- [لغة استعلام BaraQL](../en/baraql.md)
- [محركات التخزين](../en/storage.md)
- [نظام المخطط](../en/schema.md)
- [الاستعلامات عبر الأنماط](../en/crossmodal.md)
### المحركات
- [تخزين LSM-Tree](../en/lsm.md)
- [فهرس B-Tree](../en/btree.md)
- [البحث المتجهي](../en/vector.md)
- [محرك الرسم البياني](../en/graph.md)
- [البحث النصي الكامل](../en/fts.md)
- [التخزين العمودي](../en/columnar.md)
### API والعملاء
- [SDK للعملاء](../en/clients.md)
- [البروتوكول الثنائي](../en/api-binary.md)
- [HTTP/REST API](../en/api-http.md)
- [WebSocket API](../en/api-websocket.md)
- [مرجع البروتوكول](../en/protocol.md)
### العمليات
- [الأداء والمعايير](../en/performance.md)
- [دليل الأمان](../en/security.md)
- [المراقبة](../en/monitoring.md)
- [النسخ الاحتياطي والاستعادة](../en/backup.md)
- [حل المشكلات](../en/troubleshooting.md)
### متقدم
- [المعاملات و MVCC](../en/transactions.md)
- [الأنظمة الموزعة](../en/distributed.md)
- [الدوال المحددة من المستخدم](../en/udf.md)
---
## معلومات المشروع
- [سجل التغييرات](../en/changelog.md)
- [الترخيص](../../LICENSE)
- [مستودع GitHub](https://github.com/katehonz/barabaDB)
---
*التوثيق العربي قيد الترجمة.*
docs/ar/installation.md
-308
View File
@@ -1,308 +0,0 @@
# دليل تثبيت BaraDB
## المتطلبات
- **مترجم Nim** >= 2.2.0
- **ملفات رأس OpenSSL** (لدعم TLS)
- **نظام التشغيل**: لينكس، macOS، ويندوز
### المنصات المدعومة
| نظام التشغيل | البنية | الحالة |
|-------------|--------|--------|
| لينكس | x86_64 | ✅ دعم كامل |
| لينكس | ARM64 | ✅ دعم كامل |
| macOS | x86_64 | ✅ دعم كامل |
| macOS | ARM64 | ✅ دعم كامل |
| ويندوز | x86_64 | ✅ مدعوم |
| FreeBSD | x86_64 | 🟡 اختبار المجتمع |
## تثبيت Nim
### لينكس
```bash
# المثبت الرسمي
curl https://nim-lang.org/choosenim/init.sh -sSf | sh
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install nim
# Fedora
sudo dnf install nim
# Arch Linux
sudo pacman -S nim
```
### macOS
```bash
# Homebrew
brew install nim
# MacPorts
sudo port install nim
```
### ويندوز
```powershell
# باستخدام choosenim
curl.exe -A "MSYS2_$(uname -m)" -L https://nim-lang.org/choosenim/init.ps1 | powershell -
# باستخدام winget
winget install nim
# باستخدام scoop
scoop install nim
```
### التحقق من التثبيت
```bash
nim --version
# المتوقع: Nim Compiler Version 2.2.0 أو أحدث
```
## تثبيت OpenSSL
### لينكس
```bash
# Ubuntu/Debian
sudo apt-get install libssl-dev
# Fedora
sudo dnf install openssl-devel
# Arch Linux
sudo pacman -S openssl
```
### macOS
OpenSSL مضمن مع النظام. إذا لزم الأمر:
```bash
brew install openssl
```
### ويندوز
OpenSSL مضمن مع توزيع Nim ويندوز. للبناء اليدوي، قم بالتنزيل من [slproweb.com](https://slproweb.com/products/Win32OpenSSL.html).
## بناء BaraDB
### استنساخ المستودع
```bash
git clone https://codeberg.org/baraba/baradb
cd barabaDB
```
### تثبيت التبعيات
```bash
nimble install -d -y
```
### خيارات البناء
#### بناء التصحيح
```bash
nim c -d:ssl -o:build/baradadb src/baradadb.nim
```
#### بناء الإصدار (موصى به)
```bash
nim c -d:ssl -d:release --opt:speed -o:build/baradadb src/baradadb.nim
```
#### استخدام مهام Nimble
```bash
# بناء التصحيح
nimble build_debug
# بناء الإصدار
nimble build_release
```
#### تقليل حجم الملف الثنائي
```bash
nim c -d:ssl -d:release --opt:size -o:build/baradadb src/baradadb.nim
strip build/baradadb
```
### التحقق من البناء
```bash
./build/baradadb --version
# المتوقع: BaraDB v1.1.6 — Multimodal Database Engine
```
## تشغيل الاختبارات
### جميع الاختبارات
```bash
nim c -d:ssl -r tests/test_all.nim
```
### مجموعات اختبارات محددة
```bash
# اختبارات التخزين
nim c -d:ssl -r tests/test_storage.nim
# اختبارات محرك الاستعلام
nim c -d:ssl -r tests/test_query.nim
# اختبارات البروتوكول
nim c -d:ssl -r tests/test_protocol.nim
```
### المعايير
```bash
nim c -d:ssl -d:release -r benchmarks/bench_all.nim
```
## خيارات التثبيت
### التثبيت على مستوى النظام
```bash
# بناء إصدار RELEASE
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
```
### الملف الثنائي المبنى مسبقًا
قم بتنزيل أحدث إصدار لمنصتك:
```bash
# لينكس 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
# لينكس 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 \
-p 9471:9471 \
-v baradb_data:/data \
barabadb/barabadb
```
### Docker Compose
```bash
docker-compose up -d
```
### الاستخدام المدمج (مشاريع Nim)
أضف إلى ملف `.nimble` الخاص بك:
```nim
requires "barabadb >= 1.1.6"
```
استخدم في الكود:
```nim
import barabadb/storage/lsm
var db = newLSMTree("./data")
db.put("key", cast[seq[byte]]("value"))
let (found, val) = db.get("key")
db.close()
```
## التشغيل الأول
```bash
# بدء الخادم
./build/baradadb
# المخرجات المتوقعة:
# BaraDB v1.1.6 — 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 -o:build/baradadb src/baradadb.nim
```
### البناء البطيء
استخدم البناء المتوازي:
```bash
nim c -d:ssl -d:release --parallelBuild:4 -o:build/baradadb src/baradadb.nim
```
### حجم الملف الثنائي الكبير
استخدم تحسين الحجم:
```bash
nim c -d:ssl -d:release --opt:size --passL:-s -o:build/baradadb src/baradadb.nim
```
## الخطوات التالية
- [دليل البداية السريعة](quickstart.md)
- [مرجع التكوين](configuration.md)
- [نظرة عامة على البنية](architecture.md)
- [لغة استعلام BaraQL](baraql.md)
docs/ar/lsm.md
-48
View File
@@ -1,48 +0,0 @@
# محرك تخزين LSM-Tree
محرك التخزين الأساسي في BaraDB باستخدام بنية Log-Structured Merge-Tree.
## البنية
```
┌─────────────────────────────────────────────┐
│ Writes │
│ (append to WAL + MemTable) │
└─────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ MemTable │
│ (in-memory sorted buffer) │
└─────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ SSTable │
│ (sorted string table on disk) │
└─────────────────────────────────────────────┘
```
## الاستخدام
```nim
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()
```
## الميزات
- **محسن للكتابة**: هيكل log-only إضافي
- **الدائمة**: WAL يضمن استعادة بعد الانهيار
- **Bloom Filter**: بحث سلبي سريع
- **الضغط**: استراتيجية size-tiered
- **ذاكرة الصفحة**: LRU للصفحاتaccessed بشكل متكرر
docs/ar/mcp.md
-109
View File
@@ -1,109 +0,0 @@
# خادم MCP (Model Context Protocol)
يتضمن BaraDB خادم MCP مدمج يمكّن وكلاء الذكاء الاصطناعي (Claude و Cursor وما إلى ذلك) من التفاعل مع قاعدة البيانات مباشرة.
## البداية السريعة
```bash
./build/baramcp --data-dir ./data
```
يبدأ في وضع STDIO، يقبل رسائل JSON-RPC 2.0 على stdin.
## الأدوات المتاحة
### 1. `query` — تنفيذ SQL
```json
{
"name": "query",
"arguments": {
"sql": "SELECT * FROM users WHERE age > ?",
"params": [25],
"tenant_id": "company-a",
"user_id": "alice"
}
}
```
استعلامات معاملية باستخدام `?` placeholders. دعم multi-tenant عبر `tenant_id` و `user_id`.
### 2. `vector_search` — البحث الدلالي
```json
{
"name": "vector_search",
"arguments": {
"table": "docs",
"column": "embedding",
"query_vector": [0.1, 0.2, 0.3],
"k": 5,
"metric": "cosine",
"filter_column": "category",
"filter_value": "news",
"tenant_id": "company-a"
}
}
```
المقاييس: `cosine`، `euclidean`، `dot_product`، `manhattan`.
### 3. `schema_inspect` — استكشاف المخطط
```json
{
"name": "schema_inspect",
"arguments": {
"table": "users",
"tenant_id": "company-a"
}
}
```
إرجاع الجداول والأعمدة والأنواع والمفاتيح الأساسية والمفاتيح الخارجية والفهارس وسياسات RLS.
## تكوين Claude Desktop
```json
{
"mcpServers": {
"baradb": {
"command": "/path/to/build/baramcp",
"args": ["--data-dir", "/path/to/data"]
}
}
}
```
## تكوين Cursor
```json
{
"mcpServers": {
"baradb": {
"command": "/path/to/build/baramcp",
"args": ["--data-dir", "~/.baradb/data"]
}
}
}
```
## عزل Multi-Tenant
يمكن أن يتضمن كل طلب MCP قيمة `tenant_id` و `user_id`، والتي يتم تعيينها كمتغيرات جلسة:
- `app.tenant_id` — للترشيح RLS
- `app.user_id` — لمراجع `current_user`
تقوم سياسات RLS بتصفية البيانات تلقائياً بناءً على هذه المتغيرات.
## بروتوكول JSON-RPC 2.0
يستخدم الخادم JSON-RPC 2.0 عبر STDIO:
```json
// الطلب
{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {...}}
// الاستجابة
{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "..."}]}}
```
docs/ar/monitoring.md
-84
View File
@@ -1,84 +0,0 @@
# المراقبة والقابلية للملاحظة
## فحوصات الصحة
### نقطة نهاية صحة HTTP
```bash
curl http://localhost:9470/health
```
الاستجابة:
```json
{
"status": "healthy",
"version": "0.1.0",
"uptime_seconds": 86400,
"checks": {
"storage": "ok",
"memory": "ok",
"connections": "ok"
}
}
```
## المقاييس
### مقاييس متوافقة مع Prometheus
```bash
curl http://localhost:9470/metrics
```
مثال على المخرجات:
```
baradb_queries_total 152340
baradb_queries_duration_seconds_bucket{le="0.001"} 45000
baradb_storage_lsm_size_bytes 2147483648
baradb_cache_hit_rate 0.94
baradb_active_connections 42
```
## التسجيل
### مستويات السجل
| المستوى | الوصف |
|---------|-------|
| `debug` | عمليات داخلية مفصلة |
| `info` | عمليات عادية |
| `warn` | مشاكل قابلة للاسترداد |
| `error` | فشل يستلزم الاهتمام |
### سجلات JSON المهيكلة
```bash
BARADB_LOG_LEVEL=info \
BARADB_LOG_FORMAT=json \
BARADB_LOG_FILE=/var/log/baradb/baradb.log \
./build/baradadb
```
## لوحة Grafana
استيراد معرف اللوحة `baradb-001` أو استخدام JSON في `monitoring/grafana-dashboard.json`.
اللوحات الرئيسية:
- الاستعلامات في الثانية
- نسب مئوية لتأخير الاستعلام (p50, p95, p99)
- حجم التخزين وعدد SSTable
- معدل إصابة ذاكرة التخزين المؤقت
- الاتصالات النشطة
- معدل المعاملات
- معدل الأخطاء
## حل المشكلات بالمقاييس
| العَرَض | المقاييس | الإجراء |
|---------|----------|---------|
| استعلامات بطيئة | `baradb_queries_duration_seconds` | فحص معدل إصابة ذاكرة التخزين المؤقت، إضافة فهارس |
| ذاكرة عالية | `process_resident_memory_bytes` | تقليل أحجام memtable/cache |
| نمو التخزين | `baradb_storage_lsm_size_bytes` | تشغيل الضغط اليدوي |
| أخطاء الاتصال | `baradb_active_connections` | زيادة تجمع الاتصالات أو إضافة العقد |
docs/ar/performance.md
-68
View File
@@ -1,68 +0,0 @@
# دليل الأداء
## منهجية المعايير
جميع المعايير تعمل بـ:
- **المترجم**: Nim 2.2.0 مع `-d:release --opt:speed`
- **CPU**: AMD Ryzen 9 5900X (12 نواة / 24 خيط)
- **الذاكرة**: 64 GB DDR4-3600
- **التخزين**: Samsung 980 Pro NVMe SSD
```bash
nim c -d:ssl -d:release -r benchmarks/bench_all.nim
```
## معايير محركات التخزين
### LSM-Tree
| المقاييس | القيمة |
|----------|--------|
| إنتاجية الكتابة | ~580,000 ops/s |
| إنتاجية القراءة | ~720,000 ops/s |
| متوسط تأخير الكتابة | 1.7 µs |
| متوسط تأخير القراءة | 1.4 µs |
### فهرس B-Tree
| المقاييس | القيمة |
|----------|--------|
| إنتاجية الإدراج | ~1,200,000 ops/s |
| إنتاجية البحث النقطي | ~1,500,000 ops/s |
## معايير المحرك المتجهي
### فهرس HNSW
| المقاييس | القيمة |
|----------|--------|
| الإدراج (dim=128) | ~45,000 vectors/s |
| البحث top-10 (n=100K) | ~8 ms |
المعلمات: `M=16`, `efConstruction=200`, `efSearch=64`.
## دليل الضبط
### لأحمال الكتابة الثقيلة
```bash
BARADB_MEMTABLE_SIZE_MB=256
BARADB_WAL_SYNC_INTERVAL_MS=10
BARADB_COMPACTION_INTERVAL_MS=30000
```
### لأحمال القراءة الثقيلة
```bash
BARADB_CACHE_SIZE_MB=1024
BARADB_BLOOM_BITS_PER_KEY=10
BARADB_COMPACTION_INTERVAL_MS=120000
```
### للبحث المتجهي
```bash
BARADB_VECTOR_EF_CONSTRUCTION=200
BARADB_VECTOR_EF_SEARCH=128
BARADB_VECTOR_M=32
```
docs/ar/protocol.md
-67
View File
@@ -1,67 +0,0 @@
# مرجع البروتوكول
يدعم BaraDB بروتوكولات متعددة للتواصل مع العملاء:
- **Binary Wire Protocol** — عالي الأداء، منخفض التأخير
- **HTTP/REST API** — لغةagnostic، سهل التصحيح
- **WebSocket** — الدفق و pub/sub
## Binary Wire Protocol
يستخدم ترميز big-endian لجميع القيم متعددة البايت.
### دورة الاتصال
```
Client Server
| |
|─── TCP connect ──────────────>|
|─── Auth message ─────────────>|
|<── Auth_OK / Error ───────────|
|─── Query message ────────────>|
|<── Data / Complete / Error ───|
```
### تنسيق الرسالة
```
┌─────────────┬─────────────┬─────────────┬─────────────────────┐
│ Length │ Type │ Sequence │ Payload │
│ (4 bytes) │ (1 byte) │ (1 byte) │ (Length - 6 bytes) │
└─────────────┴─────────────┴─────────────┴─────────────────────┘
```
### أنواع الرسائل
| النوع | ID | الوصف |
|-------|----|-------|
| Query | 0x01 | تنفيذ استعلام |
| Insert | 0x02 | إدراج بيانات |
| Update | 0x03 | تحديث بيانات |
| Delete | 0x04 | حذف بيانات |
| Ready | 0x05 | جاهز للامر التالي |
| Error | 0x06 | استجابة خطأ |
## HTTP/REST API
Base URL: `http://localhost:9470/api/v1`
### نقاط النهاية
#### Health
```http
GET /health
```
#### استعلام
```http
POST /query
{
"query": "SELECT * FROM users"
}
```
## WebSocket Protocol
URL: `ws://localhost:9471`
docs/ar/quickstart.md
-99
View File
@@ -1,99 +0,0 @@
# دليل البداية السريعة لـ BaraDB
## تشغيل الخادم
```bash
./build/baradadb
```
الخادم يبدأ افتراضياً على `localhost:9470`.
## الاتصال عبر CLI
```bash
./build/baradadb --shell
```
## العمليات الأساسية
### إنشاء المخطط
```sql
CREATE TYPE Person {
name: str,
age: int32
};
```
### إدراج البيانات
```sql
INSERT Person { name := 'Alice', age := 30 };
```
### استعلام البيانات
```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;
```
### CTE
```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;
```
## عمليات الرسم البياني
```sql
MATCH (p:Person)-[:KNOWS]->(other:Person)
WHERE p.name = 'Alice'
RETURN other.name;
```
## HTTP/REST API
```bash
curl http://localhost:9470/api/users
curl -X POST http://localhost:9470/api/users \
-H "Content-Type: application/json" \
-d '{"name": "Alice", "age": 30}'
```
## الخطوات التالية
- [مرجع BaraQL](baraql.md)
- [محركات التخزين](storage.md)
- [نظرة عامة على البنية](architecture.md)
docs/ar/schema.md
-46
View File
@@ -1,46 +0,0 @@
# نظام المخطط
يستخدم BaraDB تصميم schema-first مع وراثة النوع والهجرة التلقائية.
## تحديد الأنواع
```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)
```
## عمليات المخطط
### Diff
```nim
let diff = s.diff(oldSchema, newSchema)
```
## أنواع الخصائص
| النوع | الوصف |
|-------|-------|
| `str` | سلسلة |
| `int32` | عدد صحيح 32 بت |
| `int64` | عدد صحيح 64 بت |
| `float32` | فاصلة عائمة 32 بت |
| `float64` | فاصلة عائمة 64 بت |
| `bool` | منطقي |
| `datetime` | تاريخ/وقت |
| `bytes` | بيانات ثنائية |
docs/ar/security.md
-76
View File
@@ -1,76 +0,0 @@
# دليل الأمان
## تشفير TLS/SSL
تدعم BaraDB TLS 1.3 لجميع البروتوكولات. إذا لم يتم توفير شهادة، ينشئ الخادم شهادة ذاتية التوقيع تلقائياً عند البدء.
### استخدام شهادات مخصصة
```bash
BARADB_TLS_ENABLED=true \
BARADB_CERT_FILE=/etc/baradb/server.crt \
BARADB_KEY_FILE=/etc/baradb/server.key \
./build/baradadb
```
### إنشاء شهادة ذاتية التوقيع
```bash
openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt \
-days 365 -nodes -subj "/CN=localhost"
```
## المصادقة
### المصادقة المبنية على JWT
تستخدم BaraDB JWT مع توقيع HMAC-SHA256.
### تمكين المصادقة
```bash
BARADB_AUTH_ENABLED=true \
BARADB_JWT_SECRET="$(openssl rand -hex 32)" \
./build/baradadb
```
### التحكم في الوصول القائم على الأدوار
| الدور | الأذونات |
|-------|----------|
| `admin` | وصول كامل |
| `write` | قراءة + كتابة |
| `read` | قراءة فقط |
| `monitor` | المقاييس والصحة فقط |
## تحديد المعدل
منع إساءة الاستخدام:
```nim
var rl = newRateLimiter(
rlaTokenBucket,
globalRate = 10000,
perClientRate = 1000,
burstSize = 100
)
```
## أمان الشبكة
### عنوان الربط
```bash
BARADB_ADDRESS=0.0.0.0 ./build/baradadb
```
## قائمة التحقق الأمنية
- [ ] تغيير سر JWT الافتراضي
- [ ] تمكين TLS بشهادات صالحة
- [ ] الربط بواجهات محددة
- [ ] تمكين المصادقة في الإنتاج
- [ ] تكوين تحديد المعدل
- [ ] تمكين سجل التدقيق
- [ ] تشفير البيانات في حالة السكون
- [ ] تشغيل BaraDB كمستخدم غير root
docs/ar/storage.md
-67
View File
@@ -1,67 +0,0 @@
# محركات التخزين
توفر BaraDB محركات تخزين متعددة محسنة لأنماط الوصول المختلفة.
## LSM-Tree (مفتاح-قيمة)
محرك التخزين الأساسي المحسن للكتابة مع بنية log-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 للدائمة
- **SSTable**: جداول السلاسل المرتبة على القرص
- **Bloom Filter**: بنية احتمالية للبحث السلبي السريع
- **الضغط**: استراتيجية ذات طبقات بحجم مع إدارة المستويات
- **ذاكرة الصفحة**: ذاكرة مؤقتة LRU مع تتبع معدل الإصابة
## فهرس 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")
```
## 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 "ربما موجود"
```
docs/ar/transactions.md
-47
View File
@@ -1,47 +0,0 @@
# المعاملات و MVCC
MVCC (تحكم التزامن متعدد الإصدارات) مع عزل اللقطة واكتشاف الجمود.
## الاستخدام
```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.write(txn, "key3", cast[seq[byte]]("value3"))
discard tm.rollbackToSavepoint(txn)
discard tm.commit(txn)
```
## عزل المعاملات
تستخدم BaraDB **عزل اللقطة**:
- القراء لا يحظرون الكتاب
- الكتاب لا يحظرون القراء
- كل معاملة ترى لقطة متسقة
## اكتشاف الجمود
```nim
import barabadb/core/deadlock
var detector = newDeadlockDetector()
if detector.detectCycle(txn1, txn2):
echo "تم اكتشاف الجمود!"
```
## التحقق الرسمي
تم تحديد بروتوكول MVCC/Snapshot Isolation رسمياً في TLA+:
```bash
cd formal-verification
java -cp tla2tools.jar tlc2.TLC -config models/mvcc.cfg mvcc.tla
```
docs/ar/troubleshooting.md
-81
View File
@@ -1,81 +0,0 @@
# دليل حل المشكلات
## مشاكل التثبيت
### Nim غير موجود
```bash
curl https://nim-lang.org/choosenim/init.sh -sSf | sh
```
### خطأ تجميع SSL
```bash
nim c -d:ssl -d:release -o:build/baradadb src/baradadb.nim
```
### تبعيات مفقودة
```bash
nimble install -d -y
```
## مشاكل وقت التشغيل
### المنفذ قيد الاستخدام
```bash
BARADB_PORT=5433 ./build/baradadb
```
### تم رفض الإذن
```bash
mkdir -p ./data
chmod 755 ./data
```
### ذاكرة غير كافية
```bash
BARADB_MEMTABLE_SIZE_MB=32 \
BARADB_CACHE_SIZE_MB=128 \
./build/baradadb
```
## مشاكل الاستعلام
### خطأ في الصياغة
```sql
SELECT name, age FROM users WHERE age > 18;
```
### الجدول غير موجود
```sql
CREATE TYPE User { name: str, age: int32 };
```
## مشاكل الاتصال
### تم رفض الاتصال
```bash
./build/baradadb
sudo ufw allow 9472
```
## مشاكل الأداء
### استعلامات بطيئة
1. إضافة فهارس: `CREATE INDEX idx_users_name ON users(name);`
2. استخدام LIMIT
3. زيادة ذاكرة التخزين المؤقت: `BARADB_CACHE_SIZE_MB=1024`
## وضع التصحيح
```bash
BARADB_LOG_LEVEL=debug ./build/baradadb
```
docs/ar/udf.md
-47
View File
@@ -1,47 +0,0 @@
# الدوال المحددة من المستخدم
توسيع BaraQL بالدوال المخصصة.
## الاستخدام
```nim
import barabadb/query/udf
var reg = newUDFRegistry()
reg.registerStdlib()
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' |
## تسجيل الدالة
```nim
reg.register(
name: "my_function",
params: @[UDFParam(name: "arg1", typeName: "str")],
returnType: "str",
body: proc(args: seq[Value]): Value =
result = Value(kind: vkString, strVal: "")
)
```
## استخدام UDF في الاستعلامات
```sql
SELECT greet(name) FROM users;
```
docs/ar/vector.md
-65
View File
@@ -1,65 +0,0 @@
# محرك البحث المتجهي
فهارس 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
رسم بياني Small World قابل للملاحة هرمي للبحث عن أقرب الجيران.
```nim
var hnsw = newHNSWIndex(
dimensions = 128,
m = 16,
efConstruction = 200,
efSearch = 100
)
```
### IVF-PQ
فهرس ملف مقلوب مع تكميم المنتج.
```nim
var ivfpq = newIVFPQIndex(
dimensions = 128,
numCentroids = 256,
subQuantizers = 8
)
```
## مقاييس المسافة
| المقياس | الوصف |
|---------|-------|
| `cosine` | تشابه جيب التمام |
| `euclidean` | مسافة L2 |
| `dotproduct` | تشابه المنتج النقطي |
| `manhattan` | مسافة L1 |
## التكميم
```nim
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)
```
docs/bg/index.md
+1 -7
View File
@@ -6,12 +6,6 @@
- [English](../en/)
- [Български (Bulgarian)](../bg/)
- [Deutsch (German)](../de/)
- [Русский (Russian)](../ru/)
- [فارسی (Farsi)](../fa/)
- [中文 (Chinese)](../zh/)
- [Türkçe (Turkish)](../tr/)
- [العربية (Arabic)](../ar/)
---
@@ -61,4 +55,4 @@
---
*За да добавите нов език, създайте нова папка в `docs/` с езиковия код (напр. `docs/de/`).*
*За да добавите нов език, създайте нова папка в `docs/` с езиковия код.*
docs/de/api-binary.md
-74
View File
@@ -1,74 +0,0 @@
# Binärprotokoll API
Niedrigstufiges Wire-Protokoll für hochperformante Client-Verbindungen.
## Nachrichtenformat
Alle Nachrichten verwenden Big-Endian-Byte-Reihenfolge:
```
┌────────┬────────┬────────┬────────┬─────────────┐
│ Length │ Type │ Seq │ Status │ Payload │
│ 4 bytes│ 1 byte │ 2 bytes│ 1 byte │ N bytes │
└────────┴────────┴────────┴────────┴─────────────┘
```
## Nachrichtentypen
### Query (0x01)
```nim
let msg = makeQueryMessage(seq, "SELECT * FROM users")
```
### Insert (0x02)
```nim
let msg = makeInsertMessage(seq, "users", data)
```
### Update (0x03)
```nim
let msg = makeUpdateMessage(seq, "users", updates, where)
```
### Delete (0x04)
```nim
let msg = makeDeleteMessage(seq, "users", where)
```
### Ready (0x05)
```nim
let msg = makeReadyMessage(seq)
```
### Error (0x06)
```nim
let msg = makeErrorMessage(seq, code, message)
```
## Antwortcodes
| Code | Name | Beschreibung |
|------|------|-------------|
| 0x00 | OK | Erfolg |
| 0x01 | ERROR | Allgemeiner Fehler |
| 0x02 | AUTH_REQUIRED | Authentifizierung erforderlich |
| 0x03 | INVALID_QUERY | Abfragesyntaxfehler |
| 0x04 | NOT_FOUND | Ressource nicht gefunden |
## Serialisierung
```nim
import barabadb/protocol/wire
# Wert serialisieren
let bytes = serializeValue(Value(kind: vkString, strVal: "test"))
# Wert deserialisieren
let value = deserializeValue(bytes)
```
docs/de/api-http.md
-91
View File
@@ -1,91 +0,0 @@
# HTTP/REST API
JSON-basierte REST API für Web-Anwendungen.
## Basis-URL
```
http://localhost:9470/api
```
## Endpoints
### GET /api/users
Alle Benutzer auflisten:
```bash
curl http://localhost:9470/api/users
```
Antwort:
```json
[
{"id": 1, "name": "Alice", "age": 30},
{"id": 2, "name": "Bob", "age": 25}
]
```
### GET /api/users/:id
Benutzer nach ID abrufen:
```bash
curl http://localhost:9470/api/users/1
```
### POST /api/users
Benutzer erstellen:
```bash
curl -X POST http://localhost:9470/api/users \
-H "Content-Type: application/json" \
-d '{"name": "Charlie", "age": 35}'
```
### PUT /api/users/:id
Benutzer aktualisieren:
```bash
curl -X PUT http://localhost:9470/api/users/1 \
-H "Content-Type: application/json" \
-d '{"name": "Alice", "age": 31}'
```
### DELETE /api/users/:id
Benutzer löschen:
```bash
curl -X DELETE http://localhost:9470/api/users/1
```
## Query-Endpoint
BaraQL-Abfragen über HTTP ausführen:
```bash
curl -X POST http://localhost:9470/api/query \
-H "Content-Type: application/json" \
-d '{"sql": "SELECT * FROM users WHERE age > 18"}'
```
## Fehlerantwort
```json
{
"error": {
"code": "INVALID_QUERY",
"message": "Syntax error at line 1"
}
}
```
## Authentifizierung
```bash
curl -H "Authorization: Bearer <token>" \
http://localhost:9470/api/users
```
docs/de/api-websocket.md
-120
View File
@@ -1,120 +0,0 @@
# WebSocket API
Vollduplex-Streaming für Echtzeit-Datenfeeds und Push-Benachrichtigungen.
## Verbindung
```
ws://localhost:9471/ws
```
## Client-Beispiel
```javascript
const ws = new WebSocket('ws://localhost:9471/ws');
ws.onopen = () => {
console.log('Connected');
ws.send(JSON.stringify({
type: 'query',
sql: 'SELECT * FROM users'
}));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Received:', data);
};
```
## Nachrichtenformat
```json
{
"type": "query",
"id": "uuid",
"sql": "SELECT * FROM users"
}
```
## Nachrichtentypen
### Query-Anfrage
```json
{
"type": "query",
"id": "123",
"sql": "SELECT * FROM users"
}
```
### Query-Antwort
```json
{
"type": "result",
"id": "123",
"data": [
{"id": 1, "name": "Alice"},
{"id": 2, "name": "Bob"}
]
}
```
### Fehlerantwort
```json
{
"type": "error",
"id": "123",
"error": {
"code": "INVALID_QUERY",
"message": "Syntax error"
}
}
```
### Subscription
Änderungen abonnieren:
```json
{
"type": "subscribe",
"id": "sub1",
"table": "users"
}
```
### Push-Benachrichtigung
Server-Push:
```json
{
"type": "push",
"table": "users",
"action": "insert",
"data": {"id": 3, "name": "Charlie"}
}
```
## JavaScript-Client
```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, sql }));
});
}
}
```
docs/de/architecture.md
-152
View File
@@ -1,152 +0,0 @@
# BaraDB Architektur
## Überblick
BaraDB ist eine **multimodale Datenbank-Engine** in Nim, die Document (KV), Graph, Vector, Columnar und Full-Text Search Speicherung in einer einzigen Engine mit einer einheitlichen Abfragesprache namens **BaraQL** kombiniert.
## Schichten-Architektur
```
┌─────────────────────────────────────────────────────────┐
│ 1. CLIENT LAYER │
│ Binary Protocol │ HTTP/REST │ WebSocket │ Embedded │
├─────────────────────────────────────────────────────────┤
│ 2. QUERY LAYER (BaraQL) │
│ Lexer → Parser → AST → IR → Optimizer → Codegen │
├─────────────────────────────────────────────────────────┤
│ 3. EXECUTION ENGINE │
│ Document │ Graph │ Vector │ Columnar │ FTS │
├─────────────────────────────────────────────────────────┤
│ 4. STORAGE │
│ LSM-Tree │ B-Tree │ WAL │ Bloom │ Compaction │ Cache │
├─────────────────────────────────────────────────────────┤
│ 5. DISTRIBUTED │
│ Raft Consensus │ Sharding │ Replication │ Gossip │
└─────────────────────────────────────────────────────────┘
```
## Schicht 1: Client-Layer
Mehrere Kommunikationsprotokolle:
- **Binärprotokoll** (`protocol/wire.nim`): Effizientes Big-Endian Binärprotokoll mit 16 Nachrichtentypen
- **HTTP/REST** (`core/httpserver.nim`): JSON-basierte REST API mit Multi-Threading
- **WebSocket** (`core/websocket.nim`): Vollduplex-Streaming
- **Embedded** (`storage/lsm.nim`): Direkter In-Process-Zugriff
### Verbindungsmanagement
- **Connection Pool** (`protocol/pool.nim`): Min/Max Verbindungslimits mit Idle-Timeout
- **Rate Limiting** (`protocol/ratelimit.nim`): Token-Bucket globale und per-Client Limits
- **Authentifizierung** (`protocol/auth.nim`): JWT mit HMAC-SHA256 und rollenbasierter Zugriff
- **TLS/SSL** (`protocol/ssl.nim`): TLS 1.3 mit auto-generierten Zertifikaten
## Schicht 2: Query-Layer (BaraQL)
Die BaraQL-Pipeline:
1. **Lexer** (`query/lexer.nim`): Tokenisiert Eingabe in 80+ Tokentypen
2. **Parser** (`query/parser.nim`): Rekursiver Descent-Parser produziert AST
3. **AST** (`query/ast.nim`): 300+ Zeilen mit 25+ Knotenarten
4. **IR** (`query/ir.nim`): Intermediate Representation für Ausführungspläne
5. **Optimizer** (`query/adaptive.nim`): Adaptive Cross-Modal Query-Optimierung
6. **Codegen** (`query/codegen.nim`): Übersetzt IR zu Speicheroperationen
7. **Executor** (`query/executor.nim`): Führt Pläne mit Parallelisierung aus
### Cross-Modal Planning
Der Optimizer (`query/adaptive.nim`) bestimmt die Ausführungsreihenfolge über Engines:
```
1. Selektivität für jedes Prädikat schätzen
2. Selektivstes Prädikat zuerst an seine Engine pushen
3. Bloom-Filter für KV-Lookups verwenden
4. Unabhängige Zweige parallelisieren
5. Results streamen um Materialisierung zu vermeiden
```
## Schicht 3: Execution Engine
### Document/KV Engine
- **LSM-Tree** (`storage/lsm.nim`): Write-optimierte Speicherung mit MemTable, WAL, SSTables
- **B-Tree Index** (`storage/btree.nim`): Geordneter Index für Bereichsscans mit COW
### Vector Engine (`vector/`)
- **HNSW Index** (`vector/engine.nim`): Hierarchical Navigable Small World Graph
- **IVF-PQ Index** (`vector/engine.nim`): Inverted File Index mit Product Quantization
- **SIMD Operations** (`vector/simd.nim`): AVX2-optimierte Distanzberechnungen
- **Quantization** (`vector/quant.nim`): Scalar, Product und Binary Quantization
### Graph Engine (`graph/`)
- **Adjacency List** (`graph/engine.nim`): Kanten-gewichteter gerichteter Graph
- **Algorithmen** (`graph/engine.nim`): BFS, DFS, Dijkstra, PageRank
- **Community Detection** (`graph/community.nim`): Louvain-Algorithmus
- **Pattern Matching** (`graph/community.nim`): Subgraph-Isomorphie
- **Cypher Parser** (`graph/cypher.nim`): Cypher-ähnliche Graph-Abfragen
### Full-Text Search (`fts/`)
- **Inverted Index** (`fts/engine.nim`): Term-Document Index
- **Ranking** (`fts/engine.nim`): BM25 und TF-IDF Scoring
- **Fuzzy Search** (`fts/engine.nim`): Levenshtein-Distanz-Matching
- **Multi-Language** (`fts/multilang.nim`): Tokenizer für EN, BG, DE, FR, RU
### Columnar Engine (`core/columnar.nim`)
- Perspalten-Speicherung für analytische Abfragen
- RLE und Dictionary-Kodierung
- SIMD-beschleunigte Aggregatfunktionen
## Schicht 4: Storage
- **LSM-Tree** (`storage/lsm.nim`): MemTable, WAL, SSTable, Bloom-Filter, Compaction
- **Page Cache** (`storage/compaction.nim`): LRU-Cache mit Trefferraten-Verfolgung
- **Memory-mapped I/O** (`storage/mmap.nim`): mmap-basierter Dateizugriff
- **Recovery** (`storage/recovery.nim`): WAL-Replay und Crash-Recovery
### Write Path
```
Client → Protocol → Auth → Parser → AST → IR → Codegen
→ StorageOp → MVCC Txn → WAL Write → MemTable → Commit
```
### Read Path
```
Client → Protocol → Auth → Parser → AST → IR → Codegen
→ StorageOp → MVCC Snapshot → MemTable → SSTable → Result
```
## Schicht 5: Distributed
- **Raft Consensus** (`core/raft.nim`): Leader Election, Log-Replikation
- **Sharding** (`core/sharding.nim`): Hash, Range und Consistent Hashing
- **Replication** (`core/replication.nim`): Sync, Async, Semi-Sync Modi
- **Gossip Protocol** (`core/gossip.nim`): SWIM-ähnliches Membership-Management
- **Distributed Transactions** (`core/disttxn.nim`): Two-Phase Commit
## Wichtige Designentscheidungen
1. **Reines Nim**: Keine Cython, Python oder Rust Abhängigkeiten
2. **Unified Storage**: Eine Engine-handelt KV, Graph, Vector, FTS und Columnar
3. **Embedded Mode**: Kann als Bibliothek oder Server laufen
4. **Binärprotokoll**: Custom effizientes Wire-Protokoll
5. **MVCC**: Multi-Version Concurrency Control
6. **Schema-First**: Stark typisiertes Schema-System mit Vererbung
7. **Cross-Modal**: Einheitliche Abfragesprache über alle Datenmodelle
8. **Formally Verified**: Kern-Algorithmen in TLA+ spezifiziert und mit TLC model-gecheckt
## Modulstatistiken
| Kategorie | Module | Codezeilen | Zweck |
|----------|--------|------------|-------|
| Core | 16 | ~4,200 | Server, Protokolle, Transaktionen, Distributed |
| Storage | 7 | ~3,100 | LSM, B-Tree, WAL, Bloom, Compaction, mmap |
| Query | 7 | ~2,800 | Lexer, Parser, AST, IR, Optimizer, Codegen, Executor |
| Vector | 3 | ~1,200 | HNSW, IVF-PQ, Quantization, SIMD |
| Graph | 3 | ~1,000 | Adjacency List, Algorithmen, Community Detection |
| FTS | 2 | ~900 | Inverted Index, BM25, Fuzzy, Multi-Language |
| Protocol | 7 | ~2,400 | Wire, HTTP, WebSocket, Pool, Auth, Rate Limit, SSL |
| Schema | 1 | ~600 | Typen, Links, Vererbung, Migrationen |
| Client | 2 | ~800 | Nim Binary Client, File Helpers |
| CLI | 1 | ~400 | Interaktive BaraQL Shell |
| **Total** | **49** | **~14,100** | |
docs/de/backup.md
-199
View File
@@ -1,199 +0,0 @@
# Backup & Wiederherstellung
## Online Snapshots
BaraDB unterstützt Online-Snapshots ohne Server-Stopp. Der Snapshot erfasst eine
konsistente Point-in-Time-Ansicht mittels MVCC.
### Snapshot erstellen
```nim
import barabadb/core/backup
var bm = newBackupManager()
bm.createSnapshot("/backup/baradb_2025-01-15")
```
### Via CLI
```bash
./build/baradadb --snapshot --output=/backup/snapshot.db
```
### Via HTTP API
```bash
curl -X POST http://localhost:9470/api/backup \
-H "Content-Type: application/json" \
-d '{"destination": "/backup/snapshot.db"}'
```
### Automatisierte Backups
Cron für geplante Backups verwenden:
```bash
# Daily snapshot at 2 AM
0 2 * * * /usr/local/bin/baradadb --snapshot --output=/backup/baradb_$(date +\%Y\%m\%d).db
# Letzte 7 Tage behalten
find /backup -name "baradb_*.db" -mtime +7 -delete
```
## Point-in-Time Recovery (PITR)
BaraDB verwendet das Write-Ahead Log (WAL) für Point-in-Time Recovery.
### WAL-Archivierung
Kontinuierliche WAL-Archivierung aktivieren:
```bash
BARADB_WAL_ARCHIVE_DIR=/backup/wal \
BARADB_WAL_ARCHIVE_INTERVAL_MS=60000 \
./build/baradadb
```
### Wiederherstellung von Checkpoint + WAL
```bash
# Von Snapshot wiederherstellen
./build/baradadb --recover \
--checkpoint=/backup/snapshot.db \
--wal-dir=/backup/wal
# Wiederherstellung zu spezifischem LSN
./build/baradadb --recover \
--checkpoint=/backup/snapshot.db \
--wal-dir=/backup/wal \
--target-lsn=15420
# Wiederherstellung zu spezifischer Zeit
./build/baradadb --recover \
--checkpoint=/backup/snapshot.db \
--wal-dir=/backup/wal \
--target-time="2025-01-15T10:30:00Z"
```
### Wiederherstellung via SQL
Sie können auch direkt via BaraQL wiederherstellen:
```sql
RECOVER TO TIMESTAMP '2026-05-07T12:00:00';
```
### Inkrementelle Backups
Inkrementelle Backups kopieren nur geänderte SSTables:
```bash
./build/baradadb --backup-incremental \
--last-backup=/backup/previous \
--output=/backup/incremental_$(date +%Y%m%d)
```
## Replikation als Backup
Für kontinuierlichen Schutz, Streaming-Replikation verwenden:
### 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
### Wiederherstellungsverfahren
#### Szenario 1: Einzelne Dateikorruption
```bash
# Korrupte SSTable aus Logs identifizieren
# Spezifische SSTable aus Backup wiederherstellen
cp /backup/sstables/000012.sst ./data/sstables/
# Index neu aufbauen
./build/baradadb --rebuild-index
```
#### Szenario 2: Kompletter Datenverlust
```bash
# 1. Neuesten Snapshot wiederherstellen
cp /backup/snapshot.db ./data/
# 2. WAL replay
./build/baradadb --recover --wal-dir=/backup/wal
# 3. Verifizieren
curl http://localhost:9470/health
```
#### Szenario 3: Cluster-Knoten-Ausfall
```bash
# Für Raft-Cluster, einfach neuen Knoten starten
BARADB_RAFT_NODE_ID=newnode \
BARADB_RAFT_PEERS=node1:9001,node2:9001 \
./build/baradadb
# Der neue Knoten wird über Raft-Log-Replikation aufholen
```
## Backup-Verifizierung
Backups immer verifizieren:
```bash
# In temporäres Verzeichnis wiederherstellen
./build/baradadb --recover \
--checkpoint=/backup/snapshot.db \
--data-dir=/tmp/verify_data
# Konsistenzprüfung ausführen
curl http://localhost:9470/api/admin/check
```
## Speicheranforderungen
| Backup-Typ | Größe | Häufigkeit | Aufbewahrung |
|-------------|------|-----------|--------------|
| Full snapshot | ~1× Datengröße | Täglich | 7 Tage |
| Inkrementell | ~0.1× Datengröße | Stündlich | 24 Stunden |
| WAL-Archiv | ~0.05× Datengröße / Tag | Kontinuierlich | 30 Tage |
## Best Practices
1. **Restores regelmäßig testen** — Ein Backup das Sie nicht wiederherstellen können ist wertlos
2. **Backups außerhalb speichern** — S3, GCS oder Azure Blob verwenden
3. **Backups verschlüsseln** — `gpg` oder OS-Level-Verschlüsselung verwenden
4. **Backup-Jobs überwachen** — Bei fehlgeschlagenen Backups alarmieren
5. **RTO/RPO dokumentieren** — Ihre Wiederherstellungszeit und Punktziele kennen
### Cloud-Backup-Upload
```bash
# Zu S3 hochladen
aws s3 cp /backup/snapshot.db s3://my-bucket/baradb/
# Zu GCS hochladen
gsutil cp /backup/snapshot.db gs://my-bucket/baradb/
# Zu Azure hochladen
az storage blob upload \
--container-name backups \
--file /backup/snapshot.db \
--name baradb/snapshot.db
```
docs/de/baraql.md
-114
View File
@@ -1,114 +0,0 @@
# BaraQL — Abfragesprache-Referenz
BaraQL ist eine SQL-kompatible Abfragesprache mit Erweiterungen für Graph-, Vektor- und Dokumentoperationen.
## Datentypen
| Typ | Beschreibung | Beispiel |
|------|-------------|---------|
| `null` | Nullwert | `null` |
| `bool` | Boolean | `true`, `false` |
| `int64` | 64-bit Ganzzahl | `42` |
| `float64` | 64-bit Fließkomma | `3.14` |
| `str` | UTF-8 String | `'hello'` |
| `vector(n)` | Float32 Vektor | `VECTOR(768)` |
| `json` | JSON-Dokument | `{"key": "value"}` |
## Grundlegende Abfragen
```sql
SELECT * FROM users;
SELECT name, age FROM users WHERE age > 18;
SELECT * FROM users ORDER BY age DESC LIMIT 10;
```
## Vektor-Operationen
```sql
-- Distanzberechnungen
SELECT cosine_distance(embedding, '[0.1, 0.2, 0.3]') AS dist FROM items;
SELECT embedding <-> '[0.1, 0.2, 0.3]' AS dist FROM items;
-- Hybride Suche
SELECT hybrid_search('query', embedding, content, 10) AS result;
```
## Graph-Operationen
```sql
CREATE GRAPH social;
DROP GRAPH social;
-- Traversierung
SELECT * FROM GRAPH_TABLE(social MATCH (n)-[r]->(m)
ALGORITHM bfs START 1
COLUMNS (id, node_label));
-- PageRank
SELECT * FROM GRAPH_TABLE(social ALGORITHM pagerank
COLUMNS (id, node_label, rank));
-- Community Detection
SELECT * FROM GRAPH_TABLE(social ALGORITHM community
COLUMNS (id, node_label, community));
```
## AI-Funktionen
```sql
-- Text in Chunks zerlegen
SELECT chunk('Langer Text...', 1024, 128) AS result;
-- Embedding generieren
SELECT embed_text('Suchtext') AS result;
-- Natural Language → SQL
SELECT nl_to_sql('Zeige alle Benutzer über 25', 'users') AS result;
-- Schema-Prompt für LLM
SELECT schema_prompt('users') AS result;
-- Cypher-Übersetzung
SELECT cypher('MATCH (a)-[r]->(b) RETURN a.node_label') AS result;
-- Knotenähnlichkeit
SELECT similarity_nodes('social', 'jaccard') AS result;
-- Graph-Embeddings
SELECT node2vec_embed('social', 64) AS result;
```
## Joins
```sql
SELECT u.name, o.amount
FROM users u
INNER JOIN orders o ON u.id = o.user_id;
```
## Aggregation
```sql
SELECT department, COUNT(*), AVG(salary)
FROM employees
GROUP BY department
HAVING COUNT(*) > 5;
```
## Index-Erstellung
```sql
CREATE INDEX idx_name ON users(name) USING btree;
CREATE INDEX idx_vec ON docs(embedding) USING hnsw;
CREATE INDEX idx_fts ON docs(content) USING fts;
```
## Multi-Tenant / RLS
```sql
CREATE POLICY tenant_policy ON orders
FOR ALL USING (tenant_id = current_setting('app.tenant_id'));
SET app.tenant_id = 'company-a';
SELECT * FROM orders; -- Automatisch gefiltert
```
docs/de/btree.md
-38
View File
@@ -1,38 +0,0 @@
# B-Tree Index
Geordnete Indexstruktur für effiziente Bereichsabfragen und Point-Lookups.
## Verwendung
```nim
import barabadb/storage/btree
var btree = newBTreeIndex[string, string]()
# Einfügen
btree.insert("key1", "value1")
btree.insert("key2", "value2")
# Point-Lookup
let values = btree.get("key1")
# Bereichsabfrage
let range = btree.scan("key_a", "key_z")
# Löschen
btree.delete("key1")
```
## Funktionen
- Geordnete Schlüssel-Wert-Speicherung
- Bereichsabfragen (BETWEEN, >, <, >=, <=)
- Präfix-Scans
- Konfigurierbare Seitengröße
- Iterator-Unterstützung
## Anwendungsfälle
- Primärschlüssel-Indizes
- Sekundärindizes für häufig abgefragte Spalten
- Bereichspartitionierte Daten
docs/de/changelog.md
-247
View File
@@ -1,247 +0,0 @@
# Changelog
Alle bemerkenswerten Änderungen an BaraDB werden in dieser Datei dokumentiert.
## [Unreleased] — AI-Native Platform
### Hinzugefügt
- **MCP Server (Model Context Protocol)** — STDIO JSON-RPC 2.0 Server mit 3 AI-Tools:
- `query` — SQL-Ausführung mit parametrisierten Abfragen + Multi-Tenant Session-Variablen
- `vector_search` — Semantische HNSW Vektor-suche mit Tenant-Isolation
- `schema_inspect` — Tabellen-/Spalten-/Index-/RLS-Policy-Exploration
- Standalone Binary: `build/baramcp`
- **Graph Engine Tiefe Integration** — `CREATE GRAPH` / `DROP GRAPH` DDL mit nativer Adjacency-List-Speicherung
- `GRAPH_TABLE()` SQL-Funktion mit 7 Algorithmen: BFS, DFS, PageRank, ShortestPath, Dijkstra, Louvain, Community
- INSERT in `_nodes`/`_edges` Tabellen synchronisiert automatisch mit nativen Graph-Objekten
- Optional `MATCH`, `ALGORITHM`, `START`, `END`, `MAXDEPTH` in GRAPH_TABLE Syntax
- **Chunking + Embedding Pipeline** — Serverseitige AI-Datenverarbeitung:
- `chunk()` SQL-Funktion — Text-Splitting mit konfigurierbarer Größe/Überlappung
- `embed_text()` SQL-Funktion — ruft externe Embedding-API auf (OpenAI/Ollama kompatibel)
- Auto-Embedding bei INSERT — wenn VECTOR-Spalte null ist, generiert aus TEXT-Spalte
- Konfigurierbar via Env-Vars: `BARADB_EMBED_ENDPOINT`, `BARADB_EMBED_MODEL`, `BARADB_EMBED_API_KEY`
- **LangChain ChatMessageHistory** — Python `BaraDBChatHistory` Klasse:
- Speichert Konversations-Threads in relationaler Tabelle mit RLS
- Multi-Tenant Isolation via `tenant_id` + `user_id`
- **RAG Pipeline Beispiel** — End-to-End Python Script (`examples/rag_pipeline.py`):
- PDF/text Ingestion → chunking → embedding → BaraDB Speicherung → hybrid search → LLM Generierung
- Unterstützt OpenAI und Ollama APIs
- **AI Agents & NL→SQL** — Serverseitige LLM-Integration:
- `nl_to_sql()` SQL-Funktion — natürliche Sprache → SQL Generierung
- `schema_prompt()` — generiert DDL + Beispieldaten für LLM-Kontext
- Abfrage-Validierungsschicht — Sandbox-Ausführung mit LIMIT 0 + EXPLAIN
- Selbst-Korrektur-Schleife — Fehlerfeedback an LLM zur Korrektur
- Konfigurierbar via Env-Vars: `BARADB_LLM_ENDPOINT`, `BARADB_LLM_MODEL`, `BARADB_LLM_API_KEY`
- **Graph Similarity & Embeddings**:
- `similarity_nodes()` — Jaccard/Adamic-Adar Ähnlichkeit zwischen Knotenpaaren
- `node2vec_embed()` — Random-walk basierte Graph Embeddings
- **Cypher Compatibility Layer**:
- `cypher()` SQL-Funktion — übersetzt `MATCH (a)-[r]->(b) RETURN ...` zu GRAPH_TABLE
- Automatische Cypher → BaraQL Konvertierung
- **German Documentation** — Vollständige Dokumentation auf Deutsch (`docs/de/`)
### Geändert
- Graph Executor upgraded von Stub zu echtem BFS/DFS/PageRank/Dijkstra/Louvain
- ExecutionContext erweitert mit `graphs`, `embedder`, `llmClient` Feldern
- Graph Engine erweitert mit `addNodeWithId`, `addEdgeWithId`, Jaccard, Adamic-Adar, node2vec
## [1.1.0] — 2026-05-13
### Hinzugefügt
- **Client SDKs v1.1.6** — Vollständige Clients für alle Sprachen:
- JavaScript: TypeScript Definitionen, package.json, Beispiele, Unit & Integration Tests
- Python: Umstrukturiert als proper Package (`baradb/` mit `__init__.py` und `core.py`), pyproject.toml, Beispiele, Tests
- Nim: Beispiele, Integration Tests, README
- Rust: Beispiele, Integration Tests, verbessertes Cargo.toml
- **SCRAM-SHA-256 Authentifizierung** — RFC 7677 konforme Authentifizierung mit PBKDF2 + HMAC + SHA-256 + Nonce/Salt Generierung
- **HTTP SCRAM Endpoints** — `/auth/scram/start` + `/auth/scram/finish` im HTTP Server
- **Docker Compose Test Configuration** — `docker-compose.test.yml` für Test-Umgebungen
- **CI/CD Clients Pipeline** — `.github/workflows/clients-ci.yml` für automatisierte Client-Tests
### Behoben
- **Query Executor** — Unärer Minus (`irNeg`) funktioniert jetzt korrekt in SELECT und WHERE Klauseln
- **Distributed Transactions** — Rollback nach Commit-Versuch verletzt nicht mehr Atomicity
- **Sharding** — Datenmigrations-Protokoll mit TCP + `scanAll` auf LSM
- **Raft** — Majority-Berechnung für gerade Knotenanzahl korrigiert
- **MVCC** — Abgebrochene Transaktionen werden nicht mehr sichtbar
- **LSM-Tree** — Datenverlust bei immutable memtable overwrite behoben; SSTable lookup sorting behoben
- **Auth** — JWT-Signatur auf HMAC-SHA256 geändert (nicht mehr trivial fälschbar); Token-Ablauf (`exp`/`nbf`/`iat`) wird jetzt validiert; Signatur-Vergleich ist jetzt constant-time
- **Recovery** — `summary()` mutiert die Datenbank nicht mehr
- **Wire Protocol** — 64MB Limit + Bounds Checking + Max Depth um OOM/DoS zu verhindern
- **SQL Injection** — `exprToSql` escaped jetzt Single Quotes
- **ReDoS** — `irLike`/`irILike` escaped jetzt Regex Metacharacters
- **Graph** — `addEdge` prüft jetzt Knotenexistenz
- **Vector** — Dimension mismatch Validierung + HNSW Locking
- **FTS** — UTF-8 Tokenisierung verwendet jetzt runes statt bytes
- **Build** — `nim.cfg` fügt `-d:ssl` hinzu damit `nimble build` ohne Flags funktioniert; `--threads:on` zu allen CI Commands hinzugefügt
### Geändert
- **Version auf 1.1.0 erhöht** über alle Komponenten
- **README** — Version Badge aktualisiert; alle Feature-Tabellen referenzieren jetzt v1.1.6
- **TLA+ Formal Verification** — `crossmodal.tla`, `backup.tla`, `recovery.tla` hinzugefügt; Symmetrie-Reduktion in allen 9 Specs
- **Clean build** — 0 Compiler Warnings auf Nim 2.2.10
## [0.1.0] — 2025-01-15
### Hinzugefügt
- **Core Storage Engines**
- LSM-Tree mit MemTable, WAL, SSTables und size-tiered Compaction
- B-Tree geordneter Index mit Range Scans und MVCC Copy-on-Write
- Bloom Filter für effizientes SSTable Skip
- Memory-mapped I/O für SSTable Reads
- LRU Page Cache mit Hit-Rate Tracking
- **Query Engine (BaraQL)**
- SQL-kompatibler Lexer mit 80+ Tokentypen
- Rekursiver Descent Parser produziert AST mit 25+ Knotenarten
- Intermediate Representation (IR) für Ausführungspläne
- Code Generator übersetzt IR zu Speicheroperationen
- Adaptiver Query Optimizer mit Cross-Modal Planning
- Query Executor mit Parallelisierung
- **BaraQL Language Features**
- SELECT, INSERT, UPDATE, DELETE
- WHERE, ORDER BY, LIMIT, OFFSET
- GROUP BY, HAVING, Aggregatfunktionen (count, sum, avg, min, max)
- INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN
- CTEs (Common Table Expressions) mit WITH
- Subqueries (EXISTS, IN, correlated)
- CASE Expressions
- UNION, INTERSECT, EXCEPT
- Schema Definition: CREATE TYPE, DROP TYPE
- **Vector Engine**
- HNSW Index für Approximate Nearest Neighbor Search
- IVF-PQ Index für Large-Scale Vector Search
- SIMD-optimierte Distanzfunktionen (cosine, L2, dot product, Manhattan)
- Quantization: scalar 8-bit/4-bit, product quantization, binary
- Metadata Filtering während Vector Search
- **Graph Engine**
- Adjacency List Speicherung für gerichtete, kanten-gewichtete Graphen
- BFS und DFS Traversierung
- Dijkstra kürzester Pfad
- PageRank Knotenwichtigkeit
- Louvain Community Detection
- Subgraph Pattern Matching
- Cypher-ähnlicher Graph Query Parser
- **Full-Text Search**
- Inverted Index mit Term-Document Mapping
- BM25 Ranking-Algorithmus
- TF-IDF Scoring
- Fuzzy Search mit Levenshtein Distanz
- Wildcard/regex Search
- Multi-Language Tokenizer (English, Bulgarian, German, French, Russian)
- **Columnar Storage**
- Perspalten-Speicherung für analytische Abfragen
- RLE (Run-Length Encoding) Kompression
- Dictionary Encoding für Low-Cardinality Spalten
- SIMD-beschleunigte Aggregatfunktionen
- **Transactions**
- MVCC (Multi-Version Concurrency Control) mit Snapshot Isolation
- Deadlock-Erkennung via Wait-for Graph
- Write-Ahead Log für Dauerhaftigkeit
- Savepoints und partielles Rollback
- **Protocol Layer**
- Binary Wire Protocol mit 16 Nachrichtentypen
- HTTP/REST JSON API
- WebSocket Streaming
- Connection Pooling
- JWT-basierte Authentifizierung
- Token-bucket Rate Limiting
- TLS/SSL mit auto-generierten Zertifikaten
- **Schema System**
- Starkes Typsystem mit 17 nativen Typen
- Typvererbung mit Multi-Base Support
- Property Links zwischen Typen
- Schema Diffing und Migrationen
- Computed Properties
- **Distributed Systems**
- Raft Consensus (Leader Election, Log Replikation)
- Hash, Range und Consistent-Hash Sharding
- Sync/async/semi-sync Replikation
- Gossip Protocol für Membership Management
- Two-Phase Commit für Distributed Transactions
- **Cross-Modal Queries**
- Vereinheitlichte Abfragesprache über alle Speicher-Engines
- Cross-Engine Predicate Pushdown
- Optimierte Ausführungspläne für Multi-Modal Abfragen
- **Backup & Recovery**
- Online Snapshots ohne Ausfallzeit
- Point-in-Time Recovery via WAL Replay
- Inkrementelle Backups
- **Client SDKs**
- JavaScript/TypeScript Client mit Binary Protocol
- Python Client mit Sync und Async APIs
- Nim Embedded Mode und Client Library
- Rust Client (async)
- **Operations**
- Interaktive CLI Shell (BaraQL REPL)
- Strukturiertes Logging (JSON und Text Formate)
- Prometheus-kompatible Metrics Endpoint
- Health und Readiness Probes
- CPU/memory Profiling Endpoints
- **Docker Support**
- Multi-stage Dockerfile (Alpine Linux)
- Docker Compose Konfiguration
- Health Checks
### Performance
- LSM-Tree: 580K writes/s, 720K reads/s
- B-Tree: 1.2M inserts/s, 1.5M lookups/s
- Vector SIMD: 850K cosine distances/s (dim=768)
- FTS: 320K docs/s indexing, 28K queries/s BM25
- Graph: 2.5M nodes/s insertion, 12K BFS traversals/s
- Binary Protocol: 380K queries/s (100 concurrent connections)
### Tests
- 262 Tests über 56 Test-Suiten
- 100% Pass Rate
## [Unreleased]
### Hinzugefügt
- **Vector SQL Integration** — Vollständige SQL-Level Vector Search Unterstützung:
- `VECTOR(n)` Spaltentyp in `CREATE TABLE` mit Dimensionsvalidierung
- `CREATE INDEX ... USING hnsw` / `USING ivfpq` für Approximate Nearest Neighbor Indizes
- SQL Distanzfunktionen: `cosine_distance()`, `euclidean_distance()`, `inner_product()`, `l1_distance()`, `l2_distance()`
- `<->` Nearest-Neighbor Operator (Euclidean Distanz)
- `ORDER BY` Support für Vektor-Distanz-Ausdrücke, inklusive Spalten nicht in `SELECT`
- Automatische HNSW Index-Wartung bei `INSERT` und `UPDATE`
- **Advanced SQL Engine** — Window Functions, MERGE/UPSERT, LATERAL JOIN, PIVOT/UNPIVOT, SQL/PGQ Property Graph, Advanced Aggregates
- **JavaScript Client — TCP Request Queue** — Interne `_requestQueue` + `_requestLock` für sichere konkurrierende Abfragen
### Behoben
- **Query Executor — Row Value Escaping** — `execInsert` escaped jetzt korrekt Kommas und Equals-Zeichen
- **Query Planner — ORDER BY Projection** — `irpkSort` ist jetzt vor `irpkProject` im IR Plan platziert
- **Wire Protocol — Big-Endian Float Serialization** — `FLOAT32`/`FLOAT64` werden jetzt in Big-Endian Byte-Reihenfolge serialisiert
- **Gossip Protocol — Async UDP Socket** — Synchrone `newSocket` + blocking `recvFrom` ersetzt durch `newAsyncSocket` + `await recvFrom`
### Geplant
- Query Plan Caching
- Materialized Views
- Geospatial Index
- Time-series Optimierungen
- CDC (Change Data Capture) Streaming
- Federated Queries über BaraDB Instances
docs/de/clients.md
-285
View File
@@ -1,285 +0,0 @@
# Client SDKs
BaraDB bietet offizielle Client-Bibliotheken für JavaScript/TypeScript, Python, Nim und Rust.
## JavaScript / TypeScript
### Installation
```bash
npm install baradb
# oder
yarn add baradb
```
### Grundlegende Verwendung
```typescript
import { Client } from 'baradb';
const client = new Client('localhost', 9472);
await client.connect();
// Einfache Abfrage
const result = await client.query('SELECT name, age FROM users WHERE age > 18');
console.log(result.rows);
// Parametrisierte Abfrage
const result2 = await client.query(
'SELECT * FROM users WHERE name = ?',
['Alice']
);
// Batch-Einfügung
await client.batch([
"INSERT users { name := 'Alice', age := 30 }",
"INSERT users { name := 'Bob', age := 25 }",
]);
// Transaktionen
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();
```
### Konkurrierende Abfragen
Der JavaScript-Client serialisiert konkurrierende Anfragen über eine einzelne TCP-Verbindung automatisch via interner Request-Queue. Sie können sicher mehrere parallele Operationen starten — ihre Binärframes werden sich nicht auf dem Wire überlappen:
```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-Streaming
```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
### Installation
```bash
pip install baradb
```
### Grundlegende Verwendung
```python
from baradb import Client
client = Client("localhost", 9472)
client.connect()
# Einfache Abfrage
result = client.query("SELECT name, age FROM users WHERE age > 18")
for row in result:
print(row["name"], row["age"])
# Parametrisierte Abfrage
result = client.query(
"SELECT * FROM users WHERE name = ?",
["Alice"]
)
# Batch-Operationen
client.batch([
"INSERT users { name := 'Alice', age := 30 }",
"INSERT users { name := 'Bob', age := 25 }",
])
# Context Manager (auto-close)
with Client("localhost", 9472) as c:
result = c.query("SELECT count(*) FROM users")
print(result[0]["count"])
```
### Async Client
```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 (Embedded Mode)
### Abhängigkeit hinzufügen
```nim
# In Ihrer .nimble Datei
requires "barabadb >= 0.1.0"
```
### Embedded-Verwendung
```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 Index
var btree = newBTreeIndex[string, int]()
btree.insert("Alice", 30)
let ages = btree.get("Alice")
# Vector Search
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)
# Graph
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)
```
### Client-Bibliothek
```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
### Abhängigkeit hinzufügen
```toml
[dependencies]
baradb = "0.1"
tokio = { version = "1", features = ["full"] }
```
### Grundlegende Verwendung
```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 (Sprachunabhängig)
Alle Sprachen können die HTTP/REST API direkt verwenden:
```bash
# Abfrage
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"}'
# Einfügen
curl -X POST http://localhost:9470/api/query \
-H "Content-Type: application/json" \
-d '{"query": "INSERT users { name := \"Alice\", age := 30 }"}'
# Schema
curl http://localhost:9470/api/schema
# Health
curl http://localhost:9470/health
# Metrics
curl http://localhost:9470/metrics
```
## Connection Pooling
Alle offiziellen Clients unterstützen 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")
```
## Datentyp-Mapping
| BaraDB Type | 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>` |
docs/de/columnar.md
-58
View File
@@ -1,58 +0,0 @@
# Kolumnare Speicherung
Spaltenorientierte Speicherung für analytische Abfragen und Aggregation.
## Verwendung
```nim
import barabadb/core/columnar
var batch = newColumnBatch()
var ageCol = batch.addInt64Col("age")
var nameCol = batch.addStringCol("name")
ageCol.appendInt64(25)
nameCol.appendString("Alice")
```
## Aggregation
```nim
echo ageCol.sumInt64()
echo ageCol.avgInt64()
echo ageCol.minInt64()
echo ageCol.maxInt64()
echo ageCol.count()
```
## Kodierung
### RLE (Run-Length Encoding)
```nim
let rle = rleEncode(@[1'i64, 1, 1, 2, 2, 3])
```
### Dictionary-Kodierung
```nim
let dict = dictEncode(@["apple", "banana", "apple"])
```
## Spaltentypen
| Typ | Beschreibung |
|------|-------------|
| `int32` | 32-Bit Integer |
| `int64` | 64-Bit Integer |
| `float32` | 32-Bit Float |
| `float64` | 64-Bit Float |
| `string` | Variable-length String |
| `bool` | Boolean |
## Anwendungsfälle
- OLAP-Workloads
- Großflächige Aggregation
- Data Warehousing
- Zeitreihenanalyse
docs/de/configuration.md
-217
View File
@@ -1,217 +0,0 @@
# Konfigurationsreferenz
BaraDB kann über **Environment-Variablen**, eine **Konfigurationsdatei** oder **Kommandozeilen-Flags** konfiguriert werden.
## Prioritätsreihenfolge
1. Kommandozeilen-Flags (höchste Priorität)
2. Environment-Variablen
3. Konfigurationsdatei (`baradb.conf` oder `baradb.json`)
4. Integrierte Standardwerte (niedrigste Priorität)
## Environment-Variablen
### Netzwerk
| Variable | Standard | Beschreibung |
|----------|---------|-------------|
| `BARADB_ADDRESS` | `127.0.0.1` | Bind-Adresse |
| `BARADB_PORT` | `9472` | TCP Binary Protocol Port |
| `BARADB_HTTP_PORT` | `9470` | HTTP/REST API Port |
| `BARADB_WS_PORT` | `9471` | WebSocket Port |
### Speicher
| Variable | Standard | Beschreibung |
|----------|---------|-------------|
| `BARADB_DATA_DIR` | `./data` | Datenverzeichnis-Pfad |
| `BARADB_MEMTABLE_SIZE_MB` | `64` | MemTable-Größe in MB |
| `BARADB_CACHE_SIZE_MB` | `256` | Page-Cache-Größe in MB |
| `BARADB_WAL_SYNC_INTERVAL_MS` | `0` | WAL fsync Intervall (0 = bei jedem Write) |
| `BARADB_COMPACTION_INTERVAL_MS` | `60000` | Background Compaction Intervall |
| `BARADB_BLOOM_BITS_PER_KEY` | `10` | Bloom-Filter Bits pro Schlüssel |
### TLS/SSL
| Variable | Standard | Beschreibung |
|----------|---------|-------------|
| `BARADB_TLS_ENABLED` | `false` | TLS aktivieren |
| `BARADB_CERT_FILE` | — | Pfad zum TLS-Zertifikat |
| `BARADB_KEY_FILE` | — | Pfad zum TLS Private Key |
### Sicherheit
| Variable | Standard | Beschreibung |
|----------|---------|-------------|
| `BARADB_AUTH_ENABLED` | `false` | Authentifizierung aktivieren |
| `BARADB_JWT_SECRET` | — | JWT Signatur-Geheimnis |
| `BARADB_RATE_LIMIT_GLOBAL` | `10000` | Globale Requests pro Sekunde |
| `BARADB_RATE_LIMIT_PER_CLIENT` | `1000` | Per-Client Requests pro Sekunde |
### Logging
| Variable | Standard | Beschreibung |
|----------|---------|-------------|
| `BARADB_LOG_LEVEL` | `info` | Log-Level: debug, info, warn, error |
| `BARADB_LOG_FILE` | — | Log-Datei-Pfad (stdout wenn leer) |
| `BARADB_LOG_FORMAT` | `json` | Log-Format: json, text |
### Vector Engine
| Variable | Standard | Beschreibung |
|----------|---------|-------------|
| `BARADB_VECTOR_M` | `16` | HNSW `M` Parameter |
| `BARADB_VECTOR_EF_CONSTRUCTION` | `200` | HNSW `efConstruction` |
| `BARADB_VECTOR_EF_SEARCH` | `64` | HNSW `efSearch` |
### Graph Engine
| Variable | Standard | Beschreibung |
|----------|---------|-------------|
| `BARADB_GRAPH_PAGE_RANK_ITERATIONS` | `20` | PageRank Iterationsanzahl |
| `BARADB_GRAPH_PAGE_RANK_DAMPING` | `0.85` | PageRank Dämpfungsfaktor |
| `BARADB_GRAPH_LOUVAIN_RESOLUTION` | `1.0` | Louvain Resolution-Parameter |
### Distributed
| Variable | Standard | Beschreibung |
|----------|---------|-------------|
| `BARADB_RAFT_NODE_ID` | — | Eindeutige Knoten-ID im Cluster |
| `BARADB_RAFT_PEERS` | — | Komma-getrennte Liste von Peer-Adressen |
| `BARADB_RAFT_PORT` | `9001` | Raft interne Kommunikation Port |
| `BARADB_SHARD_COUNT` | `1` | Anzahl der Shards |
| `BARADB_REPLICATION_FACTOR` | `1` | Replikationsfaktor |
## Konfigurationsdatei
### baradb.conf (INI-ähnlich)
```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"
}
}
```
## Kommandozeilen-Flags
```bash
./build/baradadb --help
```
```
BaraDB v1.1.6 — Multimodal Database Engine
Usage:
baradadb [options]
Options:
-c, --config <file> Config file path
-p, --port <port> TCP binary port (default: 9472)
--http-port <port> HTTP port (default: 9470)
--ws-port <port> WebSocket port (default: 9471)
-d, --data-dir <dir> Data directory (default: ./data)
--tls-cert <file> TLS certificate file
--tls-key <file> TLS private key file
--log-level <level> Log level: debug, info, warn, error
--log-file <file> Log file path
--shell Start interactive shell
--version Show version
--recover Run WAL recovery
--checkpoint <file> Checkpoint for recovery
-h, --help Show this help
```
## Beispielkonfigurationen
### Entwicklung
```bash
./build/baradadb \
--log-level debug \
--data-dir ./dev_data
```
### Produktion Single Node
```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
```
### Produktion Cluster (3 Knoten)
```bash
# Knoten 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
```
docs/de/crossmodal.md
-218
View File
@@ -1,218 +0,0 @@
# Cross-Modal Abfragen
BaraDB's einzigartige Fähigkeit ist die Ausführung von Abfragen, die mehrere
Speicher-Engines in einer einzigen vereinheitlichten BaraQL-Anweisung umfassen.
## Überblick
Traditionelle Datenbanken erfordern separate Abfragen und applikationsseitige Joins
bei der Arbeit mit verschiedenen Datenmodellen. BaraDB's Cross-Modal Query Planner
optimiert die Ausführung über:
- **Document/KV** (LSM-Tree) — strukturierte Datensätze
- **Graph** (Adjacency List) — Beziehungen
- **Vector** (HNSW/IVF-PQ) — Ähnlichkeitssuche
- **Full-Text** (Inverted Index) — Textsuche
- **Columnar** — analytische Aggregatfunktionen
## Abfragemuster
### Vector + Full-Text (Semantisch + Schlüsselwortsuche)
Finde Dokumente, die semantisch ähnlich zu einem Query-Vektor sind UND
bestimmte Schlüsselwörter enthalten:
```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;
```
Ausführungsplan:
1. FTS-Engine filtert Artikel mit "machine learning"
2. Vector-Engine rankt gefilterte Ergebnisse nach Embedding-Ähnlichkeit
3. Top-K Ergebnisse zurückgegeben
### Graph + Vector (Soziale Empfehlungen)
Finde Freunde eines Benutzers mit ähnlichen Geschmacksvektoren:
```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;
```
Ausführungsplan:
1. Graph-Engine traversiert "KNOWS"-Kanten von Alice
2. Vector-Engine berechnet Ähnlichkeit für jeden Freund
3. Ergebnisse sortiert und projiziert
### Document + Graph (Entity-Anreicherung)
Erhalte Bestelldetails mit Kunden-Beziehungsgraph:
```sql
SELECT o.id, o.total, c.name,
(SELECT count(*) FROM orders WHERE customer_id = c.id) as order_count
FROM orders o
JOIN customers c ON o.customer_id = c.id
WHERE c.id IN (
SELECT node_id FROM graph
WHERE MATCH pattern (c:Customer)-[:REFERRED]->(:Customer)
);
```
### Full-Text + Aggregate (Content-Analyse)
Analysiere welche Abteilungen am meisten über ein Thema schreiben:
```sql
SELECT department, count(*) as article_count,
avg(length(content)) as avg_length
FROM docs
WHERE MATCH(content) AGAINST('Nim programming')
GROUP BY department
ORDER BY article_count DESC;
```
### Vector + Aggregate (Cluster-Analyse)
Gruppiere ähnliche Vektoren und analysiere jedes Cluster:
```sql
SELECT cluster_id, count(*) as size,
centroid(embedding) as center,
avg(created_at) as avg_date
FROM products
GROUP BY vector_cluster(embedding, k=10)
ORDER BY size DESC;
```
### Alle Modalitäten kombiniert
Eine komplexe Abfrage unter Verwendung aller Engines:
```sql
WITH relevant_docs AS (
SELECT id, title, embedding
FROM articles
WHERE MATCH(body) AGAINST('database optimization')
AND created_at > '2024-01-01'
),
author_graph AS (
MATCH (a:Author)-[:COAUTHORED]->(b:Author)
WHERE a.name = 'Dr. Smith'
RETURN b.id as coauthor_id
)
SELECT rd.title, rd.score,
a.name as author,
cosine_distance(rd.embedding, query_vec) as similarity
FROM relevant_docs rd
JOIN authors a ON rd.author_id = a.id
WHERE a.id IN (SELECT coauthor_id FROM author_graph)
ORDER BY similarity ASC, rd.score DESC
LIMIT 20;
```
## Optimierung
### Cross-Modal Query Planner
BaraDB's adaptiver Query-Optimizer (`query/adaptive.nim`) wählt die Ausführungsreihenfolge basierend auf Selektivität:
```
1. Selektivstes Filter zuerst (normalerweise FTS oder Vector)
2. Prädikate zu jeder Engine pushen
3. Bloom-Filter für KV-Lookups verwenden
4. Unabhängige Zweige parallelisieren
```
### Index-Auswahl
Der Optimizer wählt automatisch den besten Index:
| Abfragemuster | Primäre Engine | Sekundäre Engine |
|---------------|----------------|-----------------|
| `MATCH ... ORDER BY cosine_distance` | Vector | FTS |
| `MATCH ... WHERE graph condition` | Graph | FTS |
| `WHERE id = ? AND vector_search` | KV | Vector |
| `GROUP BY + MATCH` | FTS | Columnar |
### Hints
Bestimmte Ausführungsreihenfolge erzwingen:
```sql
SELECT /*+ USE_INDEX(vector) */ *
FROM products
WHERE category = 'electronics'
ORDER BY cosine_distance(embedding, [...])
LIMIT 10;
```
## Performance
Cross-Modal Abfragen sind optimiert um Datenbewegung zu minimieren:
| Abfragetyp | Latenz (10K Zeilen) | Latenz (100K Zeilen) |
|------------|---------------------|----------------------|
| FTS + Vector | 15 ms | 85 ms |
| Graph + Vector | 25 ms | 120 ms |
| FTS + Aggregate | 12 ms | 55 ms |
| Alle Modalitäten | 45 ms | 220 ms |
## Anwendungsfälle
### E-Commerce Suche
```sql
-- Finde Produkte passend zu einem Suchbegriff, ähnlich zu einem betrachteten Artikel,
-- gekauft von ähnlichen Benutzern
SELECT p.name, p.price
FROM products p
WHERE MATCH(p.description) AGAINST('wireless headphones')
AND cosine_distance(p.embedding, viewed_embedding) < 0.3
AND p.id IN (
SELECT product_id FROM orders o
JOIN graph ON o.customer_id = graph.node_id
WHERE graph.similarity > 0.8
)
ORDER BY p.rating DESC
LIMIT 20;
```
### Betrugserkennung
```sql
-- Finde Transaktionen ähnlich zu bekannten Betrugsmustern,
-- wo der Benutzer mit markierten Konten verbunden ist
SELECT t.id, t.amount
FROM transactions t
WHERE cosine_distance(t.pattern_vector, fraud_vector) < 0.2
AND t.user_id IN (
MATCH (u:User)-[*1..3]->(f:FlaggedAccount)
RETURN u.id
);
```
### Knowledge Graph + RAG
```sql
-- Relevante Dokumente für eine Query abrufen,
-- dann den Knowledge Graph für verwandte Konzepte traversieren
WITH docs AS (
SELECT id, content, embedding
FROM documents
ORDER BY cosine_distance(embedding, query_embedding)
LIMIT 5
)
SELECT d.content, c.name as related_concept
FROM docs d
JOIN graph ON d.id = graph.doc_id
MATCH (d)-[:MENTIONS]->(c:Concept)
RETURN d.content, c.name;
```
docs/de/deployment.md
-247
View File
@@ -1,247 +0,0 @@
# Deployment-Leitfaden
## Docker
### Schnellstart
```bash
docker build -t baradb:latest .
docker compose up -d
```
### Docker Compose Dateien
| Datei | Zweck |
|-------|-------|
| `docker-compose.yml` | Entwicklung |
| `docker-compose.prod.yml` | Produktion |
| `docker-compose.override.yml` | Dev Override (automatisch) |
### Produktion
```bash
docker compose -f docker-compose.prod.yml up -d
```
### Docker Swarm
```bash
docker stack deploy -c docker-compose.prod.yml baradb
```
## systemd Service
Erstelle `/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
# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/baradb/data
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
[Install]
WantedBy=multi-user.target
```
Aktivieren und starten:
```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-Node Raft Cluster
```bash
# Knoten 1
BARADB_RAFT_NODE_ID=node1 \
BARADB_RAFT_PEERS=node2:9001,node3:9001 \
./build/baradadb
# Knoten 2
BARADB_RAFT_NODE_ID=node2 \
BARADB_RAFT_PEERS=node1:9001,node3:9001 \
./build/baradadb
# Knoten 3
BARADB_RAFT_NODE_ID=node3 \
BARADB_RAFT_PEERS=node1:9001,node2:9001 \
./build/baradadb
```
## Cloud Deployment
### AWS EC2
Empfohlene Instance: `m6i.2xlarge` (8 vCPU, 32 GB RAM)
```bash
# User data script
#!/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 (nur HTTP)
```bash
gcloud run deploy baradb \
--image gcr.io/PROJECT/baradb \
--port 9470 \
--memory 4Gi \
--cpu 2 \
--max-instances 10
```
docs/de/distributed.md
-110
View File
@@ -1,110 +0,0 @@
# Distributed Systems
BaraDB unterstützt verteiltes Deployment mit Raft Consensus, Sharding und Replikation.
## Raft Consensus
Leader Election und Log-Replikation:
```nim
import barabadb/core/raft
var cluster = newRaftCluster()
cluster.addNode("node1")
cluster.addNode("node2")
cluster.addNode("node3")
let n1 = cluster.nodes["n1"]
n1.becomeCandidate()
n1.becomeLeader()
let entry = n1.appendLog("SET key1 value1")
```
## Sharding
Daten über Knoten verteilen:
```nim
import barabadb/core/sharding
var router = newShardRouter(ShardConfig(
numShards: 4,
replicas: 2,
strategy: ssHash
))
router.rebalance(@["node1", "node2", "node3"])
let shard = router.getShard("user_123")
```
### Sharding-Strategien
| Strategie | Beschreibung |
|----------|-------------|
| `ssHash` | Hash-basiertes Sharding |
| `ssRange` | Range-basiertes Sharding |
| `ssConsistent` | Consistent Hashing |
## Replikation
```nim
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)
```
### Replikationsmodi
| Modus | Beschreibung |
|-------|--------------|
| `rmSync` | Synchronous Replikation |
| `rmAsync` | Asynchrone Replikation |
| `rmSemiSync` | Semi-synchrone Replikation |
## Gossip Protocol
Membership und Failure-Erkennung:
```nim
import barabadb/core/gossip
var g = newGossipManager()
g.addNode("node1")
g.addNode("node2")
g.tick() # Membership-Info austauschen
```
## Distributed Transactions
Two-Phase Commit über Knoten:
```nim
import barabadb/core/disttxn
var dt = newDistributedTxn()
dt.prepare(@["node1", "node2"])
dt.commit()
```
## Formale Verifikation
Kern-Algorithmen für Distributed Systems sind formal in TLA+ spezifiziert und model-gecheckt:
- **Raft Consensus** — `formal-verification/raft.tla`
- Verifiziert: ElectionSafety, StateMachineSafety
- **Two-Phase Commit** — `formal-verification/twopc.tla`
- Verifiziert: Atomicity, NoOrphanBlocks
- **Replication** — `formal-verification/replication.tla`
- Verifiziert: MonotonicLsn, AcksRemovePending
TLC lokal ausführen:
```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
```
docs/de/docker.md
-191
View File
@@ -1,191 +0,0 @@
# Docker Deployment-Leitfaden
Dieser Leitfaden beschreibt, wie Sie BaraDB mit Docker und Docker Compose verwenden.
## Schnellstart
```bash
# Repository klonen
git clone https://codeberg.org/baraba/baradb
cd barabaDB
# Image bauen
docker build -t baradb:latest .
# Mit Docker Compose starten
docker compose up -d
# Status prüfen
docker compose ps
docker compose logs -f
```
## Dateien
| Datei | Beschreibung |
|-------|--------------|
| `Dockerfile` | Multi-stage Production Build |
| `docker-compose.yml` | Development Konfiguration |
| `docker-compose.prod.yml` | Production Konfiguration |
| `docker-compose.override.yml` | Development Override (wird automatisch geladen) |
| `docker-entrypoint.sh` | Entrypoint-Skript für Initialisierung |
| `.dockerignore` | Dateien, die nicht ins Image kopiert werden sollen |
| `scripts/docker-build.sh` | Helper-Skript für Build |
| `scripts/docker-run.sh` | Helper-Skript für manuelles Starten |
## Image erstellen
```bash
# Standard Build
docker build -t baradb:latest .
# Mit Skript
./scripts/docker-build.sh
# Mit bestimmter Version
IMAGE_NAME=baradb VERSION=0.1.0 ./scripts/docker-build.sh
```
## Starten
### Development (docker compose)
```bash
# Im Hintergrund starten
docker compose up -d
# Stoppen
docker compose down
# Stoppen und Volumes löschen (WARNUNG — löscht Daten!)
docker compose down -v
# Logs ansehen
docker compose logs -f
```
### Production (docker compose)
```bash
# Mit Production-Konfiguration starten
docker compose -f docker-compose.prod.yml up -d
# Healthcheck prüfen
docker compose -f docker-compose.prod.yml ps
```
### Manuell (docker run)
```bash
# Mit Skript
./scripts/docker-run.sh
# Manuell
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
```
## Ports
| Port | Beschreibung |
|------|--------------|
| `9472` | Binary Wire Protocol |
| `9912` | HTTP/REST API (TCP port + 440) |
| `9913` | WebSocket (TCP port + 441) |
## Environment Variables
| Variable | Standardwert | Beschreibung |
|----------|--------------|--------------|
| `BARADB_ADDRESS` | `0.0.0.0` | Bind-Adresse |
| `BARADB_PORT` | `9472` | Binary Protocol Port |
| `BARADB_HTTP_PORT` | `9470` | HTTP Port |
| `BARADB_WS_PORT` | `9471` | WebSocket Port |
| `BARADB_DATA_DIR` | `/data` | Datenverzeichnis |
| `BARADB_LOG_LEVEL` | `info` | Log-Level |
## Volumes
| Pfad im Container | Beschreibung |
|-------------------|--------------|
| `/data` | Hauptdatenverzeichnis |
| `/data/server/wal` | Write-Ahead Log |
| `/data/server/sstables` | SSTable Dateien |
## Production Checklist
- [ ] TLS-Zertifikate in `./certs/` erstellen
- [ ] Starkes `BARADB_JWT_SECRET` setzen
- [ ] Firewall-Regeln konfigurieren
- [ ] Regelmäßige Backups konfigurieren
- [ ] Resource Limits prüfen
- [ ] Monitoring einrichten (Healthcheck, Logs)
## TLS in Docker
1. Zertifikate erstellen:
```bash
mkdir -p certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout certs/server.key -out certs/server.crt
```
2. In `docker-compose.prod.yml` aktivieren:
```yaml
environment:
- BARADB_TLS_ENABLED=true
- BARADB_CERT_FILE=/certs/server.crt
- BARADB_KEY_FILE=/certs/server.key
volumes:
- ./certs:/certs:ro
```
## Backup in Docker
```bash
# Manueller Backup
docker exec baradb /app/backup backup --data-dir=/data
# Backup-Liste
docker exec baradb /app/backup list
# Wiederherstellung
docker exec baradb /app/backup restore --input=backup_xxx.tar.gz
```
## Troubleshooting
### Container startet nicht
```bash
# Logs prüfen
docker compose logs -f baradb
# Status prüfen
docker compose ps
```
### Keine Verbindung zur Datenbank
```bash
# Prüfen ob Ports exponiert sind
docker port baradb
# Von innen prüfen
docker exec baradb wget -qO- http://localhost:9470/health
```
### Permission denied auf /data
Das Entrypoint-Skript erstellt automatisch Verzeichnisse und setzt korrekte Permissions. Bei Problemen:
```bash
docker exec baradb ls -la /data
docker exec baradb chown -R baradb:baradb /data
```
docs/de/fts.md
-87
View File
@@ -1,87 +0,0 @@
# Volltextsuchmaschine
Invertierter Index mit BM25 und TF-IDF-Ranking für Textsuche.
## Verwendung
```nim
import barabadb/fts/engine
var idx = newInvertedIndex()
idx.addDocument(1, "Nim is a fast programming language")
idx.addDocument(2, "Python is popular for data science")
# BM25-Suche
let results = idx.search("programming language")
# TF-IDF-Suche
let tfidf = idx.searchTfidf("programming language")
# Fuzzy-Suche (Tippfehlertoleranz)
let fuzzy = idx.fuzzySearch("programing", maxDistance = 2)
# Platzhalter-Suche
let wild = idx.regexSearch("prog*")
```
## Ranking-Methoden
### BM25
Best-Matching-Ranking-Algorithmus:
```nim
let bm25 = idx.searchBM25("query terms")
```
### TF-IDF
Term Frequency-Inverse Document Frequency:
```nim
let tfidf = idx.searchTfidf("query terms")
```
## Suchfunktionen
| Funktion | Beschreibung |
|---------|-------------|
| Fuzzy-Suche | Levenshtein-Distanz-Toleranz |
| Platzhalter | Präfix-, Suffix- und Infix-Platzhalter |
| Regex | Reguläre Ausdrucksmuster |
| Phrasensuche | Exakte Phrasenübereinstimmung |
| Boolesch | AND, OR, NOT Operatoren |
## SQL-Schnittstelle
Volltextsuche ist auch direkt in BaraQL verfügbar:
```sql
-- Tabelle mit Textspalte erstellen
CREATE TABLE articles (id INT PRIMARY KEY, title TEXT, body TEXT);
-- FTS-Index erstellen
CREATE INDEX idx_fts ON articles(body) USING FTS;
-- Suche mit dem @@ Operator (BM25-Ranking)
SELECT * FROM articles WHERE body @@ 'machine learning';
-- Suche mit mehreren Begriffen
SELECT * FROM articles WHERE body @@ 'quick brown fox';
```
## Mehrsprachige Unterstützung
```nim
import barabadb/fts/multilang
# Unterstützte Sprachen: EN, BG, DE, FR, RU
var tokenizer = newTokenizer("de") # Deutsch
let tokens = tokenizer.tokenize("Volltextsuche")
```
Funktionen pro Sprache:
- Tokenisierung
- Stoppwörter
- Stemming
- Spracherkennung
docs/de/graph.md
-145
View File
@@ -1,145 +0,0 @@
# Graph Engine
Adjazenzlisten-Speicher mit eingebauten Algorithmen für Graph-Traversierung und -Analyse.
Vollständig integriert in den SQL-Executor via `GRAPH_TABLE()`.
## SQL — Graph DDL
### Graph erstellen
```sql
CREATE GRAPH org_chart;
```
Erstellt automatisch zwei Tabellen:
- `org_chart_nodes (id INTEGER PRIMARY KEY, node_label TEXT, properties TEXT)`
- `org_chart_edges (source_id INTEGER, dest_id INTEGER, edge_label TEXT, weight REAL)`
### Graph löschen
```sql
DROP GRAPH org_chart;
```
## SQL — Daten einfügen
```sql
-- Knoten
INSERT INTO org_chart_nodes (id, node_label) VALUES (1, 'CEO');
INSERT INTO org_chart_nodes (id, node_label) VALUES (2, 'VP');
-- Kanten
INSERT INTO org_chart_edges (source_id, dest_id, edge_label) VALUES (1, 2, 'manages');
```
Alle INSERTs werden automatisch mit dem nativen Graph-Objekt synchronisiert.
## SQL — GRAPH_TABLE Abfragen
### BFS (Breitensuche)
```sql
SELECT * FROM GRAPH_TABLE(org_chart MATCH (n)-[r]->(m)
ALGORITHM bfs
START 1 MAXDEPTH 2
COLUMNS (id, node_label));
```
### DFS (Tiefensuche)
```sql
SELECT * FROM GRAPH_TABLE(org_chart MATCH (n)-[r]->(m)
ALGORITHM dfs START 1
COLUMNS (id, node_label));
```
### PageRank
```sql
SELECT id, node_label, rank FROM GRAPH_TABLE(org_chart
ALGORITHM pagerank
COLUMNS (id, node_label, rank))
ORDER BY rank DESC;
```
### Community Detection (Louvain)
```sql
SELECT id, node_label, community FROM GRAPH_TABLE(org_chart
ALGORITHM community
COLUMNS (id, node_label, community));
```
### Kürzester Pfad (Shortest Path)
```sql
SELECT * FROM GRAPH_TABLE(org_chart
ALGORITHM shortest_path
START 1 END 3
COLUMNS (id, node_label));
```
### Dijkstra (gewichtete kürzeste Pfade)
```sql
SELECT * FROM GRAPH_TABLE(org_chart
ALGORITHM dijkstra START 1
COLUMNS (id, node_label, distance));
```
## SQL-Funktionen
### Knotenähnlichkeit
```sql
-- Jaccard-Ähnlichkeit zwischen allen Knotenpaaren
SELECT similarity_nodes('social', 'jaccard') AS result;
-- Adamic-Adar-Ähnlichkeit
SELECT similarity_nodes('social', 'adamic_adar') AS result;
```
### Node2Vec Embeddings
```sql
-- Graphstruktur-Embeddings generieren (64 Dimensionen)
SELECT node2vec_embed('social', 64) AS result;
```
## Cypher-Kompatibilität
```sql
-- Cypher-Syntax automatisch nach GRAPH_TABLE übersetzen
SELECT cypher('MATCH (a)-[r]->(b) WHERE a.node_label = ''CEO'' RETURN b.node_label') AS result;
```
## Algorithmen
| Algorithmus | Beschreibung | SQL |
|-------------|--------------|-----|
| `bfs` | Breitensuche | `ALGORITHM bfs` |
| `dfs` | Tiefensuche | `ALGORITHM dfs` |
| `dijkstra` | Gewichtete kürzeste Pfade | `ALGORITHM dijkstra` |
| `pageRank` | Knoten-Wichtigkeit | `ALGORITHM pagerank` |
| `louvain` | Community Detection | `ALGORITHM community` |
| `shortestPath` | Kürzester Pfad | `ALGORITHM shortest_path START X END Y` |
| `similarityNodes` | Knotenähnlichkeit | `similarity_nodes()` |
| `node2vec` | Graph Embeddings | `node2vec_embed()` |
## Native Nim API
```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()
let communities = louvain(g)
let similarities = g.similarityNodes(smJaccard)
let embeddings = g.node2vec(64, 10, 5)
```
docs/de/index.md
-64
View File
@@ -1,64 +0,0 @@
# BaraDB Dokumentation
**Eine multimodale Datenbank-Engine — 100% Nim, null Abhängigkeiten.**
## Sprachen
- [English](../en/)
- [Български (Bulgarisch)](../bg/)
- [Deutsch (German)](../de/)
- [Русский (Russisch)](../ru/)
- [فارسی (Farsi)](../fa/)
- [中文 (Chinesisch)](../zh/)
- [Türkçe (Türkisch)](../tr/)
- [العربية (Arabisch)](../ar/)
---
## Schnellstart
- [Installation](installation.md)
- [Schnellstart](quickstart.md)
- [Architektur](architecture.md)
- [Konfiguration](configuration.md)
## Kernkonzepte
- [BaraQL Abfragesprache](baraql.md)
- [Speicher-Engines](storage.md)
- [Schema System](schema.md)
## Engines
- [LSM-Tree Speicher](lsm.md)
- [B-Tree Index](btree.md)
- [Vektor-Suche](vector.md)
- [Graph Engine](graph.md)
- [Volltext-Suche](fts.md)
- [Spaltenbasierte Speicherung](columnar.md)
## API & Clients
- [Client SDKs](clients.md)
- [Binärprotokoll](api-binary.md)
- [HTTP/REST API](api-http.md)
- [MCP Server](mcp.md)
## Betrieb
- [Performance](performance.md)
- [Sicherheit](security.md)
- [Monitoring](monitoring.md)
- [Backup & Recovery](backup.md)
- [Fehlerbehebung](troubleshooting.md)
## Erweitert
- [Transaktionen & MVCC](transactions.md)
- [Verteilte Systeme](distributed.md)
- [Docker Deployment](docker.md)
- [Änderungsprotokoll](changelog.md)
---
*Um eine neue Sprache hinzuzufügen, erstellen Sie einen neuen Ordner in `docs/` mit dem Sprachcode (z.B. `docs/de/`).*
docs/de/installation.md
-57
View File
@@ -1,57 +0,0 @@
# BaraDB — Installation
## Voraussetzungen
- **Nim >= 2.2.0** (`curl https://nim-lang.org/choosenim/init.sh -sSf | sh`)
- **Git**
- **OpenSSL** (für TLS)
## Aus dem Quellcode bauen
```bash
git clone https://github.com/katehonz/barabaDB.git
cd barabadb
nimble build_release
```
Die Binärdateien werden im `build/` Verzeichnis erstellt:
- `build/baradadb` — Datenbank-Server (TCP + HTTP)
- `build/baramcp` — MCP Server für AI-Agenten
## Debug-Build
```bash
nimble build_debug
```
## Tests ausführen
```bash
nimble test
```
## Docker
```bash
docker compose up -d
```
## Verifizierung
```bash
./build/baradadb --version
# BaraDB v1.1.6 — Multimodal Database Engine
./build/baramcp --data-dir ./data &
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ./build/baramcp
```
## Manuelle Kompilierung
```bash
# Server
nim c -d:release --opt:speed -o:build/baradadb src/baradadb.nim
# MCP Server
nim c -d:release --opt:speed -o:build/baramcp src/baramcp.nim
```
docs/de/lsm.md
-64
View File
@@ -1,64 +0,0 @@
# LSM-Tree Speicher-Engine
Die primäre Speicher-Engine in BaraDB mit Log-Structured Merge-Tree Architektur.
## Architektur
```
┌─────────────────────────────────────────────┐
│ Writes │
│ (append to WAL + MemTable) │
└─────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ MemTable │
│ (in-memory sorted buffer) │
└─────────────────────────────────────────────┘
│
(when full, flush to SSTable)
│
▼
┌─────────────────────────────────────────────┐
│ SSTable │
│ (sorted string table on disk) │
└─────────────────────────────────────────────┘
```
## Verwendung
```nim
import barabadb/storage/lsm
var db = newLSMTree("./data")
# Schreiben
db.put("key1", cast[seq[byte]]("value1"))
# Lesen
let (found, value) = db.get("key1")
# Löschen
db.delete("key1")
db.close()
```
## Funktionen
- **Write-optimiert**: Append-only Log-Struktur
- **Dauerhaftigkeit**: Write-Ahead Log (WAL) sichert Crash-Wiederherstellung
- **Bloom-Filter**: Schnelle negative Lookups
- **Compaction**: Size-tiered Strategie mischt SSTables
- **Page-Cache**: LRU-Cache für häufig zugegriffene Seiten
## Konfiguration
```nim
var db = newLSMTree(
path = "./data",
memTableSize = 64 * 1024 * 1024, # 64MB
walEnabled = true,
bloomFpRate = 0.01
)
```
docs/de/mcp.md
-108
View File
@@ -1,108 +0,0 @@
# MCP Server (Model Context Protocol)
BaraDB enthält einen eingebauten MCP-Server, der es AI-Agenten (Claude, Cursor, etc.) ermöglicht, direkt mit der Datenbank zu interagieren.
## Schnellstart
```bash
./build/baramcp --data-dir ./data
```
Der Server startet im STDIO-Modus und akzeptiert JSON-RPC 2.0 Nachrichten.
## Verfügbare Tools
### 1. `query` — SQL ausführen
```json
{
"name": "query",
"arguments": {
"sql": "SELECT * FROM users WHERE age > ?",
"params": [25],
"tenant_id": "company-a",
"user_id": "alice"
}
}
```
Parameterisierte Abfragen mit `?`-Platzhaltern. Multi-Tenant-Support über `tenant_id` und `user_id`.
### 2. `vector_search` — Semantische Suche
```json
{
"name": "vector_search",
"arguments": {
"table": "docs",
"column": "embedding",
"query_vector": [0.1, 0.2, 0.3],
"k": 5,
"metric": "cosine",
"tenant_id": "company-a"
}
}
```
Unterstützte Metriken: `cosine`, `euclidean`, `dot_product`, `manhattan`.
### 3. `schema_inspect` — Schema erkunden
```json
{
"name": "schema_inspect",
"arguments": {
"table": "users",
"tenant_id": "company-a"
}
}
```
Gibt Tabellen, Spalten, Typen, Primärschlüssel, Fremdschlüssel, Indizes und RLS-Policies zurück.
## Konfiguration in Claude Desktop
```json
{
"mcpServers": {
"baradb": {
"command": "/pfad/zu/build/baramcp",
"args": ["--data-dir", "/pfad/zu/daten"]
}
}
}
```
## Konfiguration in Cursor
```json
{
"mcpServers": {
"baradb": {
"command": "/pfad/zu/build/baramcp",
"args": ["--data-dir", "~/.baradb/data"]
}
}
}
```
## Multi-Tenant Isolation
Jede MCP-Anfrage kann `tenant_id` und `user_id` enthalten. Diese werden als Session-Variablen gesetzt:
- `app.tenant_id` — für RLS-Filterung
- `app.user_id` — für `current_user`-Referenzen
RLS-Policies filtern die Daten automatisch basierend auf diesen Variablen.
## JSON-RPC 2.0 Protokoll
Der Server verwendet JSON-RPC 2.0 über STDIO:
```json
// Anfrage
{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {...}}
// Antwort
{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "..."}]}}
```
docs/de/monitoring.md
-258
View File
@@ -1,258 +0,0 @@
# Monitoring & Observability
## Health Checks
### HTTP Health Endpoint
```bash
curl http://localhost:9470/health
```
Antwort:
```json
{
"status": "healthy",
"version": "0.1.0",
"uptime_seconds": 86400,
"checks": {
"storage": "ok",
"memory": "ok",
"connections": "ok"
}
}
```
### Readiness Probe
```bash
curl http://localhost:9470/ready
```
Gibt `200 OK` zurück wenn der Server bereit ist Traffic anzunehmen, `503` während des Starts.
## Metrics
### Prometheus-kompatible Metrics
```bash
curl http://localhost:9470/metrics
```
Beispielausgabe:
```
# HELP baradb_queries_total Total number of queries executed
# TYPE baradb_queries_total counter
baradb_queries_total 152340
# HELP baradb_queries_duration_seconds Query duration histogram
# 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 total size
# TYPE baradb_storage_lsm_size_bytes gauge
baradb_storage_lsm_size_bytes 2147483648
# HELP baradb_storage_sstables Number of SSTables
# TYPE baradb_storage_sstables gauge
baradb_storage_sstables 12
# 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 Active client connections
# TYPE baradb_active_connections gauge
baradb_active_connections 42
# HELP baradb_txns_active Active transactions
# TYPE baradb_txns_active gauge
baradb_txns_active 7
# HELP baradb_txns_committed_total Total committed transactions
# TYPE baradb_txns_committed_total counter
baradb_txns_committed_total 89123
```
### JSON Metrics
```bash
curl http://localhost:9470/metrics?format=json
```
## Logging
### Log-Level
| Level | Beschreibung |
|-------|--------------|
| `debug` | Detaillierte interne Operationen |
| `info` | Normale Operationen |
| `warn` | Behebbare Probleme |
| `error` | Fehler die Aufmerksamkeit erfordern |
### Strukturiertes JSON Logging
```bash
BARADB_LOG_LEVEL=info \
BARADB_LOG_FORMAT=json \
BARADB_LOG_FILE=/var/log/baradb/baradb.log \
./build/baradadb
```
Beispiel-Log-Eintrag:
```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"
}
```
### Textformat
```bash
BARADB_LOG_FORMAT=text ./build/baradadb
```
Ausgabe:
```
2025-01-15T10:30:00.123Z [INFO] server: Query executed | query="SELECT * FROM users" duration_ms=12
```
## Alerting-Regeln
### 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 error rate is high"
- alert: BaraDBLowCacheHitRate
expr: baradb_cache_hit_rate < 0.8
for: 10m
labels:
severity: warning
annotations:
summary: "BaraDB cache hit rate below 80%"
- alert: BaraDBHighConnections
expr: baradb_active_connections > 800
for: 5m
labels:
severity: warning
annotations:
summary: "BaraDB connection count is high"
- alert: BaraDBDown
expr: up{job="baradb"} == 0
for: 1m
labels:
severity: critical
annotations:
summary: "BaraDB instance is down"
```
## Grafana Dashboard
Dashboard ID `baradb-001` importieren oder das bereitgestellte JSON in `monitoring/grafana-dashboard.json` verwenden.
Wichtige Panels:
- Queries pro Sekunde
- Query-Latenz Perzentile (p50, p95, p99)
- Speichergröße und SSTable-Anzahl
- Cache Hit Rate
- Aktive Verbindungen
- Transaktionsrate
- Fehlerrate
## Distributed Monitoring
### Cluster Metrics
Für Raft-Cluster überwachen:
```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
}
```
## Performance Profiling
### Eingebauter 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
```
### Trace
```bash
curl -X POST http://localhost:9470/debug/pprof/trace?seconds=5 > trace.out
```
## Log-Aggregation
### Fluent Bit Konfiguration
```ini
[INPUT]
Name tail
Path /var/log/baradb/baradb.log
Parser json
Tag baradb
[OUTPUT]
Name elasticsearch
Match baradb
Host elasticsearch
Port 9200
Index baradb-logs
```
## Troubleshooting mit Metrics
| Symptom | Metrik | Aktion |
|---------|--------|--------|
| Langsame Abfragen | `baradb_queries_duration_seconds` | Cache Hit Rate prüfen, Indizes in Betracht ziehen |
| Hoher Speicherverbrauch | `process_resident_memory_bytes` | Memtable/Cache-Größen reduzieren |
| Speicher wächst | `baradb_storage_lsm_size_bytes` | Manuelle Compaction ausführen |
| Verbindungsfehler | `baradb_active_connections` | Connection Pool erhöhen oder Knoten hinzufügen |
| Replikations-Lag | `baradb_replication_lag_ms` | Netzwerk prüfen, Ressourcen erhöhen |
docs/de/performance.md
-174
View File
@@ -1,174 +0,0 @@
# BaraDB Performance-Leitfaden
## Benchmark-Methodik
Alle Benchmarks wurden ausgeführt mit:
- **Compiler**: Nim 2.2.0 mit `-d:release --opt:speed`
- **CPU**: AMD Ryzen 9 5900X (12 Kerne / 24 Threads)
- **Memory**: 64 GB DDR4-3600
- **Storage**: Samsung 980 Pro NVMe SSD
- **OS**: Ubuntu 24.04 LTS
Die vollständige Benchmark-Suite ausführen:
```bash
nim c -d:ssl -d:release -r benchmarks/bench_all.nim
```
## Storage Engine Benchmarks
### LSM-Tree Key-Value
| Metrik | Wert |
|--------|------|
| Write Throughput | ~580,000 ops/s |
| Read Throughput | ~720,000 ops/s |
| Durchschnittliche Write-Latenz | 1.7 µs |
| Durchschnittliche Read-Latenz | 1.4 µs |
| Testdatensatz | 100,000 Keys (16-Byte Keys, 64-Byte Values) |
Der LSM-Tree verwendet eine 64MB MemTable, WAL fsync bei jedem Write und size-tiered
Compaction mit 6 Levels.
### B-Tree Index
| Metrik | Wert |
|--------|------|
| Insert Throughput | ~1,200,000 ops/s |
| Point Lookup Throughput | ~1,500,000 ops/s |
| Range Scan (1000 Keys) | ~0.3 ms |
| Baumhöhe (100K Keys) | 4 |
B-Tree Knoten sind 4KB mit Copy-on-Write für MVCC-Kompatibilität.
## Vector Engine Benchmarks
### HNSW Index
| Metrik | Wert |
|--------|------|
| Insert (dim=128) | ~45,000 vectors/s |
| Search top-10 (dim=128, n=10K) | ~2 ms |
| Search top-10 (dim=128, n=100K) | ~8 ms |
| Speicher pro Vektor (dim=128) | ~580 bytes |
Parameter: `M=16`, `efConstruction=200`, `efSearch=64`.
### SIMD Distanzfunktionen
| Operation | dim=128 | dim=768 | dim=1536 |
|-----------|---------|---------|----------|
| Cosine Distance | 4.2M/s | 850K/s | 420K/s |
| L2 (Euclidean) | 4.5M/s | 920K/s | 450K/s |
| Dot Product | 4.8M/s | 980K/s | 480K/s |
SIMD verwendet AVX2 256-Bit Vektoren mit Loop Unrolling.
### Quantization
| Methode | Genauigkeitsverlust | Speicherreduzierung |
|---------|--------------------|--------------------|
| Scalar 8-bit | <1% | 4× |
| Scalar 4-bit | ~3% | 8× |
| Product Quantization (PQ16) | ~5% | 16× |
| Binary | ~15% | 32× |
## Full-Text Search Benchmarks
| Metrik | Wert |
|--------|------|
| Index Throughput | ~320,000 docs/s |
| BM25 Search | ~28,000 queries/s |
| Fuzzy Search (distance=2) | ~850 queries/s |
| Wildcard Regex Search | ~4,200 queries/s |
Testkorpus: 5 einzigartige Dokumente × 2,000 Wiederholungen (~50 Wörter/Dok).
## Graph Engine Benchmarks
| Operation | Throughput | Latenz |
|-----------|------------|--------|
| Knoten hinzufügen | ~2.5M ops/s | 0.4 µs |
| Kante hinzufügen | ~1.8M ops/s | 0.55 µs |
| BFS (1K Knoten, 5K Kanten) | ~12K Traversierungen/s | 83 µs |
| DFS (1K Knoten, 5K Kanten) | ~15K Traversierungen/s | 67 µs |
| Dijkstra kürzester Pfad | — | ~120 µs |
| PageRank (10 Iterationen) | ~450 Graphen/s | 2.2 ms |
| Louvain Community Detection | — | ~45 ms |
## Protokoll-Benchmarks
| Protokoll | Verbindungen | Queries/sec | Latenz p99 |
|-----------|--------------|-------------|------------|
| Binary (localhost) | 1 | 45,000 | 0.4 ms |
| Binary (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 |
## Query Engine Benchmarks
| Abfragetyp | Zeilen | Zeit |
|------------|--------|------|
| Simple SELECT | 100K | 12 ms |
| SELECT + WHERE | 100K | 18 ms |
| SELECT + ORDER BY | 100K | 35 ms |
| GROUP BY + Aggregates | 100K | 42 ms |
| INNER JOIN (1K × 1K) | 1M Ergebnis | 85 ms |
| CTE (2 Ebenen) | 100K | 28 ms |
| Subquery (EXISTS) | 100K | 22 ms |
## Skalierungsverhalten
### Vertikale Skalierung
| Kerne | LSM Write | LSM Read | Vector Search |
|-------|-----------|----------|---------------|
| 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 |
### Speicherverbrauch
| Komponente | Basis-Speicher | Pro-Entity Overhead |
|------------|----------------|---------------------|
| LSM MemTable | 64 MB (fest) | ~1.2× Rohdaten |
| B-Tree | 8 MB (fest) | ~8 bytes/Key |
| HNSW Index | — | ~580 bytes/Vektor (dim=128) |
| Graph | — | ~32 bytes/Knoten, ~24 bytes/Kante |
| FTS Index | — | ~40% von Rohtext |
| Page Cache | 256 MB (konfigurierbar) | — |
## Tuning-Leitfaden
### Für Write-intensive Workloads
```bash
export BARADB_MEMTABLE_SIZE_MB=256
export BARADB_WAL_SYNC_INTERVAL_MS=10
export BARADB_COMPACTION_INTERVAL_MS=30000
```
### Für Read-intensive Workloads
```bash
export BARADB_CACHE_SIZE_MB=1024
export BARADB_BLOOM_BITS_PER_KEY=10
export BARADB_COMPACTION_INTERVAL_MS=120000
```
### Für Vector Search
```bash
export BARADB_VECTOR_EF_CONSTRUCTION=200
export BARADB_VECTOR_EF_SEARCH=128
export BARADB_VECTOR_M=32
```
### Für Graph Analytics
```bash
export BARADB_GRAPH_PAGE_RANK_ITERATIONS=20
export BARADB_GRAPH_LOUVAIN_RESOLUTION=1.0
```
docs/de/protocol.md
-240
View File
@@ -1,240 +0,0 @@
# Protokoll-Referenz
BaraDB unterstützt mehrere Protokolle für Client-Kommunikation:
- **Binär Wire Protokoll** — hochperformant, niedrige Latenz
- **HTTP/REST API** — sprachunabhängig, einfach zu debuggen
- **WebSocket** — Streaming und Pub/Sub
---
## Binär Wire Protokoll
Das Binärprotokoll verwendet Big-Endian-Kodierung für alle Multi-Byte-Werte.
### Verbindungslebenszyklus
```
Client Server
| |
|─── TCP connect ──────────────>|
|<── TLS handshake (optional) ──|
|─── Auth message ─────────────>|
|<── Auth_OK / Error ───────────|
|─── Query message ────────────>|
|<── Data / Complete / Error ───|
|─── Close message ────────────>|
|<── TCP close ─────────────────|
```
### Nachrichtenformat
Jede Nachricht beginnt mit einem 8-Byte-Header:
```
┌─────────────┬─────────────┬─────────────┬─────────────────────┐
│ Length │ Type │ Sequence │ Payload │
│ (4 bytes) │ (1 byte) │ (1 byte) │ (Length - 6 bytes) │
│ uint32 BE │ uint8 │ uint8 │ │
└─────────────┴─────────────┴─────────────┴─────────────────────┘
```
### Nachrichtentypen
| Typ | ID | Richtung | Beschreibung |
|------|----|-----------|-------------|
| Query | 0x01 | C→S | Abfrage ausführen |
| Insert | 0x02 | C→S | Daten einfügen |
| Update | 0x03 | C→S | Daten aktualisieren |
| Delete | 0x04 | C→S | Daten löschen |
| Ready | 0x05 | S→C | Bereit für nächsten Befehl |
| Error | 0x06 | S→C | Fehlerantwort |
| Auth | 0x07 | C→S | Authentifizierungsanfrage |
| Batch | 0x08 | C→S | Batch-Operationen |
| Ping | 0x09 | C→S | Keepalive Ping |
| Data | 0x81 | S→C | Abfrageergebnis-Daten |
| Complete | 0x82 | S→C | Abfrage abgeschlossen |
| Auth_OK | 0x83 | S→C | Authentifizierung erfolgreich |
| Pong | 0x84 | S→C | Keepalive-Antwort |
### Query-Nachrichten-Payload
```
┌──────────────┬──────────────┬────────────────────────────┐
│ Result Format│ Query Length │ Query String │
│ (1 byte) │ (4 bytes) │ (Query Length bytes) │
│ 0x00=Binary │ uint32 BE │ UTF-8 │
│ 0x01=JSON │ │ │
│ 0x02=Text │ │ │
└──────────────┴──────────────┴────────────────────────────┘
```
### Data-Nachrichten-Payload
```
┌──────────────┬─────────────────────────────────────────────┐
│ Column Count │ Column Definitions + Row Data │
│ (2 bytes) │ │
│ uint16 BE │ │
└──────────────┴─────────────────────────────────────────────┘
```
### Spaltendefinition
```
┌──────────────┬──────────────┬────────────────────────────┐
│ Name Length │ Name │ Type │
│ (2 bytes) │ (N bytes) │ (1 byte) │
│ uint16 BE │ UTF-8 │ Siehe FieldKind-Tabelle │
└──────────────┴──────────────┴────────────────────────────┘
```
### Feldtypen
| Typ | ID | Größe | Beschreibung |
|------|----|------|-------------|
| NULL | 0x00 | 0 | NULL-Wert |
| 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 Single Precision (Big-Endian) |
| FLOAT64 | 0x07 | 8 | IEEE 754 Double Precision (Big-Endian) |
| STRING | 0x08 | variable | UTF-8 String (4-Byte Längenpräfix) |
| BYTES | 0x09 | variable | Raw Bytes (4-Byte Längenpräfix) |
| ARRAY | 0x0A | variable | Array von Werten |
| OBJECT | 0x0B | variable | Key-Value Objekt |
| VECTOR | 0x0C | variable | Float32 Array (4-Byte Längenpräfix, Big-Endian Floats) |
### Fehler-Nachrichten-Payload
```
┌──────────────┬──────────────┬────────────────────────────┐
│ Error Code │ Message Len │ Error Message │
│ (4 bytes) │ (4 bytes) │ (Message Len bytes) │
│ uint32 BE │ uint32 BE │ UTF-8 │
└──────────────┴──────────────┴────────────────────────────┘
```
### Beispiel: Raw TCP-Session
```bash
# Verbinden
nc localhost 9472
# Senden: Auth-Anfrage (Token "mytoken")
# Header: length=15, type=0x07, seq=1
# Payload: token length=7, token="mytoken"
printf '\x00\x00\x00\x0f\x07\x01\x00\x00\x00\x07mytoken' > /dev/tcp/localhost/9472
# Empfangen: Auth_OK
# \x00\x00\x00\x06\x83\x01
# Senden: Query "SELECT 1"
printf '\x00\x00\x00\x12\x01\x02\x00\x00\x00\x00\x08SELECT 1' > /dev/tcp/localhost/9472
# Empfangen: Data + Complete
```
---
## HTTP/REST API
Basis-URL: `http://localhost:9470/api/v1`
### Endpoints
#### Health
```http
GET /health
```
Antwort:
```json
{
"status": "healthy",
"version": "0.1.0",
"uptime_seconds": 86400
}
```
#### Ready
```http
GET /ready
```
Gibt `200` zurück wenn bereit, `503` während des Starts.
#### Query
```http
POST /query
Content-Type: application/json
Authorization: Bearer <token>
{
"query": "SELECT name, age FROM users WHERE age > 18",
"params": [],
"format": "json"
}
```
#### Batch
```http
POST /batch
Content-Type: application/json
{
"queries": [
"INSERT users { name := 'Alice', age := 30 }",
"INSERT users { name := 'Bob', age := 25 }"
]
}
```
### HTTP-Statuscodes
| Code | Bedeutung |
|------|----------|
| 200 | Erfolg |
| 400 | Bad request (Syntaxfehler) |
| 401 | Unauthorized (Auth erforderlich) |
| 403 | Forbidden (ungenügende Berechtigungen) |
| 404 | Not found (Tabelle/Typ existiert nicht) |
| 429 | Too many requests (Rate limitiert) |
| 500 | Internal server error |
| 503 | Service unavailable (wird gestartet) |
---
## WebSocket-Protokoll
URL: `ws://localhost:9471`
### Frame-Format
WebSocket Text-Frames enthalten JSON-Nachrichten:
```json
{
"id": 1,
"type": "query",
"query": "SELECT * FROM users"
}
```
### Nachrichtentypen
| Typ | Richtung | Beschreibung |
|------|-----------|--------------|
| `query` | C→S | Abfrage ausführen |
| `subscribe` | C→S | Änderungen abonnieren |
| `unsubscribe` | C→S | Abonnement beenden |
| `ping` | C→S | Keepalive |
| `result` | S→C | Abfrageergebnis |
| `notification` | S→C | Änderungsbenachrichtigung |
| `error` | S→C | Fehler |
| `pong` | S→C | Keepalive-Antwort |
docs/de/quickstart.md
-134
View File
@@ -1,134 +0,0 @@
# BaraDB — Schnellstart
## Server starten
```bash
./build/baradadb
```
Der Server startet standardmäßig auf `localhost:9470`.
## Verbindung via CLI
```bash
./build/baradadb --shell
```
## MCP Server (AI Agenten)
```bash
./build/baramcp --data-dir ./data
```
Der MCP Server startet im STDIO-Modus und stellt 3 Tools für AI-Agenten bereit: `query`, `vector_search`, `schema_inspect`.
## Grundlegende Operationen
### Tabelle erstellen
```sql
CREATE TABLE users (
id INTEGER PRIMARY KEY,
name TEXT,
email TEXT,
age INTEGER
);
```
### Daten einfügen
```sql
INSERT INTO users (id, name, email, age) VALUES (1, 'Alice', 'alice@test.com', 30);
INSERT INTO users (id, name, email, age) VALUES (2, 'Bob', 'bob@test.com', 25);
```
### Daten abfragen
```sql
SELECT name, age FROM users WHERE age > 18;
```
### Indizes erstellen
```sql
-- BTree Index
CREATE INDEX idx_name ON users(name) USING btree;
-- Volltext-Index
CREATE INDEX idx_email_fts ON users(email) USING fts;
-- Vektor-Index
CREATE INDEX idx_vec ON items(embedding) USING hnsw;
```
## Vector Search
```sql
CREATE TABLE docs (id INTEGER PRIMARY KEY, content TEXT, embedding VECTOR(768));
CREATE INDEX docs_vec ON docs(embedding) USING hnsw;
-- Ähnlichkeitssuche
SELECT id, cosine_distance(embedding, '[0.1, 0.2, ...]') AS dist
FROM docs ORDER BY dist ASC LIMIT 10;
```
## Graph Engine
```sql
CREATE GRAPH social;
INSERT INTO social_nodes (id, node_label) VALUES (1, 'Alice'), (2, 'Bob');
INSERT INTO social_edges (source_id, dest_id) VALUES (1, 2);
-- BFS Traversal
SELECT * FROM GRAPH_TABLE(social MATCH (n)-[r]->(m) ALGORITHM bfs COLUMNS (id, node_label));
-- PageRank
SELECT * FROM GRAPH_TABLE(social ALGORITHM pagerank COLUMNS (id, node_label, rank));
-- Community Detection (Louvain)
SELECT * FROM GRAPH_TABLE(social ALGORITHM community COLUMNS (id, node_label, community));
-- Kürzester Pfad
SELECT * FROM GRAPH_TABLE(social ALGORITHM shortest_path START 1 END 2 COLUMNS (id, node_label));
-- Knoten-Ähnlichkeit (Jaccard)
SELECT similarity_nodes('social', 'jaccard') AS result;
```
## AI Pipeline
```sql
-- Text in Chunks zerlegen
SELECT chunk('Langer Text hier...', 1024, 128) AS result;
-- Embedding generieren (mit konfiguriertem externen Service)
SELECT embed_text('Suchanfrage') AS result;
-- Schema-Prompt für LLM generieren
SELECT schema_prompt('users') AS result;
-- Natural Language → SQL (mit konfiguriertem LLM)
SELECT nl_to_sql('Zeige alle Benutzer über 25', 'users') AS result;
-- Cypher zu BaraQL übersetzen
SELECT cypher('MATCH (a)-[r]->(b) RETURN a.node_label, b.node_label') AS result;
```
## HTTP/REST API
```bash
curl -X POST http://localhost:9470/query \
-H "Content-Type: application/json" \
-d '{"query": "SELECT * FROM users"}'
```
## Konfiguration
```bash
# Umgebungsvariablen
export BARADB_DATA_DIR=./data
export BARADB_EMBED_ENDPOINT=http://localhost:11434/api/embeddings
export BARADB_EMBED_MODEL=nomic-embed-text
export BARADB_LLM_ENDPOINT=http://localhost:11434/api/generate
export BARADB_LLM_MODEL=llama3
```
docs/de/schema.md
-55
View File
@@ -1,55 +0,0 @@
# Schema-System
BaraDB verwendet ein Schema-first Design mit Typvererbung und automatischen Migrationen.
## Typen definieren
```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)
```
## Typvererbung
```nim
let employee = newType("Employee")
employee.setBases(@["Person"])
employee.addProperty("department", "str")
s.addType("default", employee)
# Vererbung auflösen — Employee erhält name, age, department
let resolved = s.resolveInheritance(employee)
```
## Schema-Operationen
### Diff
Zwei Schemata vergleichen:
```nim
let diff = s.diff(oldSchema, newSchema)
```
### Migrationen
Schema-Änderungen werden verfolgt und können Migrationsskripte generieren.
## Eigenschaftstypen
| Typ | Beschreibung |
|------|-------------|
| `str` | String |
| `int32` | 32-Bit Integer |
| `int64` | 64-Bit Integer |
| `float32` | 32-Bit Float |
| `float64` | 64-Bit Float |
| `bool` | Boolean |
| `datetime` | Datums-/Zeitwert |
| `bytes` | Binärdaten |
docs/de/security.md
-184
View File
@@ -1,184 +0,0 @@
# Sicherheitsleitfaden
## TLS/SSL-Verschlüsselung
BaraDB unterstützt TLS 1.3 für alle Protokolle (Binary, HTTP, WebSocket). Wenn kein
Zertifikat bereitgestellt wird, generiert der Server automatisch ein selbstsigniertes Zertifikat
beim Start für Zero-Configuration-Verschlüsselung.
### Eigene Zertifikate verwenden
```bash
# Vorhandene Zertifikate bereitstellen
BARADB_TLS_ENABLED=true \
BARADB_CERT_FILE=/etc/baradb/server.crt \
BARADB_KEY_FILE=/etc/baradb/server.key \
./build/baradadb
```
### Selbstsignierte Zertifikate generieren
```bash
openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt \
-days 365 -nodes -subj "/CN=localhost"
```
### Let's Encrypt (Production)
Certbot verwenden und BaraDB auf die generierten Dateien zeigen:
```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
```
## Authentifizierung
### JWT-basierte Authentifizierung
BaraDB verwendet JWT (JSON Web Tokens) mit HMAC-SHA256-Signatur.
#### Authentifizierung aktivieren
```bash
BARADB_AUTH_ENABLED=true \
BARADB_JWT_SECRET="$(openssl rand -hex 32)" \
./build/baradadb
```
#### Tokens erstellen
```nim
import barabadb/protocol/auth
var am = newAuthManager("your-secret-key")
let token = am.createToken(JWTClaims(
sub: "user1",
role: "admin",
exp: getTime() + 24.hours
))
```
#### Rollenbasierte Zugriffskontrolle
| Rolle | Berechtigungen |
|------|---------------|
| `admin` | Voller Zugriff |
| `write` | Lesen + Schreiben |
| `read` | Nur Lesen |
| `monitor` | Nur Metrics und Health |
#### Tokens verwenden
```bash
curl -H "Authorization: Bearer $TOKEN" \
http://localhost:9470/api/query \
-d '{"query": "SELECT * FROM users"}'
```
## Rate Limiting
Token-Bucket Rate Limiting verhindert Missbrauch:
```nim
import barabadb/protocol/ratelimit
var rl = newRateLimiter(
rlaTokenBucket,
globalRate = 10000, # 10K req/s global
perClientRate = 1000, # 1K req/s pro IP/Token
burstSize = 100 # 100 req Burst erlauben
)
if not rl.allowRequest("client-ip"):
return error("Rate limit exceeded")
```
## Netzwerksicherheit
### Bind-Adresse
Standardmäßig bindet BaraDB an `127.0.0.1` (nur Localhost). Für Production:
```bash
# An alle Interfaces binden (hinter Firewall oder Reverse Proxy)
BARADB_ADDRESS=0.0.0.0 ./build/baradadb
# An spezifisches internes Interface binden
BARADB_ADDRESS=10.0.0.5 ./build/baradadb
```
### Firewall-Regeln
```bash
# Nur Application-Server erlauben
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
# Externen Zugriff auf Management-Ports blockieren
sudo ufw deny 9471 # WebSocket (nur für internen Gebrauch)
```
## Datenverschlüsselung at Rest
### OS-Level-Verschlüsselung
LUKS für Vollständige-Festplatten-Verschlüsselung verwenden:
```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
```
### Applikations-Level-Verschlüsselung
BaraDB unterstützt transparente Verschlüsselung von SSTable-Dateien:
```bash
BARADB_STORAGE_ENCRYPTION_KEY="$(openssl rand -hex 32)" \
./build/baradadb
```
## Audit Logging
Alle Abfragen und administrativen Aktionen werden geloggt:
```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
}
```
Audit Logging aktivieren:
```bash
BARADB_LOG_LEVEL=info \
BARADB_LOG_FORMAT=json \
BARADB_LOG_FILE=/var/log/baradb/audit.log \
./build/baradadb
```
## Sicherheits-Checkliste
- [ ] Standard-JWT-Geheimnis ändern
- [ ] TLS mit gültigen Zertifikaten aktivieren
- [ ] An spezifische Interfaces binden
- [ ] Authentifizierung in Production aktivieren
- [ ] Rate Limiting konfigurieren
- [ ] Audit Logging aktivieren
- [ ] Daten at Rest verschlüsseln (LUKS oder App-Level)
- [ ] BaraDB als Non-Root-Benutzer ausführen
- [ ] Firewall-Regeln restriktiv halten
- [ ] JWT-Geheimnisse regelmäßig rotieren
docs/de/storage.md
-78
View File
@@ -1,78 +0,0 @@
# Speicher-Engines
BaraDB bietet mehrere Speicher-Engines, optimiert für verschiedene Zugriffsmuster.
## LSM-Tree (Key-Value)
Die primäre Speicher-Engine mit write-optimierter Append-only Log-Struktur.
### Verwendung
```nim
import barabadb/storage/lsm
var db = newLSMTree("./data")
db.put("key1", cast[seq[byte]]("value1"))
let (found, value) = db.get("key1")
db.close()
```
### Komponenten
- **MemTable**: In-Memory sortierter Puffer
- **WAL**: Write-Ahead Log für Dauerhaftigkeit
- **SSTable**: Sortierte String-Tabellen auf Disk
- **Bloom-Filter**: Probabilistische Mengenmitgliedschaft
- **Compaction**: Size-tiered Strategie mit Level-Management
- **Page-Cache**: LRU-Cache mit Trefferraten-Verfolgung
## B-Tree Index
Geordneter Index für Bereichsabfragen und Point-Lookups.
### Verwendung
```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)
Sichert Dauerhaftigkeit von Schreiboperationen.
```nim
import barabadb/storage/wal
var wal = newWAL("./wal")
wal.append("txn1", "SET key1 value1")
wal.flush()
```
## Bloom-Filter
Probabilistische Datenstruktur für schnelle negative Lookups.
```nim
import barabadb/storage/bloom
var filter = newBloomFilter(10000, 0.01)
filter.add("key1")
if filter.mightContain("key1"):
echo "possibly exists"
```
## Memory-mapped I/O
Effizienter Dateizugriff mittels mmap.
```nim
import barabadb/storage/mmap
var mapped = mmapFile("./data/file.dat")
let data = mapped.read(0, 100)
```
docs/de/transactions.md
-78
View File
@@ -1,78 +0,0 @@
# Transaktionen & MVCC
MVCC (Multi-Version Concurrency Control) mit Snapshot-Isolation und Deadlock-Erkennung.
## Verwendung
```nim
import barabadb/core/mvcc
var tm = newTxnManager()
let txn = tm.beginTxn()
# Schreiboperationen
discard tm.write(txn, "key1", cast[seq[byte]]("value1"))
discard tm.write(txn, "key2", cast[seq[byte]]("value2"))
# Savepoint
tm.savepoint(txn)
discard tm.write(txn, "key3", cast[seq[byte]]("value3"))
discard tm.rollbackToSavepoint(txn) # rückgängig machen key3
# Commit
discard tm.commit(txn)
```
## Transaktionsisolation
BaraDB verwendet **Snapshot-Isolation**:
- Leser blockieren keine Schreiber
- Schreiber blockieren keine Leser
- Jede Transaktion sieht einen konsistenten Snapshot
## Deadlock-Erkennung
```nim
import barabadb/core/deadlock
var detector = newDeadlockDetector()
if detector.detectCycle(txn1, txn2):
echo "Deadlock erkannt!"
```
## Write-Ahead Log
```nim
import barabadb/storage/wal
var wal = newWAL("./wal")
wal.append(txnId, "SET key value")
wal.flush()
```
## Savepoints
Verschachtelte Transaktions-Savepoints:
```nim
tm.savepoint(txn, "sp1")
# ... Operationen ...
tm.rollbackToSavepoint(txn, "sp1")
```
## Formale Verifikation
Das MVCC / Snapshot-Isolation Protokoll ist formal in TLA+ spezifiziert:
- **Spec:** `formal-verification/mvcc.tla`
- **Verifizierte Eigenschaften:**
- `NoDirtyReads` — Transaktionen lesen niemals nicht-committete Daten
- `ReadOwnWrites` — Transaktionen sehen immer ihre eigenen Schreiboperationen
- `WriteWriteConflict` — First-committer-wins (keine zwei committete Transaktionen schreiben denselben Schlüssel)
Lokale TLC-Ausführung:
```bash
cd formal-verification
java -cp tla2tools.jar tlc2.TLC -config models/mvcc.cfg mvcc.tla
```
docs/de/troubleshooting.md
-335
View File
@@ -1,335 +0,0 @@
# Fehlerbehebungsleitfaden
## Installationsprobleme
### Nim nicht gefunden
```
im: command not found
```
**Lösung:**
```bash
# Linux/macOS
curl https://nim-lang.org/choosenim/init.sh -sSf | sh
# Zu PATH hinzufügen
echo 'export PATH=$HOME/.nimble/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```
### SSL-Kompilierungsfehler
```
Error: BaraDB requires SSL support. Compile with -d:ssl
```
**Lösung:** Immer mit `-d:ssl` kompilieren:
```bash
nim c -d:ssl -d:release -o:build/baradadb src/baradadb.nim
```
### Fehlende Abhängigkeiten
```
Error: cannot open file: hunos
```
**Lösung:**
```bash
nimble install -d -y
```
## Laufzeitprobleme
### Port bereits in Verwendung
```
Error: unhandled exception: Address already in use [OSError]
```
**Lösung 1:** Port ändern:
```bash
BARADB_PORT=5433 ./build/baradadb
```
**Lösung 2:** Bestehenden Prozess beenden:
```bash
lsof -ti:9472 | xargs kill -9
# oder
fuser -k 9472/tcp
```
### Permission Denied auf Datenverzeichnis
```
Error: cannot create directory: Permission denied
```
**Lösung:**
```bash
mkdir -p ./data
chmod 755 ./data
# Oder anderes Verzeichnis verwenden
BARADB_DATA_DIR=/tmp/baradb_data ./build/baradadb
```
### Out of Memory
```
Error: out of memory
```
**Lösung:** Speicherverbrauch reduzieren:
```bash
BARADB_MEMTABLE_SIZE_MB=32 \
BARADB_CACHE_SIZE_MB=128 \
BARADB_VECTOR_EF_CONSTRUCTION=100 \
./build/baradadb
```
### Disk Full
```
Error: No space left on device
```
**Lösung:**
```bash
# Disk-Nutzung prüfen
df -h
# Compaction auslösen um Platz freizugeben
curl -X POST http://localhost:9470/api/admin/compact
# Oder manuell
./build/baradadb --compact
```
## Abfrageprobleme
### Syntaxfehler
```
Error: Syntax error at position 15: unexpected token
```
**Lösung:** Abfragesyntax prüfen:
```sql
-- Korrekt
SELECT name, age FROM users WHERE age > 18;
-- Inkorrekt (fehlendes Komma)
SELECT name age FROM users WHERE age > 18;
```
### Tabelle nicht gefunden
```
Error: Table 'users' does not exist
```
**Lösung:** Zuerst Schema erstellen:
```sql
CREATE TYPE User {
name: str,
age: int32
};
```
### Typ-Mismatch
```
Error: Cannot compare int32 with str
```
**Lösung:** Korrekte Typen verwenden:
```sql
-- Korrekt
SELECT * FROM users WHERE age > 18;
-- Inkorrekt
SELECT * FROM users WHERE age > '18';
```
### Timeout
```
Error: Query execution timeout
```
**Lösung:** LIMIT hinzufügen oder optimieren:
```sql
-- Limit hinzufügen
SELECT * FROM large_table LIMIT 1000;
-- Index verwenden
SELECT * FROM users WHERE id = 123;
```
## Verbindungsprobleme
### Connection Refused
```
Connection refused: localhost:9472
```
**Lösung:**
```bash
# Prüfen ob Server läuft
ps aux | grep baradadb
# Server starten
./build/baradadb
# Firewall prüfen
sudo ufw status
sudo ufw allow 9472
```
### Authentifizierung fehlgeschlagen
```
Error: Authentication failed
```
**Lösung:**
```bash
# Prüfen ob JWT-Geheimnis übereinstimmt
BARADB_AUTH_ENABLED=true \
BARADB_JWT_SECRET="correct-secret" \
./build/baradadb
```
## Performance-Probleme
### Langsame Abfragen
**Diagnose:**
```bash
# Abfrageplan prüfen
curl -X POST http://localhost:9470/api/explain \
-d '{"query": "SELECT * FROM large_table"}'
```
**Lösungen:**
1. Indizes hinzufügen:
```sql
CREATE INDEX idx_users_name ON users(name);
```
2. LIMIT verwenden:
```sql
SELECT * FROM users LIMIT 100;
```
3. Cache erhöhen:
```bash
BARADB_CACHE_SIZE_MB=1024 ./build/baradadb
```
### Hohe CPU-Nutzung
**Ursachen:**
- Compaction läuft
- Große Vektor-Suche ohne HNSW
- Komplexe Graph-Traversierung
**Lösungen:**
```bash
# Compaction-Intervall anpassen
BARADB_COMPACTION_INTERVAL_MS=300000 ./build/baradadb
# Approximative Vektor-Suche verwenden
SELECT /*+ APPROXIMATE */ * FROM vectors
ORDER BY cosine_distance(embedding, [...])
LIMIT 10;
```
## Cluster-Probleme
### Raft Split-Brain
```
Warning: Multiple leaders detected
```
**Lösung:** Ungerade Anzahl von Knoten sicherstellen (3, 5, 7). Minority-Partition neu starten.
### Replikations-Lag
```
Warning: Replication lag > 10s
```
**Lösung:**
```bash
# Netzwerk-Latenz prüfen
ping replica-node
# Replikations-Threads erhöhen
BARADB_REPLICATION_THREADS=4 ./build/baradadb
# Auf Async-Replikation umschalten
BARADB_REPLICATION_MODE=async
```
## Datenkorruption
### Prüfsummen-Mismatch
```
Error: SSTable checksum mismatch
```
**Lösung:**
```bash
# Korrupte SSTable entfernen (Daten werden aus WAL wiederhergestellt)
rm ./data/sstables/corrupted.sst
# Neustarten und wiederherstellen
./build/baradadb --recover
```
## Debug-Modus
Debug-Logging für detaillierte Diagnostik aktivieren:
```bash
BARADB_LOG_LEVEL=debug \
BARADB_LOG_FILE=/tmp/baradb_debug.log \
./build/baradadb
```
## Hilfe erhalten
Wenn das Problem weiterhin besteht:
1. Logs prüfen: `tail -f /var/log/baradb/baradb.log`
2. Metrics prüfen: `curl http://localhost:9470/metrics`
3. Diagnostik ausführen: `./build/baradadb --diagnose`
4. Issue öffnen mit:
- BaraDB Version (`./build/baradadb --version`)
- OS und Architektur
- Relevante Log-Auszüge
- Schritte zur Reproduktion
docs/de/udf.md
-56
View File
@@ -1,56 +0,0 @@
# Benutzerdefinierte Funktionen
BaraQL mit benutzerdefinierten Funktionen erweitern.
## Verwendung
```nim
import barabadb/query/udf
var reg = newUDFRegistry()
# Standard-Bibliothek registrieren
reg.registerStdlib() # abs, sqrt, pow, lower, upper, len, trim, substr, toString, toInt
# Benutzerdefinierte Funktion
reg.register("greet", @[UDFParam(name: "name", typeName: "str")],
"str", proc(args: seq[Value]): Value =
return Value(kind: vkString, strVal: "Hello, " & args[0].strVal & "!"))
```
## Standard-Bibliotheksfunktionen
| Funktion | Beschreibung | Beispiel |
|----------|-------------|---------|
| `abs(n)` | Absoluter Wert | `abs(-5)` → 5 |
| `sqrt(n)` | Quadratwurzel | `sqrt(16)` → 4 |
| `pow(n, e)` | Potenz | `pow(2, 3)` → 8 |
| `lower(s)` | Kleinbuchstaben | `lower('ABC')` → 'abc' |
| `upper(s)` | Großbuchstaben | `upper('abc')` → 'ABC' |
| `len(s)` | Länge | `len('hello')` → 5 |
| `trim(s)` | Leerzeichen trimmen | `trim(' hello ')` → 'hello' |
| `substr(s, start, len)` | Substring | `substr('hello', 0, 3)` → 'hel' |
| `toString(n)` | In String konvertieren | `toString(123)` → '123' |
| `toInt(s)` | In Integer konvertieren | `toInt('123')` → 123 |
## Funktionsregistrierung
```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 =
# Implementierung
result = Value(kind: vkString, strVal: "")
)
```
## UDFs in Abfragen verwenden
```sql
SELECT greet(name) FROM users;
```
docs/de/vector.md
-129
View File
@@ -1,129 +0,0 @@
# Vektor-Suche
Native HNSW und IVF-PQ Indizes für Ähnlichkeitssuche mit vollständiger SQL-Integration.
## SQL — Vektor-Spalten
```sql
CREATE TABLE items (
id INT PRIMARY KEY,
embedding VECTOR(768)
);
```
Der `VECTOR(n)`-Typ speichert float32-Arrays mit fester Dimension `n`.
## Vektoren einfügen
```sql
INSERT INTO items (id, embedding) VALUES (1, '[0.1, 0.2, 0.3, ...]');
```
## Vektor-Distanzfunktionen
```sql
-- Kosinus-Distanz (0 = identisch, 1 = orthogonal)
SELECT id, cosine_distance(embedding, '[0.1, 0.2, 0.3]') AS dist FROM items;
-- Euklidische / L2 Distanz
SELECT id, euclidean_distance(embedding, '[0.1, 0.2, 0.3]') AS dist FROM items;
SELECT id, embedding <-> '[0.1, 0.2, 0.3]' AS dist FROM items;
-- Inneres Produkt (negativ für Minimierung)
SELECT id, inner_product(embedding, '[0.1, 0.2, 0.3]') AS dist FROM items;
-- Manhattan / L1 Distanz
SELECT id, l1_distance(embedding, '[0.1, 0.2, 0.3]') AS dist FROM items;
```
## Vektor-Indizes
```sql
-- HNSW-Index für approximative Nächste-Nachbarn-Suche
CREATE INDEX idx_items_vec ON items(embedding) USING hnsw;
-- Der Index wird bei INSERT und UPDATE automatisch aktualisiert
```
## Hybrid RAG Search
```sql
-- Kombinierte Vektor- + Volltext-Suche mit RRF-Reranking
SELECT hybrid_search('AI query', embedding, content, 10) AS result;
-- Gefilterte hybride Suche
SELECT hybrid_search_filtered('AI query', embedding, content, 10, 'category', 'news') AS result;
```
## AI Pipeline
### Text-Chunking
```sql
-- Text in überlappende Chunks zerlegen
SELECT chunk('Langer Text hier...', 1024, 128) AS result;
-- Ergebnis: [{"index":0, "text":"...", "size":124}, ...]
```
### Embedding-Generierung
```sql
-- Externen Embedding-Service aufrufen (konfiguriert via Umgebungsvariablen)
SELECT embed_text('Suchtext hier') AS result;
```
Umgebungsvariablen für den Embedder:
```bash
export BARADB_EMBED_ENDPOINT=http://localhost:11434/api/embeddings
export BARADB_EMBED_MODEL=nomic-embed-text
```
### Auto-Embedding bei INSERT
Wenn eine VECTOR-Spalte NULL ist, aber eine TEXT-Spalte einen Wert hat, wird das Embedding automatisch generiert (falls ein Embedder konfiguriert ist).
```sql
CREATE TABLE docs (id INTEGER PRIMARY KEY, content TEXT, embedding VECTOR(768));
CREATE INDEX docs_vec ON docs(embedding) USING hnsw;
-- embedding wird automatisch gefüllt
INSERT INTO docs (id, content) VALUES (1, 'Dieser Text wird automatisch embedded');
```
## Distanzmetriken
| Metrik | SQL-Funktion | Beschreibung |
|--------|-------------|-------------|
| `cosine` | `cosine_distance(a, b)` | Kosinus-Distanz |
| `euclidean` | `euclidean_distance(a, b)` / `<->` | L2-Distanz |
| `dotproduct` | `inner_product(a, b)` | Negatives Skalarprodukt |
| `manhattan` | `l1_distance(a, b)` | L1-Distanz |
## Index-Typen
### HNSW (Standard)
```nim
import barabadb/vector/engine
var hnsw = newHNSWIndex(dimensions = 128, m = 16, efConstruction = 200)
```
### IVF-PQ
```nim
var ivfpq = newIVFPQIndex(dimensions = 128, numCentroids = 256, subQuantizers = 8)
```
## Native Nim API
```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)
let filtered = idx.searchWithFilter(queryVector, k = 10,
filter = proc(meta: Table[string, string]): bool = return "category" in meta)
```
docs/en/changelog.md
+1 -1
View File
@@ -53,7 +53,7 @@ All notable changes to BaraDB are documented in this file.
- **Cypher Compatibility Layer**:
- `cypher()` SQL function — translates `MATCH (a)-[r]->(b) RETURN ...` to GRAPH_TABLE
- Automatic Cypher → BaraQL conversion
- **German Documentation** — Full documentation set in German (`docs/de/`)
- **Bulgarian Documentation** — Full documentation set in Bulgarian (`docs/bg/`) (replaces removed German, Russian, Arabic, Farsi, Turkish, and Chinese docs)
### Changed
docs/fa/api-binary.md
-62
View File
@@ -1,62 +0,0 @@
# API پروتکل باینری
پروتکل سطح پایین برای اتصالات با کارایی بالا.
## فرمت پیام
همه پیام‌ها از ترتیب big-endian استفاده می‌کنند:
```
┌────────┬────────┬────────┬────────┬─────────────┐
│ Length │ Type │ Seq │ Status │ Payload │
│ 4 bytes│ 1 byte │ 2 bytes│ 1 byte │ N bytes │
└────────┴────────┴────────┴────────┴─────────────┘
```
## انواع پیام
### Query (0x01)
```nim
let msg = makeQueryMessage(seq, "SELECT * FROM users")
```
### Insert (0x02)
```nim
let msg = makeInsertMessage(seq, "users", data)
```
### Update (0x03)
```nim
let msg = makeUpdateMessage(seq, "users", updates, where)
```
### Delete (0x04)
```nim
let msg = makeDeleteMessage(seq, "users", where)
```
### Ready (0x05)
```nim
let msg = makeReadyMessage(seq)
```
### Error (0x06)
```nim
let msg = makeErrorMessage(seq, code, message)
```
## کدهای پاسخ
| کد | نام | توضیح |
|----|-----|--------|
| 0x00 | OK | موفق |
| 0x01 | ERROR | خطای عمومی |
| 0x02 | AUTH_REQUIRED | نیاز به احراز هویت |
| 0x03 | INVALID_QUERY | خطای نحوی |
| 0x04 | NOT_FOUND | منبع یافت نشد |
docs/fa/api-http.md
-62
View File
@@ -1,62 +0,0 @@
# HTTP/REST API
API REST مبتنی بر JSON برای برنامه‌های وب.
## Base URL
```
http://localhost:9470/api
```
## Endpoints
### GET /api/users
لیست همه کاربران:
```bash
curl http://localhost:9470/api/users
```
### GET /api/users/:id
دریافت کاربر با ID:
```bash
curl http://localhost:9470/api/users/1
```
### POST /api/users
ایجاد کاربر:
```bash
curl -X POST http://localhost:9470/api/users \
-d '{"name": "Charlie", "age": 35}'
```
### PUT /api/users/:id
به‌روزرسانی کاربر:
```bash
curl -X PUT http://localhost:9470/api/users/1 \
-d '{"name": "Alice", "age": 31}'
```
### DELETE /api/users/:id
حذف کاربر:
```bash
curl -X DELETE http://localhost:9470/api/users/1
```
## Query Endpoint
اجرای کوئری BaraQL:
```bash
curl -X POST http://localhost:9470/api/query \
-d '{"sql": "SELECT * FROM users WHERE age > 18"}'
```
docs/fa/api-websocket.md
-67
View File
@@ -1,67 +0,0 @@
# WebSocket API
استریم تمام‌دوطرفه برای فیدهای داده real-time.
## اتصال
```
ws://localhost:9471/ws
```
## مثال کلاینت
```javascript
const ws = new WebSocket('ws://localhost:9471/ws');
ws.onopen = () => {
ws.send(JSON.stringify({
type: 'query',
sql: 'SELECT * FROM users'
}));
};
ws.onmessage = (event) => {
console.log('Received:', JSON.parse(event.data));
};
```
## فرمت پیام
```json
{
"type": "query",
"id": "uuid",
"sql": "SELECT * FROM users"
}
```
## انواع پیام
### درخواست
```json
{
"type": "query",
"id": "123",
"sql": "SELECT * FROM users"
}
```
### پاسخ
```json
{
"type": "result",
"id": "123",
"data": [{"id": 1, "name": "Alice"}]
}
```
### اشتراک
```json
{
"type": "subscribe",
"table": "users"
}
```
docs/fa/architecture.md
-197
View File
@@ -1,197 +0,0 @@
# معماری BaraDB
## بررسی اجمالی
BaraDB یک **موتور پایگاه داده چند حالته** است که با Nim نوشته شده و ذخیره‌سازی سندی (KV)، گرافی، برداری، ستونی و جستجوی تمام‌متن را در یک موتور واحد با زبان پرس‌وجوی واحد **BaraQL** ترکیب می‌کند.
## معماری لایه‌ای
```
┌─────────────────────────────────────────────────────────┐
│ 1. لایه کلاینت │
│ پروتکل باینری │ HTTP/REST │ WebSocket │ توکار │
├─────────────────────────────────────────────────────────┤
│ 2. لایه پرس‌وجو (BaraQL) │
│ لکسر → پارسر → AST → IR → بهینه‌ساز → کد‌ژن │
├─────────────────────────────────────────────────────────┤
│ 3. موتور اجرا │
│ سند │ گراف │ بردار │ ستونی │ FTS │
├─────────────────────────────────────────────────────────┤
│ 4. ذخیره‌سازی │
│ LSM-Tree │ B-Tree │ WAL │ Bloom │ فشردهسازی │ کش │
├─────────────────────────────────────────────────────────┤
│ 5. توزیع‌شده │
│ Raft │ شاردینگ │ ریپلیکیشن │ Gossip │
└─────────────────────────────────────────────────────────┘
```
## لایه 1: لایه کلاینت
چندین پروتکل ارتباطی:
- **پروتکل باینری** (`protocol/wire.nim`): پروتکل باینری کارآمد big-endian با 16 نوع پیام
- **HTTP/REST** (`core/httpserver.nim`): API REST مبتنی بر JSON با چند نخی
- **WebSocket** (`core/websocket.nim`): استریم تمام‌دوطرفه
- **حالت توکار** (`storage/lsm.nim`): دسترسی مستقیم درون‌پروسه‌ای
### مدیریت اتصال
- **استخر اتصال** (`protocol/pool.nim`): محدودیت‌های کمینه/بیشینه اتصال با تایم‌اوت بیکاری
- **محدودیت نرخ** (`protocol/ratelimit.nim`): Token-bucket سراسری و برای هر کلاینت
- **احراز هویت** (`protocol/auth.nim`): JWT با HMAC-SHA256 و دسترسی مبتنی بر نقش
- **TLS/SSL** (`protocol/ssl.nim`): TLS 1.3 با گواهینامه‌های خودتولید
## لایه 2: لایه پرس‌وجو (BaraQL)
خط لوله BaraQL:
1. **لکسر** (`query/lexer.nim`): توکن‌سازی ورودی به بیش از 80 نوع توکن
2. **پارسر** (`query/parser.nim`): پارسر نزولی بازگشتی تولیدکننده AST
3. **AST** (`query/ast.nim`): بیش از 300 خط，覆盖 بیش از 25 نوع گره
4. **IR** (`query/ir.nim`): نمایش میانی برای نقشه‌های اجرا
5. **بهینه‌ساز** (`query/adaptive.nim`): بهینه‌سازی تطبیقی کross-modal
6. **کد‌ژن** (`query/codegen.nim`): ترجمه IR به عملیات ذخیره‌سازی
7. **اجراکننده** (`query/executor.nim`): اجرای نقشه‌ها با موازی‌سازی
### برنامه‌ریزی کross-modal
بهینه‌ساز (`query/adaptive.nim`) ترتیب اجرا را بین موتورها تعیین می‌کند:
```
1. تخمین گزینش‌پذیری برای هر شرط
2. ارسال گزینش‌پذیرترین شرط به موتور مربوطه اول
3. استفاده از فیلترهای Bloom برای جستجوهای KV
4. موازی‌سازی شاخه‌های مستقل
5. استریم نتایج برای اجتناب از مادی‌سازی
```
## لایه 3: موتور اجرا
### موتور سند/KV
- **LSM-Tree** (`storage/lsm.nim`): ذخیره‌سازی بهینه برای نوشتن با MemTable، WAL، SSTables
- **اندیس B-Tree** (`storage/btree.nim`): اندیس مرتب برای اسکن بازه‌ای با COW
### موتور برداری (`vector/`)
- **اندیس HNSW** (`vector/engine.nim`): گراف Navigable Small World سلسله‌مراتبی
- **اندیس IVF-PQ** (`vector/engine.nim`): فایل معکوس با کوانتیزاسیون محصول
- **عملیات SIMD** (`vector/simd.nim`): محاسبات فاصله بهینه‌شده با AVX2
- **کوانتیزاسیون** (`vector/quant.nim`): اسکالر، محصول، و باینری
### موتور گراف (`graph/`)
- **لیست مجاورت** (`graph/engine.nim`): گراف جهت‌دار با وزن یال
- **الگوریتم‌ها** (`graph/engine.nim`): BFS، DFS، Dijkstra، PageRank
- **تشخیص جامعه** (`graph/community.nim`): الگوریتم Louvain
- **تطبیق الگو** (`graph/community.nim`): ایزومورفیسم زیرگراف
- **پارسر Cypher** (`graph/cypher.nim`): پرس‌وجوهای گرافی Cypher-مانند
### جستجوی تمام‌متن (`fts/`)
- **اندیس معکوس** (`fts/engine.nim`): اندیس سند-ترم
- **رتبه‌بندی** (`fts/engine.nim`): امتیازدهی BM25 و TF-IDF
- **جستجوی تقریبی** (`fts/engine.nim`): تطبیق با فاصله Levenshtein
- **چندزبانه** (`fts/multilang.nim`): توکنایزرهایی برای EN، BG، DE، FR، RU
### موتور ستونی (`core/columnar.nim`)
- ذخیره‌سازی هر-ستونی برای پرس‌وجوهای تحلیلی
- کدگذاری RLE و دیکشنری
- تجمیع‌های شتاب‌گرفته با SIMD
## لایه 4: ذخیره‌سازی
- **LSM-Tree** (`storage/lsm.nim`): MemTable، WAL، SSTable، Bloom Filter، فشرده‌سازی
- **کش صفحه** (`storage/compaction.nim`): کش LRU با ردیابی نرخ hit
- **I/O نگاشته‌شده به حافظه** (`storage/mmap.nim`): دسترسی فایل مبتنی بر mmap
- **بازیابی** (`storage/recovery.nim`): بازپخش WAL و بازیابی پس از خرابی
### مسیر نوشتن
```
کلاینت → پروتکل → احراز → پارسر → AST → IR → کد‌ژن
→ StorageOp → MVCC Txn → WAL Write → MemTable → Commit
```
### مسیر خواندن
```
کلاینت → پروتکل → احراز → پارسر → AST → IR → کد‌ژن
→ StorageOp → MVCC Snapshot → MemTable → SSTable → Result
```
## لایه 5: توزیع‌شده
- **Raft Consensus** (`core/raft.nim`): انتخاب رهبر، تکثیر لاگ
- **شاردینگ** (`core/sharding.nim`): Hash، range، و consistent hashing
- **ریپلیکیشن** (`core/replication.nim`): حالت‌های sync، async، semi-sync
- **پروتکل Gossip** (`core/gossip.nim`): مدیریت عضویت SWIM-مانند
- **تراکنش‌های توزیع‌شده** (`core/disttxn.nim`): commit دو مرحله‌ای
## تصمیمات کلیدی طراحی
1. **Nim خالص**: بدون وابستگی به Cython، Python یا Rust
2. **ذخیره‌سازی یکپارچه**: یک موتور برای KV، گراف، بردار، FTS و ستونی
3. **حالت توکار**: می‌تواند به‌عنوان کتابخانه یا سرور اجرا شود
4. **پروتکل باینری**: پروتکل سیمی کارآمد سفارشی
5. **MVCC**: کنترل همزمانی چندنسخه‌ای
6. **طرحواره-اول**: سیستم طرحواره با نوع قوی با وراثت
7. **کross-modal**: زبان پرس‌وجوی واحد در تمام مدل‌های داده
8. **تأیید رسمی**: الگوریتم‌های اصلی توزیع‌شده در TLA+ مشخص و با TLC بررسی شده
## آمار ماژول‌ها
| دسته | ماژول‌ها | خطوط کد | هدف |
|------|----------|----------|-----|
| Core | 16 | ~4,200 | سرور، پروتکل‌ها، تراکنش‌ها، توزیع‌شده |
| Storage | 7 | ~3,100 | LSM، B-Tree، WAL، bloom، فشرده‌سازی، mmap |
| Query | 7 | ~2,800 | لکسر، پارسر، AST، IR، بهینه‌ساز، کد‌ژن، اجراکننده |
| Vector | 3 | ~1,200 | HNSW، IVF-PQ، کوانتیزاسیون، SIMD |
| Graph | 3 | ~1,000 | لیست مجاورت، الگوریتم‌ها، تشخیص جامعه |
| FTS | 2 | ~900 | اندیس معکوس، BM25، تقریبی، چندزبانه |
| Protocol | 7 | ~2,400 | Wire، HTTP، WebSocket، استخر، auth، محدودیت نرخ، SSL |
| Schema | 1 | ~600 | انواع، لینک‌ها، وراثت، مهاجرت‌ها |
| Client | 2 | ~800 | کلاینت باینری Nim، کمکی فایل |
| CLI | 1 | ~400 | شل تعاملی BaraQL |
| **مجموع** | **49** | **~14,100** | |
## نمودارهای جریان داده
### پرس‌وجوی ساده
```
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ Client │───→│ Lexer │───→│ Parser │───→│ IR │───→│ Codegen│
└────────┘ └────────┘ └────────┘ └────────┘ └───┬────┘
│
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│ Result │←───│ Format │←───│ Execute│←───│ Storage│←──────┘
└────────┘ └────────┘ └────────┘ └────────┘
```
### پرس‌وجوی کross-modal
```
┌─────────────┐
│ Parser │
└──────┬──────┘
│
┌──────▼──────┐
│ Adaptive │
│ Optimizer │
└──────┬──────┘
│
┌───────────────┼───────────────┐
│ │ │
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ Vector │ │ Graph │ │ FTS │
│ Engine │ │ Engine │ │ Engine │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└───────────────┼───────────────┘
│
┌──────▼──────┐
│ Join │
│ & Sort │
└──────┬──────┘
│
┌──────▼──────┐
│ Result │
└─────────────┘
```
docs/fa/backup.md
-81
View File
@@ -1,81 +0,0 @@
# پشتیبان‌گیری و بازیابی
## Snapshot آنلاین
BaraDB از snapshot آنلاین بدون توقف سرور پشتیبانی می‌کند.
### ایجاد 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 \
-d '{"destination": "/backup/snapshot.db"}'
```
### پشتیبان‌گیری خودکار
```bash
0 2 * * * /usr/local/bin/baradadb --snapshot --output=/backup/baradb_$(date +\%Y\%m\%d).db
find /backup -name "baradb_*.db" -mtime +7 -delete
```
## بازیابی نقطه‌درزمان (PITR)
### بازیابی از snapshot + WAL
```bash
./build/baradadb --recover \
--checkpoint=/backup/snapshot.db \
--wal-dir=/backup/wal
```
### بازیابی از طریق SQL
```sql
RECOVER TO TIMESTAMP '2026-05-07T12:00:00';
```
## سناریوهای بازیابی
### سناریو 1: خرابی فایل
```bash
cp /backup/sstables/000012.sst ./data/sstables/
./build/baradadb --rebuild-index
```
### سناریو 2: از دست دادن کامل داده
```bash
cp /backup/snapshot.db ./data/
./build/baradadb --recover --wal-dir=/backup/wal
```
### سناریو 3: خرابی گره کلاستر
```bash
BARADB_RAFT_NODE_ID=newnode \
BARADB_RAFT_PEERS=node1:9001,node2:9001 \
./build/baradadb
```
## بهترین شیوه‌ها
1. بازیابی را مرتب تست کنید
2. پشتیبان‌ها را خارج از سایت ذخیره کنید
3. پشتیبان‌ها را رمزنگاری کنید
4. کارهای پشتیبان‌گیری را مانیتور کنید
docs/fa/baraql.md
-597
View File
@@ -1,597 +0,0 @@
# مرجع زبان پرس‌وجو BaraQL
BaraQL یک زبان پرس‌وجو سازگار با SQL با افزونه‌هایی برای عملیات گراف، بردار و سند است.
## انواع داده
| نوع | توضیح | مثال |
|------|--------|------|
| `null` | مقدار تهی | `null` |
| `bool` | بولی | `true`, `false` |
| `int8` | عدد صحیح 8 بیتی علامت‌دار | `127` |
| `int16` | عدد صحیح 16 بیتی علامت‌دار | `32767` |
| `int32` | عدد صحیح 32 بیتی علامت‌دار | `2147483647` |
| `int64` | عدد صحیح 64 بیتی علامت‌دار | `9223372036854775807` |
| `float32` | عدد اعشاری 32 بیتی | `3.14` |
| `float64` | عدد اعشاری 64 بیتی | `3.14159265359` |
| `str` | رشته UTF-8 | `'hello'` |
| `bytes` | بایت‌های خام | `0xDEADBEEF` |
| `array<T>` | آرایه همگن | `[1, 2, 3]` |
| `vector` | بردار float32 | `[0.1, 0.2, 0.3]` |
| `object` | شیء کلید-مقدار | `{"a": 1}` |
| `datetime` | timestamp 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 * 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'; -- بدون حساسیت به حروف
-- بررسی 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;
-- حذف شرطی
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(*) 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;
```
## JOINها
```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;
-- 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;
-- JOINهای چندگانه
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;
```
## CTEها (عبارات جدول مشترک)
```sql
-- CTE واحد
WITH active_users AS (
SELECT * FROM users WHERE active = true
)
SELECT * FROM active_users;
-- CTEهای چندگانه
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
```sql
SELECT name,
CASE
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;
```
## عملیات مجموعه‌ای
```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
};
-- با فیلدهای الزامی
CREATE TYPE User {
email: str REQUIRED,
name: str,
age: int32,
created_at: datetime DEFAULT now()
};
-- با لینک‌ها
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
CREATE TYPE Animal {
name: str
};
CREATE TYPE Dog EXTENDING Animal {
breed: str
};
CREATE TYPE Cat EXTENDING Animal {
indoor: bool
};
```
### اندیس‌ها
```sql
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;
```
### DROP
```sql
DROP TYPE User;
DROP INDEX idx_users_name;
```
## جستجوی برداری
```sql
-- درج با بردار
INSERT articles {
title := 'Nim Programming',
embedding := [0.1, 0.2, 0.3, 0.4]
};
-- جستجوی شباهت (فاصله کسینوسی)
SELECT title FROM articles
ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4])
LIMIT 5;
-- فاصله اقلیدسی
SELECT title FROM articles
ORDER BY l2_distance(embedding, [0.1, 0.2, 0.3, 0.4])
LIMIT 5;
-- ضرب نقطه‌ای
SELECT title FROM articles
ORDER BY dot_product(embedding, [0.1, 0.2, 0.3, 0.4]) DESC
LIMIT 5;
-- با فیلتر ابرداده
SELECT title FROM articles
WHERE category = 'tech'
ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4])
LIMIT 5;
```
## الگوهای گراف
```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);
-- جستجوی تقریبی
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;
```
## توابع تعریف‌شده کاربر
```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');
```
## اشاره‌های پرس‌وجو
```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;
```
## توابع پنجره‌ای
```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
)
```
## ERP چند مستأجری
BaraDB از اجرای چندین شرکت (tenant) در یک نمونه پایگاه داده پشتیبانی می‌کند، با استفاده از **امنیت سطح سطر (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
```
### چرا چند مستأجری؟
- **یک نمونه، مستأجران زیاد** — نیازی به اجرای ۱۰۰ پایگاه داده جداگانه نیست
- **اسناد 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 |
| Transaction | BEGIN, COMMIT, ROLLBACK, SAVEPOINT |
| Graph | MATCH, RETURN, WHERE, shortestPath, type |
| FTS | MATCH, AGAINST, relevance, IN BOOLEAN MODE, WITH FUZZINESS |
| Vector | cosine_distance, euclidean_distance, inner_product, l1_distance, l2_distance, <-> |
| JSON | ->, ->> |
| FTS | @@ (BM25 match) |
| Recovery | RECOVER TO TIMESTAMP |
| Functions | count, sum, avg, min, max, stddev, variance, abs, sqrt, lower, upper, len, trim, substr, now, last_insert_id, current_setting |
| Session | SET, current_setting, current_user, current_role |
| Window | OVER, PARTITION BY, ROWS, RANGE, UNBOUNDED PRECEDING, CURRENT ROW, FOLLOWING |
| Window Functions | ROW_NUMBER, RANK, DENSE_RANK, LEAD, LAG, FIRST_VALUE, LAST_VALUE, NTILE |
docs/fa/btree.md
-25
View File
@@ -1,25 +0,0 @@
# اندیس B-Tree
ساختار اندیس مرتب برای اسکن بازه‌ای و جستجوی نقطه‌ای.
## استفاده
```nim
import barabadb/storage/btree
var btree = newBTreeIndex[string, string]()
btree.insert("key1", "value1")
btree.insert("key2", "value2")
let values = btree.get("key1")
let range = btree.scan("key_a", "key_z")
btree.delete("key1")
```
## ویژگی‌ها
- ذخیره‌سازی مرتب کلید-مقدار
- جستجوهای بازه‌ای (BETWEEN, >, <, >=, <=)
- اسکن پیشوندی
- پشتیبانی از iterator
docs/fa/changelog.md
-70
View File
@@ -1,70 +0,0 @@
# سیاهه تغییرات
## [0.1.0] — 2025-01-15
### افزوده شده
- **موتورهای ذخیره‌سازی اصلی**
- LSM-Tree با MemTable، WAL، SSTables و size-tiered compaction
- B-Tree اندیس مرتب با اسکن بازه‌ای و MVCC copy-on-write
- Bloom filterها
- Memory-mapped I/O
- LRU page cache
- **موتور کوئری (BaraQL)**
- لکسر SQL-سازگار با 80+ نوع توکن
- پارسر تولیدکننده AST با 25+ نوع گره
- نمایش میانی (IR)
- بهینه‌ساز تطبیقی
- اجراکننده موازی
- **قابلیت‌های زبان BaraQL**
- SELECT, INSERT, UPDATE, DELETE
- WHERE, ORDER BY, LIMIT, OFFSET
- GROUP BY, HAVING
- INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN
- CTEs با WITH
- زیرکوئری‌ها
- CASE
- UNION, INTERSECT, EXCEPT
- **موتور برداری**
- اندیس HNSW
- IVF-PQ
- SIMD-بهینه‌شده
- **موتور گراف**
- لیست مجاورت
- BFS و DFS
- Dijkstra
- PageRank
- Louvain
- Cypher
- **جستجوی تمام‌متن**
- اندیس معکوس
- BM25
- TF-IDF
- جستجوی فازی
- چندزبانه
- **پروتکل‌ها**
- Binary wire protocol
- HTTP/REST JSON API
- WebSocket
- Connection pooling
- JWT auth
- TLS/SSL
- **سیستم توزیع‌شده**
- Raft consensus
- Sharding
- Replication
- Gossip
- Two-phase commit
### عملکرد
- LSM-Tree: 580K نوشتن/ثانیه، 720K خواندن/ثانیه
- B-Tree: 1.2M درج/ثانیه
- Vector SIMD: 850K فاصله کسینوسی/ثانیه
docs/fa/clients.md
-66
View File
@@ -1,66 +0,0 @@
# SDK های کلاینت
BaraDB کتابخانه‌های کلاینت رسمی برای JavaScript/TypeScript، Python، Nim و Rust فراهم می‌کند.
## JavaScript / TypeScript
### نصب
```bash
npm install 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');
```
## 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")
```
## Nim (حالت توکار)
```nim
import barabadb/storage/lsm
var db = newLSMTree("./data")
db.put("key", cast[seq[byte]]("value"))
let (found, val) = db.get("key")
db.close()
```
## Rust
```rust
use baradb::Client;
let mut client = Client::connect("localhost:9472").await?;
```
## HTTP/REST
```bash
curl -X POST http://localhost:9470/api/query \
-d '{"query": "SELECT * FROM users"}'
```
docs/fa/columnar.md
-50
View File
@@ -1,50 +0,0 @@
# ذخیره‌سازی ستونی
ذخیره‌سازی ستون-محور برای کوئری‌های تحلیلی و تجمیع‌ها.
## استفاده
```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()
```
## کدگذاری
### RLE
```nim
let rle = rleEncode(@[1'i64, 1, 1, 2, 2, 3])
```
### Dictionary
```nim
let dict = dictEncode(@["apple", "banana", "apple"])
```
## انواع ستون
| نوع | توضیح |
|-----|--------|
| `int32` | عدد صحیح 32 بیتی |
| `int64` | عدد صحیح 64 بیتی |
| `float32` | عدد اعشاری 32 بیتی |
| `float64` | عدد اعشاری 64 بیتی |
| `string` | رشته با طول متغیر |
| `bool` | بولی |
docs/fa/configuration.md
-94
View File
@@ -1,94 +0,0 @@
# مرجع پیکربندی
BaraDB از **متغیرهای محیطی**، **فایل پیکربندی** یا **پرچم‌های خط فرمان** پیکربندی می‌شود.
## اولویت
1. پرچم‌های خط فرمان (بالاترین)
2. متغیرهای محیطی
3. فایل پیکربندی (`baradb.conf` یا `baradb.json`)
4. مقادیر پیش‌فرض (پایین‌ترین)
## متغیرهای محیطی
### شبکه
| متغیر | پیش‌فرض | توضیح |
|--------|---------|--------|
| `BARADB_ADDRESS` | `127.0.0.1` | آدرس اتصال |
| `BARADB_PORT` | `9472` | پورت پروتکل باینری |
| `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` | اندازه کش صفحه (MB) |
### TLS/SSL
| متغیر | پیش‌فرض | توضیح |
|--------|---------|--------|
| `BARADB_TLS_ENABLED` | `false` | فعال‌سازی TLS |
| `BARADB_CERT_FILE` | — | مسیر گواهی TLS |
| `BARADB_KEY_FILE` | — | مسیر کلید TLS |
### امنیت
| متغیر | پیش‌فرض | توضیح |
|--------|---------|--------|
| `BARADB_AUTH_ENABLED` | `false` | فعال‌سازی احراز هویت |
| `BARADB_JWT_SECRET` | — | رمز امضای JWT |
## فایل پیکربندی
### baradb.conf
```ini
[server]
address = "0.0.0.0"
port = 9472
http_port = 9470
[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"
[auth]
enabled = true
jwt_secret = "change-me-in-production"
```
## پرچم‌های خط فرمان
```bash
./build/baradadb --help
```
## نمونه پیکربندی‌ها
### توسعه
```bash
./build/baradadb --log-level debug --data-dir ./dev_data
```
### تولید - گره واحد
```bash
BARADB_TLS_ENABLED=true \
BARADB_AUTH_ENABLED=true \
BARADB_JWT_SECRET="$(openssl rand -hex 32)" \
BARADB_MEMTABLE_SIZE_MB=256 \
BARADB_CACHE_SIZE_MB=1024 \
./build/baradadb
```
docs/fa/crossmodal.md
-40
View File
@@ -1,40 +0,0 @@
# پرس‌وجوهای بین‌حالتی
توانایی منحصربه‌فرد BaraDB برای اجرای کوئری‌هایی که چندین موتور ذخیره‌سازی را در یک عبارت BaraQL واحد پوشش می‌دهند.
## نمای کلی
- **سند/KV** (LSM-Tree) — رکوردهای ساختاریافته
- **گراف** (لیست مجاورت) — روابط
- **بردار** (HNSW/IVF-PQ) — جستجوی شباهت
- **تمام‌متن** (اندیس معکوس) — جستجوی متنی
- **ستونی** — تجمیع‌های تحلیلی
## پترن‌های کوئری
### بردار + تمام‌متن
```sql
SELECT title FROM articles
WHERE MATCH(body) AGAINST('machine learning')
ORDER BY cosine_distance(embedding, [...])
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;
```
## بهینه‌سازی
### برنامه‌ریز پرس‌وجو
1. فیلتر انتخابی‌ترین اول
2. پوش‌داون پریدایکت‌ها به هر موتور
3. فیلترهای Bloom برای جستجوهای KV
4. موازی‌سازی شاخه‌های مستقل
docs/fa/deployment.md
-249
View File
@@ -1,249 +0,0 @@
# راهنمای استقرار BaraDB
## Docker
برای راهنمای کامل استقرار Docker به [راهنمای Docker](docker.md) مراجعه کنید.
### شروع سریع
```bash
docker build -t baradb:latest .
docker compose up -d
```
### فایل‌های Docker Compose
| فایل | کاربرد |
|------|--------|
| `docker-compose.yml` | توسعه |
| `docker-compose.prod.yml` | تولید |
| `docker-compose.override.yml` | Override توسعه (خودکار) |
### تولید
```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
# Hardening امنیت
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";
}
}
```
## دسترس‌پذیری بالا
### خوشه 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 script
#!/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
```
docs/fa/distributed.md
-82
View File
@@ -1,82 +0,0 @@
# سیستم‌های توزیع‌شده
BaraDB از استقرار توزیع‌شده با اجماع 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.becomeCandidate()
n1.becomeLeader()
```
## شاردینگ
```nim
import barabadb/core/sharding
var router = newShardRouter(ShardConfig(
numShards: 4,
replicas: 2,
strategy: ssHash
))
```
### استراتژی‌های شاردینگ
| استراتژی | توضیح |
|-----------|--------|
| `ssHash` | شاردینگ مبتنی بر hash |
| `ssRange` | شاردینگ مبتنی بر بازه |
| `ssConsistent` | هش سازگار |
## تکثیر
```nim
import barabadb/core/replication
var rm = newReplicationManager(rmSync)
rm.addReplica(newReplica("r1", "10.0.0.1", 9472))
```
### حالت‌های تکثیر
| حالت | توضیح |
|------|--------|
| `rmSync` | تکثیر همگام |
| `rmAsync` | تکثیر ناهمگام |
| `rmSemiSync` | تکثیر نیمه‌همگام |
## پروتکل Gossip
```nim
import barabadb/core/gossip
var g = newGossipManager()
g.addNode("node1")
g.addNode("node2")
g.tick()
```
## تراکنش‌های توزیع‌شده
```nim
import barabadb/core/disttxn
var dt = newDistributedTxn()
dt.prepare(@["node1", "node2"])
dt.commit()
```
## تأیید رسمی
الگوریتم‌های اصلی توزیع‌شده در TLA+ مشخص و تأیید شده‌اند.
docs/fa/docker.md
-113
View File
@@ -1,113 +0,0 @@
# راهنمای استقرار Docker
## شروع سریع
```bash
git clone https://codeberg.org/baraba/baradb
cd barabaDB
docker build -t baradb:latest .
docker compose up -d
docker compose ps
docker compose logs -f
```
## فایل‌ها
| فایل | توضیح |
|------|--------|
| `Dockerfile` | ساخت multi-stage production |
| `docker-compose.yml` | پیکربندی توسعه |
| `docker-compose.prod.yml` | پیکربندی تولید |
| `docker-compose.override.yml` | Override توسعه |
| `docker-entrypoint.sh` | اسکریپت entrypoint |
| `.dockerignore` | فایل‌های مستثنی از کپی |
| `scripts/docker-build.sh` | اسکریپت کمکی ساخت |
| `scripts/docker-run.sh` | اسکریپت کمکی اجرا |
## ساخت تصویر
```bash
docker build -t baradb:latest .
./scripts/docker-build.sh
```
## اجرا
### توسعه
```bash
docker compose up -d
docker compose down
docker compose logs -f
```
### تولید
```bash
docker compose -f docker-compose.prod.yml up -d
```
### دستی
```bash
docker run -d \
--name baradb \
-p 9472:9472 \
-p 9470:9470 \
-p 9471:9471 \
-v baradb_data:/data \
baradb:latest
```
## پورت‌ها
| پورت | توضیح |
|------|--------|
| `9472` | پروتکل باینری |
| `9470` | HTTP/REST API |
| `9471` | WebSocket |
## متغیرهای محیطی
| متغیر | پیش‌فرض | توضیح |
|--------|---------|--------|
| `BARADB_ADDRESS` | `0.0.0.0` | آدرس اتصال |
| `BARADB_PORT` | `9472` | پورت پروتکل باینری |
| `BARADB_HTTP_PORT` | `9470` | پورت HTTP |
| `BARADB_DATA_DIR` | `/data` | پوشه داده |
## Volumeها
| مسیر | توضیح |
|------|--------|
| `/data` | پوشه اصلی داده |
| `/data/server/wal` | Write-ahead log |
| `/data/server/sstables` | فایل‌های SSTable |
## چک‌لیست تولید
- [ ] ایجاد گواهی‌های TLS
- [ ] تنظیم `BARADB_JWT_SECRET` قوی
- [ ] پیکربندی قوانین فایروال
- [ ] تنظیم پشتیبان‌گیری منظم
- [ ] بررسی محدودیت منابع
- [ ] تنظیم مانیتورینگ
## TLS در Docker
```bash
mkdir -p certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout certs/server.key -out certs/server.crt
```
## پشتیبان‌گیری
```bash
docker exec baradb /app/backup backup --data-dir=/data
docker exec baradb /app/backup list
docker exec baradb /app/backup restore --input=backup_xxx.tar.gz
```
docs/fa/fts.md
-47
View File
@@ -1,47 +0,0 @@
# موتور جستجوی تمام‌متن
اندیس معکوس با رتبه‌بندی BM25 و TF-IDF.
## استفاده
```nim
import barabadb/fts/engine
var idx = newInvertedIndex()
idx.addDocument(1, "Nim is a fast programming language")
idx.addDocument(2, "Python is popular for data science")
let results = idx.search("programming language")
let fuzzy = idx.fuzzySearch("programing", maxDistance = 2)
```
## روش‌های رتبه‌بندی
### BM25
```nim
let bm25 = idx.searchBM25("query terms")
```
### TF-IDF
```nim
let tfidf = idx.searchTfidf("query terms")
```
## ویژگی‌های جستجو
| ویژگی | توضیح |
|--------|--------|
| Fuzzy search | تساهل فاصله Levenshtein |
| Wildcard | پیشوند، پسوند، میانوند |
| Regex | الگوهای regular |
| Phrase search | تطبیق عبارت دقیق |
| Boolean | عملگرهای AND, OR, NOT |
## رابط SQL
```sql
CREATE INDEX idx_fts ON articles(body) USING FTS;
SELECT * FROM articles WHERE body @@ 'machine learning';
```
docs/fa/graph.md
-42
View File
@@ -1,42 +0,0 @@
# موتور گراف
ذخیره‌سازی لیست مجاورت با الگوریتم‌های داخلی برای پیمایش و تحلیل گراف.
## استفاده
```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` | پیمایش اول سطح |
| `dfs` | پیمایش اول عمق |
| `dijkstra` | کوتاه‌ترین مسیر وزن‌دار |
| `pageRank` | رتبه‌بندی اهمیت گره |
| `louvain` | تشخیص جامعه |
| `patternMatch` | ایزومورفیسم زیرگراف |
## Cypher
```nim
import barabadb/graph/cypher
var engine = newCypherEngine(g)
let results = engine.execute("""
MATCH (p:Person)-[:KNOWS]->(friend:Person)
WHERE p.name = 'Alice'
RETURN friend.name
""")
```
docs/fa/index.md
-59
View File
@@ -1,59 +0,0 @@
# مستندات BaraDB (فارسی)
**یک موتور پایگاه داده چند حالته به زبان Nim — کاملاً بومی، بدون وابستگی.**
## پیوندهای سریع
> **توجه:** مستندات فارسی در حال توسعه است. لطفاً برای اطلاعات کامل به [نسخه انگلیسی](../en/) مراجعه کنید.
### شروع کار
- [نصب](../en/installation.md)
- [شروع سریع](../en/quickstart.md)
- [بررسی معماری](../en/architecture.md)
- [پیکربندی](../en/configuration.md)
- [راهنمای استقرار](../en/deployment.md)
### مفاهیم اصلی
- [BaraQL — زبان پرس‌وجو](../en/baraql.md)
- [موتورهای ذخیره‌سازی](../en/storage.md)
- [سیستم طرحواره](../en/schema.md)
- [پرس‌وجوهای بین‌حالتی](../en/crossmodal.md)
### موتورها
- [LSM-Tree](../en/lsm.md)
- [اندیس B-Tree](../en/btree.md)
- [جستجوی برداری](../en/vector.md)
- [موتور گراف](../en/graph.md)
- [جستجوی تمام‌متن](../en/fts.md)
- [ذخیره‌سازی ستونی](../en/columnar.md)
### API و کلاینت‌ها
- [SDK های کلاینت](../en/clients.md)
- [پروتکل باینری](../en/api-binary.md)
- [HTTP/REST API](../en/api-http.md)
- [WebSocket API](../en/api-websocket.md)
- [مرجع پروتکل](../en/protocol.md)
### عملیات
- [عملکرد و معیارسنجی](../en/performance.md)
- [امنیت](../en/security.md)
- [نظارت](../en/monitoring.md)
- [پشتیبان‌گیری و بازیابی](../en/backup.md)
- [عیب‌یابی](../en/troubleshooting.md)
### مباحث پیشرفته
- [تراکنش‌ها و MVCC](../en/transactions.md)
- [سیستم‌های توزیع‌شده](../en/distributed.md)
- [توابع تعریف‌شده کاربر](../en/udf.md)
---
## اطلاعات پروژه
- [تاریخچه تغییرات](../en/changelog.md)
- [مجوز](../../LICENSE)
- [مخزن GitHub](https://github.com/katehonz/barabaDB)
---
*مستندات فارسی در دست تهیه است.*
docs/fa/installation.md
-309
View File
@@ -1,309 +0,0 @@
# راهنمای نصب BaraDB
## الزامات
- **کامپایلر Nim** >= 2.2.0
- **فایل‌های هدر OpenSSL** (برای پشتیبانی TLS)
- **سیستم‌عامل**: لینوکس، macOS، ویندوز
### پلتفرم‌های پشتیبانی‌شده
| سیستم‌عامل | معماری | وضعیت |
|------------|--------|--------|
| لینوکس | x86_64 | ✅ پشتیبانی کامل |
| لینوکس | ARM64 | ✅ پشتیبانی کامل |
| macOS | x86_64 | ✅ پشتیبانی کامل |
| macOS | ARM64 (Apple Silicon) | ✅ پشتیبانی کامل |
| ویندوز | x86_64 | ✅ پشتیبانی‌شده |
| FreeBSD | x86_64 | 🟡 تست‌شده توسط جامعه |
## نصب Nim
### لینوکس
```bash
# نصب‌کننده رسمی
curl https://nim-lang.org/choosenim/init.sh -sSf | sh
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install nim
# Fedora
sudo dnf install nim
# Arch Linux
sudo pacman -S nim
```
### macOS
```bash
# Homebrew
brew install nim
# MacPorts
sudo port install nim
```
### ویندوز
```powershell
# Using choosenim
curl.exe -A "MSYS2_$(uname -m)" -L https://nim-lang.org/choosenim/init.ps1 | powershell -
# Using winget
winget install nim
# Using scoop
scoop install nim
```
### تأیید نصب
```bash
nim --version
# انتظار: Nim Compiler Version 2.2.0 یا بالاتر
```
## نصب OpenSSL
### لینوکس
```bash
# Ubuntu/Debian
sudo apt-get install libssl-dev
# Fedora
sudo dnf install openssl-devel
# Arch Linux
sudo pacman -S openssl
```
### macOS
OpenSSL همراه سیستم است. در صورت نیاز:
```bash
brew install openssl
```
### ویندوز
OpenSSL همراه توزیع ویندوز Nim است. برای ساخت دستی،
از [slproweb.com](https://slproweb.com/products/Win32OpenSSL.html) دانلود کنید.
## ساخت BaraDB
### کلون کردن مخزن
```bash
git clone https://codeberg.org/baraba/baradb
cd barabaDB
```
### نصب وابستگی‌ها
```bash
nimble install -d -y
```
### گزینه‌های ساخت
#### ساخت دیباگ
```bash
nim c -d:ssl -o:build/baradadb src/baradadb.nim
```
#### ساخت ریلیز (توصیه‌شده)
```bash
nim c -d:ssl -d:release --opt:speed -o:build/baradadb src/baradadb.nim
```
#### استفاده از Nimble Tasks
```bash
# ساخت دیباگ
nimble build_debug
# ساخت ریلیز
nimble build_release
```
#### کاهش حجم باینری
```bash
nim c -d:ssl -d:release --opt:size -o:build/baradadb src/baradadb.nim
strip build/baradadb
```
### تأیید ساخت
```bash
./build/baradadb --version
# انتظار: BaraDB v1.1.6 — Multimodal Database Engine
```
## اجرای تست‌ها
### همه تست‌ها
```bash
nim c -d:ssl -r tests/test_all.nim
```
### مجموعه‌های تست خاص
```bash
# تست‌های ذخیره‌سازی
nim c -d:ssl -r tests/test_storage.nim
# تست‌های موتور پرس‌وجو
nim c -d:ssl -r tests/test_query.nim
# تست‌های پروتکل
nim c -d:ssl -r tests/test_protocol.nim
```
### بنچمارک‌ها
```bash
nim c -d:ssl -d:release -r benchmarks/bench_all.nim
```
## گزینه‌های نصب
### نصب سیستمی
```bash
# ساخت باینری ریلیز
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
```
### باینری از پیش ساخته‌شده
آخرین ریلیز را برای پلتفرم خود دانلود کنید:
```bash
# لینوکس 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
# لینوکس 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 \
-p 9471:9471 \
-v baradb_data:/data \
barabadb/barabadb
```
### Docker Compose
```bash
docker-compose up -d
```
### استفاده توکار (پروژه‌های Nim)
به فایل `.nimble` خود اضافه کنید:
```nim
requires "barabadb >= 0.1.0"
```
در کد خود استفاده کنید:
```nim
import barabadb/storage/lsm
var db = newLSMTree("./data")
db.put("key", cast[seq[byte]]("value"))
let (found, val) = db.get("key")
db.close()
```
## اجرای اولیه
```bash
# شروع سرور
./build/baradadb
# خروجی مورد انتظار:
# BaraDB v1.1.6 — 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 -o:build/baradadb src/baradadb.nim
```
### کامپایل کند
از کامپایل موازی استفاده کنید:
```bash
nim c -d:ssl -d:release --parallelBuild:4 -o:build/baradadb src/baradadb.nim
```
### حجم باینری زیاد
از بهینه‌سازی اندازه استفاده کنید:
```bash
nim c -d:ssl -d:release --opt:size --passL:-s -o:build/baradadb src/baradadb.nim
```
## مراحل بعدی
- [راهنمای شروع سریع](quickstart.md)
- [مرجع پیکربندی](configuration.md)
- [بررسی معماری](architecture.md)
- [زبان پرس‌وجو BaraQL](baraql.md)
docs/fa/lsm.md
-48
View File
@@ -1,48 +0,0 @@
# موتور ذخیره‌سازی LSM-Tree
موتور ذخیره‌سازی اصلی BaraDB با معماری Log-Structured Merge-Tree.
## معماری
```
┌─────────────────────────────────────────────┐
│ Writes │
│ (append to WAL + MemTable) │
└─────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ MemTable │
│ (in-memory sorted buffer) │
└─────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ SSTable │
│ (sorted string table on disk) │
└─────────────────────────────────────────────┘
```
## استفاده
```nim
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()
```
## ویژگی‌ها
- **بهینه برای نوشتن**: ساختار log-only اضافه‌شونده
- **دوام**: WAL تضمین‌کننده بازیابی پس از خرابی
- **Bloom Filter**: جستجوهای منفی سریع
- **Compaction**: استراتژی size-tiered
- **Page Cache**: کش LRU
docs/fa/mcp.md
-109
View File
@@ -1,109 +0,0 @@
# سرور MCP (Model Context Protocol)
BaraDB شامل یک سرور MCP داخلی است که به عوامل هوش مصنوعی (Claude، Cursor و غیره) امکان تعامل مستقیم با پایگاه داده را می‌دهد.
## شروع سریع
```bash
./build/baramcp --data-dir ./data
```
در حالت STDIO شروع می‌شود و پیام‌های JSON-RPC 2.0 را در stdin قبول می‌کند.
## ابزارهای موجود
### 1. `query` — اجرای SQL
```json
{
"name": "query",
"arguments": {
"sql": "SELECT * FROM users WHERE age > ?",
"params": [25],
"tenant_id": "company-a",
"user_id": "alice"
}
}
```
پرس‌وجوهای پارامتری با `?` placeholders. پشتیبانی multi-tenant از طریق `tenant_id` و `user_id`.
### 2. `vector_search` — جستجوی معنایی
```json
{
"name": "vector_search",
"arguments": {
"table": "docs",
"column": "embedding",
"query_vector": [0.1, 0.2, 0.3],
"k": 5,
"metric": "cosine",
"filter_column": "category",
"filter_value": "news",
"tenant_id": "company-a"
}
}
```
معیارها: `cosine`، `euclidean`، `dot_product`، `manhattan`.
### 3. `schema_inspect` — بررسی طرحواره
```json
{
"name": "schema_inspect",
"arguments": {
"table": "users",
"tenant_id": "company-a"
}
}
```
جداول، ستون‌ها، انواع، کلیدهای اصلی، کلیدهای خارجی، شاخص‌ها و سیاست‌های RLS را برمی‌گرداند.
## پیکربندی Claude Desktop
```json
{
"mcpServers": {
"baradb": {
"command": "/path/to/build/baramcp",
"args": ["--data-dir", "/path/to/data"]
}
}
}
```
## پیکربندی Cursor
```json
{
"mcpServers": {
"baradb": {
"command": "/path/to/build/baramcp",
"args": ["--data-dir", "~/.baradb/data"]
}
}
}
```
## جداسازی Multi-Tenant
هر درخواست MCP می‌تواند شامل `tenant_id` و `user_id` باشد که به عنوان متغیرهای session تنظیم می‌شوند:
- `app.tenant_id` — برای فیلتر RLS
- `app.user_id` — برای referencهای `current_user`
سیاست‌های RLS به طور خودکار داده‌ها را بر اساس این متغیرها فیلتر می‌کنند.
## پروتکل JSON-RPC 2.0
سرور از JSON-RPC 2.0 از طریق STDIO استفاده می‌کند:
```json
// درخواست
{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {...}}
// پاسخ
{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "..."}]}}
```
docs/fa/monitoring.md
-78
View File
@@ -1,78 +0,0 @@
# پایش و مشاهده‌پذیری
## بررسی‌های سلامت
### endpoint سلامت HTTP
```bash
curl http://localhost:9470/health
```
پاسخ:
```json
{
"status": "healthy",
"version": "0.1.0",
"uptime_seconds": 86400,
"checks": {
"storage": "ok",
"memory": "ok",
"connections": "ok"
}
}
```
## معیارها
### معیارهای سازگار با Prometheus
```bash
curl http://localhost:9470/metrics
```
### معیارهای 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
```
## Grafana
پنل‌های کلیدی:
- Queries per second
- Latency درصدها (p50, p95, p99)
- اندازه ذخیره‌سازی
- نرخ hit کش
- اتصالات فعال
- نرخ تراکنش
- نرخ خطا
## عیب‌یابی با معیارها
| علامت | معیار | عمل |
|-------|-------|-----|
| کوئری‌های کند | `baradb_queries_duration_seconds` | بررسی نرخ hit کش |
| حافظه بالا | `process_resident_memory_bytes` | کاهش اندازه‌های memtable/cache |
| رشد ذخیره‌سازی | `baradb_storage_lsm_size_bytes` | اجرای فشرده‌سازی دستی |
| خطاهای اتصال | `baradb_active_connections` | افزایش استخر اتصال |
docs/fa/performance.md
-62
View File
@@ -1,62 +0,0 @@
# راهنمای عملکرد
## روش‌شناسی بنچمارک
همه بنچمارک‌ها با Nim 2.2.0 و `-d:release --opt:speed` اجرا می‌شوند.
## بنچمارک‌های ذخیره‌سازی
### LSM-Tree
| متریک | مقدار |
|--------|-------|
| توان عملیاتی نوشتن | ~580,000 ops/s |
| توان عملیاتی خواندن | ~720,000 ops/s |
### B-Tree
| متریک | مقدار |
|--------|-------|
| توان عملیاتی درج | ~1,200,000 ops/s |
| جستجوی نقطه‌ای | ~1,500,000 ops/s |
## بنچمارک‌های موتور برداری
### HNSW
| متریک | مقدار |
|--------|-------|
| درج (dim=128) | ~45,000 vectors/s |
| جستجوی top-10 (n=100K) | ~8 ms |
## بنچمارک‌های پروتکل
| پروتکل | اتصال | کوئری/ثانیه |
|--------|-------|--------------|
| Binary | 1 | 45,000 |
| Binary | 100 | 380,000 |
| HTTP/REST | 1 | 12,000 |
## راهنمای تنظیم
### برای بار کاری سنگین نوشتن
```bash
BARADB_MEMTABLE_SIZE_MB=256
BARADB_WAL_SYNC_INTERVAL_MS=10
```
### برای بار کاری سنگین خواندن
```bash
BARADB_CACHE_SIZE_MB=1024
BARADB_BLOOM_BITS_PER_KEY=10
```
### برای جستجوی برداری
```bash
BARADB_VECTOR_EF_CONSTRUCTION=200
BARADB_VECTOR_EF_SEARCH=128
BARADB_VECTOR_M=32
```
docs/fa/protocol.md
-67
View File
@@ -1,67 +0,0 @@
# مرجع پروتکل
BaraDB چندین پروتکل پشتیبانی می‌کند:
- **Binary Wire Protocol** — با کارایی بالا
- **HTTP/REST API** — مستقل از زبان
- **WebSocket** — استریمینگ و pub/sub
## Binary Wire Protocol
از کدگذاری big-endian استفاده می‌کند.
### چرخه اتصال
```
Client Server
| |
|─── TCP connect ──────────────>|
|─── Auth message ─────────────>|
|<── Auth_OK / Error ───────────|
|─── Query message ────────────>|
|<── Data / Complete / Error ───|
```
### فرمت پیام
```
┌─────────────┬─────────────┬─────────────┬─────────────────────┐
│ Length │ Type │ Sequence │ Payload │
│ (4 bytes) │ (1 byte) │ (1 byte) │ (Length - 6 bytes) │
└─────────────┴─────────────┴─────────────┴─────────────────────┘
```
### انواع پیام
| نوع | ID | توضیح |
|----|----|--------|
| Query | 0x01 | اجرای کوئری |
| Insert | 0x02 | درج داده |
| Update | 0x03 | به‌روزرسانی |
| Delete | 0x04 | حذف |
| Ready | 0x05 | آماده |
| Error | 0x06 | پاسخ خطا |
## HTTP/REST API
Base URL: `http://localhost:9470/api/v1`
### Endpoints
#### Health
```http
GET /health
```
#### Query
```http
POST /query
{
"query": "SELECT * FROM users"
}
```
## WebSocket Protocol
URL: `ws://localhost:9471`
docs/fa/quickstart.md
-134
View File
@@ -1,134 +0,0 @@
# راهنمای شروع سریع BaraDB
## شروع سرور
پس از ساخت BaraDB، سرور را_START کنید:
```bash
./build/baradadb
```
سرور به‌صورت پیش‌فرض روی `localhost:9470` شروع می‌شود.
## اتصال از طریق 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;
```
### CTEها
```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;
```
## عملیات گراف
```sql
-- تطبیق الگوی گراف
MATCH (p:Person)-[:KNOWS]->(other:Person)
WHERE p.name = 'Alice'
RETURN other.name;
```
## جستجوی تمام‌متن
```sql
-- جستجوی اسناد
SELECT * FROM articles WHERE MATCH(title, body) AGAINST('database');
```
## HTTP/REST API
```bash
# درخواست GET
curl http://localhost:9470/api/users
# درخواست POST
curl -X POST http://localhost:9470/api/users \
-H "Content-Type: application/json" \
-d '{"name": "Alice", "age": 30}'
```
## مراحل بعدی
- [مرجع BaraQL](baraql.md)
- [موتورهای ذخیره‌سازی](storage.md)
- [بررسی معماری](architecture.md)
- [مرجع پروتکل](protocol.md)
docs/fa/schema.md
-46
View File
@@ -1,46 +0,0 @@
# سیستم طرحواره
BaraDB از طراحی schema-first با وراثت نوع و مهاجرت‌های خودکار استفاده می‌کند.
## تعریف انواع
```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)
```
## عملیات طرحواره
### Diff
```nim
let diff = s.diff(oldSchema, newSchema)
```
## انواع ویژگی
| نوع | توضیح |
|-----|--------|
| `str` | رشته |
| `int32` | عدد صحیح 32 بیتی |
| `int64` | عدد صحیح 64 بیتی |
| `float32` | عدد اعشاری 32 بیتی |
| `float64` | عدد اعشاری 64 بیتی |
| `bool` | بولی |
| `datetime` | تاریخ/زمان |
| `bytes` | داده باینری |
docs/fa/security.md
-120
View File
@@ -1,120 +0,0 @@
# راهنمای امنیت
## رمزنگاری TLS/SSL
BaraDB از TLS 1.3 برای تمام پروتکل‌ها (باینری، HTTP، WebSocket) پشتیبانی می‌کند. اگر گواهی ارائه نشود، سرور در هنگام راه‌اندازی یک گواهی خودامضا تولید می‌کند.
### استفاده از گواهی‌های سفارشی
```bash
BARADB_TLS_ENABLED=true \
BARADB_CERT_FILE=/etc/baradb/server.crt \
BARADB_KEY_FILE=/etc/baradb/server.key \
./build/baradadb
```
### تولید گواهی‌های خودامضا
```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
```
## احراز هویت
### احراز هویت مبتنی بر JWT
BaraDB از JWT با امضای 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` | فقط معیارها و سلامت |
### احراز هویت چندعاملی (MFA)
```nim
import barabadb/protocol/auth
var am = newAuthManager("secret-key")
let mfaCode = am.generateTOTP("user1")
let valid = am.validateTOTP("user1", mfaCode)
```
## محدودیت نرخ
محدودیت نرخ token-bucket از سوءاستفاده جلوگیری می‌کند:
```nim
import barabadb/protocol/ratelimit
var rl = newRateLimiter(
rlaTokenBucket,
globalRate = 10000,
perClientRate = 1000,
burstSize = 100
)
if not rl.allowRequest("client-ip"):
return error("محدودیت نرخ تجاوز شده")
```
## امنیت شبکه
### آدرس اتصال
به‌صورت پیش‌فرض BaraDB به `127.0.0.1` متصل می‌شود. برای تولید:
```bash
BARADB_ADDRESS=0.0.0.0 ./build/baradadb
```
## چک‌لیست امنیتی
- [ ] تغییر رمز JWT پیش‌فرض
- [ ] فعال‌سازی TLS با گواهی‌های معتبر
- [ ] اتصال به رابط‌های خاص
- [ ] فعال‌سازی احراز هویت در تولید
- [ ] پیکربندی محدودیت نرخ
- [ ] فعال‌سازی لاگ حسابرسی
- [ ] رمزنگاری داده در حالت سکون
- [ ] اجرای BaraDB به‌عنوان کاربر غیرroot
- [ ] محدود نگه‌داشتن قوانین فایروال
- [ ] چرخش منظم رمزهای JWT
docs/fa/storage.md
-78
View File
@@ -1,78 +0,0 @@
# موتورهای ذخیره‌سازی
BaraDB چندین موتور ذخیره‌سازی بهینه‌شده برای الگوهای دسترسی مختلف فراهم می‌کند.
## LSM-Tree (کلید-مقدار)
موتور ذخیره‌سازی اصلی با ساختار log-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**: log جلوگیری از نوشتن برای دوام
- **SSTable**: جداول رشته‌ای مرتب روی دیسک
- **Bloom Filter**: ساختار احتمالی برای جستجوهای منفی سریع
- **Compaction**: استراتژی size-tiered با مدیریت سطح
- **Page Cache**: کش LRU با ردیابی نرخ hit
## اندیس 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")
```
## 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 "احتمالاً وجود دارد"
```
## I/O نگاشته‌شده به حافظه
دسترسی کارآمد به فایل با استفاده از mmap.
```nim
import barabadb/storage/mmap
var mapped = mmapFile("./data/file.dat")
let data = mapped.read(0, 100)
```
docs/fa/transactions.md
-67
View File
@@ -1,67 +0,0 @@
# تراکنش‌ها و MVCC
MVCC (کنترل همزمانی چندنسخه‌ای) با جداسازی 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"))
# Savepoint
tm.savepoint(txn)
discard tm.write(txn, "key3", cast[seq[byte]]("value3"))
discard tm.rollbackToSavepoint(txn)
# Commit
discard tm.commit(txn)
```
## جداسازی تراکنش
BaraDB از **جداسازی snapshot** استفاده می‌کند:
- خوانندگان نویسندگان را مسدود نمی‌کنند
- نویسندگان خوانندگان را مسدود نمی‌کنند
- هر تراکنش یک snapshot سازگار می‌بیند
## تشخیص بن‌بست
```nim
import barabadb/core/deadlock
var detector = newDeadlockDetector()
if detector.detectCycle(txn1, txn2):
echo "بن‌بست تشخیص داده شد!"
```
## WAL
```nim
import barabadb/storage/wal
var wal = newWAL("./wal")
wal.append(txnId, "SET key value")
wal.flush()
```
## Savepoints
```nim
tm.savepoint(txn, "sp1")
tm.rollbackToSavepoint(txn, "sp1")
```
## تأیید رسمی
پروتکل MVCC در TLA+ مشخص شده:
```bash
cd formal-verification
java -cp tla2tools.jar tlc2.TLC -config models/mvcc.cfg mvcc.tla
```
docs/fa/troubleshooting.md
-87
View File
@@ -1,87 +0,0 @@
# عیب‌یابی
## مشکلات نصب
### Nim یافت نشد
```bash
curl https://nim-lang.org/choosenim/init.sh -sSf | sh
```
### خطای کامپایل SSL
```bash
nim c -d:ssl -d:release -o:build/baradadb src/baradadb.nim
```
### وابستگی‌های گم‌شده
```bash
nimble install -d -y
```
## مشکلات زمان اجرا
### پورت در حال استفاده
```bash
BARADB_PORT=5433 ./build/baradadb
```
### Permission denied
```bash
mkdir -p ./data
chmod 755 ./data
```
### کمبود حافظه
```bash
BARADB_MEMTABLE_SIZE_MB=32 \
BARADB_CACHE_SIZE_MB=128 \
./build/baradadb
```
## مشکلات کوئری
### خطای نحوی
```sql
SELECT name, age FROM users WHERE age > 18;
```
### جدول یافت نشد
```sql
CREATE TYPE User { name: str, age: int32 };
```
### عدم تطابق نوع
```sql
SELECT * FROM users WHERE age > 18;
```
## مشکلات اتصال
### Connection refused
```bash
./build/baradadb
sudo ufw allow 9472
```
## مشکلات عملکرد
### کوئری‌های کند
1. ایجاد اندیس: `CREATE INDEX idx_users_name ON users(name);`
2. استفاده از LIMIT
3. افزایش کش: `BARADB_CACHE_SIZE_MB=1024`
## حالت اشکال‌زدایی
```bash
BARADB_LOG_LEVEL=debug ./build/baradadb
```
docs/fa/udf.md
-46
View File
@@ -1,46 +0,0 @@
# توابع تعریف‌شده کاربر
گسترش BaraQL با توابع سفارشی.
## استفاده
```nim
import barabadb/query/udf
var reg = newUDFRegistry()
reg.registerStdlib()
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 |
## ثبت تابع
```nim
reg.register(
name: "my_function",
params: @[UDFParam(name: "arg1", typeName: "str")],
returnType: "str",
body: proc(args: seq[Value]): Value =
result = Value(kind: vkString, strVal: "")
)
```
## استفاده در کوئری
```sql
SELECT greet(name) FROM users;
```
docs/fa/vector.md
-57
View File
@@ -1,57 +0,0 @@
# موتور جستجوی برداری
اندیس‌های 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
گراف Navigable Small World سلسله‌مراتبی.
```nim
var hnsw = newHNSWIndex(
dimensions = 128,
m = 16,
efConstruction = 200,
efSearch = 100
)
```
### IVF-PQ
اندیس فایل معکوس با تکمیم محصول.
```nim
var ivfpq = newIVFPQIndex(
dimensions = 128,
numCentroids = 256,
subQuantizers = 8
)
```
## معیارهای فاصله
| معیار | توضیح |
|-------|--------|
| `cosine` | شباهت کسینوسی |
| `euclidean` | فاصله L2 |
| `dotproduct` | ضرب نقطه‌ای |
| `manhattan` | فاصله L1 |
## کوانتیزاسیون
```nim
let scalar = scalarQuantize(data, bits = 8)
let pq = productQuantize(data, subVectors = 8, bits = 8)
```
docs/index.md
+1 -7
View File
@@ -5,13 +5,7 @@
## Documentation Languages
- [English](en/)
- [العربية (Arabic)](ar/)
- [Български (Bulgarian)](bg/)
- [Deutsch (German)](de/)
- [فارسی (Farsi)](fa/)
- [Русский (Russian)](ru/)
- [Türkçe (Turkish)](tr/)
- [中文 (Chinese)](zh/)
---
@@ -67,4 +61,4 @@
---
*To add a new language, create a new folder in `docs/` with the language code (e.g., `docs/de/`) and add a link above.*
*To add a new language, create a new folder in `docs/` with the language code and add a link above.*

Some files were not shown because too many files have changed in this diff Show More