Skip to main content

RushDB Logo

RushDB — Python SDK

RushDB — the database for AI

One database for your records, their relationships, and search over them.

PyPI - Version PyPI - Python Version PyPI - License

📖 Documentation • 🌐 Website • ☁️ Cloud


Why RushDB

Agents need memory. Apps need connected data. The standard answer involves multiple databases, schema design, and an embedding pipeline before you write a single useful line of business logic.

RushDB skips all of that. Push any JSON — nested structure becomes a traversable graph, string properties become semantically searchable, type inference happens automatically.

Works with LangChain, CrewAI, AutoGen, or any Python AI framework.


Installation

pip install rushdb

Compatibility

Package RushDB 3.x and RushDB Cloud RushDB 2.x (legacy)
@rushdb/javascript-sdk 3.x 2.11.0: npm i @rushdb/javascript-sdk@2
rushdb (PyPI) 3.x 2.10.0: pip install "rushdb<3"
@rushdb/mcp-server 3.x 2.13.0: npx @rushdb/mcp-server@2

RushDB Cloud or a self-hosted engine

The SDK works with RushDB in one of two ways:

RushDB Cloud Self-hosted RushDB 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.

from rushdb import RushDB

# RushDB Cloud
db = RushDB("RUSHDB_API_KEY")

# A self-hosted engine
db = RushDB(
    "ENGINE_TOKEN",
    direct=True,
    engine_url="http://127.0.0.1:3000",
    scope="tenant-1",  # only for an engine started with --multitenant
)

What each offers:

Feature Cloud Self-hosted engine
Records: create, read, update, set, upsert, delete, find with where, orderBy, select, groupBy ✓ ✓
Relationships: attach/detach, relationships.create_many/delete_many/find/update ✓ ✓
Labels, properties, property values ✓ ✓
Import JSON and CSV, export CSV ✓ ✓
External vector indexes; vector search with a queryVector you supply ✓ ✓
Raw openCypher (query.raw; the engine needs --languages cypher) ✓ ✓
Schema (ai.get_schema, ai.get_schema_markdown) ✓ ✓
Keyword (BM25) search (records.text_search), text indexes (text_indexes.*), hybrid search ✓ ✓
Transactions ✓ record creates, updates, sets, deletes by id, attaches and imports are staged; other writes refuse a transaction
Managed embeddings: managed indexes, records.vector_search by text query ✓ —
Natural-language search on SQL (ai.search, ai.run_sql) ✓ —
Relationship-pattern suggestions (relationships.patterns.*) ✓ —
Project settings (settings.get), dashboard, team access ✓ —

In direct mode a Cloud-only method raises CloudOnlyError (with method and reason) before sending anything, and no request ever goes to RushDB Cloud. A write the engine cannot stage into a transaction raises DirectModeError, also before sending anything. The list is available in code:

from rushdb import CLOUD_ONLY_METHODS, CloudOnlyError, is_cloud_only_method

db.engine.execute() runs any Protocol v1 operation directly.


Agent memory in 3 lines

Get an API key at app.rushdb.com.

from rushdb import RushDB

db = RushDB('RUSHDB_API_KEY')

# Store an agent action — graph links sessions and context automatically
db.records.create(
    label='MEMORY',
    data={
        'agent_id': 'agent-42',
        'session_id': 'sess-001',
        'action': 'summarized',
        'topic': 'Q4 results',
        'output': summary_text,
    },
)

# Recall — traverse relationships, filter by properties
results = db.records.find({
    'labels': ['MEMORY'],
    'where': {
        'agent_id': 'agent-42',
        'topic': {'$contains': 'Q4'},
    },
    'limit': 10,
})

for memory in results:
    print(memory.get('output'))

Graph traversal

# Push nested JSON — relationships created automatically
db.records.create_many('COMPANY', {
    'name': 'Acme Corp',
    'DEPARTMENT': [{
        'name': 'Engineering',
        'EMPLOYEE': [{
            'name': 'Alice',
            'role': 'Staff Engineer',
        }]
    }]
})

