Records

In RushDB, you have the capability to store meaningful data within Records. These Records consist of individual data pieces, each containing keys and their corresponding values - Properties.

Typescript Definition

type MaybeArray<T> = T | T[]
type PropertyType = "number" | "string" | "boolean" | "datetime" | "null"

type DBRecord = {
  // autogenerated UUIDv7
  __id: string

  // Record label (Order, User, Route, ...)
  __label: string

  // autogenerated map of Record's properties types
  __proptypes: Record<string, PropertyType>

  // Record's own properties
  [key?: string]: MaybeArray<number | string | null | boolean>
}

Data Example

{
  "__id": "0191b44a-c815-7d40-bf48-b2d1727670d7",
  "__label": "ORDER",
  "__proptypes": {
    "items": "number",
    "sum": "number",
    "promocode": "string",
    "confirmed": "boolean",
    "createdAt": "datetime"
  },
  "items": 5,
  "sum": 232,
  "promocode": "3heg09j",
  "confirmed": true,
  "createdAt": "2024-09-02T19:22:21+0000"
}

How it works

Consider a Record as a row in a database, with each Property being like a column. Though the inner implementation may involve complex graph structures, at its core, a Record is just an object that holds simple keys and values. You can think of it as a "dictionary", "map", "hash table", or "associative array" depending on your programming language or context.

Create Record

Endpoints

Create single Record

POST /api/v1/records

Create single Record related to specific Record

POST /api/v1/records/:id

info

Note: New Record will be created with a default incoming Relation from the Record provided in the :id parameter.

To create Record in RushDB simply pass one-level object to .create method or through the REST API in body.

Request

await db.records.create("ORDER", {
  items: 5,
  sum: 232,
  promocode: "3heg09j",
  confirmed: true,
  createdAt: "2024-09-02T19:22:21+0000"
})

Response

// DBRecord
{
  "__id": "0191b44a-c815-7d40-bf48-b2d1727670d7",
  "__label": "ORDER",
  "__proptypes": {
    "items": "number",
    "sum": "number",
    "promocode": "string",
    "confirmed": "boolean",
    "createdAt": "datetime"
  },
  "items": 5,
  "sum": 232,
  "promocode": "3heg09j",
  "confirmed": true,
  "createdAt": "2024-09-02T19:22:21+0000"
}

Bulk Create Records

Endpoints

Create Records from JSON-like data:

POST /api/v1/import/json

Create Records from CSV-like data:

POST /api/v1/import/csv

info

Please note that the maximum payload size for a single request is 24MB.

This API allows you to push data and get it is automatically normalized, and labels are generated based on the structure of the payload. The API also suggests data types for each field within the payload. Currently, this API supports JSON and CSV formats, with upcoming support for YAML, NDJSON, XML, and GEXF.

This API facilitates the creation of records and their relationships using a Breadth-First Search (BFS) algorithm, ensuring accurate and efficient connections between data points.

Request

await db.records.createMany({
  label: "PRODUCT",
  payload: [
    {
      title: 'T-Shirt',
      price: 50,
    },
    {
      title: 'Sneakers',
      price: 135,
      // Nested Records `SIZE`
      SIZE: [
        {
          uk: 8.5,
          qty: 5
        }
      ]
    }
  ]
})

Response

// DBRecord[]
[
  {
    "__id": "0191b44a-c815-7d40-bf48-b2d1727670d5",
    "__label": "PRODUCT",
    "__proptypes": {
      "title": "string",
      "price": "number"
    },
    "title": 'T-Shirt',
    "price": 50
  },
  {
    "__id": "0191b44a-c815-7d40-bf48-b2d1727670d4",
    "__label": "PRODUCT",
    "__proptypes": {
      "title": "string",
      "price": "number"
    },
    "title": 'Sneakers',
    "price": 135
  },
  {
    "__id": "0191b44a-c815-7d40-bf48-b2d1727670d3",
    "__label": "SIZE",
    "__proptypes": {
      "uk": "number",
      "qty": "number"
    },
    "uk": 8.5,
    "qty": 5
  }
]

Search

Endpoints

Search from root:

POST /api/v1/records/search

Search from specific Record:

POST /api/v1/records/:id/search

info

Note: When searching from a specific Record, replace :id with the actual ID of the Record you want to start the search from.

To search for Records in RushDB, use the .find method or make a POST request to the REST API endpoint.

Request

await db.records.find("PRODUCT", {
  where: {
    title: { $contains: "Sneakers" },
    SIZE: {
      uk: { $gte: 8, $lte: 9 },
      qty: { $gt: 0 }
    }
  }
})

Response

// DBRecord[]
[
  {
    "__id": "0191b44a-c815-7d40-bf48-b2d1727670d4",
    "__label": "PRODUCT",
    "__proptypes": {
      "title": "string",
      "price": "number"
    },
    "title": 'Sneakers',
    "price": 135
  },
  // ...
]

Search with Data Aggregation

Endpoints

Search from root:

POST /api/v1/records/search

Search from specific Record:

POST /api/v1/records/:id/search

info

Note: When searching from a specific Record, replace :id with the actual ID of the Record you want to start the search from.

You can also return records related to a given Record (those that have a Relation with that Record) during the search. Sometimes, you may also need to perform mathematical operations on your data during the search, adding new dynamic fields to the response.

