Skip to main content

Relationships

This page explains relationships in RushDB — their type, direction and properties — and every way to create, inspect, rename and remove them through the native protocol. It is for developers modelling connected data. Querying across relationships is covered in Relationships and traversal. The rdb helper used in the examples is defined in the Quickstart.

What a relationship is​

A relationship connects a source record to a target record. It has:

PartMeaning
TypeA string naming the connection, such as WORKS_AT or HAS_DEPARTMENT.
DirectionAlways stored from source to target. Queries can follow it either way.
PropertiesOptional values on the relationship itself, such as since or role.
IdA stable identifier assigned by the engine.

Relationships are first-class: they appear in the schema catalog as shapes (sourceLabel, type, targetLabel, count and properties), they can be filtered and listed, and they can carry vectors of their own (see Vector search).

Deleting a record deletes every relationship attached to it.

Naming relationship types​

Any non-empty string is a valid type, but use upper-case snake case (WORKS_AT, HAS_DEPARTMENT). The native query document upper-cases the type you name in a $relation filter before matching, so a relationship stored as works_at cannot be selected by type from a native query.

Relationships created by nested import without an explicit type use the default type __RUSHDB__RELATION__DEFAULT__.

Relationship properties​

Relationships carry properties with the same value types as records (boolean, number, string, datetime, arrays, explicit null). Two differences:

  • No type inference is applied: a date string on a relationship stays a string unless the request declares it a datetime in types.
  • Properties are set when the relationship is created; a link request that finds the relationship already present leaves it untouched (use updateRelationshipsById to change them).

Declared types​

linkRecordsById, linkRecordsPairs and updateRelationshipsById take an optional types map from property name to string, number, boolean or datetime, next to the properties they write (properties, or set for an update):

JSON
"properties": { "since": "2024-03-01T09:30:00Z", "weight": 0.8, "note": null },
"types": { "since": "datetime", "weight": "number", "note": "datetime" }
  • Every name in types must be among the written properties; otherwise the call fails with invalid_request.
  • A non-null value must match its type: a string, number or boolean property takes that scalar or an array of them. A datetime takes one ISO 8601 date or datetime string (2024-03-01, 2024-03-01T09:30:00Z, 2024-03-01T09:30:00.250+02:00; no zone means UTC) and is stored as a datetime. Datetime arrays are rejected, as for records. A mismatch fails the call with invalid_request and nothing is written.
  • null stores an explicit null whatever its declared type.
  • A property without a declared type is stored as sent.

Engines that support types advertise the relationshipPropertyTypes capability.

Relationships are returned with their datetime properties as ISO 8601 strings and a propertyTypes map, as records are (see List relationships).

linkRecordsById creates one relationship from every source id to every target id (a cross product):

Shell
rdb '{
"protocolVersion": 1,
"operation": {
"kind": "mutate",
"mutation": {
"kind": "linkRecordsById",
"command": {
"relationType": "INFLUENCED",
"sourceIds": ["019a0000-0000-7000-8000-000000000001"],
"targetIds": ["019a0000-0000-7000-8000-000000000002",
"019a0000-0000-7000-8000-000000000003"],
"properties": { "via": "the Analytical Engine notes" }
}
}
}
}'
JSON
{"protocolVersion":1,"response":{"kind":"linked","created":2,"skippedExisting":0}}
FieldRequiredMeaning
relationTypeYesThe relationship type.
sourceIds, targetIdsYesRecord ids (dashed UUIDs or 32 hex digits).
directionNoout (default): source → target. in: each pair is stored target → source.
propertiesNoProperties for every relationship created.
typesNoDeclared types of named properties; see Declared types.

Behaviour:

  • Every endpoint is resolved first; an unknown id fails the whole call with not_found and nothing is written.
  • An edge of the same type that already exists between the same two records is skipped, so the call is idempotent. created counts new edges and skippedExisting the pairs that were already linked.
  • All new edges are written in one atomic commit.