# Traverse the auto-created graph
engineers = db.records.find({
    'labels': ['EMPLOYEE'],
    'where': {
        'role': {'$contains': 'Engineer'},
        'DEPARTMENT': {'COMPANY': {'name': 'Acme Corp'}},
    },
})

# Constrain by relationship type and direction
authored_posts = db.records.find({
    'labels': ['USER'],
    'where': {
        'POST': {
            '$relation': {'type': 'AUTHORED', 'direction': 'out'},
            'title': {'$contains': 'graph'},
        }
    },
    'limit': 10,
})

# Multi-hop: add hops to $relation — everyone in Alice's reporting chain, up to 4 levels
chain = db.records.find({
    'labels': ['EMPLOYEE'],
    'where': {
        'EMPLOYEE': {
            '$relation': {'type': 'REPORTS_TO', 'direction': 'out', 'hops': {'min': 1, 'max': 4}},
            'name': {'$contains': 'Alice'},
        }
    },
})

# Cycle detection: accounts on a circular transfer ring (fraud rings, circular ownership)
ring_members = db.records.find({
    'labels': ['ACCOUNT'],
    'where': {
        'RING': {  # key is a display name — the $cycle block holds only $relation
            '$cycle': True,
            '$relation': {'type': 'TRANSFERRED_TO', 'direction': 'out', 'hops': {'min': 2, 'max': 6}},
        }
    },
})

# Manage relationships explicitly
user = db.records.find_uniq({'labels': ['USER'], 'where': {'name': 'Alice'}})
company = db.records.find_uniq({'labels': ['COMPANY'], 'where': {'name': 'Acme Corp'}})
user.attach(
    target=company,
    options={'type': 'WORKS_AT', 'direction': 'out', 'properties': {'source': 'profile'}},
)

# Relationship search: where filters edge type/properties, source/target filter endpoint records
relationships = db.relationships.find({
    'source': {'labels': ['USER'], 'where': {'name': 'Alice'}},
    'target': {'labels': ['COMPANY']},
    'where': {'type': 'WORKS_AT', 'source': 'profile'},
})

# Change properties on existing relationships (RushDB 3.0.4+): set writes, unset removes
db.relationships.update(user, company, type='WORKS_AT', set={'source': 'hr'}, unset=['legacy'])
# types marks values JSON can't type: 'datetime' stores an ISO string as a datetime
db.relationships.update(
    user, company, type='WORKS_AT', set={'since': '2024-03-01'}, types={'since': 'datetime'}
)

Importing CSV

csv_data = "name,email,age\nJohn,john@example.com,30\nJane,jane@example.com,25"

db.records.import_csv(
    label='USER',
    data=csv_data,
    # skipEmptyValues: treat empty cells ("" / []) as unset instead of storing them (0/False are kept)
    options={'returnResult': True, 'suggestTypes': True, 'skipEmptyValues': True},
    parse_config={'header': True, 'skipEmptyLines': True, 'dynamicTyping': True},
)

SearchResult

db.records.find() returns a SearchResult — a list-like container with pagination metadata.

result = db.records.find({
    'where': {'status': 'active'},
    'limit': 10,
    'skip': 0,
})

# List-like usage
print(f"Loaded {len(result)} of {result.total} total")
print(f"Has more: {result.has_more}")

for record in result:
    print(record.get('name'))

# Indexing and slicing
first = result[0]
top_five = result[:5]

# Boolean check
if result:
    process(result[0])
Property Type Description
data List[Record] The result items
total int Total matching records in the database
has_more bool Whether more records exist beyond this page
search_query dict The query that produced this result
sql str For Smart search, the SQL statement it ran

Use db.records.vector_search() for direct semantic/vector retrieval over an embedding index:

results = db.records.vector_search({
    'labels': ['MEMORY'],
    'propertyName': 'content',
    'query': 'how agents remember things',
    'where': {'agent_id': 'agent-42'},
    'limit': 5,
})

for record in results:
    print(record.score, record.get('content'))

Use db.ai.search() when you want RushDB to turn a natural-language request into one read-only SQL statement over your schema and run it (RushDB Cloud):

