Compendium chapter 42 docs assistant usage

Navigation: Home > Pages

Kapitel 42: Dokumentations-Assistent – Verwendung für Admin, Superuser und User

"KI-gestützte Hilfe: Der integrierte LLM-Dokumentations-Assistent beantwortet Konfigurations- und Troubleshooting-Fragen in Echtzeit."

Überblick

Der ThemisDB Dokumentations-Assistent nutzt llama.cpp und eine vorkompilierte RocksDB-Datenbank mit 1.151 Dokumenten, um Administratoren, Superusern und normalen Benutzern kontextbewusste Hilfe zu bieten. Alle Dokumentationen aus ./docs und ./compendium sind über mehrere Datenmodelle indexiert.

Automatische Konfiguration: Der Dokumentations-Assistent findet die Dokumentationsdatenbank automatisch beim Start. Keine manuelle Konfiguration erforderlich!

Suchpfade (Auto-Discovery):

data/docs.db (RocksDB - empfohlen)
data/docs_database.json (JSON - Fallback)
./docs.db (aktuelles Verzeichnis)
./docs_database.json
../data/docs.db (parent directory)

Manuelle Konfiguration (optional):

# config/docs_assistant.yaml
docs_assistant:
  enabled: true
  database:
    path: "data/docs.db"  # Expliziter Pfad
    type: "rocksdb"        # json oder rocksdb
    auto_discover: false   # Deaktiviert Auto-Discovery

Zielgruppen:

Administratoren: Vollzugriff auf Konfiguration, Troubleshooting und Systemoptimierung
Superuser: Erweiterte Abfragen, Performance-Tuning, erweiterte Features
User: Grundlegende Queries, Dokumentationssuche, Anwendungshilfe

Zugriffsmethoden:

REST API (HTTP/1.1)
AQL-Funktionen (nativ)
ThemisDB CLI
C++ SDK

graph TB
    subgraph "Benutzertypen"
        Admin[👤 Administrator<br/>Vollzugriff]
        Super[👤 Superuser<br/>Erweitert]
        User[👤 User<br/>Basis]
    end
    
    subgraph "Dokumentations-Datenbank"
        DB[(RocksDB<br/>7 Column Families<br/>1151 Dokumente)]
    end
    
    subgraph "Zugriffsmethoden"
        REST["REST API<br/>/api/v1/llm/docs/*"]
        AQL["AQL Funktionen<br/>DOCS_QUERY()"]
        CLI["ThemisDB CLI<br/>docs-query"]
        SDK["C++ SDK<br/>DocsAssistant"]
    end
    
    subgraph "LLM Engine"
        LLM[llama.cpp<br/>RAG-basiert]
    end
    
    Admin --> REST
    Admin --> AQL
    Admin --> CLI
    Admin --> SDK
    
    Super --> REST
    Super --> AQL
    Super --> CLI
    
    User --> REST
    User --> CLI
    
    REST --> LLM
    AQL --> LLM
    CLI --> LLM
    SDK --> LLM
    
    LLM --> DB
    
    style Admin fill:#ff6b6b
    style Super fill:#ffd93d
    style User fill:#6bcf7f
    style DB fill:#4d96ff
    style LLM fill:#a78bfa

Abb. 42.0: Dokumentations-Assistent Architektur nach Benutzerrolle

42.1 Für Administratoren: Vollständige Systemkontrolle

42.1.0 Konfiguration und Auto-Discovery

Automatische Konfiguration (empfohlen für Entwicklung):

Der Dokumentations-Assistent kann die Datenbank automatisch beim Server-Start finden, aber für Produktionsumgebungen wird die explizite YAML-Konfiguration empfohlen.

# Generiere Datenbank
python3 scripts/generate_docs_rocksdb.py --output data/docs.db

# Entwicklung: Auto-Discovery (nur wenn keine YAML-Config vorhanden)
./themis_server

# Produktion: Explizite YAML-Konfiguration (empfohlen!)
# Siehe config/docs_assistant.yaml

Manuelle Konfiguration via YAML (empfohlen für Produktion):

Die YAML-Konfiguration ist der bevorzugte Weg für Produktionsumgebungen und bietet bessere Kontrolle:

# config/docs_assistant.yaml
docs_assistant:
  enabled: true
  
  database:
    path: "/var/lib/themisdb/docs.db"  # Expliziter Pfad (empfohlen!)
    type: "rocksdb"                     # json oder rocksdb
    auto_discover: false                # Deaktiviert Auto-Discovery (sicherer)
  
  llm:
    max_context_docs: 10                # Admin braucht mehr Kontext
    enable_caching: true
    cache_ttl_seconds: 300
  
  access:
    enable_rbac: true
    default_role: "user"

# Server-Log:
# [INFO] Documentation Assistant: Loading database from config: /var/lib/themisdb/docs.db
# [INFO] Documentation Assistant: Loaded 1151 documents from 7 column families

Wichtige Sicherheitshinweise:

⚠️ Security Considerations:

Explizite Konfiguration bevorzugen: Auto-Discovery ist praktisch für Entwicklung, aber in Produktion sollte immer ein expliziter Pfad gesetzt werden
Zugriffskontrolle: Stellen Sie sicher, dass nur autorisierte Benutzer auf docs.db zugreifen können
Zukünftige Datenbanken: Admins können später nutzungsspezifische Datenbanken hinzufügen - siehe TODO für Security-Folgenabschätzung
Dateisystemberechtigungen: chmod 600 /var/lib/themisdb/docs.db (nur Owner-Zugriff)

📋 TODO: Security-Folgenabschätzung

Bewertung der Risiken bei mehreren benutzerdefinierten Dokumentationsdatenbanken
Validierung der Datenbank-Inhalte beim Laden
Sandbox-Mechanismus für Drittanbieter-Datenbanken
Audit-Trail für Datenbankzugriffe
Rate-Limiting pro Datenbank

Umgebungsvariablen (höchste Priorität):

# Überschreibt YAML-Konfiguration
export THEMIS_DOCS_DATABASE_PATH="/custom/path/docs.db"
export THEMIS_DOCS_DATABASE_TYPE="rocksdb"
export THEMIS_DOCS_AUTO_DISCOVER="false"  # Explizit deaktivieren

./themis_server

Konfigurationspriorität:

Umgebungsvariablen (höchste)
YAML-Konfiguration (empfohlen für Produktion) ⭐
Auto-Discovery (nur für Entwicklung)
Fallback: data/docs_database.json

Verifizierung:

# Prüfe welche Datenbank geladen wurde
curl -X GET http://localhost:8765/api/v1/llm/health \
  -H "Authorization: Bearer ${ADMIN_TOKEN}"

# Antwort:
{
  "status": "healthy",
  "docs_assistant": {
    "enabled": true,
    "database_path": "/var/lib/themisdb/docs.db",
    "database_type": "rocksdb",
    "documents_loaded": 1151,
    "column_families": 7,
    "discovery_method": "yaml_config"  # yaml_config, env, auto, fallback
  }
}

Best Practice: YAML-Konfiguration in Produktion

# config/docs_assistant.yaml - Produktionskonfiguration
docs_assistant:
  enabled: true
  
  # Primäre Dokumentationsdatenbank (System)
  database:
    path: "/var/lib/themisdb/docs.db"
    type: "rocksdb"
    auto_discover: false  # Sicherheit: Explizit deaktiviert
    read_only: true       # Verhindert Änderungen an der Datenbank
  
  # TODO: Zukünftige Feature - Zusätzliche Datenbanken
  # additional_databases:
  #   - name: "custom_docs"
  #     path: "/var/lib/themisdb/custom_docs.db"
  #     enabled: true
  #     requires_role: "administrator"  # Nur für Admins
  #     security_validated: true        # Muss validiert sein
  
  access:
    enable_rbac: true
    require_auth: true
    
  monitoring:
    enable_audit_log: true
    audit_log_path: "/var/log/themisdb/docs_assistant_audit.log"

42.1.1 Anwendungsfälle für Administratoren

Administratoren benötigen Hilfe bei:

Systemkonfiguration: Sharding, Replikation, Performance-Tuning
Troubleshooting: Fehlerdiagnose, Log-Analyse, Deadlock-Behebung
Sicherheit: RBAC-Setup, Verschlüsselung, HSM-Integration
Deployment: Docker, Kubernetes, Produktionsumgebung
Monitoring: Metrics, Alerts, Observability

42.1.2 REST API Zugriff (Admin)

Allgemeine Dokumentationsabfrage

# Admin fragt nach RAID-Sharding-Konfiguration
curl -X POST https://themisdb.example.com:8765/api/v1/llm/docs/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -d '{
    "query": "Wie konfiguriere ich RAID 6 Sharding mit 9 Shards und Replikationsfaktor 6?"
  }'

# Antwort:
{
  "query": "Wie konfiguriere ich RAID 6 Sharding...",
  "answer": "Um RAID 6 Sharding zu konfigurieren:\n\n1. Setzen Sie Umgebungsvariablen:\n   - THEMIS_ENABLE_SHARDING=true\n   - THEMIS_SHARD_COUNT=9\n   - THEMIS_SHARD_REPLICATION_FACTOR=6\n\n2. Konfigurieren Sie config/shards.yaml:\n   shards:\n     - id: 1\n       endpoint: themis-shard-1:8765\n       weight: 1.0\n     - id: 2\n       endpoint: themis-shard-2:8765\n       weight: 1.0\n   [...]\n\n3. Starten Sie den Coordinator:\n   ./themis_server --mode coordinator --config config/shards.yaml\n\nWichtig: RAID 6 benötigt mindestens 4 Shards. Mit 9 Shards und RF=6 haben Sie optimale Fehlertoleranz.\n\nReferenz: docs/en/features/RAID_SHARDING.md",
  "confidence_score": 0.94,
  "documents_searched": 1151,
  "documents_used": 5,
  "search_time_ms": 12,
  "generation_time_ms": 1840,
  "relevant_documents": [
    {
      "file_name": "RAID_SHARDING.md",
      "relevance_score": 0.96,
      "content_preview": "# RAID Sharding in ThemisDB\n\nRAID-style sharding provides data redundancy..."
    }
  ]
}

Konfigurationshilfe

# Admin benötigt Hilfe zur Sicherheits-Konfiguration
curl -X POST https://themisdb.example.com:8765/api/v1/llm/docs/config \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -d '{
    "topic": "security"
  }'

