proximadb-embedded 0.4.1

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

[.lead]
**Object-storage-native context serving for SQL, JSON, and vectors**

ProximaDB's MVP gives AI application teams one typed record and one canonical REST API for
metadata-aware vector retrieval. The broader document, graph, time-series, event, observability,
and SQL-extension architecture remains the product direction, but it graduates only through the
link:docs/00-product/MVP_TRUST_CORRIDOR.toml[machine-checked MVP trust corridor].

---

== Why Developers Use ProximaDB

* **One canonical record** for an identifier, typed JSON properties, and an embedding
* **One supported API path** for create, batch write, get, scan, vector search, and delete
* **Metadata filters on both scan and vector search**, proven by the same first-run smoke
* **SST as the safe default**, backed by the canonical WAL on the single-node path
* **Object-storage-aware internals** with measured request, byte, cache, and compute signals

=== Context Serving: The MVP Differentiator

Modern vector systems increasingly include document payloads, metadata filters, hybrid search,
and distributed operation. ProximaDB therefore does not differentiate by pretending those features
are absent. Its wager is narrower: one typed context record, served through standard interfaces,
with workload-specific projections and object-economics evidence behind it.

|===
| Capability | MVP trust corridor | Broader ProximaDB direction

| Typed context records | *Supported* | Canonical authority for every modality
| Metadata scan + vector search | *Supported* | Hybrid and cross-modal retrieval
| SST single-node storage | *Supported* | Object-storage-aware projection placement
| pgwire SQL subset | Beta | Wider relational/context query surface
| Document, graph, observability | Beta | Rebuildable projections over canonical records
| Distributed execution | Excluded | Evidence-gated post-MVP capability
|===

*Beta vision example — outside the MVP trust corridor:*
[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]
    REST[Canonical REST v2]
    BETA[Beta gRPC / pgwire / multimodel APIs]
  end

  subgraph Services[Services]
    RECORD[Typed Context Record Ops]
    PROJ[Beta Projection Services]
  end

  subgraph DataPlane[Data Plane]
    WAL[Canonical WAL]
    MEM[Memtables]
    SST["SST / PAX<br/>(Supported default)"]
    BETAENG["Graph / document / observability / alternate engines<br/>(Beta; recovery parity incomplete)"]
  end

  REST --> RECORD --> WAL --> MEM --> SST
  BETA -.-> PROJ -.-> BETAENG
----

---

== 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% (historical internal HNSW reference; 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

The supported first-run path is Docker plus the canonical v2 smoke. It fails on any incorrect
status, missing record, filter leak, unsupported write-contract signal, or deprecated route.

[source,bash]
----
docker run --rm -d --name proximadb-mvp -p 5678:5678 vjsingh1984/proximadb:latest
python3 scripts/mvp_smoke.py --base-url http://127.0.0.1:5678
----

See link:docs/01-quick-start/CONTEXT_SERVING_MVP.adoc[Context Serving MVP Quickstart] for the
verified request sequence and production caveats. Release archives currently cover Linux x86_64
(glibc) and Windows x86_64; the release page is authoritative for available assets.

=== From Source (Rust)

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

---

== Core Models

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

=== Documents
Beta JSON/document projection; canonical-record convergence and recovery parity are incomplete.

=== Graphs
Beta nodes/edges and traversal through ORION; shared-WAL replay parity is incomplete.

=== Observability
Beta logs, metrics, and traces with modality-specific ingestion and incomplete canonical recovery.

---

== 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 | SST is the supported storage engine; VIPER/HELIX/NOVA are Beta. AXIS (HNSW/IVF) indexes and 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), autocommit statements, pgvector-compatible operator; transaction control returns `0A000` and 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   # Vite dev server on :3000, proxies /api to :5678
----

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).

== Branching and Releases

- `develop` is the integration branch: feature branches open PRs into `develop` (CI-gated).
- Promotion is staged: `develop` -> `qa` (staging validation) -> `main` (release); releases are tagged on `main`.
- `qa` and `main` always reflect promoted states; nothing merges directly to either without passing through the previous stage.