Skip to content

Latest commit

 

History

History
317 lines (244 loc) · 10.1 KB

FAQ.md

File metadata and controls

317 lines (244 loc) · 10.1 KB

Frequently Asked Questions (FAQ)

Table of Contents

General

What is ThemisDB?

ThemisDB is a high-performance multi-model database that combines relational, graph, vector, and document models in a single system with full ACID transaction support. It's built on RocksDB for reliability and includes optional native LLM integration.

How does ThemisDB differ from other databases?

ThemisDB uniquely combines:

  • Multiple data models (relational, graph, vector, document) in one unified system
  • Full ACID transactions with MVCC
  • Optional native LLM integration (llama.cpp)
  • GPU-accelerated vector search
  • Production-ready performance (45K writes/s, 120K reads/s)

Which edition should I use?

  • Minimal Edition: Embedded systems, IoT, edge devices (core database only)
  • Community Edition: Development, startups, single-server deployments (full-featured)
  • Enterprise Edition: Large-scale production with horizontal scaling, HA, and replication

Is ThemisDB production-ready?

Yes! The Community Edition is production-ready for single-node deployments. The Enterprise Edition adds horizontal scaling and high availability for large-scale production environments.

Installation & Setup

What are the system requirements?

Minimum:

  • CPU: 2 cores
  • RAM: 4 GB
  • Storage: 10 GB SSD
  • OS: Linux (Ubuntu 20.04+), macOS (10.15+), Windows (10+)

Recommended:

  • CPU: 8+ cores
  • RAM: 16+ GB
  • Storage: 100+ GB NVMe SSD
  • OS: Linux (Ubuntu 22.04+)

How do I install ThemisDB?

Docker (Recommended):

docker pull themisdb/themisdb:latest
docker run -d -p 8080:8080 -v themis_data:/data themisdb/themisdb:latest

From Source:

git clone https://github.com/makr-code/ThemisDB.git
cd ThemisDB
./scripts/setup.sh
./scripts/build.sh
./build/themis_server --config config.yaml

See the Quick Start guide for more options.

What ports does ThemisDB use?

  • 8080: HTTP/REST API, GraphQL
  • 18765: Binary Wire Protocol, gRPC
  • 4318: OpenTelemetry/Prometheus metrics

See docs/de/deployment/PORT_REFERENCE.md for complete details.

Can I run ThemisDB on ARM64/Apple Silicon?

Yes! ThemisDB supports ARM64 architecture including Apple Silicon (M1/M2/M3). Use the appropriate build configuration or Docker image for your platform.

How do I upgrade ThemisDB?

  1. Backup your data directory
  2. Stop the current server
  3. Install the new version
  4. Start the server with the same data directory

ThemisDB handles data migration automatically when needed.

Performance

What performance can I expect?

Typical performance (release build, 20 cores @ 3.7 GHz):

  • Entity PUT: 45,000 ops/s
  • Entity GET: 120,000 ops/s
  • Indexed Query: 3.4M queries/s
  • Graph Traverse: 9.56M ops/s
  • Vector Search: 59.7M queries/s

Actual performance varies based on hardware, data size, and workload complexity.

How do I optimize performance?

  1. Use SSDs (preferably NVMe) for storage
  2. Allocate sufficient memory (recommend 16+ GB)
  3. Enable appropriate indexes for your query patterns
  4. Use GPU acceleration for vector search (if available)
  5. Tune RocksDB settings in configuration

See docs/de/performance/performance_memory.md for detailed tuning.

Does ThemisDB support GPU acceleration?

Yes! ThemisDB supports GPU acceleration for:

  • Vector similarity search (CUDA-enabled GPUs)
  • Some LLM operations (when LLM feature is enabled)

GPU support is optional and automatically detected at runtime.

How much memory does ThemisDB need?

Memory requirements depend on:

  • Base system: 2-4 GB
  • Data working set: 1-2x your active dataset size for optimal performance
  • Index structures: Varies by index type and data size
  • LLM (optional): 4-16 GB depending on model size

For production, we recommend 16+ GB RAM.

Features & Capabilities

What query languages does ThemisDB support?

ThemisDB uses AQL (Advanced Query Language), which supports:

  • SQL-like syntax for relational operations
  • Graph traversal operations (BFS, Dijkstra, A*)
  • Vector similarity search
  • Document operations with JSON

See docs/de/aql/aql_syntax.md for syntax reference.

