01 · quickstart

Quickstart — OriginChain in five minutes.

OriginChain is an AI-native database that runs SQL, vector search, BM25 full-text, and graph traversal on one managed endpoint. In the next five minutes you will provision an instance, register a schema, insert a row, and run all four query shapes against it — plus wire up the Python SDK. curl and Python are shown side by side at every step. See core concepts for the substrate model or /architecture for the full picture.

Examples in this page use

Endpoint

acme.ap-south-1.db.originchain.ai

Tenant ID (ULID)

acme

Sign up and grab a bearer.

Head to /signup for a 7-day trial — no card required during the trial. Pick a region (your data never leaves it) and a tier. Provisioning averages ~90 seconds. The console shows your endpoint and a one-time bearer token.

export OC_HOST=acme.ap-south-1.db.originchain.ai
export OC_TENANT=acme
export OC_TOKEN=oc_live_7f3...bc2     # one-shot, store in your secrets manager

Register a schema.

Schemas are TOML manifests. This one declares an orders table with a status index, a full-text extraction on notes, and a vector extraction on embedding.

schemas/orders.toml

name    = "orders"
version = 1

[[columns]]
name = "id"        ; type = "ulid"     ; pk = true
[[columns]]
name = "customer"  ; type = "ulid"
[[columns]]
name = "amount"    ; type = "decimal"
[[columns]]
name = "status"    ; type = "string"
[[columns]]
name = "notes"     ; type = "string"
[[columns]]
name = "embedding" ; type = "vector"   ; dim = 8 ; metric = "cosine"
[[columns]]
name = "placed"    ; type = "timestamp"

[[indexes]]
columns = ["status"]

[[extractions.fts]]
field    = "notes"
analyzer = "english"

[[extractions.vector]]
field = "embedding"

POST /v1/tenants/:t/schema

curl -X POST "https://acme.ap-south-1.db.originchain.ai/v1/tenants/acme/schema" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/toml" \
  --data-binary @schemas/orders.toml

from originchain import Client

oc = Client(
    base_url="https://acme.ap-south-1.db.originchain.ai",
    tenant="acme",
    token=os.environ["OC_TOKEN"],
)

with open("schemas/orders.toml") as f:
    oc.schema.put(f.read())

Insert a row.

The same write covers the row store, the status index, the FTS posting list, and the vector index — atomically, behind one WAL fsync. Idempotency-Key is honoured for at-least-once retries.

POST /v1/tenants/:t/rows/:schema

curl -X POST "https://acme.ap-south-1.db.originchain.ai/v1/tenants/acme/rows/orders" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c4f...e1" \
  -d '{
    "id":       "01JTRX9KQ3YH8K2WMX0F5JZAB7",
    "customer": "01JTRX1H4Q9P0N2WMX0F5JZ001",
    "amount":   "129.50",
    "status":   "paid",
    "notes":    "rush delivery, signed by recipient",
    "embedding": [0.12, -0.04, 0.91, 0.33, -0.18, 0.05, 0.42, -0.27],
    "placed":   "2026-04-30T11:14:09Z"
  }'

oc.rows("orders").put({
    "id":       "01JTRX9KQ3YH8K2WMX0F5JZAB7",
    "customer": "01JTRX1H4Q9P0N2WMX0F5JZ001",
    "amount":   "129.50",
    "status":   "paid",
    "notes":    "rush delivery, signed by recipient",
    "embedding": [0.12, -0.04, 0.91, 0.33, -0.18, 0.05, 0.42, -0.27],
    "placed":   "2026-04-30T11:14:09Z",
})

Read it back.

Hash-keyed lookup by primary key — single key fetch, no plan compile, no LLM. The response includes the internal _oc_row_version field for optimistic CAS.

GET /v1/tenants/:t/rows/:schema/:pk

curl "https://acme.ap-south-1.db.originchain.ai/v1/tenants/acme/rows/orders/01JTRX9KQ3YH8K2WMX0F5JZAB7" \
  -H "Authorization: Bearer $OC_TOKEN"

