HelixDB Docs

Guide

Embedded clients execute operation-tree requests without HTTP. The process opens a writer or read-only handle against memory, disk, or S3-compatible object storage.

Install

Install the forthcoming v3 SDK and its embedded runtime package. These package commands describe the upcoming release and are not expected to resolve before the v3 SDKs are published.

cargo add helix-db@3.0.0 --features embedded

npm install @helix-db/helix-db@3.0.0 @helix-db/uniffi

go get github.com/helixdb/helix-db/sdks/go

python -m pip install helix-db helix-db-embedded

Open a writer

use helix_db::{Client, HelixDbSource};

let client = Client::open(HelixDbSource::Disk {
    root: "/data/helix".into(),
    database: "app".to_string(),
})
.await?;

const client = await Client.embedded({
  kind: "disk",
  root: "/data/helix",
  database: "app",
});

client, err := helix.NewEmbeddedClient(
	helix.DiskSource{Root: "/data/helix", Database: "app"},
)
if err != nil {
	return err
}

from helixdb import Client, Disk

client = Client.embedded(Disk("/data/helix", "app"))

Choose a storage source

Source	Persistence	Use
In-memory	Process-local	Tests, scratch data, and short-lived tools
Disk	Filesystem path	Persistent single-host applications
Object storage	Bucket and logical database path	Durable shared storage with an S3-compatible service

const client = await Client.embedded({
  kind: "inMemory",
  database: "app",
});

const client = await Client.embedded({
  kind: "disk",
  root: "/data/helix",
  database: "app",
});

const client = await Client.embedded({
  kind: "objectStorage",
  database: "app",
  bucket: "helix-production",
  region: "eu-west-2",
});

Configure caches

Cache configuration is optional and fixed when the handle opens. Omit it to use these defaults:

Setting	Default
Profile	Memory
Vector memory	256 MiB, hydrated and refreshed in the background
SlateDB	Default in-memory block and metadata caches, warmed in the background
Full-text search	64 MiB in-memory split cache, warmed in the background
Disk cache	Disabled

Pass an explicit cache configuration to change the vector-memory budget or enable bounded disk caches:

Profile	Behavior
Memory	Uses in-memory database caches
Hybrid	Adds bounded disk caches with explicit paths and byte budgets

const client = await Client.embedded(
  { kind: "disk", root: "/data/helix", database: "app" },
  {
    vectorMemoryBytes: 512 * 1024 * 1024,
    mode: { kind: "memory" },
  },
);

const client = await Client.embedded(
  { kind: "disk", root: "/data/helix", database: "app" },
  {
    vectorMemoryBytes: 512 * 1024 * 1024,
    mode: {
      kind: "hybrid",
      slateMemoryBytes: 256 * 1024 * 1024,
      slateDiskPath: "/var/cache/helix/slate",
      slateDiskBytes: 4 * 1024 * 1024 * 1024,
      objectStoreDiskPath: "/var/cache/helix/objects",
      objectStoreDiskBytes: 8 * 1024 * 1024 * 1024,
    },
  },
);

Cache byte budgets bound those caches. They are not a hard cap on total process RSS; requests and index work can allocate transient memory.

Open a read-only database

Use a read-only handle for processes that must never mutate the database. It opens an existing disk or object-storage database, executes read requests, and rejects writes.

use helix_db::{Client, HelixDbSource};

let reader = Client::open_reader(HelixDbSource::Disk {
    root: "/data/helix".into(),
    database: "app".to_string(),
})
.await?;

const reader = await Client.embeddedReader({
  kind: "disk",
  root: "/data/helix",
  database: "app",
});

reader, err := helix.NewEmbeddedReaderClient(
	helix.DiskSource{Root: "/data/helix", Database: "app"},
)
if err != nil {
	return err
}

from helixdb import Client, Disk

reader = Client.embedded_reader(Disk("/data/helix", "app"))

Embedded request rules

Use the same QueryRequest and response contract as server mode.
Writer handles can execute read and write requests.
Server routing options such as writer-only, warm-only, API headers, and durability headers are rejected because there is no gateway.
Reopen the same disk or object-storage source to retain canonical data across process lifetimes.

Start Here

Core Concepts

Query Guides

Embedded database

Install

Open a writer

Choose a storage source

Configure caches

Open a read-only database

Embedded request rules

Next steps

Local server

Deployment options

​Install

​Open a writer

​Choose a storage source

​Configure caches

​Open a read-only database

​Embedded request rules

​Next steps

Local server

Deployment options

Install

Open a writer

Choose a storage source

Configure caches

Open a read-only database

Embedded request rules

Next steps