Quick Tutorial

This tutorial stores a small project graph, queries it, and searches it. Every step runs unchanged on RushDB Cloud and on a self-hosted engine; only the connection differs. You need a database from Get Started.

1. Install and connect

Python

pip install rushdb

import os
from rushdb import RushDB

if os.environ.get("RUSHDB_API_KEY"):
    db = RushDB(os.environ["RUSHDB_API_KEY"])  # RushDB Cloud
else:
    db = RushDB(os.environ["RUSHDB_TOKEN"], direct=True, engine_url="http://127.0.0.1:3000")  # self-hosted

TSTypeScript

npm install @rushdb/javascript-sdk

import RushDB from '@rushdb/javascript-sdk'

const db = process.env.RUSHDB_API_KEY
  ? new RushDB(process.env.RUSHDB_API_KEY) // RushDB Cloud
  : new RushDB(process.env.RUSHDB_TOKEN!, { direct: true, engineUrl: 'http://127.0.0.1:3000' }) // self-hosted

2. Push nested JSON

Nested objects become their own records, linked to their parent. Keys in upper case become labels.

Python

db.records.import_json(
    {
        "name": "Search revamp",
        "status": "active",
        "TASK": [
            {"title": "Add keyword search to the docs site", "status": "done", "estimate": 3},
            {"title": "Rank results by meaning and keywords", "status": "pending", "estimate": 5},
            {"title": "Measure search latency", "status": "pending", "estimate": 2},
        ],
    },
    label="PROJECT",
)

TSTypeScript

await db.records.importJson({
  label: 'PROJECT',
  data: {
    name: 'Search revamp',
    status: 'active',
    TASK: [
      { title: 'Add keyword search to the docs site', status: 'done', estimate: 3 },
      { title: 'Rank results by meaning and keywords', status: 'pending', estimate: 5 },
      { title: 'Measure search latency', status: 'pending', estimate: 2 }
    ]
  }
})

3. Query across relationships

Find the pending tasks of active projects, then total the remaining estimate. One SearchQuery shape filters, traverses and aggregates.

Python

pending = db.records.find({
    "labels": ["TASK"],
    "where": {"status": "pending", "PROJECT": {"status": "active"}},
    "orderBy": {"estimate": "desc"},
})
print(pending.total, [task.get("title") for task in pending.data])

remaining = db.records.find({
    "labels": ["TASK"],
    "where": {"status": "pending"},
    "select": {"estimate": {"$sum": "$record.estimate"}},
})
print(remaining.data[0].get("estimate"))  # 7

TSTypeScript

const pending = await db.records.find({
  labels: ['TASK'],
  where: { status: 'pending', PROJECT: { status: 'active' } },
  orderBy: { estimate: 'desc' }
})
console.log(pending.total, pending.data.map((task) => task.data.title))

const remaining = await db.records.find({
  labels: ['TASK'],
  where: { status: 'pending' },
  select: { estimate: { $sum: '$record.estimate' } }
})
console.log(remaining.data[0].data.estimate) // 7

4. Search by keywords

Declare a text index once; it is built in the background and kept current on every write.

Python

db.text_indexes.create({"label": "TASK", "property": "title", "consistency": "immediate"})

hits = db.records.text_search({"labels": ["TASK"], "query": "search latency"})
for task in hits.data:
    print(task.score, task.get("title"))

TSTypeScript

await db.textIndexes.create({ label: 'TASK', property: 'title', consistency: 'immediate' })

const hits = await db.records.textSearch({ labels: ['TASK'], query: 'search latency' })
hits.data.forEach((task) => console.log(task.score, task.data.title))

A search right after creating the index can report that the index is still building; wait until textIndexes.find() shows it ready.

5. Search by meaning

Vector search ranks records by similarity of embeddings.

• On RushDB Cloud, create a managed index and search with plain text; Cloud embeds both the records and the query:

  await db.ai.indexes.create({ label: 'TASK', propertyName: 'title' })
  // when the index status is 'ready':
  const similar = await db.records.vectorSearch({ labels: ['TASK'], propertyName: 'title', query: 'make search faster' })

• On a self-hosted engine, the engine stores and searches vectors you produce: create an external index, write vectors from your model, and search with a queryVector. Follow Bring Your Own Vectors.

Add text: { query: 'latency' } to a vector search to make it hybrid: both rankings fused into one.

Next steps

Next	Guide
Model your own data	Import Data · Relationships
Learn the query language	SearchQuery · Where Operators
Search	Keyword · Semantic · Hybrid
Group writes atomically	Transactions
Give an agent memory	Agent Memory Quickstart
Run the engine in production	Engine manual: Operations