Relations

Relations in RushDB allow you to create links between records, simplifying the modeling of complex data interactions and enhancing relationships between different Records in your application.

Typescript Definition

export type RelationTarget = DBRecordsArrayInstance<any> | MaybeArray<DBRecord<any>> | MaybeArray<DBRecordInstance<any>> | MaybeArray<string>;

export type RelationOptions = {
  direction?: 'in' | 'out';
  type?: string;
};

export type RelationDetachOptions = Omit<RelationDetachOptions, 'type'> & {
  typeOrTypes?: string | string[];
};

How it works

Relations are one of the key concepts in RushDB. When building applications, it’s common that Records do not exist in isolation. They are usually interconnected, interacting with each other in meaningful ways. RushDB provides a powerful tool for describing these interactions by allowing you to define the direction of relations between Records and give them meaningful labels. This enables complex data structures where Records can reference each other in ways that model real-world interactions. Using relations in RushDB allows you to establish powerful queries that take these relationships into account, providing a robust and scalable way to search and retrieve interconnected data across your application.

---

Create Relation

Endpoints

Create a Relation

POST /api/v1/records/:entityId/relations

info

Note: Replace :entityId with the actual ID of the Record whose relations you want to retrieve.

Creates a new relation between Records by linking them. You can provide extra options for relation: set direction and create name for them.

Request

const product = await db.records.create("Product", {
  title: "Nike Air Max 270",
  price: 150,
  description: "Nike's stylish and comfortable sneakers with Max Air cushioning for all-day wear.",
  category: "Footwear",
  stock: 50,
});

const owner = await db.records.create("Client", {
  name: "Jane Smith",
  username: "janesmith99",
  email: "janesmith@example.com",
});

await db.records.attach(owner.data.__id, product, {
  direction: "out",
  type: "owner",
});

Response

{
  "message": "Relations to Record 019214e7-6421-790f-b164-24bd73d239f0 have been successfully created"
},

---

Get Relation

Endpoint

Get list of all parents of Record's Relations

GET /api/v1/records/:entityId/relations

info

Note: Replace :entityId with the actual ID of the Record whose relations you want to retrieve.

To retrieve the Relations of a Record's in RushDB, use the .relations method or make a GET request to the REST API endpoint.

Request

const relations = await db.records.relations("019214ab-ed65-7ce8-9c54-51cdb9b7f662");

Response

[
  {
    "type": "RUSHDB_DEFAULT_RELATION",
    "relations": [
      {
        "count": 2,
        "label": "post"
      }
    ]
  }
]

---

Delete Relation

Endpoints

Remove relation or relations between Records

PUT /api/v1/records/:entityId/relations

info

Note: Replace :entityId with the actual ID of the Record whose relations you want to retrieve.

Removes an existing relation between Records

Request

await db.records.detach("019214e7-6421-790f-b164-24bd73d239f0", ["019214e7-64c6-7a89-8d27-1441b54c4967", "019214e7-647b-7e37-8aaa-b3f1444a2de8"], {
  direction: "out",
  typeOrTypes: "owner"
});

Response

{
  "message": "Relations to Record 019214e7-6421-790f-b164-24bd73d239f0 have been successfully deleted"
}

---

Endpoints Overview

The Relations API provides several endpoints to work with relations. Here's an overview of all available endpoints in this section:

Method	Endpoint	Description
POST	/api/v1/records/:entityId/relations	Create a new Relation
GET	/api/v1/records/:entityId/relations	Retrieve information about Record Relations
PUT	/api/v1/records/:entityId/relations	Remove Relation or Relations