proximadb-embedded 0.2.2

ProximaDB - High-performance vector database with embedded mode

= ProximaDB
:toc: left
:toclevels: 2
:icons: font

[.lead]
**Developer‑first multi‑model database for vectors, documents, graphs, and observability data**

ProximaDB lets builders store and query embeddings, JSON documents, graph relationships, and
observability logs/metrics in one system. It is optimized for early‑stage product teams who want
one data plane for RAG, code search, recommendation graphs, and telemetry prototypes.

---

== Why Developers Use ProximaDB

* **One API surface** for embeddings, documents, graphs, and observability
* **Unified WAL** for durability across vector, document, and observability writes
* **Multi‑engine storage** tuned for write‑heavy, read‑heavy, or analytics workloads
* **Cross‑model queries** (vector + document + graph + logs) in a single request
* **SQL interface with extensions** - pgvector-compatible `<->` operator, GRAPH_QUERY, DOCUMENT_QUERY

=== Multi-Model: The Key Differentiator

Most vector databases are single-model systems. They excel at vector search but require external systems for graphs, documents, and logs. ProximaDB unifies all data models behind a single SQL interface:

|===
| Capability | Traditional Vector DBs | ProximaDB

| Vector Search | Yes | Yes
| Graph Traversal | No | *Yes* (ORION engine)
| Document Store | No | *Yes* (WAL-backed)
| Observability | No | *Yes* (Logs + Metrics)
| Cross-Model Joins | No | *Yes* (SQL)
| SQL Interface | Limited | *Full SQL + Extensions*
|===

*Example cross-model query:*
[source,sql]
----
-- Find similar products for a user, then get reviews from the document store
SELECT u.name, v.product_id, v.score, d.review_text
FROM users u
JOIN LATERAL VECTOR_SEARCH('products', u.preference_vector, 10) v ON true
JOIN LATERAL DOCUMENT_QUERY('reviews', 'product_id = "' || v.product_id || '"') d ON true;
----

---

== Architecture At A Glance

[source,mermaid]
----
%%{init: {"theme": "neutral"}}%%
flowchart TB
  subgraph API[API Layer]
    UNIFIED[Unified Port :5678
REST + gRPC + Arrow Flight]
    PG[Postgres Wire :5433]
  end

  subgraph Services[Services]
    VEC[Vector Ops]
    DOC[Document Ops]
    GRAPH[Graph Ops]
    OBS[Observability Ops]
    UQ[Unified Query]
  end

  subgraph DataPlane[Data Plane]
    WAL[Unified WAL]
    MEM[Memtables]
    ENG["Vector Engines<br/>(SST, VIPER, HELIX, NOVA)"]
    GRAPHENG["Graph Engine<br/>(ORION)"]
    OBSSTORE["Observability Storage<br/>(partitioned logs, time-series, traces)"]
  end

  API --> Services --> WAL --> MEM
  MEM --> ENG
  MEM --> GRAPHENG
  MEM --> OBSSTORE
----

---

== Performance

*Vector search optimised for single-node, low-latency workloads. Numbers below
are reference points from internal benchmarks on a single arm64 macOS host —
treat as headroom indicators, not a published SLA.*

[.table-striped]
[cols="1,1"]
|===
|Metric|Reference (10M vectors, 768-d, single-node, internal arm64 macOS bench)

|Recall@10|~97% (HNSW, M=32; not an SLA — see SUPPORTED_SURFACE)
|Memory efficiency|~1.2 GB for 10M vectors (PQ-quantised path)
|===

[NOTE]
====
**v0.2 positioning**: this release is a narrow single-node cut. Hybrid retrieval,
document/graph/observability, pgwire/federated SQL, object-economy and
filtered-ANN routes are **Beta**. Distributed cluster execution, full SQL parity,
external-table execution, Arrow Flight as a customer-facing transport, the
SWIFT/RAPTOR storage engines, and conditional/filter writes are
**Experimental** and must not be inferred from the numbers above. (The PULSAR and
QUASAR graph engine names are *retired* — use ORION.) See
link:docs/SUPPORTED_SURFACE.adoc[`docs/SUPPORTED_SURFACE.adoc`] for the support
contract and
link:docs/release-notes/v0.2.0.adoc[`docs/release-notes/v0.2.0.adoc`] for the
release split.
====

* link:docs/10-quality/benchmarks/BENCHMARKS.adoc[Detailed benchmark notes] — methodology, hardware, scaling characteristics
* link:docs/10-quality/benchmarks/ENGINE_PERFORMANCE_BENCHMARK.adoc[Engine performance] — storage-engine benchmarks
* link:docs/_internal/status/OBJECT_ECONOMY_BENCH_REPORT_2026_05_28.adoc[Object-economy bench report (2026-05-28)] — building-block CPU costs
* link:scripts/run_benchmarks.sh[Run benchmarks yourself] — reproduction script