linkRecordsPairs takes an explicit list of pairs — one edge per pair, no cross product — and lets each pair override the type:

Shell
rdb '{
"protocolVersion": 1,
"operation": {
"kind": "mutate",
"mutation": {
"kind": "linkRecordsPairs",
"command": {
"relationType": "KNOWS",
"pairs": [
{ "sourceId": "019a0000-0000-7000-8000-000000000002",
"targetId": "019a0000-0000-7000-8000-000000000003" },
{ "sourceId": "019a0000-0000-7000-8000-000000000003",
"targetId": "019a0000-0000-7000-8000-000000000001",
"relationType": "ADMIRES" }
]
}
}
}
}'

The same guarantees apply: all endpoints are resolved before anything is written, existing edges are skipped, and the batch commits atomically. This is the most efficient way to load many edges whose endpoints you already know; batches of about 500 pairs per request work well.

linkRecords joins two sets of records by label, filter and key, much like a foreign-key join. This links every Employee to the Company whose id property equals the employee's companyId:

Shell
rdb '{
"protocolVersion": 1,
"operation": {
"kind": "mutate",
"mutation": {
"kind": "linkRecords",
"command": {
"relationType": "WORKS_AT",
"source": { "label": "Employee", "property": "companyId" },
"target": { "label": "Company", "property": "id" }
}
}
}
}'
FieldMeaning
source, targetEach selects records: label (required), property (the join key) and an optional predicate filter.
allowCartesianWhen true, property may be omitted on both sides and every selected source is linked to every selected target. Both sides must then have a non-empty predicate. When source and target have the same label, a record is not linked to itself.
directionout (default) or in, as above.
propertiesProperties for every relationship created.

Join keys compare values with their types (17 does not match "17"), and a multi-value key matches when any of its values matches. Existing edges of the same type are skipped. Like the id-based operations, linkRecords writes every new edge in one atomic commit: all of them, or none.

Other ways to create relationships​

  • Nested import creates parent → child relationships for every nested object; see Nested import.
  • Transactions stage createRelationship together with other writes and commit them atomically; see Transactions.
  • Statement languages create relationships with their own syntax, for example CREATE (a)-[:KNOWS]->(b) in Cypher; see Query languages.

Update relationship properties​

updateRelationshipsById changes the properties of the existing edges of relationType from every source to every target, in direction (out by default; in swaps the endpoints). set writes properties (null stores an explicit null) and unset removes them; one name cannot be in both. types declares the type of named set properties (see Declared types):

Shell
rdb '{"protocolVersion":1,"operation":{"kind":"mutate","mutation":{
"kind":"updateRelationshipsById",
"command":{"relationType":"INFLUENCED","direction":"out",
"sourceIds":["019a0000-0000-7000-8000-000000000001"],
"targetIds":["019a0000-0000-7000-8000-000000000002"],
"set":{"strength":"high","note":null,"since":"1843-10-01"},
"types":{"since":"datetime"},"unset":["source"]}}}}'

A pair without such an edge is skipped. An unknown id fails the call before anything is written, and all updates are one commit. The response is {"kind": "mutation", "affected": <updated edges>}. Statement languages update edges too (SET r.strength = 'high' in Cypher), but select them by pattern rather than by record id.

Remove relationships​

unlinkRecordsById deletes the edges between every source and every target:

  • relationTypes lists the types to delete; omitted or empty, it deletes edges of every type;
  • direction is out (source → target) or in (target → source); omitted, it deletes edges pointing either way.

Deleting an edge that does not exist is not an error, so the call is idempotent:

Shell
rdb '{"protocolVersion":1,"operation":{"kind":"mutate","mutation":{
"kind":"unlinkRecordsById",
"command":{"relationTypes":["INFLUENCED"],"direction":"out",
"sourceIds":["019a0000-0000-7000-8000-000000000001"],
"targetIds":["019a0000-0000-7000-8000-000000000002"]}}}}'

unlinkRecords takes the same selector command as linkRecords. The response of both is {"kind": "mutation", "affected": <deleted edges>}.

