Heap.RefLink

Declares a reference field to another record in a heap table (either another or its own). It is analogous to a foreign key in relational databases.

This is a non-standard type in the JSON schema. It is stored in the database as a string identifier of the referenced record, and at runtime, it is represented by an instance of a special class RefLink.

You can read more about working with references in the relevant section of the guide.

Usage / Signature

import { Heap } from '@app/heap'
Heap.RefLink(tableNameOrRepo, options)

When calling Heap.RefLink, you must directly use the Heap object imported from this module; you cannot do:

import { Heap } from '@app/heap'
const RenamedHeap = Heap
RenamedHeap.RefLink(...)

Arguments

• <b id="tableNameOrRepo">tableNameOrRepo</b>: HeapTableRepo | string <b style="color:red">*</b>
  The target table that the reference "points to." It can be specified either as the name of the table or directly as the repository of the target heap table:

  • <b id="tableNameOrRepo_HeapTableRepo">HeapTableRepo</b>: HeapTableRepo
    The repository of the table (result of Heap.Table) that we are referencing.

    This is the recommended and most efficient way. It works in all cases except for recursive references.

  • <b id="tableNameOrRepo_string">string</b>
    The name of the table (the first argument of Heap.Table) that we are referencing. This method is only available for "local" (declared in the same account) target tables. It should only be used in the case of recursive references (when a table references itself or two tables reference each other), as in this case, it is not possible to use the repository for the reference.

    This method is also available for non-recursive cases, but it is not recommended to use it unnecessarily, as it is slightly less performant than declaring the reference through the repository of the target table.

• <b id="options">options</b>: {onDelete}
  An object with additional optional parameters for the field.

  • <b id="onDelete">onDelete</b>: 'restrict' | 'none' (default - 'restrict')
    Defines the integrity control behavior for this field, answering the question: what to do when the record that this field references is deleted.
    • 'restrict' - prohibit deletion. The delete operation will fail with an error.
    • 'none' - (not recommended) ignore. The record will be deleted, and this field will retain a reference to a non-existent record.

  Unlike most other field types, references do not support default values.

Return Value

A JSON schema for a string field (only the string identifier of the referenced record is stored).

Examples

Simple reference declared through a repository

const projects = Heap.Table('projects', {
  name: Heap.String(),
})
const issues = Heap.Table('issues', {
  project: Heap.RefLink(projects),
})
const project1 = await projects.create(ctx, { name: 'project 1' })
const issue1 = await issues.create(ctx, { project: project1 })

Tree structure, self-referencing link

const folders = Heap.Table('folders', {
  name: Heap.String(),
  parent: Heap.Nullable(Heap.RefLink('folders')),
})

Reference to an imported table

import { projects } from '@someAccount/projects'
const issues = Heap.Table('issues', {
  project: Heap.RefLink(projects),
})