---

== Quick Start

=== Platform Packages (Linux/Windows)

[source,bash]
----
# Linux (RPM - RHEL/CentOS/Fedora)
sudo rpm -ivh proximadb-0.2.0-1.el8.x86_64.rpm
sudo systemctl start proximadb

# Linux (DEB - Debian/Ubuntu)
sudo dpkg -i proximadb_0.2.0_amd64.deb
sudo systemctl start proximadb

# Windows
msiexec /i proximadb-0.2.0-x64.msi
----

See link:docs/02-guides/platform-packages.md[Platform Packages Guide] for details.

=== Docker

[source,bash]
----
docker run -it --rm \
  -p 5678:5678 \
  -p 5433:5433 \
  vjsingh1984/proximadb:latest
----

=== From Source (Rust)

[source,bash]
----
git clone https://github.com/vjsingh1984/proximaDB
cd proximaDB
cargo run --release --bin proximadb-server
----

---

== Core Models

=== Vectors
Embeddings + metadata with similarity search and filtering.

=== Documents
JSON documents with WAL‑backed durability and indexed paths (read path is in‑memory today).

=== Graphs
Nodes/edges with traversal support (ORION engine default).

=== Observability
Logs and metrics with WAL‑backed ingestion, partitioned storage, and aggregation.

---

== API Examples (REST)

=== Vector Search

[source,bash]
----
curl -X POST http://localhost:5678/api/v2/collections/docs/search \
  -H "Content-Type: application/json" \
  -d '{
    "query_vector": [0.1, 0.2, 0.3],
    "top_k": 10,
    "filters": [
      {"field": "category", "op": "eq", "value": "tech"}
    ]
  }'
----

=== Document Insert

[source,bash]
----
curl -X POST http://localhost:5678/api/v2/document-collections/docs/documents \
  -H "Content-Type: application/json" \
  -d '{
    "document": {"title": "Runbook", "service": "api", "severity": "warn"}
  }'
----

=== Graph Traverse

[source,bash]
----
curl -X POST http://localhost:5678/api/v2/graphs/topology/traverse \
  -H "Content-Type: application/json" \
  -d '{
    "start_node_id": "service-api",
    "max_depth": 2
  }'
----

=== Log Ingestion

[source,bash]
----
curl -X POST http://localhost:5678/api/v2/observability/namespaces/prod/logs \
  -H "Content-Type: application/json" \
  -d '{
    "message": "request failed",
    "severity": "error",
    "service": "api"
  }'
----

=== Federated SQL Query (Multi-Model)

[source,bash]
----
curl -X POST http://localhost:5678/api/v2/unified/federated \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM VECTOR_SEARCH('\''products'\'', '\''[0.1, 0.2, 0.3]'\'', 10)"
  }'
----

---

== SQL Extensions

ProximaDB extends standard SQL with functions for each data model:

=== Vector Search

[source,sql]
----
-- pgvector-compatible distance operator
SELECT * FROM products ORDER BY embedding <-> '[0.1,0.2,...]'::vector LIMIT 10;

-- Explicit function call
SELECT * FROM VECTOR_SEARCH('products', '[0.1, 0.2, 0.3]', 10);
----

=== Graph Traversal

[source,sql]
----
-- Embedded Cypher syntax
SELECT * FROM GRAPH_QUERY('MATCH (a:Person)-[:KNOWS]->(b) RETURN b.name');

-- Find friends-of-friends
SELECT * FROM GRAPH_QUERY('MATCH (a:Person {name: "Alice"})-[:KNOWS*2]->(fof) RETURN fof');
----

=== Document Query

[source,sql]
----
-- Query with JSON path filter
SELECT * FROM DOCUMENT_QUERY('orders', 'status = "pending"');
----

=== Observability

[source,sql]
----
-- Query logs
SELECT * FROM LOGS('production') WHERE timestamp > now() - interval '1h';

-- Query metrics
SELECT * FROM METRICS('system') WHERE metric_name = 'cpu_usage';
----

=== Cross-Model Joins

[source,sql]
----
-- Vector + Document: Similar products with reviews
SELECT v.product_id, v.score, d.review_text
FROM VECTOR_SEARCH('products', '[0.1,0.2]', 10) v
JOIN LATERAL DOCUMENT_QUERY('reviews', 'product_id = "' || v.product_id || '"') d ON true;