# Antwort:
{
  "topic": "security",
  "configuration_help": "ThemisDB Sicherheits-Konfiguration:\n\n**Basis-Sicherheit:**\n- THEMIS_ENABLE_TLS=true\n- THEMIS_TLS_CERT_PATH=/path/to/cert.pem\n- THEMIS_TLS_KEY_PATH=/path/to/key.pem\n\n**RBAC (Role-Based Access Control):**\n- THEMIS_ENABLE_RBAC=true\n- THEMIS_RBAC_CONFIG=/path/to/rbac.yaml\n\n**Verschlüsselung:**\n- THEMIS_ENABLE_ENCRYPTION_AT_REST=true\n- THEMIS_ENCRYPTION_KEY_PATH=/path/to/master.key\n\n**HSM-Integration (Optional):**\n- THEMIS_ENABLE_HSM_REAL=ON (CMake)\n- THEMIS_HSM_PROVIDER=pkcs11\n- THEMIS_HSM_LIB_PATH=/usr/lib/softhsm/libsofthsm2.so\n\n**Best Practices:**\n1. Verwenden Sie starke TLS-Zertifikate (mind. 2048-bit RSA)\n2. Rotieren Sie Encryption Keys regelmäßig\n3. Aktivieren Sie Audit-Logging\n4. Implementieren Sie Network Policies (Firewall)\n\nReferenzen:\n- docs/en/features/SECURITY.md\n- docs/en/configuration/RBAC_SETUP.md",
  "confidence_score": 0.91,
  "documents_used": 7
}

Troubleshooting-Hilfe

# Admin diagnostiziert einen Deadlock
curl -X POST https://themisdb.example.com:8765/api/v1/llm/docs/troubleshoot \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -d '{
    "error": "Server hängt beim Start bei \"Adaptive Index Manager initialized\". RAID Sharding ist aktiviert."
  }'

# Antwort:
{
  "error": "Server hängt beim Start...",
  "troubleshooting_help": "**Diagnose: RAID Sharding Deadlock (bekannter Bug in v1.3.3)**\n\nUrsache: AdaptiveIndexManager versucht, Column Families zu öffnen, bevor ShardingManager initialisiert ist.\n\n**Lösung:**\n\n1. **Sofort-Fix:** Update auf v1.3.4+\n   ```bash\n   git pull origin main\n   cmake --build build --target themis_server\n   ```\n\n2. **Workaround für v1.3.3:**\n   - Deaktivieren Sie temporär Sharding\n   - Starten Sie Server neu\n   - Aktivieren Sie Sharding wieder\n\n3. **Prüfen Sie docker-compose.yml:**\n   Stellen Sie sicher, dass Port-Mappings korrekt sind:\n   ```yaml\n   ports:\n     - \"8081:8765\"  # NICHT 8081:8080\n   ```\n\n4. **Überprüfen Sie Logs:**\n   ```bash\n   tail -f logs/themis_server.log | grep -i \"shard\\|deadlock\"\n   ```\n\n**Weitere Informationen:**\n- docs/RAID_SHARDING_DEADLOCK_HOTFIX.md\n- GitHub Issue #234",
  "confidence_score": 0.97,
  "documents_used": 3
}

42.1.3 AQL-Funktionen (Admin)

-- Admin sucht nach Performance-Tuning-Dokumentation
RETURN DOCS_SEARCH('performance tuning query optimization', 10)

-- Kombinierte Abfrage: Suche + Antwort
LET docs = DOCS_SEARCH('replication setup', 5)
LET answer = DOCS_QUERY('How do I set up multi-master replication?')
RETURN {
    answer: answer,
    sources: docs,
    query_time: DATE_NOW()
}

-- Batch-Abfragen für mehrere Themen
FOR topic IN ['sharding', 'replication', 'security', 'monitoring']
    RETURN {
        topic: topic,
        help: DOCS_CONFIG_HELP(topic)
    }

-- Troubleshooting aus :document Collection
FOR doc IN :document
    FILTER doc.type == 'documentation'
    FILTER CONTAINS(doc.title, 'TROUBLESHOOT') OR CONTAINS(doc.title, 'ERROR')
    RETURN {
        title: doc.title,
        source: doc.source,
        preview: SUBSTRING(doc.content, 0, 300)
    }
    LIMIT 20

42.1.4 CLI-Zugriff (Admin)

# Admin verwendet ThemisDB CLI
themis_cli --database themisdb.db --execute "RETURN DOCS_QUERY('How to enable GPU acceleration?')"

# Output:
# ============================================================
# ThemisDB Documentation Assistant
# ============================================================
# Query: How to enable GPU acceleration?
# 
# Answer:
# To enable GPU acceleration in ThemisDB:
# 
# 1. CMake Configuration:
#    cmake -B build -DTHEMIS_ENABLE_GPU=ON -DTHEMIS_ENABLE_CUDA=ON
# 
# 2. Environment Variables:
#    export THEMIS_GPU_DEVICE=0  # GPU device ID
#    export THEMIS_GPU_MEMORY_LIMIT=8GB
# 
# 3. Verify GPU Support:
#    ./themis_server --check-gpu
# 
# Supported Backends:
# - CUDA (NVIDIA)
# - HIP (AMD)
# - Vulkan (Cross-platform)
# 
# References:
# - docs/en/features/GPU_ACCELERATION.md
# - docs/en/configuration/GPU_SETUP.md
# ============================================================

# Interaktiver Modus
themis_cli --database themisdb.db --interactive

themis> RETURN DOCS_QUERY('explain vector embeddings')
themis> RETURN DOCS_CONFIG_HELP('llm')
themis> RETURN DOCS_TROUBLESHOOT('out of memory error')
themis> EXIT

42.1.5 C++ SDK (Admin)

#include "llm/docs_assistant.h"
#include <iostream>

int main() {
    // Initialisiere Dokumentations-Assistenten
    themis::llm::DocsAssistantConfig config;
    config.docs_database_path = "/var/lib/themisdb/docs.db";
    config.database_type = "rocksdb";
    config.max_context_docs = 10;  // Admin braucht mehr Kontext
    config.enable_semantic_search = true;
    config.enable_caching = true;
    
    themis::llm::DocsAssistant assistant(config);
    
    if (!assistant.loadDatabase()) {
        std::cerr << "Failed to load documentation database\n";
        return 1;
    }
    
    // Beispiel 1: Konfigurationshilfe
    auto config_result = assistant.getConfigHelp("sharding");
    std::cout << "Configuration Help:\n"
              << config_result.generated_answer << "\n\n";
    
    // Beispiel 2: Troubleshooting
    auto trouble_result = assistant.getTroubleshootingHelp(
        "Database crashes with segmentation fault on startup"
    );
    std::cout << "Troubleshooting:\n"
              << trouble_result.generated_answer << "\n\n";
    
    // Beispiel 3: Dokumentensuche
    auto search_results = assistant.searchDocs("RAID configuration", 5);
    std::cout << "Found " << search_results.size() << " relevant documents:\n";
    for (const auto& doc : search_results) {
        std::cout << "  - " << doc.file_name 
                  << " (relevance: " << (doc.relevance_score * 100) << "%)\n";
    }
    
    // Beispiel 4: Statistiken
    auto stats = assistant.getStats();
    std::cout << "\nDatabase Statistics:\n"
              << stats.dump(2) << "\n";
    
    return 0;
}

42.2 Für Superuser: Erweiterte Features und Performance

42.2.1 Anwendungsfälle für Superuser

Superuser fokussieren sich auf:

Query-Optimierung: EXPLAIN ANALYZE, Index-Tuning
Erweiterte Features: Vector-Suche, Graph-Traversierung, Multi-Model
Performance-Analyse: Profiling, Bottleneck-Identifikation
Datenmodellierung: Best Practices, Schema-Design
Batch-Operationen: Bulk-Insert, ETL-Pipelines

42.2.2 REST API Zugriff (Superuser)

# Superuser fragt nach Query-Optimierung
curl -X POST https://themisdb.example.com:8765/api/v1/llm/docs/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${SUPERUSER_TOKEN}" \
  -d '{
    "query": "How can I optimize a slow JOIN query between graph and relational collections?"
  }'

# Antwort mit spezifischen Optimierungstipps
{
  "answer": "**Query-Optimierung für Multi-Model JOINs:**\n\n1. **Verwenden Sie sekundäre Indizes:**\n   ```aql\n   -- Erstelle Indizes (via separate CREATE INDEX Statements)\n   -- Index auf users.user_id wird erstellt\n   -- Index auf friends._from wird erstellt\n   ```\n\n2. **Optimieren Sie Join-Reihenfolge:**\n   ```aql\n   -- Schlecht: Graph zuerst, dann Filter\n   FOR user IN users\n     FOR friend IN friends\n       FILTER friend._from == user._id\n       RETURN friend\n   \n   -- Gut: Filter zuerst, dann Join\n   FOR user IN users\n     FILTER user.age > 25\n     FOR friend IN friends\n       FILTER friend._from == user._id\n       RETURN friend\n   ```\n\n3. **Nutzen Sie EXPLAIN:**\n   ```aql\n   EXPLAIN\n   FOR user IN users\n     FOR friend IN friends\n       FILTER friend._from == user._id\n       RETURN {user: user, friend: friend}\n   ```\n\n4. **Verwenden Sie LET für Subqueries:**\n   ```aql\n   FOR user IN users\n     FILTER user.age > 25\n     LET user_friends = (\n       FOR friend IN friends\n         FILTER friend._from == user._id\n         RETURN friend\n     )\n     RETURN {user: user, friends: user_friends}\n   ```\n\n**Performance-Metriken:**\n- Index-Scan: ~1-5ms\n- Full Collection Scan: ~50-500ms\n- Optimized Join: ~10-50ms\n- Unoptimized Join: ~500-5000ms\n\nReferenzen:\n- docs/en/features/QUERY_OPTIMIZATION.md\n- compendium/chapter_34_query_optimization.md",
  "confidence_score": 0.89,
  "documents_used": 6
}

42.2.3 AQL-Funktionen (Superuser)