results = db.ai.search('Find active memories about Q4 results for agent-42')
print(results.name)  # a short title, e.g. to save the query under
print(results.sql)   # the statement it ran
more = results.next()  # the next page of the statement's rows

# Run a statement directly, e.g. a saved one:
rows = db.ai.run_sql('SELECT agent_id, count(*) AS memories FROM "MEMORY" GROUP BY agent_id')

Rows that select a record's __id come back as full records; aggregates come back as plain rows.

db.ai.search({...}) still works as a deprecated vector-search alias, but new code should use db.records.vector_search({...}).

Declare a BM25 text index, then search it by keywords:

db.text_indexes.create({'label': 'MEMORY', 'property': 'content'})

results = db.records.text_search({
    'query': 'quarterly results',
    'labels': ['MEMORY'],
    'where': {'agent_id': 'agent-42'},
    'limit': 5,
})
print(results.total, results.meta['textSearch'])

Add a text leg to a vector search to fuse keyword and vector ranking. fusion is rrf (default) or dbsf; weight and prefetchLimit tune each leg:

results = db.records.vector_search({
    'labels': ['MEMORY'],
    'propertyName': 'content',
    'queryVector': embedding,
    'text': {'query': 'quarterly results', 'weight': 0.5},
    'fusion': 'dbsf',
    'limit': 5,
})

Record API

user = db.records.create('USER', {
    'name': 'Alice',
    'email': 'alice@example.com',
})

# Safe field access
name = user.get('name')                  # 'Alice'
phone = user.get('phone', 'N/A')         # 'N/A'

# Clean data (excludes internal __id, __label fields)
data = user.get_data()                   # {'name': 'Alice', 'email': '...'}
full = user.get_data(exclude_internal=False)  # includes __id, __label, etc.

# Existence check (no exception if record was deleted)
if user.exists:
    user.update({'status': 'active'})

# String representations
repr(user)   # Record(id='abc-123', label='USER')
str(user)    # USER: Alice

Transactions

with db.transactions.begin() as tx:
    record_a = db.records.create('NODE', {'value': 1}, transaction=tx)
    record_b = db.records.create('NODE', {'value': 2}, transaction=tx)
    record_a.attach(target=record_b, options={'type': 'LINKED'}, transaction=tx)
# auto-committed on exit, rolled back on exception

Configuration

from rushdb import RushDB

db = RushDB(
    'RUSHDB_API_KEY',
    url='https://api.rushdb.com/api/v1',  # a different RushDB Cloud API endpoint; this is the default
    timeout=30,
)

Documentation

docs.rushdb.com/3.x/connect/sdks and the Python reference — full API reference, vector search, aggregations, and more.


Support


Contributing

See CONTRIBUTING.md. Issues and PRs welcome.

Metadata

Release files for rushdb 3.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rushdb 3.2.1
File Size Uploaded Provenance Actions
rushdb-3.2.1.tar.gz 137.6 kB With provenance Details for rushdb-3.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rushdb 3.2.1
File Interpreter ABI Platform Actions
rushdb-3.2.1-py3-none-any.whl Python 3 none any Details for rushdb-3.2.1-py3-none-any.whl

Total release size: 205.3 kB

Release files / rushdb-3.2.1.tar.gz

Download URL rushdb-3.2.1.tar.gz
Size 137.6 kB
Tags Source
SHA-256 checksum
How to use checksums
35678cbefe68f96adea3e65efa99fa4e075be6553dbe051c58b70e4538a4e16a
BLAKE2b-256 checksum
How to use checksums
163f19699742ba3b909dde1385b4d4090f229b60e230bc3a4295b68283bd4ea4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Release files / rushdb-3.2.1-py3-none-any.whl

Download URL rushdb-3.2.1-py3-none-any.whl
Size 67.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
668103f768b3a1f5bf675d3a42837fbb238fcdadc750031d224f45fd1b89a0e4
BLAKE2b-256 checksum
How to use checksums
2a03d6428fbbcde8d0ae1950ede75b95ce19b307a2eb0083a68465d9391f6386
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Security for rushdb 3.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for rushdb-3.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page