row = oc.rows("orders").get("01JTRX9KQ3YH8K2WMX0F5JZAB7")
print(row["status"], row["amount"])

Run a SELECT.

Full SQL surface: SELECT, WHERE, projections, GROUP BY, HAVING, ORDER BY, LIMIT, plus INNER / LEFT / RIGHT / FULL OUTER joins (left-deep, up to 5 tables).

POST /v1/tenants/:t/sql

curl -X POST "https://acme.ap-south-1.db.originchain.ai/v1/tenants/acme/sql" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT customer, SUM(amount) AS total FROM orders WHERE status = ? GROUP BY customer HAVING SUM(amount) > ? ORDER BY total DESC LIMIT 10",
    "params": ["paid", 1000]
  }'

rows = oc.sql(
    """
    SELECT customer, SUM(amount) AS total
      FROM orders
     WHERE status = ?
     GROUP BY customer
    HAVING SUM(amount) > ?
     ORDER BY total DESC
     LIMIT 10
    """,
    params=["paid", 1000],
)
for r in rows:
    print(r["customer"], r["total"])

Vector topk.

HNSW with SIMD f32 distance kernels. Cosine, dot, or L2. Filtered topk via metadata equality — the filter is fused into the graph traversal, not applied post-hoc.

POST /v1/tenants/:t/vector/:schema/topk

curl -X POST "https://acme.ap-south-1.db.originchain.ai/v1/tenants/acme/vector/orders/topk" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "field":  "embedding",
    "query":  [0.10, -0.05, 0.88, 0.30, -0.20, 0.07, 0.40, -0.25],
    "k":      10,
    "metric": "cosine",
    "filter": { "status": "paid" }
  }'

hits = oc.vector("orders").topk(
    field="embedding",
    query=[0.10, -0.05, 0.88, 0.30, -0.20, 0.07, 0.40, -0.25],
    k=10,
    metric="cosine",
    filter={"status": "paid"},
)
for hit in hits:
    print(hit.id, hit.score)

Full-text BM25.

Lucene-default scoring (k1=1.2, b=0.75) over the analyzer pipeline declared in the schema. Supports mode=boolean, mode=bm25, and mode=phrase for exact-position queries.

POST /v1/tenants/:t/fts/:schema/:field?mode=bm25

curl -X POST "https://acme.ap-south-1.db.originchain.ai/v1/tenants/acme/fts/orders/notes?mode=bm25" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "q":     "rush delivery signed",
    "limit": 20
  }'

hits = oc.fts("orders", "notes").search(
    q="rush delivery signed",
    mode="bm25",
    limit=20,
)
for hit in hits:
    print(hit.score, hit.row["id"])

Graph neighbors.

The customer relation declared in the schema is automatically indexed forward and reverse. Walk it with neighbors, reverse, bfs, path, or dijkstra.

GET /v1/tenants/:t/graph/:schema/neighbors

curl "https://acme.ap-south-1.db.originchain.ai/v1/tenants/acme/graph/orders/neighbors?from=01JTRX1H4Q9P0N2WMX0F5JZ001&edge=customer" \
  -H "Authorization: Bearer $OC_TOKEN"

neighbors = oc.graph("orders").neighbors(
    from_id="01JTRX1H4Q9P0N2WMX0F5JZ001",
    edge="customer",
)
print(len(neighbors), "orders for this customer")

Wire the Python SDK.

Sync and async clients. Pandas-friendly row coercion. Types regenerated from your schema catalog so column access is autocompleted and statically checked.

pip

pip install originchain
# or, for the typed-async surface:
pip install 'originchain[async]'

import os
from originchain import Client

oc = Client(
    base_url="https://acme.ap-south-1.db.originchain.ai",
    tenant="acme",
    token=os.environ["OC_TOKEN"],
)

# everything else: oc.rows, oc.sql, oc.vector, oc.fts, oc.graph, oc.ask