-- Superuser analysiert Performance-Dokumentation
FOR doc IN :document
    FILTER doc.type == 'documentation'
    FILTER CONTAINS(doc.content, 'performance') OR CONTAINS(doc.content, 'optimization')
    LET relevance = (
        LENGTH(SPLIT(LOWER(doc.content), 'performance')) +
        LENGTH(SPLIT(LOWER(doc.content), 'optimization')) +
        LENGTH(SPLIT(LOWER(doc.content), 'index'))
    )
    SORT relevance DESC
    RETURN {
        title: doc.title,
        source: doc.source,
        relevance: relevance,
        preview: SUBSTRING(doc.content, 0, 200)
    }
    LIMIT 15

-- Kombinierte Suche mit Aggregation
LET vector_docs = DOCS_SEARCH('vector search embeddings', 5)
LET graph_docs = DOCS_SEARCH('graph traversal', 5)
LET relational_docs = DOCS_SEARCH('relational queries', 5)
RETURN {
    vector: vector_docs,
    graph: graph_docs,
    relational: relational_docs,
    total: LENGTH(vector_docs) + LENGTH(graph_docs) + LENGTH(relational_docs)
}

42.2.4 Performance-Analyse mit Docs-Assistent

# Superuser fragt nach Profiling-Tools
curl -X POST https://themisdb.example.com:8765/api/v1/llm/docs/query \
  -H "Authorization: Bearer ${SUPERUSER_TOKEN}" \
  -d '{
    "query": "What profiling tools are available for performance analysis?"
  }'

# CLI-basierte Performance-Analyse mit AQL
themis_cli --database themisdb.db \
    --execute "RETURN DOCS_QUERY('explain PROFILE and EXPLAIN in AQL')"

42.3 Für User: Grundlegende Dokumentationssuche

42.3.1 Anwendungsfälle für User

Normale User benötigen Hilfe bei:

Basis-Queries: Einfache FOR...FILTER...RETURN
Datentypen: JSON, Arrays, Nested Objects
Built-in Funktionen: String, Math, Date/Time
Fehlerbehandlung: Verständliche Fehlermeldungen
API-Nutzung: HTTP Endpoints, Request/Response-Format

42.3.2 REST API Zugriff (User)

# User fragt nach einfacher Query-Syntax
curl -X POST https://themisdb.example.com:8765/api/v1/llm/docs/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${USER_TOKEN}" \
  -d '{
    "query": "How do I select all users older than 30?"
  }'

# Antwort mit einfachem Beispiel
{
  "answer": "Um alle Benutzer über 30 zu selektieren, verwenden Sie:\n\n```aql\nFOR user IN users\n    FILTER user.age > 30\n    RETURN user\n```\n\n**Erklärung:**\n- `FOR user IN users` iteriert über die 'users' Collection\n- `FILTER user.age > 30` filtert Benutzer mit age > 30\n- `RETURN user` gibt die gefilterten Benutzer zurück\n\n**Beispiel-Ausgabe:**\n```json\n[\n  {\"_key\": \"user1\", \"name\": \"Alice\", \"age\": 35},\n  {\"_key\": \"user2\", \"name\": \"Bob\", \"age\": 42}\n]\n```\n\nSie können auch spezifische Felder zurückgeben:\n```aql\nFOR user IN users\n    FILTER user.age > 30\n    RETURN {name: user.name, age: user.age}\n```",
  "confidence_score": 0.95,
  "documents_used": 3
}

42.3.3 CLI-Zugriff (User)

# User verwendet vereinfachte CLI-Befehle
themis_cli --docs-search "how to insert data"

# Output:
# ============================================================
# Documentation Search Results
# ============================================================
# Found 8 relevant documents:
# 
# 1. GETTING_STARTED.md (relevance: 87%)
#    "Getting Started with ThemisDB... To insert data, use FOR...INSERT..."
# 
# 2. AQL_BASICS.md (relevance: 82%)
#    "AQL Basics... FOR doc IN [{name: 'Alice', age: 30}] INSERT doc INTO users..."
# 
# 3. REST_API.md (relevance: 75%)
#    "REST API Documentation... POST /api/v1/query with AQL statement..."
# 
# [...]
# ============================================================

# User stellt Follow-up-Frage
themis_cli --execute "RETURN DOCS_QUERY('show me an example of inserting multiple records')"

42.3.4 Web-Interface (User) - Geplant

<div class="themis-docs-assistant">
    <input type="text" 
           placeholder="Frage zur ThemisDB-Dokumentation..." 
           id="docsQuery">
    <button onclick="queryDocs()">Suchen</button>
    
    <div id="docsResults">
        
    </div>
</div>

<script>
async function queryDocs() {
    const query = document.getElementById('docsQuery').value;
    const response = await fetch('/api/v1/llm/docs/query', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer ' + getUserToken()
        },
        body: JSON.stringify({ query })
    });
    
    const result = await response.json();
    document.getElementById('docsResults').innerHTML = 
        `<div class="answer">${result.answer}</div>`;
}
</script>

42.4 Berechtigungsmodell und Zugriffskontrolle

42.4.0 YAML-Konfiguration - Detaillierte Dokumentation

Vollständige config/docs_assistant.yaml mit allen Optionen:

# ============================================================
# ThemisDB Documentation Assistant - Vollständige Konfiguration
# ============================================================
# Empfohlen für Produktionsumgebungen
# Auto-Discovery ist nur für Entwicklung gedacht

docs_assistant:
  # Grundeinstellungen
  enabled: true
  
  # ============================================================
  # Datenbank-Konfiguration (KRITISCH)
  # ============================================================
  database:
    # Pfad zur Dokumentationsdatenbank
    # SICHERHEIT: Immer explizit setzen in Produktion!
    path: "/var/lib/themisdb/docs.db"
    
    # Datenbanktyp: "rocksdb" oder "json"
    type: "rocksdb"
    
    # Auto-Discovery deaktivieren (empfohlen für Produktion)
    # Verhindert automatisches Laden von unbekannten Datenbanken
    auto_discover: false
    
    # Read-Only-Modus (empfohlen)
    # Verhindert versehentliche Änderungen an der Datenbank
    read_only: true
    
    # Validierung beim Laden
    validate_on_load: true
    
    # Maximale Datenbankgröße (MB)
    max_size_mb: 500
    
    # TODO: Zusätzliche Datenbanken (zukünftiges Feature)
    # Erfordert Security-Folgenabschätzung vor Implementierung
    # additional_databases:
    #   - name: "custom_legal_docs"
    #     path: "/var/lib/themisdb/legal_docs.db"
    #     type: "rocksdb"
    #     enabled: true
    #     requires_role: "administrator"
    #     security_validated: true
    #     checksum: "sha256:abc123..."
    #     signed_by: "security@example.com"
  
  # ============================================================
  # LLM-Konfiguration
  # ============================================================
  llm:
    # Modell-ID (leer = Standardmodell verwenden)
    model_id: ""
    
    # Maximale Anzahl Dokumente im RAG-Kontext
    max_context_docs: 5
    
    # Zeichen pro Dokument im Kontext
    context_preview_length: 1000
    
    # Semantische Suche aktivieren (benötigt Vector Embeddings)
    enable_semantic_search: true
    
    # Response-Caching
    enable_caching: true
    cache_ttl_seconds: 300
  
  # ============================================================
  # Zugriffskontrolle (RBAC)
  # ============================================================
  access:
    # RBAC aktivieren
    enable_rbac: true
    
    # Standardrolle wenn nicht authentifiziert
    default_role: "anonymous"
    
    # Authentifizierung erzwingen
    require_auth: true
    
    # Rollenbasierte Limits (siehe 42.4.1)
    roles:
      administrator:
        requests_per_minute: 100
        max_context_docs: 10
        cache_ttl_seconds: 300
        allowed_endpoints:
          - query
          - search
          - config
          - troubleshoot
          - stats
        # TODO: Zugriff auf zusätzliche Datenbanken
        additional_databases_access: true
      
      superuser:
        requests_per_minute: 50
        max_context_docs: 7
        cache_ttl_seconds: 600
        allowed_endpoints:
          - query
          - search
          - config  # read-only
      
      user:
        requests_per_minute: 20
        max_context_docs: 3
        cache_ttl_seconds: 900
        allowed_endpoints:
          - query
          - search
      
      anonymous:
        requests_per_minute: 5
        max_context_docs: 1
        cache_ttl_seconds: 1800
        allowed_endpoints:
          - search  # nur Suche, keine LLM-Queries
  
  # ============================================================
  # REST API
  # ============================================================
  api:
    enabled: true
    base_path: "/api/v1/llm/docs"
    require_auth: true
    enable_cors: true
    cors_origins:
      - "https://app.example.com"
      - "https://admin.example.com"
  
  # ============================================================
  # AQL-Funktionen
  # ============================================================
  aql:
    enabled: true
    function_prefix: "DOCS_"
    functions:
      - QUERY        # DOCS_QUERY()
      - SEARCH       # DOCS_SEARCH()
      - CONFIG_HELP  # DOCS_CONFIG_HELP()
      - TROUBLESHOOT # DOCS_TROUBLESHOOT()
  
  # ============================================================
  # Monitoring und Audit
  # ============================================================
  monitoring:
    # Prometheus-Metriken
    enable_metrics: true
    metrics_prefix: "themis_docs_"
    
    # Audit-Logging (WICHTIG für Compliance)
    enable_audit_log: true
    audit_log_path: "/var/log/themisdb/docs_assistant_audit.log"
    
    # Was wird geloggt
    log_queries: false  # WARNUNG: Kann sensible Daten enthalten
    log_failed_queries: true
    log_access_denied: true
    log_database_access: true
  
  # ============================================================
  # Performance
  # ============================================================
  performance:
    worker_threads: 4
    search_timeout_ms: 5000
    generation_timeout_ms: 30000
    enable_async: true
    async_queue_size: 100

