Records

In Collect, 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 CollectRecord = {
  // autogenerated UUIDv7
  __id: string

  // optional 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 Collect simply pass one-level object to .create method or through the REST API in body.

Request

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

Response

// CollectRecord
{
  "__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 CollectInstance.records.createMany({
  label: "PRODUCT",
  payload: [
    {
      title: 'T-Shirt',
      price: 50,
    },
    {
      title: 'Sneakers',
      price: 135,
      // Nested Records `SIZE`
      SIZE: [
        {
          uk: 8.5,
          qty: 5
        }
      ]
    }
  ]
})

Response

// CollectRecord[]
[
  {
    "__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 Collect, use the .find method or make a POST request to the REST API endpoint.

Request

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

Response

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

---

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 Collect, use the .findById method or make a GET request to the REST API endpoint.

Request

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

Response

// CollectRecord
{
  "__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 Collect, use the .update method or make a PUT request to the REST API endpoint.

Request

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

Response

// Updated CollectRecord
{
  "__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 Collect, use the .delete method or make a DELETE request to the REST API endpoint.

Request

await Collect.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.