SDKs

Use the TypeScript or Python SDK when RushDB is part of your application, service, script, or data pipeline. Each SDK works with RushDB in one of two ways, with the same API:

	RushDB Cloud	Self-hosted engine (direct mode)
What you run	Nothing: the managed service at app.rushdb.com	One rushdb binary, on your own infrastructure
Connect with	An API key	The engine URL and the engine token

The engine is what you can self-host. RushDB Cloud runs that engine for you and adds the dashboard, managed embeddings and the AI features (natural-language search, relationship-pattern suggestions), which exist only in RushDB Cloud.

Package	Install	Version
@rushdb/javascript-sdk	npm install @rushdb/javascript-sdk	3.x — Node.js and browsers, zero runtime dependencies
rushdb	pip install rushdb	3.x — Python 3.10 or newer, no runtime dependencies

---

Connect

Python

import os
from rushdb import RushDB

# RushDB Cloud
db = RushDB(os.environ["RUSHDB_API_KEY"])

# A self-hosted engine
engine = RushDB(
    os.environ["RUSHDB_TOKEN"],
    direct=True,
    engine_url="http://127.0.0.1:3000",
    scope="tenant-1",  # only for an engine started with --multitenant
)

TSTypeScript

import RushDB from '@rushdb/javascript-sdk'

// RushDB Cloud
const db = new RushDB(process.env.RUSHDB_API_KEY!)

// A self-hosted engine
const engine = new RushDB(process.env.RUSHDB_TOKEN!, {
  direct: true,
  engineUrl: 'http://127.0.0.1:3000',
  scope: 'tenant-1' // only for an engine started with --multitenant
})

Get an API key at app.rushdb.com, or start an engine with rushdb up (see Installation). direct: true without an engine URL throws instead of falling back to RushDB Cloud.

---

Write and Read

The fastest useful test is a nested import followed by a search. Nested objects become linked records automatically.

Python

db.records.import_json(
    {
        "name": "RushDB adoption",
        "TASK": [
            {"title": "Connect RushDB", "status": "done"},
            {"title": "Query linked records", "status": "pending"},
        ],
    },
    label="PROJECT",
)

projects = db.records.find({
    "labels": ["PROJECT"],
    "where": {"TASK": {"status": "pending"}},
})
print(projects.total, projects.data)

TSTypeScript

await db.records.importJson({
  label: 'PROJECT',
  data: {
    name: 'RushDB adoption',
    TASK: [
      { title: 'Connect RushDB', status: 'done' },
      { title: 'Query linked records', status: 'pending' }
    ]
  }
})

const { data: projects, total } = await db.records.find({
  labels: ['PROJECT'],
  where: { TASK: { status: 'pending' } }
})
console.log({ total, projects })

shell

curl -X POST https://api.rushdb.com/api/v1/records/import/json \
  -H "Authorization: Bearer $RUSHDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "PROJECT",
    "data": {
      "name": "RushDB adoption",
      "TASK": [
        {"title": "Connect RushDB", "status": "done"},
        {"title": "Query linked records", "status": "pending"}
      ]
    }
  }'

The REST API is RushDB Cloud's; a self-hosted engine is reached through the SDKs or its own native protocol.

---

What Each Mode Offers

Feature	Cloud	Self-hosted engine
Records: create, read, update, set, upsert, delete, find with where, orderBy, select, groupBy	✓	✓
Relationships: attach/detach, relationships.createMany / deleteMany / find	✓	✓
Labels, properties, property values	✓	✓
Import JSON and CSV, export CSV	✓	✓
Keyword (BM25) search and text indexes	✓	✓
External vector indexes; vector and hybrid search with a queryVector you supply	✓	✓
Raw openCypher (query.raw)	✓	✓ (engine started with --languages cypher)
Schema (ai.getSchema, ai.getSchemaMarkdown)	✓	✓
Transactions	✓	✓
Managed embeddings: managed indexes, records.vectorSearch by text query	✓	—
Natural-language search (ai.search)	✓	—
Relationship-pattern suggestions (relationships.patterns.*)	✓	—
Project settings (settings.get), dashboard, projects, team access	✓	—

In both modes, a transaction stages record creates, updates, sets, deletes by id, attaches and imports; other writes are refused inside a transaction. See Transactions.

Errors in direct mode

Error	Raised when	Fields
CloudOnlyError	A Cloud-only method or form is called. Nothing is sent, and no request ever goes to RushDB Cloud.	method, reason, code: 'CLOUD_ONLY'
DirectModeError	A write the engine cannot stage is called inside a transaction. Nothing is sent.	code: 'DIRECT_MODE_UNSUPPORTED'

The lists are available in code, so an application can decide at runtime:

Python

from rushdb import CLOUD_ONLY_METHODS, CloudOnlyError, is_cloud_only_method

TSTypeScript

import { CLOUD_ONLY_METHODS, CloudOnlyError, isCloudOnlyMethod } from '@rushdb/javascript-sdk'

if (!isCloudOnlyMethod('ai.search')) {
  // offer natural-language search
}

The native protocol from the SDK

In direct mode, any Protocol v1 operation the SDK has no method for is one call away: db.engine.execute(operation) in Python.

schema = engine.engine.execute({"kind": "describe", "describe": {"kind": "capabilities"}})

---

Add Search

1. Keyword search works as soon as you declare a text index.
2. For vector search, create an embedding index — managed on Cloud, or external with your own vectors anywhere — and wait until its status is ready.
3. Run semantic or hybrid search.

For natural-language query planning over your schema on RushDB Cloud, see Smart Search.

Full References

• TypeScript / JavaScript reference
• Python reference
• REST API reference [Cloud]
• Store records
• Import nested data