Rename a relationship type​

retypeRelations rewrites every relationship of one type between two labels to a new type, keeping endpoints and direction:

Shell
rdb '{"protocolVersion":1,"operation":{"kind":"mutate","mutation":{
"kind":"retypeRelations",
"command":{"sourceLabel":"Company","targetLabel":"department",
"sourceType":"__RUSHDB__RELATION__DEFAULT__","targetType":"HAS_DEPARTMENT"}}}}'

sourceType defaults to the nested-import default type, which makes this the natural follow-up to an import that did not name its relationship types.

Each pair of records ends with one relationship of the target type. When a pair already has one, the retyped relationships merge into it and it keeps its id. mergeStrategy decides what happens to properties that both sides hold (a conflict: the same name with different values):

mergeStrategyEffect on the pair's existing target-type relationship
keep (default)Keeps its own values and gains every property it lacks from the retyped relationships (older first).
appendThe retyped relationships' values win a conflict (newest last); properties only it has are kept. Same meaning as append for import upserts.
rewriteIts properties are replaced by the retyped relationships' (newest wins among them). Same meaning as rewrite for import upserts.
failWith any conflict the retype is refused with conflict and nothing is written; the message gives the count and the first 20 conflicts (property, both record ids, both values). Without one, as keep.

A pair without a target-type relationship gets a new one carrying the union of the retyped relationships' properties (keep and fail: the oldest value wins a conflict; append and rewrite: the newest). The response counts the relationships retyped in affected, and also reports merged (relationships folded into another one) and propertyConflicts (conflicts met, whichever value won). To check before writing, retype with fail first.

Shell
rdb '{"protocolVersion":1,"operation":{"kind":"mutate","mutation":{
"kind":"retypeRelations",
"command":{"sourceLabel":"PERSON","targetLabel":"COMPANY","sourceType":"EMPLOYED_BY",
"targetType":"WORKS_AT","mergeStrategy":"fail"}}}}'

List relationships​

The relationships query returns relationship instances, optionally filtered by endpoint labels, endpoint records, type and relationship properties:

Shell
rdb '{"protocolVersion":1,"operation":{"kind":"query","query":{"kind":"relationships","query":{
"sourceLabels": ["Person"],
"relationType": "INFLUENCED",
"predicate": { "via": "the Analytical Engine notes" },
"limit": 50
}}}}'
JSON
{
"protocolVersion": 1,
"response": {
"kind": "relationships",
"total": 2,
"relationships": [
{
"id": "…",
"type": "INFLUENCED",
"sourceId": "019a0000-0000-7000-8000-000000000001",
"targetId": "019a0000-0000-7000-8000-000000000002",
"sourceLabel": "Person",
"targetLabel": "Person",
"properties": { "via": "the Analytical Engine notes", "since": "1843-10-01" },
"propertyTypes": { "via": "string", "since": "datetime" }
}
]
}
}

Every id in a row (id, sourceId, targetId) is a dashed UUID. propertyTypes names the stored type of each property (string, number, boolean or datetime); a property holding only null has no entry. A datetime property is returned as an ISO 8601 string: a date at midnight UTC as YYYY-MM-DD, any other instant as YYYY-MM-DDTHH:MM:SS.sssZ.

The relationship predicate filters the relationship's own properties with every field operator and logical combinator of the record predicate (see Filtering), for example {"since": {"$gte": 2020}, "role": {"$in": ["engineer", "lead"]}}. It cannot contain traversal blocks.

sourcePredicate and targetPredicate filter the records at either end, with the record predicate syntax ($id included). They are answered from those records' own links, so listing one record's relationships costs as much as that record's relationship count, not the store's:

JSON
{ "sourcePredicate": { "$id": "019a0000-0000-7000-8000-000000000001" }, "limit": 100 }

total counts every match before offset/limit. When you only need counts per shape, use describe.schema instead — it is answered from the catalog without visiting individual relationships; see Schema catalog.

See also​