Start free
← All posts

OriginChainDB quickstart in five minutes

OriginChainDB Team · May 5, 2026
tutorial quickstart sdk getting-started vector-search

TL;DR - Provision an OriginChainDB instance from the dashboard, install the SDK, then write a JSON payload and its vector embedding in one atomic transaction and read the record back by similarity search. No infrastructure, no schema migration, no glue code - the shape declaration is the schema.

What you’ll need

That’s it. No Docker, no provisioning scripts, no CLI auth dance.

Step 1 - Provision an instance

Sign in at originchaindb.com/login, click + New instance on the dashboard, name it (e.g. dev-1), and pick a region. The smallest configuration is what the free database gives you - adequate for everything in this guide.

Provisioning takes under two minutes. When the status flips to running, you’ll see the instance card show an HTTPS endpoint that looks like:

https://abc123def.originchain.ai

Copy that. It’s your tenant endpoint.

Click the instance to drill in, then API keys → + New key. Copy the key (shown once). This is your bearer token for everything below.

Step 2 - Install the SDK

# Node / TypeScript
npm install @originchain/sdk

# Python
pip install originchain

Both clients are thin wrappers over the HTTP API - if your stack isn’t covered, the OpenAPI spec is auto-generated and works with any client generator.

Step 3 - Connect

import { OriginChainClient } from "@originchain/sdk";

const oc = new OriginChainClient({
 baseUrl: process.env.OC_ENDPOINT!, // from step 1
 bearer: process.env.OC_API_KEY!, // from step 1
});

await oc.health; // → { ok: true }
from originchain import OriginChain

oc = OriginChain(
 endpoint=os.environ["OC_ENDPOINT"],
 api_key=os.environ["OC_API_KEY"],
)
oc.health # → {"ok": True}

Step 4 - Declare a shape

A key shape describes how a logical entity maps onto the substrate. We’re modelling articles with text + a vector embedding:

await oc.shapes.create({
 shape: "article",
 key: "article/{id}",
 value: {
 title: { type: "string", indexed: true },
 body: { type: "string" },
 author: { type: "string" },
 },
});

await oc.shapes.create({
 shape: "article-embedding",
 key: "vec/article/{id}/body",
 value: { type: "f32", dim: 768 },
});

That’s it. No DDL, no migration. The shape is the schema.

(For more on shapes, see Schemas.)

Step 5 - Write a record

const article = {
 id: "intro-to-rag",
 title: "Introduction to RAG",
 body: "Retrieval-augmented generation is a technique for...",
 author: "Lalith",
};

const embedding = await yourEmbeddingModel(article.body); // 768-dim f32

await oc.transaction([
 { shape: "article", id: article.id, set: article },
 { shape: "article-embedding", id: article.id, set: embedding },
]);

Both writes - the JSON record and the vector - commit in the same atomic operation. Either both make it durable or neither does. That’s the point of one substrate: every shape sees the row, or none do.

(For more on the atomicity guarantee, see Transactions.)

Step 6 - Read it back

Direct read by id:

const a = await oc.get("article", "intro-to-rag");
// → { id: "intro-to-rag", title: "...", body: "...", author: "Lalith" }

Lookup by indexed attribute:

const found = await oc.findOne("article", { title: "Introduction to RAG" });
// → same article

Vector similarity search:

const queryVec = await yourEmbeddingModel("how does retrieval-augmented generation work");

const matches = await oc.vectorSearch("article-embedding", {
 query: queryVec,
 top_k: 5,
});
// → [{ id: "intro-to-rag", distance: 0.18 },...]

// Hydrate matched articles
const articles = await Promise.all(
 matches.map((m) => oc.get("article", m.id))
);

That’s the loop. JSON payload + vector + similarity search, all atomic, all from one client.

Step 7 - Wire it into your app

Most AI features fit one of three patterns at this point:

Personalized retrieval - embed user queries, ANN-search a content corpus, hydrate the top hits. Steps 5-6 are the loop; the rest is your prompt-engineering taste.

Tool-call memory - every tool call your agent makes writes a record + a vector. Future calls can search the past for “have we tried this before?”.

Live feature stores - every user event writes a record; your model reads the most recent N at inference time. Last-writer-wins handles concurrent updates correctly without retry loops.

Going to production

When you flip from the free database to a paid plan, three things change:

There’s no migration step. The instance you started on the free database is the instance you keep.

FAQ

How fast is this in practice?

Single-record reads are sub-millisecond from a co-located client. Writes are ~280 µs at the 50th percentile under sustained load. Vector search latency depends on corpus size - around 5 ms at 10M vectors with default ANN settings.

Do I need to manage the database?

No. OriginChainDB is managed-cloud only. You don’t see the underlying compute, you don’t run the upgrades, you don’t tune storage internals. You write records and read them back.

What languages have official SDKs?

TypeScript/JavaScript and Python today. Go and Rust are next on the SDK roadmap. The HTTP API is documented as OpenAPI so any code generator works in the meantime.

Can I run this locally for dev?

The substrate is a managed service; there’s no self-hosted binary. For local dev, hit the free database - it costs nothing, and dev tenants are sized for $0.50/day once you outgrow it.

What if I need to change the shape?

Add a field to a value-side schema and old records keep working with the new field defaulting to null. Renames and type changes are version-bumped: declare a new shape version, the substrate runs a dual-read transform during cutover, no downtime.

← All posts Subscribe to RSS →