Skip to main content
Learn

Store Records

A Record is a typed key-value node with a label. Records are the fundamental unit of data in RushDB — like a document in a document store, but with seamless relationship traversal built in.

Each record has system properties (__id, __label, __proptypes) plus your own fields.

Create a Record​

db.records.create()

movie = db.records.create(
    label="MOVIE",
    data={"title": "Inception", "rating": 8.8, "genre": "sci-fi"}
)
# → Record  { __id, __label, title, rating, genre }

Create Multiple Records​

db.records.create_many()

Flat rows only — no nested objects. For nested data use import_json.

result = db.records.create_many(
    label="ACTOR",
    data=[
        {"name": "Leonardo DiCaprio", "country": "USA"},
        {"name": "Ken Watanabe",      "country": "Japan"}
    ]
)
# → SearchResult  { data: [...], total: 2 }

Upsert (Create or Update)​

Creates a new record if no match is found, or updates the existing record if matched.

db.records.upsert()

# Match on 'title'; update rating if found, create if not
movie = db.records.upsert(
    label="MOVIE",
    data={"title": "Inception", "rating": 9.0, "genre": "sci-fi"},
    options={"mergeBy": ["title"], "mergeStrategy": "append"}
)

Merge strategies​

StrategyBehaviour
append (default)Add / update incoming fields; preserve all other existing fields
rewriteReplace all fields with incoming data; unmentioned fields are removed

mergeBy behaviour​

mergeBy valueMatch behaviour
['field']Match only on listed fields
[] or omittedMatch on ALL incoming property keys

Partial Update​

Updates only the specified fields; all other fields are preserved.

db.records.update()

# Update via record object (recommended)
movie.update({"rating": 9.0})

# Also works: pass the Record directly or any RecordTarget
db.records.update(movie, {"rating": 9.0})

# Or by ID string
db.records.update("movie-123", {"rating": 9.0})

Full Replacement​

Replaces all fields. Fields not in data are removed.

db.records.set()

# Set via record object (recommended)
movie.set({"title": "Inception", "rating": 9.0, "genre": "sci-fi"})

# Also works: pass the Record directly or any RecordTarget
db.records.set(movie, {"title": "Inception", "rating": 9.0, "genre": "sci-fi"})

# Or by ID string
db.records.set("movie-123", {"title": "Inception", "rating": 9.0, "genre": "sci-fi"})

update() vs set() parameters​

ParameterTypeDescription
targetRecordTargetUUID string, Record instance, or dict with __id
labelstrLabel for the record (TypeScript only, required)
datadict / objectFlat object or PropertyDraft[] for precise type control
optionsdict / objectsuggestTypes, convertNumericValuesToNumbers, skipEmptyValues
transactionTransactionOptional transaction

Delete Records​

Delete by ID​

db.records.delete_by_id()

# Single record
db.records.delete_by_id("movie-123")

# Multiple records
db.records.delete_by_id(["movie-123", "movie-456"])

# From a record object
movie.delete()

All relationships attached to deleted records are removed automatically.

Bulk Delete​

Delete all records matching a query.

db.records.delete()

db.records.delete({
    "labels": ["MOVIE"],
    "where": {"rating": {"$lt": 5}}
})
warning

Calling delete() without a where clause deletes all records with the given label.

Options​

All write methods accept an options object:

OptionDefaultDescription
suggestTypestrueInfer property types automatically
convertNumericValuesToNumbersfalseConvert string numbers to number type
capitalizeLabelsfalseUppercase all inferred label names
skipEmptyValuesfalseSkip empty strings/arrays (0/false kept)
relationshipType__RUSHDB__RELATION__DEFAULT__Relationship type for nested links
returnResultfalseReturn the created record in the response
mergeBy—Fields to match on for upsert
mergeStrategyappendappend or rewrite

Precise Type Control​

By default, RushDB infers property types. Use PropertyDraft / properties array for explicit control.

db.records.create(
    label="MOVIE",
    data=[
        {"name": "title",      "type": "string",   "value": "Inception"},
        {"name": "rating",     "type": "number",   "value": 8.8},
        {"name": "genres",     "type": "string",   "value": "sci-fi,thriller", "valueSeparator": ","},
        {"name": "releasedAt", "type": "datetime", "value": "2010-07-16T00:00:00Z"}
    ]
)

PropertyDraft fields​

FieldTypeDescription
namestringProperty name
typestringstring · number · boolean · datetime
valueanyThe value
valueSeparatorstringSplit value string into an array on this separator

In a Transaction​

tx = db.tx.begin()
try:
    movie = db.records.create(
        label="MOVIE",
        data={"title": "Inception"},
        transaction=tx
    )
    actor = db.records.create(
        label="ACTOR",
        data={"name": "Leonardo DiCaprio"},
        transaction=tx
    )
    db.relationships.attach(
        source=movie,
        target=actor,
        options={"type": "STARS"},
        transaction=tx
    )
    tx.commit()
except Exception:
    tx.rollback()
    raise

TypeScript: Via Model​

const MovieModel = new Model('MOVIE', {
  title: { type: 'string' },
  rating: { type: 'number' }
})

// Create
const movie = await MovieModel.create({ title: 'Inception', rating: 8.8 })

// Create many
const movies = await MovieModel.createMany([{ title: 'Dune' }, { title: 'Arrival' }])

// Partial update
await MovieModel.update('movie-id-123', { rating: 9.1 })

// Full replace
await MovieModel.set('movie-id-123', { title: 'Inception', rating: 9.1, genre: 'sci-fi' })

// Delete
await MovieModel.deleteById(['id-1', 'id-2'])
await MovieModel.delete({ where: { genre: 'temp' } })

See also​