Does ThemisDB support transactions?

Yes! ThemisDB provides:

  • Full ACID guarantees
  • Snapshot isolation (MVCC)
  • Write-write conflict detection
  • Atomic updates across all index types

Can I use multiple data models in the same transaction?

Yes! ThemisDB's unified storage engine allows you to combine relational, graph, vector, and document operations in a single ACID transaction.

What vector search algorithms are supported?

ThemisDB supports:

  • HNSW (Hierarchical Navigable Small World): Fast approximate nearest neighbor search
  • FAISS: GPU-accelerated similarity search
  • Multiple distance metrics: Euclidean, Cosine, Inner Product

Does ThemisDB support full-text search?

Yes! ThemisDB includes full-text search capabilities with support for:

  • Tokenization and stemming
  • Boolean operators
  • Phrase matching
  • Relevance scoring

What security features are included?

ThemisDB includes:

  • TLS 1.3 with mutual TLS (mTLS) support
  • Role-Based Access Control (RBAC)
  • Field-level encryption (AES-256-GCM)
  • Audit logging with SIEM integration
  • Input validation and SQL injection prevention

See docs/de/security/security_implementation.md for details.

Development

What programming languages can I use with ThemisDB?

ThemisDB provides:

  • REST API: Any language with HTTP support
  • GraphQL: Any GraphQL client
  • gRPC: Multiple language bindings
  • Native SDKs: C++, Python, JavaScript, Go, Java

See clients/README.md for SDK details.

How do I contribute to ThemisDB?

We welcome contributions! Please:

  1. Read the Contributing Guide
  2. Check Good First Issues
  3. Follow our Code of Conduct
  4. Submit a pull request

Where can I find API documentation?

How do I run tests?

# Run all tests
cmake --build build --target test

# Run specific test suite
./build/tests/themis_tests --gtest_filter=VectorIndex*

# Run benchmarks
./build/benchmarks/themis_benchmarks

What build systems are supported?

ThemisDB uses CMake as the primary build system with support for:

  • Make (Unix/Linux)
  • Ninja (all platforms)
  • MSBuild (Windows)
  • Xcode (macOS)

Troubleshooting

ThemisDB won't start. What should I check?

  1. Check if ports 8080 or 18765 are already in use
  2. Verify configuration file syntax (config.yaml)
  3. Check disk space (need at least 1 GB free)
  4. Review logs in logs/ directory
  5. Ensure proper file permissions on data directory

How do I enable debug logging?

Edit config.yaml:

logging:
  level: debug
  file: logs/themis.log

Or set environment variable:

export THEMIS_LOG_LEVEL=debug

I'm getting "out of memory" errors. What should I do?

  1. Increase system RAM or reduce memory limits in config
  2. Reduce RocksDB block cache size
  3. Disable LLM features if not needed
  4. Use the Minimal Edition for lower memory usage
  5. Check for memory leaks (enable memory profiling)

Vector search is slow. How can I improve it?

  1. Ensure proper index type (HNSW recommended)
  2. Enable GPU acceleration if available
  3. Tune HNSW parameters (M, ef_construction)
  4. Consider reducing vector dimensions
  5. Check if CPU is bottleneck (add more cores)

How do I backup my data?

Online backup (recommended):

curl -X POST http://localhost:8080/admin/backup

Offline backup:

  1. Stop ThemisDB server
  2. Copy the entire data directory
  3. Restart server

See docs/de/guides/guides_deployment.md for details.

Where can I get help?

Licensing

What license is ThemisDB under?

  • Community Edition: MIT License (free, open source)
  • Enterprise Edition: Commercial license

See LICENSE for details.

Can I use ThemisDB in commercial projects?

Yes! The Community Edition (MIT License) allows commercial use, modification, and distribution. The Enterprise Edition is available for large-scale deployments requiring additional features.

What's the difference between Community and Enterprise editions?

Feature Community Enterprise
Core Database ✅ ✅
Single-Node ✅ ✅
Horizontal Sharding ❌ ✅
High Availability ❌ ✅
Auto-Rebalancing ❌ ✅
Multi-Region ❌ ✅
Support SLA ❌ ✅

See docs/reports/ENTERPRISE.md for Enterprise details.

How do I get an Enterprise license?

Contact us at: sales@themisdb.com

Additional Resources

Didn't find your answer? Ask a question in GitHub Discussions