rushdb-data-modeling

name	rushdb-data-modeling
description	Model data in RushDB's property-centric LMPG graph. Use when designing or evolving schemas, choosing labels and properties, defining relationships, importing nested JSON, structuring a new use case, or modeling agent memory with EPISODE, MEMORY_FACT, domain records, scope fields, semantic properties, and fact supersession.

RushDB Data Modeling

RushDB uses the LMPG (Labels, Multi-Properties, Graph) model — a property-centric graph where every node (record) has a label, a set of typed properties, and can be connected to other records via named relationships.

Core insight: you don't define a schema upfront. You push JSON, and RushDB infers structure. Labels and properties emerge from your data. Schema discovery happens via getSchemaMarkdown.

---

The LMPG Model

Concept	RushDB term	Description
Node	Record	A single data entity — like a row, but with flexible properties
Node type	Label	The record's category/type (USER, ORDER, PROJECT)
Attributes	Properties	Key-value pairs with typed values attached to a record
Edge	Relationship	A named, directed connection between two records

Records are schema-free: two USER records can have different property sets. Properties carry one of four types: string, number, boolean, datetime. A null value leaves the field unset — query whether a field is set with $exists. Embeddings are number arrays with an embedding index for semantic search.

---

Labels

Naming Rules

• Prefer UPPER_CASE as the RushDB convention. Labels are case-sensitive, so User and USER are distinct; copy existing labels exactly.
• Singular noun: USER not USERS, ORDER not ORDERS
• No spaces or special characters — use underscores: BLOG_POST

Choosing Labels

Labels should reflect the entity type, not the action or state:

Good	Avoid
USER	REGISTERED_USER, ACTIVE_USER
ORDER	PLACED_ORDER, ORDER_ENTITY
BLOG_POST	PUBLISHED_CONTENT, POST_NODE

Use a single label per record type. Model state with a status property, not separate labels.

Multi-Label Queries

findRecords with labels: ["ARTICLE", "BLOG_POST"] returns both types (OR). Useful for shared abstract types (e.g., all content records).

---

Properties

Supported Types

Type	Example values	Notes
string	"hello", "active"	Case-sensitive equality; case-insensitive for $contains etc.
number	42, 3.14, -100	Supports full range operators
boolean	true, false
datetime	"2026-04-10T09:00:00Z"	ISO 8601 UTC format. Use component objects for range queries.

Writing null (or an all-null array) leaves the field unset — it is not stored and does not appear in the schema. Match set/unset fields with { field: { $exists: true } } / { field: { $exists: false } }.

Naming Conventions

• camelCase for all property names: createdAt, isActive, userId
• Consistent types per property across all records of the same label
• Avoid reusing a property name with different types across records of the same label
• ISO 8601 for all timestamps: "2026-04-10T09:00:00Z" (always UTC)
• Booleans as isX or hasX: isActive, hasAccess, isPremium

Property Discovery

getSchemaMarkdown()         → all labels + all properties + value ranges
findProperties({ labels: ["USER"] })  → detailed property list for a label
getSchema()                 → same as above but structured JSON with propertyId values
propertyValues(propertyId)    → distinct values / min-max for a property

---

Relationships

How Auto-Linking Works

When you pass nested objects to bulkCreateRecords, RushDB creates:

• One record per nested label key
• One relationship per parent→child nesting level
• Relationship type defaults to the uppercase label name

Example — this single import:

{
  "label": "COMPANY",
  "data": {
    "name": "Acme Corp",
    "DEPARTMENT": [
      {
        "name": "Engineering",
        "EMPLOYEE": [
          { "name": "Alice", "role": "Engineer" },
          { "name": "Bob", "role": "Manager" }
        ]
      }
    ]
  }
}

Produces:

• 1 COMPANY record
• 1 DEPARTMENT record → linked to COMPANY
• 2 EMPLOYEE records → each linked to DEPARTMENT
• Relationships: COMPANY -[HAS_DEPARTMENT]→ DEPARTMENT, DEPARTMENT -[HAS_EMPLOYEE]→ EMPLOYEE

No schema declaration. No migration. Just push the JSON.

Manual Relationship Management

attachRelation({ sourceId, targetId, type: "AUTHORED" })
detachRelation({ sourceId, targetId, type: "AUTHORED" })
findRelationships({ source: { where: { $id: "record-id" } } })
findRelationships({ target: { where: { $id: "record-id" } } })

Relationship Naming Conventions

• UPPER_SNAKE_CASE: AUTHORED_BY, BELONGS_TO, DEPENDS_ON, HAS_TASK
• Directional and readable: AUTHOR -[WROTE]→ POST, SESSION -[HAS_DECISION]→ DECISION
• Verb-based: describes the action/association from source to target