# ============================================================
# TODO: Security-Folgenabschätzung
# ============================================================
# Bevor zusätzliche Datenbanken implementiert werden:
# 
# 1. Risikobewertung:
#    - Kann Admin bösartige Datenbanken einhängen?
#    - Sandboxing-Mechanismus erforderlich?
#    - Validierung der Datenbank-Inhalte?
#
# 2. Authentifizierung:
#    - Digitale Signaturen für Datenbanken
#    - Checksummen-Validierung
#    - Whitelisting von Datenbankquellen
#
# 3. Zugriffskontrolle:
#    - Welche Rollen dürfen Datenbanken hinzufügen?
#    - Separate Berechtigungen pro Datenbank
#    - Isolation zwischen Datenbanken
#
# 4. Audit und Compliance:
#    - Vollständiger Audit-Trail
#    - Wer hat wann welche Datenbank hinzugefügt?
#    - Welche Abfragen wurden auf welcher Datenbank ausgeführt?
#
# 5. Rate-Limiting:
#    - Pro Datenbank getrennte Limits?
#    - Globale Limits über alle Datenbanken?
#
# 6. Datenbank-Validierung:
#    - Schema-Validierung
#    - Content-Filtering (keine Malware, Scripts, etc.)
#    - Maximale Größenbeschränkungen
#
# Siehe: docs/en/security/DOCS_ASSISTANT_SECURITY_ASSESSMENT.md

Umgebungsvariablen-Überschreibung:

# Alle YAML-Optionen können via Env-Vars überschrieben werden
export THEMIS_DOCS_ENABLED=true
export THEMIS_DOCS_DATABASE_PATH="/var/lib/themisdb/docs.db"
export THEMIS_DOCS_DATABASE_TYPE="rocksdb"
export THEMIS_DOCS_AUTO_DISCOVER=false
export THEMIS_DOCS_READ_ONLY=true
export THEMIS_DOCS_REQUIRE_AUTH=true
export THEMIS_DOCS_ENABLE_AUDIT_LOG=true
export THEMIS_DOCS_AUDIT_LOG_PATH="/var/log/themisdb/audit.log"

./themis_server

Deployment-Szenarien:

Szenario 1: Entwicklung (lokale Maschine)

docs_assistant:
  enabled: true
  database:
    path: "data/docs.db"
    auto_discover: true  # OK für Entwicklung
  access:
    require_auth: false  # Nur für lokale Entwicklung!

Szenario 2: Staging (Test-Umgebung)

docs_assistant:
  enabled: true
  database:
    path: "/opt/themisdb/docs.db"
    auto_discover: false
    read_only: true
  access:
    require_auth: true
    enable_rbac: true
  monitoring:
    enable_audit_log: true

Szenario 3: Produktion (empfohlen)

docs_assistant:
  enabled: true
  database:
    path: "/var/lib/themisdb/docs.db"
    type: "rocksdb"
    auto_discover: false  # KRITISCH!
    read_only: true       # KRITISCH!
    validate_on_load: true
  access:
    require_auth: true
    enable_rbac: true
  monitoring:
    enable_audit_log: true
    audit_log_path: "/var/log/themisdb/docs_assistant_audit.log"
    log_access_denied: true
    log_database_access: true

42.4.1 RBAC-Integration

# config/rbac_docs_assistant.yaml
roles:
  administrator:
    permissions:
      - docs:query:*
      - docs:search:*
      - docs:config:*
      - docs:troubleshoot:*
      - docs:stats:*
    rate_limit:
      requests_per_minute: 100
      max_context_docs: 10
  
  superuser:
    permissions:
      - docs:query:*
      - docs:search:*
      - docs:config:read
    rate_limit:
      requests_per_minute: 50
      max_context_docs: 7
  
  user:
    permissions:
      - docs:query:basic
      - docs:search:*
    rate_limit:
      requests_per_minute: 20
      max_context_docs: 3
    restrictions:
      - no_system_config_docs
      - no_internal_implementation_docs

42.4.2 API-Key-Basierte Authentifizierung

# Admin erstellt API Keys für verschiedene Rollen
themis_cli --create-api-key \
    --role administrator \
    --name "admin-docs-key" \
    --expires 90d

# Output:
# API Key created: themis_admin_abc123xyz...
# Role: administrator
# Expires: 2026-04-11

# User verwendet den API Key
curl -X POST https://themisdb.example.com:8765/api/v1/llm/docs/query \
  -H "X-API-Key: themis_user_def456uvw..." \
  -d '{"query": "how to filter data?"}'

42.4.3 Audit-Logging

// Docs-Assistent loggt alle Anfragen
struct DocsAuditLog {
    std::string timestamp;
    std::string user_id;
    std::string role;
    std::string query;
    std::string endpoint;  // "query", "search", "config", "troubleshoot"
    int documents_accessed;
    float response_time_ms;
    bool success;
};

// Beispiel-Log-Eintrag
{
    "timestamp": "2026-01-11T09:30:45Z",
    "user_id": "admin@example.com",
    "role": "administrator",
    "query": "How to configure RAID sharding?",
    "endpoint": "config",
    "documents_accessed": 5,
    "response_time_ms": 1840.5,
    "success": true
}

42.5 Rate-Limiting und Resource-Management

42.5.1 Rate-Limits nach Rolle

Rolle	Requests/Min	Max Context Docs	Cache-TTL	Priority
Administrator	100	10	5 min	High
Superuser	50	7	10 min	Medium
User	20	3	15 min	Low
Anonymous	5	1	30 min	Lowest

42.5.2 Konfiguration

# config/docs_assistant.yaml
rate_limiting:
  enabled: true
  backend: redis  # oder "memory"
  
  roles:
    administrator:
      requests_per_minute: 100
      burst: 20
      max_concurrent: 10
    
    superuser:
      requests_per_minute: 50
      burst: 10
      max_concurrent: 5
    
    user:
      requests_per_minute: 20
      burst: 5
      max_concurrent: 2

resource_limits:
  max_context_docs:
    administrator: 10
    superuser: 7
    user: 3
  
  llm_timeout_seconds:
    administrator: 30
    superuser: 20
    user: 10
  
  cache_ttl_seconds:
    administrator: 300
    superuser: 600
    user: 900

42.6 Best Practices und Tipps

42.6.1 Für Administratoren

✅ DOs:

Nutzen Sie DOCS_CONFIG_HELP() für schnelle Konfigurationsreferenzen
Kombinieren Sie Docs-Assistent mit EXPLAIN ANALYZE für Troubleshooting
Cachen Sie häufige Queries mit enable_caching=true
Verwenden Sie spezifische Queries statt generische Fragen

❌ DON'Ts:

Verlassen Sie sich nicht ausschließlich auf den Assistenten für kritische Entscheidungen
Vermeiden Sie extrem lange Queries (>500 Zeichen)
Ignorieren Sie nicht die Konfidenz-Scores (<0.5 = unsicher)

42.6.2 Für Superuser

✅ DOs:

Nutzen Sie DOCS_SEARCH() für gezielte Dokumentensuche
Kombinieren Sie mit FOR ... IN :document für Custom-Analysen
Verwenden Sie Batch-Queries für multiple Topics

❌ DON'Ts:

Überschreiten Sie nicht Ihre Rate-Limits (50 req/min)
Vermeiden Sie redundante Queries (nutzen Sie Cache)

42.6.3 Für User

✅ DOs:

Formulieren Sie klare, spezifische Fragen
Nutzen Sie die CLI für schnelle Lookups
Prüfen Sie relevant_documents für zusätzliche Infos

❌ DON'Ts:

Stellen Sie keine Fragen zu internen Implementierungen
Überschreiten Sie nicht Ihre Rate-Limits (20 req/min)

42.7 Troubleshooting und Häufige Probleme

42.7.1 Docs-Datenbank nicht gefunden

Problem:

Error: Documentation database not loaded. Please ensure docs_database.json is available.

Lösung (Admin):

# 1. Generiere Dokumentations-Datenbank
python3 scripts/generate_docs_rocksdb.py --output data/docs.db

# 2. Verifiziere Datenbank
ls -lh data/docs.db
# Erwartete Größe: ~2-3 MB

# 3. Setze Umgebungsvariable
export THEMIS_DOCS_DATABASE_PATH=/var/lib/themisdb/data/docs.db
export THEMIS_DOCS_DATABASE_TYPE=rocksdb

# 4. Starte Server neu
systemctl restart themisdb

42.7.2 Rate-Limit überschritten

Problem:

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded 20 requests per minute. Please wait 45 seconds.",
  "retry_after": 45
}

Lösung (User):

# Warte bis Rate-Limit zurückgesetzt wird
sleep 45

# Oder: Verwende Caching
curl -X POST /api/v1/llm/docs/query \
  -H "X-Use-Cache: true" \
  -d '{"query": "..."}'

42.7.3 Niedrige Konfidenz-Scores

Problem:

{
  "answer": "...",
  "confidence_score": 0.32
}

Lösung:

# Verbessere Query-Formulierung
# Schlecht: "wie geht das?"
# Gut: "How do I configure RAID 6 sharding with 9 shards?"

# Nutze DOCS_SEARCH() für manuelle Dokumentensuche
themis_cli --execute "RETURN DOCS_SEARCH('RAID sharding configuration', 10)"

42.8 Monitoring und Metriken

42.8.1 Prometheus-Metriken

# Docs-Assistent Request-Rate
rate(themis_docs_requests_total[5m])

# Durchschnittliche Response-Zeit
histogram_quantile(0.95, themis_docs_response_time_seconds_bucket)

# Konfidenz-Score-Verteilung
histogram_quantile(0.5, themis_docs_confidence_score_bucket)

# Cache-Hit-Rate
rate(themis_docs_cache_hits_total[5m]) / rate(themis_docs_requests_total[5m])

42.8.2 Grafana-Dashboard

# grafana/dashboards/docs_assistant.json
{
  "title": "ThemisDB Docs Assistant",
  "panels": [
    {
      "title": "Requests by Role",
      "targets": [
        {
          "expr": "sum(rate(themis_docs_requests_total[5m])) by (role)"
        }
      ]
    },
    {
      "title": "Response Time (p95)",
      "targets": [
        {
          "expr": "histogram_quantile(0.95, themis_docs_response_time_seconds_bucket)"
        }
      ]
    }
  ]
}

42.9 Migration und Upgrades

42.9.1 Upgrade von JSON zu RocksDB

# Alte JSON-basierte Datenbank
# Größe: 4.2 MB
# Load-Zeit: 42 ms

# Neue RocksDB-basierte Datenbank
python3 scripts/generate_docs_rocksdb.py --output data/docs.db

# Größe: 2.8 MB (-33%)
# Load-Zeit: 7 ms (-83%)

# Update Konfiguration
# config/themis.yaml
llm:
  docs_assistant:
    database_type: rocksdb  # war: json
    database_path: data/docs.db  # war: data/docs_database.json