-- Vector + Graph: Similar items filtered by category relationships
SELECT * FROM VECTOR_SEARCH('products', '[0.1,0.2]', 100)
WHERE id IN (
  SELECT target FROM GRAPH_QUERY('MATCH (:Category {name:"Electronics"})-[:CONTAINS]->(p) RETURN p.id')
);

-- Logs + Graph: Errors with service dependencies
SELECT l.timestamp, l.message, g.dependency
FROM LOGS('errors') l
JOIN LATERAL GRAPH_QUERY('MATCH (s:Service {name: "' || l.service || '"})-[:DEPENDS_ON]->(d) RETURN d.name as dependency') g ON true;
----

---

== Feature Status (Builder View)

Statuses use the support-contract ladder from
link:docs/SUPPORTED_SURFACE.adoc[`docs/SUPPORTED_SURFACE.adoc`]:
*Supported* / *Beta* / *Experimental* / *Planned*.

|===
| Capability | Status | Notes

| Vector search + filters | Supported | 4 supported storage engines (SST/VIPER/HELIX/NOVA) + AXIS (HNSW/IVF) indexes, metadata filters
| Document store | Beta | WAL‑backed, JSON path queries, full‑text search; canonical record storage is the convergence path
| Graph traversal | Beta | ORION (in‑memory CSR), WAL persistence, algorithms; some v1-only RPCs deferred
| Observability logs | Beta | WAL‑backed, partitioned storage, 6 SIEM adapters
| Observability metrics | Beta | Time‑series aggregation, downsampling
| Unified multi‑model query | Beta | Cross‑model joins, parallel execution; strongest on function-backed sources
| Postgres wire protocol | Supported | ANSI SQL for SQL clients (psql/JDBC/ORM), transactions, pgvector-compatible operator; full Postgres/SQL parity remains Experimental
| Unified port mode | Experimental | Arrow Flight / gRPC service multiplexing is an experimental customer-facing transport
| Web UI dashboard | Beta | SQL editor, graph visualization, dark/light theme; fronts Beta surfaces
| Python SDK | Beta | Graph analytics, AutoML, observability, security; wraps Beta surfaces
|===

Authoritative status: link:docs/SUPPORTED_SURFACE.adoc[`docs/SUPPORTED_SURFACE.adoc`] — where
this table and that contract disagree, the contract wins.

NOTE: Tier detail lives in link:docs/SUPPORTED_SURFACE.adoc[`docs/SUPPORTED_SURFACE.adoc`]. A
few capabilities in the tree are *not* in the supported surface above: the SWIFT and RAPTOR
storage engines are **experimental** (off by default behind the `experimental-engines` cargo
feature), Arrow Flight is an **experimental** customer-facing transport, and distributed
cluster execution is **experimental**.

---

== Web UI Dashboard

ProximaDB includes a built‑in React dashboard for data exploration:

[source,bash]
----
cd ui && npm install && npm start
----

Features:

* **SQL Query Editor** - Monaco editor with ProximaDB syntax highlighting
* **Graph Explorer** - Cytoscape.js visualization with multiple layouts
* **System Metrics** - Real‑time performance monitoring
* **Dark/Light Theme** - Toggle between themes

---

== Documentation

* link:docs/README.md[Documentation] - Complete documentation with infographic guides
* link:docs/01-quick-start/[Quick Start] - Get running in 5 minutes
* link:docs/02-guides/[Guides] - Vector search, multi-model joins, platform packages
* link:docs/05-concepts/[Concepts] - Storage engines, graph engines, WAL architecture
* link:docs/03-api-reference/[API Reference] - REST, gRPC, PostgreSQL wire, Python SDK
* link:docs/04-operations/[Operations] - Deployment, monitoring, security
* link:docs/06-internals/[Internals] - Contributing, testing, architecture decisions

**v0.2.0 Release** (June 2026):
* Platform packages: link:docs/02-guides/platform-packages.md[RPM, DEB, MSI]
* Unified port architecture (single port 5678)
* Multi-model query engine with cross-model joins

**Key Guides**:
* link:docs/02-guides/vector-search.md[Vector Search] - Semantic search, filtering, hybrid search
* link:docs/02-guides/multi-model-joins.md[Multi-Model Joins] - Cross-model SQL queries
* link:docs/05-concepts/storage-engines.adoc[Storage Engines] - SST, VIPER, HELIX, NOVA (SWIFT/RAPTOR experimental)
* link:docs/06-internals/GRAPH_ENGINES_GUIDE.adoc[Graph Engines Guide] - ORION

---

== License

Apache License 2.0 - See link:LICENSE[LICENSE]

Open-core boundary: the full single-node engine is free forever with no feature gates — see link:OPEN_CORE.md[OPEN_CORE.md] for what the commercial layer sells (operations, never features).