Relationship Query Patterns

Relationships are traversed in where by using the target label as the key:

{
  "labels": ["COMPANY"],
  "where": {
    "DEPARTMENT": {
      "name": "Engineering",
      "$relation": { "type": "HAS_DEPARTMENT", "direction": "out" }
    }
  }
}

Omit $relation when direction and type are not important — RushDB traverses any edge.

For self-referencing hierarchies (org charts, category trees, dependency graphs), one nested block traverses multiple levels via hops: "$relation": { "type": "REPORTS_TO", "direction": "out", "hops": { "max": 4 } }. Cycles in such graphs are queryable with the $cycle operator — see the query-builder skill for both.

---

Data Import Patterns

Flat Records (simple entities)

Use createRecord for individual records with no nesting:

{
  "label": "PRODUCT",
  "data": {
    "name": "Widget Pro",
    "sku": "WGT-PRO-001",
    "price": 49.99,
    "category": "hardware",
    "inStock": true,
    "createdAt": "2026-04-10T00:00:00Z"
  }
}

Hierarchical Data (nested structures)

Use bulkCreateRecords with nested label keys for structures like org charts, project trees, or content hierarchies. The nesting depth can be arbitrary.

CSV / Flat Files

Use exportRecords to export existing records to CSV. For import, use bulkCreateRecords by transforming flat rows into records with a consistent label.

When source rows have blank cells, pass options: { skipEmptyValues: true } so empty strings ("") and empty arrays ([]) are treated as unset (no property is created) instead of being stored as empty values. 0 and false are real values and are always kept. Defaults to false.

Enum Fields

Define a consistent set of values upfront and document them as a status or type field comment. Enforce consistency via propertyValues queries during writes if needed.

---

Schema Discovery Workflow

When working with an existing database:

1. getSchemaMarkdown() — see all labels, their property names/types, and relationships
2. findProperties({ labels: ["LABEL"] }) — deep-dive a specific label
3. propertyValues(propertyId) — enumerate distinct string/boolean values or get number/date ranges
4. findRelationships({ source: { where: { $id: "sample-id" } } }) and findRelationships({ target: { where: { $id: "sample-id" } } }) — explore outgoing and incoming connections from a sample record

Never guess label names or property names — always discover them first.

---

Schema Evolution Patterns

Add a property

Just include it in new records. Existing records that lack it are unmatched by filters on that field — they're not broken.

Change a property name

1. findRecords to get all affected records
2. updateRecord each with the new property name added and old removed
3. There is no schema migration — just update the data

Add a label

Start creating records with the new label — it appears in getSchemaMarkdown once at least one record exists.

Retire a label

1. Add deprecated: true to all existing records of that label
2. Stop creating new ones
3. Filter with { deprecated: { $ne: true } } in queries until fully cleaned up
4. Delete with bulkDeleteRecords (always preview first)

Split a label into two

1. findRecords on old label, classify each record by new label
2. bulkCreateRecords into new labels
3. Re-attach relationships with attachRelation
4. Mark old records as deprecated

---

Agent Memory Model

Separate lifecycle projections from domain knowledge:

Label	Purpose	Semantic property
EPISODE	One bounded completed turn or lifecycle observation	summary
MEMORY_FACT	Curated, versioned fact, preference, or rule	text
SESSION	Optional graph-visible work/conversation boundary	Optional
DECISION, TASK, ENTITY, ARTIFACT	Explicit domain knowledge	Domain-specific

Every canonical episode and fact must carry agentId, profileId, privacyScope, participantScopeHash, and sandboxEligible. These properties form an authorization scope and must have consistent types across both labels.

Use deterministic eventId for episodes and factId for facts. Configure managed embedding indexes for EPISODE.summary and MEMORY_FACT.text; do not index raw complete transcripts.

Model fact changes as history:

1. Create the replacement MEMORY_FACT with a new deterministic factId, active: true, and supersedesFactId referencing the prior fact.
2. Mark the prior fact active: false.
3. Recall with active: true; query both versions only for audit/history.

Keep explicit graph labels separate from automatically captured episodes. A native runtime provider owns turn capture; MCP/application logic may add structured decisions or tasks without duplicating the turn.

---

Common Modeling Mistakes

Mistake	Correct approach
Changing existing label casing	Copy the exact case returned by getSchemaMarkdown
Storing state in the label: ACTIVE_USER	Store state as status: "active" on USER
One giant label with all fields	Split into focused labels linked by relationships
Guessing property names	Call getSchemaMarkdown or findProperties first
Hardcoding enum values	Probe with propertyValues before filtering
Plain date strings in range queries	Use component objects: { $gte: { $year: 2024 } }
Inventing $label/$direction operators	Use the label as the key, $alias for naming, $relation for edge type