42.9.2 Dokumentations-Update

# Nach Änderungen an ./docs oder ./compendium
cd /path/to/ThemisDB

# Regeneriere Datenbank
python3 scripts/generate_docs_database.py
python3 scripts/generate_docs_rocksdb.py

# Restart Server (Hot-Reload nicht unterstützt)
systemctl restart themisdb

# Verifiziere neue Dokumente
themis_cli --execute "
  FOR meta IN docs_metadata
    FILTER meta.key == 'generation_time'
    RETURN meta.value
"

42.9.3 FAQ: Typische Fragen und erwartete Antworten

Diese FAQ zeigt realistische Beispiele für Fragen, die an den Dokumentations-Assistenten gestellt werden können, und die zu erwartenden Antworten.

42.9.3.1 Konfiguration & Setup

Frage 1: "Wie aktiviere ich Sharding in ThemisDB?"

RETURN DOCS_QUERY('Wie aktiviere ich Sharding in ThemisDB?')

Erwartete Antwort:

Um Sharding in ThemisDB zu aktivieren:

1. Konfiguration in config/themis.yaml:
   sharding:
     enabled: true
     mode: "consistent_hash"  # oder "range", "round_robin"
     shards: 3
     replication_factor: 2

2. Shard-Keys definieren:
   CREATE COLLECTION users SHARD_KEY user_id;

3. Server neu starten:
   systemctl restart themisdb

4. Verifizierung:
   RETURN CURRENT_SHARDING_TOPOLOGY()

Weitere Details: Kapitel 16 (Sharding & Partitioning)
Verwandte Themen: RAID-Konfiguration, Replication, Load-Balancing

Frage 2: "Was sind die Hardware-Mindestanforderungen für ThemisDB?"

RETURN DOCS_CONFIG_HELP('hardware requirements')

Erwartete Antwort:

ThemisDB Hardware-Anforderungen:

MINIMUM (Development):
- CPU: 2 Cores (x86_64 oder ARM64)
- RAM: 4 GB
- Disk: 20 GB SSD
- Netzwerk: 100 Mbit/s

EMPFOHLEN (Production):
- CPU: 8+ Cores, AVX2-Support
- RAM: 32 GB+
- Disk: 500 GB NVMe SSD (RAID 10)
- Netzwerk: 1 Gbit/s+

ENTERPRISE (High-Performance):
- CPU: 32+ Cores, AVX-512
- RAM: 128 GB+
- Disk: 2 TB+ NVMe SSD (RAID 10)
- Netzwerk: 10 Gbit/s+
- GPU: NVIDIA A100 (optional für ML)

Quelle: Kapitel 4 (Installation), Kapitel 25 (DevOps & Infrastructure)

Frage 3: "Wie konfiguriere ich SSL/TLS für sichere Verbindungen?"

RETURN DOCS_CONFIG_HELP('SSL/TLS configuration')

Erwartete Antwort:

SSL/TLS-Konfiguration für ThemisDB:

1. Zertifikate generieren:
   openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365

2. config/themis.yaml anpassen:
   server:
     ssl:
       enabled: true
       cert_file: "/path/to/cert.pem"
       key_file: "/path/to/key.pem"
       ca_file: "/path/to/ca.pem"  # optional
       min_tls_version: "1.2"
       ciphers: "HIGH:!aNULL:!MD5"

3. Client-Konfiguration:
   themis_cli --ssl --ssl-cert /path/to/cert.pem

4. Verifizierung:
   curl https://localhost:8765/health --cacert ca.pem

Weitere Details: Kapitel 21 (Authentifizierung & Autorisierung)
Verwandte Themen: mTLS, Certificate Rotation, LDAP-Integration

42.9.3.2 Troubleshooting & Performance

Frage 4: "Server startet nicht - 'Port already in use' Fehler"

RETURN DOCS_TROUBLESHOOT('Server startet nicht - Port already in use')

Erwartete Antwort:

Lösung für 'Port already in use' Fehler:

DIAGNOSE:
1. Prüfen, welcher Prozess Port 8765 nutzt:
   sudo lsof -i :8765
   # oder
   sudo netstat -tulpn | grep 8765

LÖSUNGEN:
A) Prozess beenden:
   sudo kill -9 <PID>

B) Anderen Port konfigurieren (config/themis.yaml):
   server:
     port: 8766  # Alternativer Port

C) Zombie-Prozesse bereinigen:
   pkill -9 themisdb
   systemctl reset-failed themisdb

PRÄVENTION:
- Graceful Shutdown verwenden: systemctl stop themisdb
- Startup-Script mit Port-Check ergänzen
- Monitoring für Port-Konflikte einrichten

Verwandte Dokumente: Kapitel 27 (Troubleshooting), Appendix I

Frage 5: "Warum sind meine Queries so langsam?"

RETURN DOCS_TROUBLESHOOT('Queries sind langsam - Performance-Probleme')

Erwartete Antwort:

Performance-Optimierung für langsame Queries:

DIAGNOSE:
1. Query-Profiling aktivieren:
   EXPLAIN <your_query>

2. Metriken prüfen:
   curl http://localhost:8765/metrics | grep query_duration

HÄUFIGE URSACHEN & LÖSUNGEN:

A) Fehlende Indizes:
   - Problem: Full-Table-Scans
   - Lösung: CREATE INDEX idx_name ON collection(field)

B) Suboptimale Query-Struktur:
   - Problem: Nested loops ohne LIMIT
   - Lösung: LIMIT hinzufügen, Filter optimieren

C) Große Datenmengen ohne Paging:
   - Problem: Millionen Rows im Result-Set
   - Lösung: LIMIT + OFFSET verwenden (Batch-Processing)

D) Unzureichende Hardware:
   - Problem: RAM < Arbeitsspeicherbedarf
   - Lösung: RAM erhöhen, Caching aktivieren

E) Fragmentierung:
   - Problem: Viele Updates/Deletes
   - Lösung: COMPACT_COLLECTION()

QUICK-WINS:
- Indizes auf Filter-Feldern: +80% schneller
- LIMIT 1000 statt unbegrenzt: +95% schneller
- Parallele Queries aktivieren: +60% schneller

Details: Kapitel 34 (Query Optimization), Kapitel 39 (Performance Tuning)

Frage 6: "Out of Memory - Server crashed"

RETURN DOCS_TROUBLESHOOT('Out of Memory Error - Server crashed')

Erwartete Antwort:

Lösung für Out-of-Memory (OOM) Fehler:

SOFORTMASSNAHMEN:
1. Server neustarten:
   systemctl restart themisdb

2. Memory-Limit erhöhen (config/themis.yaml):
   system:
     max_memory: "16GB"  # erhöhen von z.B. 8GB
     max_query_memory: "2GB"

LANGFRISTIGE LÖSUNGEN:

A) Memory-Profiling:
   - Aktivieren: monitoring.memory_profiling = true
   - Analyse: curl http://localhost:8765/debug/memory

B) Query-Optimierungen:
   - Große Result-Sets vermeiden (LIMIT verwenden)
   - Streaming für große Datenmengen aktivieren
   - Materialized Views für häufige Aggregationen

C) Cache-Konfiguration anpassen:
   cache:
     query_cache_size: "4GB"  # reduzieren wenn nötig
     block_cache_size: "8GB"

D) Hardware-Upgrade:
   - RAM verdoppeln (z.B. 32GB → 64GB)
   - Swap-Space aktivieren (nur als Fallback)