Below, you can see an example that will return all available shoe sizes and also add the minimum and maximum UK size.

Read more about Search with Data Aggregation

Request

await db.records.find("PRODUCT", {
  where: {
    title: { $contains: "Sneakers" },
    SIZE: {
      // Linking the aggregate field with the where condition
      $alias: "$size",
      uk: { $lte: 10 },
      qty: { $gt: 0 }
    }
  },
  aggregate: {
    // Add the necessary PRODUCT fields that need to be returned in the Response.
    title: "$record.title",
    price: "$record.price",
    // Return all sizes related to PRODUCT
    SIZE: {
    fn: 'collect',
    uniq: true,
    alias: '$size',
  },
  // Add a field with the minimum and maximum sizes for the found SIZE
  minSize: { fn: 'min', field: 'uk', alias: '$size' },
  maxSize: { fn: 'max', field: 'uk', alias: '$size' },
},
})

Response

// DBRecord[]
[
{
  "__id": "0191b44a-c815-7d40-bf48-b2d1727670d4",
  "__label": "PRODUCT",
  "__proptypes": {
    "title": "string",
    "price": "number"
  },
  "title": 'Sneakers'
  "price": 135,
  "maxSize": 8,
  "minSize": 3,
  "SIZE": [
    {
      "__id": "0193dabd-c783-76f2-bb8f-c18ac915c91b",
      "__label": "SIZE",
      "uk": 7,
      "qty" 2,
      // Remaining SIZE properties
      "__proptypes": {
        "uk": "number",
        "qty": "number"
      },
    }
  // Other SIZE records
  ]
},
// ...
]

Get Record

Endpoint

Get single Record

GET /api/v1/records/:id

info

Note: Replace :id with the actual ID of the Record you want to retrieve.

To retrieve a Record in RushDB, use the .findById method or make a GET request to the REST API endpoint.

Request

const record = await db.records.findById(
"0191b44a-c815-7d40-bf48-b2d1727670d7"
)

Response

// DBRecord
{
  "__id": "0191b44a-c815-7d40-bf48-b2d1727670d4",
  "__label": "PRODUCT",
  "__proptypes": {
    "title": "string",
    "price": "number"
  },
  "title": 'Sneakers',
  "price": 135
}

Update Record

Endpoint

Update single Record

PUT /api/v1/records/:id

info

Note: Replace :id with the actual ID of the Record you want to update.

To update a Record in RushDB, use the .update method or make a PUT request to the REST API endpoint.

Request

await db.records.update("0191b44a-c815-7d40-bf48-b2d1727670d7", {
  sum: 250,
  confirmed: false
})

Response

// Updated DBRecord
{
  "__id": "0191b44a-c815-7d40-bf48-b2d1727670d7",
  "__label": "ORDER",
  "__proptypes": {
    "items": "number",
    "sum": "number",
    "promocode": "string",
    "confirmed": "boolean",
    "createdAt": "datetime"
  },
  "items": 5,
  "sum": 250,
  "promocode": "3heg09j",
  "confirmed": false,
  "createdAt": "2024-09-02T19:22:21+0000"
}

Delete Records

Endpoint

Delete single Record

DELETE /api/v1/records/:id

info

Note: Replace :id with the actual ID of the Record you want to delete.

To delete a Record in RushDB, use the .delete method or make a DELETE request to the REST API endpoint.

Request

await db.records.delete("0191b44a-c815-7d40-bf48-b2d1727670d7")

Response

// Successful deletion
{
  "success": true,
  "message": "Record successfully deleted"
}

Endpoints Overview

The Records API provides several endpoints for managing and interacting with Records. Here's an overview of all available endpoints in this section:

Method	Endpoint	Description
POST	`/api/v1/records`	Create a single Record
POST	`/api/v1/records/:id`	Create a single Record as a child of a specific Record
GET	`/api/v1/records/:id`	Retrieve a single Record
POST	`/api/v1/records/search`	Search for Records from the root (all data in the project)
POST	`/api/v1/records/:id/search`	Search for Records from a specific Record to its nested children
PUT	`/api/v1/records/:id`	Update a single Record
PUT	`/api/v1/records/delete`	Delete Records by criteria
DELETE	`/api/v1/records/:id`	Delete a single Record
POST	`/api/v1/records/:id/properties`	Get detailed list of Record's Properties

Each endpoint is designed to perform specific operations on Records, allowing you to create, read, update, delete, and search for Records within your project. The following sections provide more detailed information about each operation.

Typescript Definition​

Data Example​

How it works​

Create Record​

Endpoints​

Request​

Response​

Bulk Create Records​

Endpoints​

Request​

Response​

Search​

Endpoints​

Request​

Response​

Search with Data Aggregation​

Endpoints​

Request​

Response​

Get Record​

Endpoint​

Request​

Response​

Update Record​

Endpoint​

Request​

Response​

Delete Records​

Endpoint​

Request​

Response​

Endpoints Overview​

Typescript Definition

Data Example

How it works

Create Record

Endpoints

Request

Response

Bulk Create Records

Endpoints

Request

Response

Search

Endpoints

Request

Response

Search with Data Aggregation

Endpoints

Request

Response

Get Record

Endpoint

Request

Response

Update Record

Endpoint

Request

Response

Delete Records

Endpoint

Request

Response

Endpoints Overview