Skip to main content
Learn

Connect Records

Relationships are the connections that link records together, creating a graph structure. They have a type (a string label you define) and a direction.

RushDB supports three categories of relationships:

TypeCreated byDescription
__RUSHDB__RELATION__DEFAULT__Auto, on importLinks parent → child records in nested JSON
__RUSHDB__RELATION__VALUE__Auto, internallyConnects property nodes to record nodes (read-only)
Custom ("STARS_IN", "DIRECTED_BY", etc.)YouDomain-specific, manually created

Attach Records​

db.records.attach()

# Single target
db.records.attach(
    source=movie,
    target=actor,
    options={"type": "STARS_IN", "direction": "out"}
)

# One-to-many (target list)
db.records.attach(
    source=movie,
    target=[actor1, actor2, actor3],
    options={"type": "STARS_IN"}
)

Detach Records​

db.records.detach()

db.records.detach(
    source=movie,
    target=actor,
    options={"type": "STARS_IN"}
    # Omit "type" to detach all relationship types
)

List Relationships​

db.relationships.find()

# All relationships for records matching a search
relationships = db.relationships.find(
    search_query={
        "labels": ["MOVIE"],
        "where": {
            "ACTOR": {"$relation": "STARS_IN", "country": "USA"}
        }
    }
)

# With pagination
page = db.relationships.find(
    search_query={"labels": ["MOVIE"]},
    pagination={"limit": 50, "skip": 0}
)

Direction Reference​

directionGraph pattern
out(source) -[:TYPE]-> (target)
in(source) <-[:TYPE]- (target)

Search by Relationship​

Use $relation inside a where clause to filter records through their graph connections. The nested key is the label of the related record; $relation constrains which relationship edge to follow.

Any relationship type​

Omit $relation to traverse any edge connecting the two labels:

# Find MOVIEs connected to an ACTOR named "Timothée Chalamet" — any relationship type
result = db.records.find({
    "labels": ["MOVIE"],
    "where": {
        "ACTOR": {
            "name": "Timothée Chalamet"
        }
    }
})

Filter by relationship type​

Pass $relation as a string to restrict traversal to a specific relationship type. This produces a direction-agnostic Cypher pattern (-[:TYPE]-) that matches the edge regardless of its stored direction — use the full object form (below) to also constrain direction:

result = db.records.find({
    "labels": ["MOVIE"],
    "where": {
        "ACTOR": {
            "$relation": "STARS_IN",
            "country": "USA"
        }
    }
})

Filter by relationship type and direction​

Use the full object form when direction matters:

FieldTypeDescription
typestringRelationship type label
direction"in" | "out"Edge direction relative to the root record
# Find MOVIEs where an ACTOR is connected via an incoming STARS_IN edge
# i.e. (ACTOR) -[:STARS_IN]-> (MOVIE)
result = db.records.find({
    "labels": ["MOVIE"],
    "where": {
        "ACTOR": {
            "$relation": {"type": "STARS_IN", "direction": "in"},
            "country": "USA"
        }
    }
})

Multi-hop traversal​

Nest $relation filters to traverse multiple relationship levels in a single query:

# Companies → Engineering departments → projects with budget over 10k
result = db.records.find({
    "labels": ["COMPANY"],
    "where": {
        "name": "Acme Corp",
        "DEPARTMENT": {
            "$relation": "HAS_DEPARTMENT",
            "name": "Engineering",
            "PROJECT": {
                "$relation": "HAS_PROJECT",
                "budget": {"$gte": 10000}
            }
        }
    }
})

→ For the full operator reference including $alias, $id, and logical grouping, see Where Operators — Relationship Queries.

In a Transaction​

tx = db.tx.begin()
try:
    movie = db.records.create(
        label="MOVIE", data={"title": "Dune"}, transaction=tx
    )
    actor = db.records.create(
        label="ACTOR", data={"name": "Timothée Chalamet"}, transaction=tx
    )
    db.records.attach(
        source=movie,
        target=actor,
        options={"type": "STARS_IN"},
        transaction=tx
    )
    tx.commit()
except Exception:
    tx.rollback()
    raise

Via Record Instance​

# Record instance methods — equivalent to db.records.attach/detach
movie.attach(
    target=actor,
    options={"type": "STARS_IN", "direction": "out"}
)

movie.detach(
    target=actor,
    options={"type": "STARS_IN"}
)

See also​

  • Bulk Relationships — connect/disconnect many records at once by key match or many-to-many
  • Import Data — nested JSON auto-creates relationships
  • Transactions — ACID guarantees for multi-step operations