MONITORING:
- Grafana Dashboard: Memory Usage Alert bei >85%
- Log-Überwachung: grep "out of memory" /var/log/themisdb/*

Details: Kapitel 19 (Monitoring), Kapitel 27 (Troubleshooting)

42.9.3.3 Datenmodellierung & AQL

Frage 7: "Wie modelliere ich Many-to-Many Beziehungen?"

RETURN DOCS_QUERY('Wie modelliere ich Many-to-Many Beziehungen in ThemisDB?')

Erwartete Antwort:

Many-to-Many Beziehungen in ThemisDB modellieren:

METHODE 1: Edge-Collection (Graph-Modell - empfohlen)

1. Collections erstellen:
   CREATE COLLECTION users;
   CREATE COLLECTION projects;
   CREATE EDGE COLLECTION user_projects;

2. Daten einfügen:
   INSERT {_key: "u1", name: "Alice"} INTO users;
   INSERT {_key: "p1", name: "Project A"} INTO projects;
   INSERT {_from: "users/u1", _to: "projects/p1", role: "lead"} 
     INTO user_projects;

3. Abfragen:
   FOR u IN users
     FOR proj IN OUTBOUND u user_projects
       RETURN {user: u.name, project: proj.name}

METHODE 2: Junction-Table (Relational-Modell)

1. Collections:
   CREATE COLLECTION users;
   CREATE COLLECTION projects;
   CREATE COLLECTION user_project_junction;

2. Daten:
   INSERT {user_id: "u1", project_id: "p1", role: "lead"} 
     INTO user_project_junction;

3. Abfragen mit JOIN:
   FOR uj IN user_project_junction
     LET u = DOCUMENT(CONCAT("users/", uj.user_id))
     LET p = DOCUMENT(CONCAT("projects/", uj.project_id))
     RETURN {user: u.name, project: p.name, role: uj.role}

BEST PRACTICE: Graph-Modell für:
- Häufige Traversierungen
- Komplexe Beziehungen (>2 Entitäten)
- Pfad-Abfragen (SHORTEST_PATH)

Details: Kapitel 6 (Graph-Modell), Kapitel 35 (Data Modeling Patterns)

Frage 8: "Wie verwende ich Vector-Embeddings für Ähnlichkeitssuche?"

RETURN DOCS_QUERY('Wie verwende ich Vector-Embeddings für Ähnlichkeitssuche?')

Erwartete Antwort:

Vector-Embeddings für Ähnlichkeitssuche in ThemisDB:

SETUP:

1. Collection mit Vector-Index:
   CREATE COLLECTION documents;
   CREATE VECTOR INDEX vec_idx ON documents(embedding) 
     DIMENSION 768 METRIC cosine;

2. Embeddings generieren (z.B. mit Sentence-Transformers):
   import sentence_transformers
   model = sentence_transformers.SentenceTransformer('all-MiniLM-L6-v2')
   embedding = model.encode("Your text here").tolist()

3. Dokument mit Embedding einfügen:
   INSERT {
     text: "ThemisDB is a multi-model database",
     embedding: [0.12, -0.45, 0.78, ...]  // 768 Dimensionen
   } INTO documents;

QUERIES:

A) K-Nearest-Neighbors (KNN):
   LET query_vec = [0.15, -0.42, 0.81, ...]
   FOR doc IN documents
     SORT COSINE_SIMILARITY(doc.embedding, query_vec) DESC
     LIMIT 10
     RETURN {text: doc.text, score: COSINE_SIMILARITY(doc.embedding, query_vec)}

B) Similarity-Threshold:
   FOR doc IN documents
     LET sim = COSINE_SIMILARITY(doc.embedding, @query_embedding)
     FILTER sim > 0.85
     RETURN {text: doc.text, similarity: sim}

C) Hybrid-Search (Text + Vector):
   FOR doc IN FULLTEXT(documents, "database", 0.8)
     LET vec_sim = COSINE_SIMILARITY(doc.embedding, @vec)
     LET combined_score = 0.7 * doc.score + 0.3 * vec_sim
     SORT combined_score DESC
     LIMIT 10
     RETURN doc

METRIKEN:
- cosine: Für normalisierte Vektoren (Standard)
- euclidean: Für nicht-normalisierte Vektoren
- dot_product: Für Performance-kritische Anwendungen

Details: Kapitel 8 (Vector-Modell), Kapitel 16 (ML-Integration)

42.9.3.4 Sicherheit & Compliance

Frage 9: "Wie implementiere ich Row-Level-Security?"

RETURN DOCS_CONFIG_HELP('Row-Level Security implementation')

Erwartete Antwort:

Row-Level-Security (RLS) in ThemisDB implementieren:

METHODE 1: AQL-basierte Policy (empfohlen)

1. Security-Funktion definieren:
   CREATE FUNCTION can_access_row(doc, user)
     RETURN (
       doc.owner_id == user.id OR
       user.role == "admin" OR
       doc.public == true
     );

2. In Queries verwenden:
   FOR doc IN documents
     FILTER can_access_row(doc, CURRENT_USER())
     RETURN doc

3. View mit Policy:
   CREATE VIEW secure_documents AS
     FOR doc IN documents
       FILTER can_access_row(doc, CURRENT_USER())
       RETURN doc

METHODE 2: Collection-Level-Policies

1. Policy erstellen (config/policies.yaml):
   policies:
     documents:
       read:
         condition: "doc.owner_id == @user_id OR doc.public == true"
       write:
         condition: "doc.owner_id == @user_id OR @user_role == 'admin'"

2. Policy aktivieren:
   ALTER COLLECTION documents SET POLICY read_policy;

3. Automatische Enforcement:
   FOR doc IN documents  // Policy automatisch angewendet
     RETURN doc

METHODE 3: Tenant-Isolation (Multi-Tenancy)

1. Tenant-ID in jedem Dokument:
   INSERT {tenant_id: "tenant_a", data: {...}} INTO documents;

2. Middleware mit Tenant-Filter:
   app.use((req, res, next) => {
     req.aql_filter = `doc.tenant_id == "${req.user.tenant_id}"`;
   });

AUDIT-LOGGING:
   monitoring:
     audit_log:
       enabled: true
       log_access_violations: true

Details: Kapitel 21 (Auth), Kapitel 36 (Security Hardening)

Frage 10: "Wie erfülle ich GDPR-Anforderungen (Recht auf Vergessen)?"

RETURN DOCS_QUERY('Wie erfülle ich GDPR-Anforderungen in ThemisDB?')

Erwartete Antwort:

GDPR-Compliance in ThemisDB (Recht auf Vergessen):

1. DATEN-LÖSCHUNG (Right to be Forgotten):

   A) Vollständige Löschung:
      // Alle Daten eines Users löschen
      FOR doc IN users
        FILTER doc.email == @user_email
        REMOVE doc IN users;
      
      // Related Collections durchsuchen
      FOR collection IN ["orders", "preferences", "logs"]
        FOR doc IN collection
          FILTER doc.user_id == @user_id
          REMOVE doc IN collection;

   B) Anonymisierung (Alternative):
      UPDATE {_key: @user_key} WITH {
        email: "anonymized@deleted.user",
        name: "[DELETED]",
        phone: null,
        address: null,
        gdpr_deleted_at: DATE_NOW()
      } IN users;

2. AUDIT-TRAIL für GDPR-Requests:

   CREATE COLLECTION gdpr_requests;
   INSERT {
     user_id: @user_id,
     request_type: "deletion",  // oder "export", "correction"
     timestamp: DATE_NOW(),
     processed_by: CURRENT_USER(),
     status: "completed"
   } INTO gdpr_requests;

3. DATEN-EXPORT (Right to Data Portability):

   // JSON-Export aller User-Daten
   LET user_data = DOCUMENT("users/@user_key")
   LET orders = (FOR o IN orders FILTER o.user_id == @user_id RETURN o)
   LET preferences = DOCUMENT("preferences/@user_key")
   
   RETURN {
     user: user_data,
     orders: orders,
     preferences: preferences,
     export_date: DATE_NOW()
   }

4. DATEN-RETENTION-POLICY:

   // Automatische Löschung alter Daten
   FOR doc IN logs
     FILTER doc.created_at < DATE_SUBTRACT(DATE_NOW(), 90, "days")
     REMOVE doc IN logs;

5. VERSCHLÜSSELUNG:

   config/themis.yaml:
     encryption:
       at_rest: true
       algorithm: "AES-256-GCM"
       key_rotation: "monthly"

COMPLIANCE-CHECKLIST:
✅ Recht auf Löschung implementiert
✅ Recht auf Export implementiert
✅ Audit-Trail für alle Requests
✅ Verschlüsselung (at-rest + in-transit)
✅ Zugriffskontrollen (RBAC)
✅ Daten-Minimierung (nur notwendige Daten)
✅ Anonymisierung von Logs

Details: Kapitel 40 (Data Governance & Compliance)

42.9.3.5 Integration & DevOps

Frage 11: "Wie integriere ich ThemisDB mit Kubernetes?"

RETURN DOCS_QUERY('Wie deploye ich ThemisDB in Kubernetes?')

Erwartete Antwort:

ThemisDB Kubernetes Deployment:

1. STATEFULSET für ThemisDB (Persistence):

   apiVersion: apps/v1
   kind: StatefulSet
   metadata:
     name: themisdb
   spec:
     serviceName: themisdb
     replicas: 3
     selector:
       matchLabels:
         app: themisdb
     template:
       metadata:
         labels:
           app: themisdb
       spec:
         containers:
         - name: themisdb
           image: themisdb/themisdb:v1.4.0
           ports:
           - containerPort: 8765
           volumeMounts:
           - name: data
             mountPath: /var/lib/themisdb
           env:
           - name: THEMIS_CLUSTER_MODE
             value: "true"
           - name: THEMIS_RAFT_PEERS
             value: "themisdb-0.themisdb:7687,themisdb-1.themisdb:7687"
     volumeClaimTemplates:
     - metadata:
         name: data
       spec:
         accessModes: ["ReadWriteOnce"]
         resources:
           requests:
             storage: 100Gi
         storageClassName: fast-ssd

2. SERVICE (ClusterIP):

   apiVersion: v1
   kind: Service
   metadata:
     name: themisdb
   spec:
     selector:
       app: themisdb
     ports:
     - protocol: TCP
       port: 8765
       targetPort: 8765
     type: ClusterIP

3. CONFIGMAP:

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: themisdb-config
   data:
     themis.yaml: |
       server:
         port: 8765
         threads: 8
       storage:
         path: /var/lib/themisdb
       cluster:
         enabled: true

4. HELM-CHART (Empfohlen):

   helm repo add themisdb https://charts.themisdb.io
   helm install my-themisdb themisdb/themisdb \
     --set replicaCount=3 \
     --set persistence.size=100Gi \
     --set resources.limits.memory=32Gi

MONITORING:
- Prometheus Operator: ServiceMonitor für Metriken
- Grafana: Dashboard für Cluster-Health
- Alertmanager: Alerts für Node-Failures

Details: Kapitel 25 (DevOps), Kapitel 30 (Deployment & Operations)

Frage 12: "Wie richte ich Backups mit Point-in-Time-Recovery ein?"

RETURN DOCS_CONFIG_HELP('backup and point-in-time recovery')

Erwartete Antwort:

Backup & Point-in-Time-Recovery (PITR) in ThemisDB:

1. AUTOMATISCHE BACKUPS konfigurieren:

   config/themis.yaml:
     backup:
       enabled: true
       schedule: "0 2 * * *"  # Täglich um 2:00 Uhr
       retention_days: 30
       destination: "s3://my-bucket/themisdb-backups"
       compression: "zstd"
       encryption: true

2. MANUELLES BACKUP:

   # Full Backup
   themis_admin backup create \
     --type full \
     --output /backup/themisdb-full-$(date +%Y%m%d).tar.zst

   # Incremental Backup
   themis_admin backup create \
     --type incremental \
     --base-backup /backup/themisdb-full-20260101.tar.zst \
     --output /backup/themisdb-incr-$(date +%Y%m%d).tar.zst

3. WRITE-AHEAD-LOG (WAL) für PITR:

   config/themis.yaml:
     wal:
       enabled: true
       retention_hours: 72  # 3 Tage
       archive_dir: "/var/lib/themisdb/wal_archive"

4. POINT-IN-TIME-RESTORE:

   # Restore zu spezifischem Zeitpunkt
   themis_admin restore \
     --backup /backup/themisdb-full-20260101.tar.zst \
     --wal-archive /var/lib/themisdb/wal_archive \
     --point-in-time "2026-01-10 14:30:00" \
     --target-dir /var/lib/themisdb/restore

5. RESTORE-PROZESS:

   # 1. Server stoppen
   systemctl stop themisdb

   # 2. Daten sichern (Sicherheitskopie)
   mv /var/lib/themisdb/data /var/lib/themisdb/data.old

   # 3. Restore durchführen
   themis_admin restore --backup /backup/latest.tar.zst

   # 4. Server starten
   systemctl start themisdb

   # 5. Verifizieren
   themis_cli --execute "RETURN COUNT(FOR doc IN users RETURN 1)"

6. S3-BACKUP (Cloud):

   # AWS S3 konfigurieren
   export AWS_ACCESS_KEY_ID=...
   export AWS_SECRET_ACCESS_KEY=...
   
   themis_admin backup create \
     --destination s3://my-bucket/backups/ \
     --encryption AES256

BACKUP-STRATEGIE:
- Full: Täglich (2:00 Uhr)
- Incremental: Stündlich (während Geschäftszeiten)
- WAL-Archive: Kontinuierlich
- Retention: 30 Tage Full, 7 Tage Incremental
- Off-Site: S3 + Glacier (90 Tage)

Details: Kapitel 20 (Backup & Recovery)

42.9.3.6 Erweiterte Features

Frage 13: "Wie verwende ich die Zeitreihen-Funktionen?"

RETURN DOCS_QUERY('Wie verwende ich Zeitreihen-Features in ThemisDB?')

Erwartete Antwort:

Zeitreihen-Features in ThemisDB:

1. TIMESERIES-COLLECTION erstellen:

   CREATE TIMESERIES COLLECTION sensor_data
     TIME_FIELD timestamp
     GRANULARITY hour
     RETENTION 90  # Tage

2. DATEN EINFÜGEN:

   INSERT {
     timestamp: DATE_NOW(),
     sensor_id: "temp_001",
     temperature: 23.5,
     humidity: 65.2,
     location: "room_a"
   } INTO sensor_data;

3. ZEITREIHEN-QUERIES:

   A) Aggregation über Zeitfenster:
      FOR data IN sensor_data
        FILTER data.timestamp >= DATE_SUBTRACT(DATE_NOW(), 24, "hours")
        COLLECT time_bucket = DATE_TRUNC(data.timestamp, "hour")
        AGGREGATE avg_temp = AVG(data.temperature),
                  max_temp = MAX(data.temperature),
                  min_temp = MIN(data.temperature)
        RETURN {
          hour: time_bucket,
          avg: avg_temp,
          max: max_temp,
          min: min_temp
        }

   B) Downsampling (Daten-Verdichtung):
      FOR data IN sensor_data
        FILTER data.timestamp < DATE_SUBTRACT(DATE_NOW(), 30, "days")
        COLLECT bucket = DATE_TRUNC(data.timestamp, "day"),
                sensor = data.sensor_id
        AGGREGATE avg_temp = AVG(data.temperature)
        INSERT {
          timestamp: bucket,
          sensor_id: sensor,
          temperature_avg: avg_temp,
          aggregated: true
        } INTO sensor_data_daily;

   C) Gap-Filling (fehlende Daten interpolieren):
      LET time_range = DATE_RANGE(
        DATE_SUBTRACT(DATE_NOW(), 7, "days"),
        DATE_NOW(),
        "PT1H"  # 1-Stunden-Intervalle
      )
      FOR t IN time_range
        LET data = FIRST(
          FOR d IN sensor_data
            FILTER d.timestamp >= DATE_SUBTRACT(t, 30, "minutes")
            FILTER d.timestamp <= DATE_ADD(t, 30, "minutes")
            LIMIT 1
            RETURN d.temperature
        )
        RETURN {
          timestamp: t,
          temperature: data != null ? data : INTERPOLATE(...)
        }

4. AUTOMATISCHE ROLLUPS:

   config/themis.yaml:
     timeseries:
       rollups:
         - name: "hourly_stats"
           source: "sensor_data"
           target: "sensor_data_hourly"
           interval: "1 hour"
           aggregations:
             - field: "temperature"
               functions: ["avg", "min", "max", "stddev"]

5. RETENTION-POLICIES:

   ALTER TIMESERIES COLLECTION sensor_data
     SET RETENTION 90 DAYS
     SET DOWNSAMPLING_POLICY (
       AFTER 30 DAYS AGGREGATE BY 1 HOUR,
       AFTER 90 DAYS AGGREGATE BY 1 DAY
     );

PERFORMANCE-TIPPS:
- Partitionierung nach Zeit für schnellere Queries
- Indizes auf sensor_id + timestamp
- Bulk-Inserts verwenden (1000+ pro Request)
- Materialized Views für häufige Aggregationen

Details: Kapitel 9 (Timeseries-Modell)

Frage 14: "Wie aktiviere ich GPU-Beschleunigung für ML-Workloads?"

RETURN DOCS_CONFIG_HELP('GPU acceleration for ML')

Erwartete Antwort:

GPU-Beschleunigung für ML-Workloads in ThemisDB:

1. VORAUSSETZUNGEN:

   Hardware:
   - NVIDIA GPU (CUDA 11.8+): Tesla V100, A100, H100
   - Mindestens 16 GB VRAM
   - PCIe 4.0 x16

   Software:
   - NVIDIA Driver 525.x+
   - CUDA Toolkit 11.8+
   - cuDNN 8.9+
   - TensorRT (optional, für Inferenz)

2. THEMISDB GPU-SUPPORT AKTIVIEREN:

   config/themis.yaml:
     ml:
       gpu:
         enabled: true
         device_id: 0  # GPU 0 verwenden
         memory_fraction: 0.8  # 80% VRAM für ThemisDB
         allow_growth: true  # Dynamische VRAM-Allokation

3. GPU-BESCHLEUNIGTE OPERATIONEN:

   A) Vector-Similarity-Search (GPU):
      CREATE VECTOR INDEX vec_idx ON documents(embedding)
        DIMENSION 768
        METRIC cosine
        ACCELERATOR gpu;  # GPU-Beschleunigung

      // Query wird automatisch auf GPU ausgeführt
      FOR doc IN documents
        SORT COSINE_SIMILARITY(doc.embedding, @query_vec) DESC
        LIMIT 100
        RETURN doc;

   B) ML-Inferenz (GPU):
      // Model laden
      REGISTER ML_MODEL my_classifier
        FROM "/models/bert_classifier.onnx"
        ACCELERATOR gpu
        BATCH_SIZE 32;

      // Batch-Inferenz
      FOR doc IN documents
        LIMIT 10000
        LET prediction = ML_PREDICT("my_classifier", doc.text)
        UPDATE doc WITH {category: prediction.label} IN documents;

   C) Matrix-Operationen (GPU):
      LET matrix_a = [...];  // 1000x1000 Matrix
      LET matrix_b = [...];
      RETURN MATMUL(matrix_a, matrix_b, {device: "gpu"});

4. MULTI-GPU-SETUP (Cluster):

   config/themis.yaml:
     ml:
       gpu:
         enabled: true
         devices: [0, 1, 2, 3]  # 4 GPUs
         distribution: "data_parallel"  # oder "model_parallel"

5. MONITORING:

   # GPU-Auslastung
   curl http://localhost:8765/metrics/gpu

   # Output:
   # themisdb_gpu_utilization{device="0"} 85.2
   # themisdb_gpu_memory_used{device="0"} 13.5GB
   # themisdb_gpu_temperature{device="0"} 72C

6. PERFORMANCE-BENCHMARKS:

   Operation               | CPU      | GPU (A100) | Speedup
   ----------------------- | -------- | ---------- | -------
   Vector Search (100k)    | 450ms    | 12ms       | 37.5x
   Matrix Multiply (1kx1k) | 850ms    | 8ms        | 106x
   ML Inference (BERT)     | 120ms    | 9ms        | 13.3x
   Embedding Generation    | 2.5s     | 45ms       | 55x

TROUBLESHOOTING:
- CUDA out of memory: memory_fraction reduzieren
- Langsame Inferenz: batch_size erhöhen
- GPU nicht erkannt: nvidia-smi prüfen

Details: Kapitel 16 (ML-Integration), Kapitel 39 (Performance Tuning)

42.9.3.7 Best Practices & Patterns

Frage 15: "Was sind die wichtigsten Performance-Best-Practices?"

RETURN DOCS_QUERY('Performance Best Practices für ThemisDB')

Erwartete Antwort:

Top 10 Performance-Best-Practices für ThemisDB:

1. INDIZIERUNG:
   ✅ DO: Indizes auf Filter- und Sort-Felder
      CREATE INDEX idx_user_email ON users(email);
   ❌ DON'T: Zu viele Indizes (max 5-7 pro Collection)

2. QUERY-OPTIMIERUNG:
   ✅ DO: Filter VOR Joins/Subqueries
      FOR u IN users
        FILTER u.active == true  // Filter zuerst!
        FOR o IN orders
          FILTER o.user_id == u._key
          RETURN o
   
   ❌ DON'T: Subqueries in Projektion
      FOR u IN users
        RETURN {
          user: u,
          orders: (FOR o IN orders FILTER o.user_id == u._key RETURN o)  // LANGSAM!
        }

3. LIMIT & PAGING:
   ✅ DO: Immer LIMIT verwenden
      FOR doc IN collection
        FILTER doc.type == "active"
        LIMIT 100
        RETURN doc
   
   ❌ DON'T: Unbegrenzte Result-Sets
      FOR doc IN collection RETURN doc  // Millionen Rows!

4. BULK-OPERATIONEN:
   ✅ DO: Batch-Inserts (1000+ pro Request)
      INSERT [
        {name: "Alice"},
        {name: "Bob"},
        ... // 1000 Dokumente
      ] INTO users OPTIONS {overwriteMode: "ignore"};
   
   ❌ DON'T: Einzelne Inserts in Schleife
      FOR i IN 1..10000
        INSERT {_key: i} INTO collection  // SEHR LANGSAM!

5. CACHING:
   ✅ DO: Query-Cache für häufige Queries
      FOR doc IN documents
        FILTER doc.category == @category
        OPTIONS {cache: true}
        RETURN doc
   
   config/themis.yaml:
     cache:
       query_cache_size: "4GB"

6. PROJECTION:
   ✅ DO: Nur benötigte Felder zurückgeben
      FOR doc IN documents
        RETURN {id: doc._key, title: doc.title}
   
   ❌ DON'T: Vollständige Dokumente bei großen Feldern
      FOR doc IN documents
        RETURN doc  // inkl. 10MB Binärdaten!

7. PARTITIONIERUNG:
   ✅ DO: Sharding nach Access-Pattern
      CREATE COLLECTION orders SHARD_KEY date;  // Zeit-basiert
   
   ❌ DON'T: Random Sharding bei Zeitreihen

8. AGGREGATIONEN:
   ✅ DO: Materialized Views für häufige Aggregationen
      CREATE VIEW user_stats AS
        FOR u IN users
          COLLECT WITH COUNT INTO total
          RETURN total
   
   ❌ DON'T: COUNT(*) auf großen Collections

9. TRANSACTIONS:
   ✅ DO: Kurze Transaktionen (<100ms)
      BEGIN TRANSACTION
        INSERT ... INTO users
        UPDATE ... IN orders
      COMMIT
   
   ❌ DON'T: Long-Running-Transactions (>10s)

10. MONITORING:
    ✅ DO: Slow-Query-Log aktivieren
       monitoring:
         slow_query_threshold: 100ms  # Log queries >100ms
    
    ✅ DO: EXPLAIN verwenden
       EXPLAIN FOR doc IN documents FILTER doc.field == @val RETURN doc

QUICK-WINS:
- Indizes hinzufügen: +80% schneller
- LIMIT verwenden: +95% schneller
- Bulk-Operationen: +90% schneller
- Query-Cache: +99% schneller (bei Cache-Hit)

Details: Kapitel 34 (Query Optimization), Kapitel 39 (Performance Tuning)

42.9.3.8 Verwendung des Dokumentations-Assistenten

Meta-Frage: "Wie verwende ich den Dokumentations-Assistenten effektiv?"

RETURN DOCS_QUERY('Tipps für effektive Nutzung des Dokumentations-Assistenten')

Erwartete Antwort:

Effektive Nutzung des ThemisDB Dokumentations-Assistenten:

1. FRAGESTELLUNG:

   ✅ GUTE FRAGEN (spezifisch, kontextreich):
   - "Wie konfiguriere ich SSL/TLS mit selbst-signierten Zertifikaten?"
   - "Warum sind meine Vector-Similarity-Queries langsam bei 1M Dokumenten?"
   - "Wie implementiere ich Multi-Tenancy mit Row-Level-Security?"

   ❌ SCHLECHTE FRAGEN (zu allgemein):
   - "Hilfe"
   - "Performance"
   - "Wie funktioniert Datenbank?"

2. KONTEXT ANGEBEN:

   ✅ MIT Kontext:
      "Ich habe 10M Dokumente in einer Collection und meine Aggregations-Query 
       dauert 30 Sekunden. Wie kann ich das optimieren?"

   ❌ OHNE Kontext:
      "Query ist langsam"

3. AQL-FUNKTIONEN NUTZEN:

   // Allgemeine Fragen
   RETURN DOCS_QUERY('Deine Frage hier')

   // Suche mit Relevanz-Ranking
   RETURN DOCS_SEARCH('sharding performance', 10)

   // Konfigurationshilfe
   RETURN DOCS_CONFIG_HELP('backup')

   // Troubleshooting
   RETURN DOCS_TROUBLESHOOT('Server startet nicht - Port 8765 already in use')

4. FOLLOW-UP-FRAGEN:

   ✅ DO: Aufbauende Fragen stellen
      1. "Wie aktiviere ich Sharding?"
      2. "Welche Shard-Keys sind für Zeitreihen optimal?"
      3. "Wie migriere ich bestehende Daten zu geshardeten Collections?"

5. FEHLERME LDUNGEN EINFÜGEN:

   ✅ DO: Vollständige Fehlermeldung kopieren
      RETURN DOCS_TROUBLESHOOT('
        ERROR: Out of memory
        Process: themisdb (PID 12345)
        Memory: 15.8 GB / 16 GB
        Stack trace: ...
      ')

6. ERWEITERTE SUCHE:

   // Nach Kapiteln filtern
   FOR doc IN :document
     FILTER doc.type == 'documentation'
     FILTER CONTAINS(doc.source, 'chapter_16')  // ML-Integration
     FILTER CONTAINS(doc.content, @search_term)
     RETURN doc

   // Multi-Model-Zugriff
   FOR node IN docs_graph_nodes
     FOR edge IN OUTBOUND node docs_graph_edges
       FILTER edge.type == 'related'
       RETURN edge._to

7. RATE-LIMITS BEACHTEN:

   Rolle      | Limit (req/min) | Context Docs
   ---------- | --------------- | ------------
   Admin      | 100             | 10
   Superuser  | 50              | 7
   User       | 20              | 3

8. BEST PRACTICES:

   ✅ DO:
   - Spezifische, klar formulierte Fragen
   - Fehler mit vollständigem Kontext beschreiben
   - AQL-Funktionen für verschiedene Zwecke nutzen
   - Verwandte Kapitel und Dokumente durchlesen

   ❌ DON'T:
   - Mehrere unzusammenhängende Fragen auf einmal
   - Erwartung, dass LLM Code schreibt (nur Anleitung!)
   - Rate-Limits ignorieren
   - Sicherheitskritische Daten in Queries einfügen

9. OFFLINE-ZUGRIFF:

   // Dokumentation auch ohne LLM durchsuchbar
   FOR doc IN :document
     FILTER doc.type == 'documentation'
     FILTER FULLTEXT(doc, @query)
     SORT BM25(doc) DESC
     LIMIT 10
     RETURN {
       title: doc.title,
       source: doc.source,
       snippet: SUBSTRING(doc.content, 0, 200)
     }

RESSOURCEN:
- Kapitel 42: Diese Anleitung
- docs/en/features/DOCS_ASSISTANT.md: Technische Details
- TODO_DOCS_DATABASE_BUILD.md: Roadmap und Features

Feedback & Verbesserungen: github.com/makr-code/ThemisDB/issues

42.10 Zusammenfassung

42.10.1 Feature-Matrix nach Rolle

Feature	Admin	Superuser	User
REST API Query	✅	✅	✅
REST API Config	✅	🟡 Read-Only	❌
REST API Troubleshoot	✅	✅	🟡 Basic
AQL Functions	✅	✅	🟡 Limited
CLI Access	✅	✅	✅
C++ SDK	✅	✅	❌
Max Context Docs	10	7	3
Rate Limit (req/min)	100	50	20
Cache TTL	5 min	10 min	15 min
System Config Docs	✅	❌	❌
Internal Impl Docs	✅	❌	❌

42.10.2 Wichtige Befehle

# Docs-Datenbank generieren
python3 scripts/generate_docs_rocksdb.py

# Query via CLI (AQL)
themis_cli --execute "RETURN DOCS_QUERY('your question here')"

# Query via REST API
curl -X POST /api/v1/llm/docs/query -H "Authorization: Bearer TOKEN" -d '{"query": "..."}'

# Search via AQL
RETURN DOCS_SEARCH('search term', 10)

# Config Help
RETURN DOCS_CONFIG_HELP('topic')

# Troubleshoot
RETURN DOCS_TROUBLESHOOT('error description')

42.10.3 Nächste Schritte

Administratoren: Integrieren Sie den Docs-Assistent in Ihr Monitoring
Superuser: Nutzen Sie AQL-Funktionen für Custom-Workflows
User: Erkunden Sie die interaktive CLI

Weitere Ressourcen:

Kapitel 33: Best Practices
Kapitel 38: Observability & SRE
Kapitel 41: Hands-on Labs
docs/en/features/DOCS_ASSISTANT.md
docs/en/features/DOCS_ROCKSDB_DATABASE.md
TODO_DOCS_DATABASE_BUILD.md

Ende Kapitel 42

ThemisDB 1.9.0-beta · Home · Module-Index · GitHub · Issues

ThemisDB 1.9.0-beta · Home · Wiki-Index · Module-Index · FAQ · Quick-Reference · GitHub · Issues · Discussions · License

Compendium chapter 42 docs assistant usage

Kapitel 42: Dokumentations-Assistent – Verwendung für Admin, Superuser und User

Überblick

42.1 Für Administratoren: Vollständige Systemkontrolle

42.1.0 Konfiguration und Auto-Discovery

42.1.1 Anwendungsfälle für Administratoren

42.1.2 REST API Zugriff (Admin)

Allgemeine Dokumentationsabfrage

Konfigurationshilfe

Troubleshooting-Hilfe

42.1.3 AQL-Funktionen (Admin)

42.1.4 CLI-Zugriff (Admin)

42.1.5 C++ SDK (Admin)

42.2 Für Superuser: Erweiterte Features und Performance

42.2.1 Anwendungsfälle für Superuser

42.2.2 REST API Zugriff (Superuser)

42.2.3 AQL-Funktionen (Superuser)

42.2.4 Performance-Analyse mit Docs-Assistent

42.3 Für User: Grundlegende Dokumentationssuche

42.3.1 Anwendungsfälle für User

42.3.2 REST API Zugriff (User)

42.3.3 CLI-Zugriff (User)

42.3.4 Web-Interface (User) - Geplant

42.4 Berechtigungsmodell und Zugriffskontrolle

42.4.0 YAML-Konfiguration - Detaillierte Dokumentation

42.4.1 RBAC-Integration

42.4.2 API-Key-Basierte Authentifizierung

42.4.3 Audit-Logging

42.5 Rate-Limiting und Resource-Management

42.5.1 Rate-Limits nach Rolle

42.5.2 Konfiguration

42.6 Best Practices und Tipps

42.6.1 Für Administratoren

42.6.2 Für Superuser

42.6.3 Für User

42.7 Troubleshooting und Häufige Probleme

42.7.1 Docs-Datenbank nicht gefunden

42.7.2 Rate-Limit überschritten

42.7.3 Niedrige Konfidenz-Scores

42.8 Monitoring und Metriken

42.8.1 Prometheus-Metriken

42.8.2 Grafana-Dashboard

42.9 Migration und Upgrades

42.9.1 Upgrade von JSON zu RocksDB

42.9.2 Dokumentations-Update

42.9.3 FAQ: Typische Fragen und erwartete Antworten

42.9.3.1 Konfiguration & Setup

42.9.3.2 Troubleshooting & Performance

42.9.3.3 Datenmodellierung & AQL

42.9.3.4 Sicherheit & Compliance

42.9.3.5 Integration & DevOps

42.9.3.6 Erweiterte Features

42.9.3.7 Best Practices & Patterns

42.9.3.8 Verwendung des Dokumentations-Assistenten

42.10 Zusammenfassung

42.10.1 Feature-Matrix nach Rolle

42.10.2 Wichtige Befehle

42.10.3 Nächste Schritte

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!