Skip to main content

​
Overview

LINK and LOOKUP are special workbook column types that enable relational data modeling across tables. Both are configured through ColumnDTO.colOptions. A table can have multiple link columns, and each link can have multiple lookup columns.

​
UI Data Types

LINK

Special column used to represent inter-table relations.

LOOKUP

Special column used to project associated table fields via a link.
A LINK column stores metadata for: Supported relation patterns:

​
LOOKUP Semantics

A LOOKUP column is tightly coupled with a specific LINK column.
  • References a link using linkColumnId
  • Represents a selected column from the associated table
  • Multiple lookup columns can be defined for the same link

​
Metadata in ColumnDTO.colOptions

Use colOptions to persist link/lookup metadata.

​
Manual Linking Record Flow

To create manual record-level links:
1

Fetch Schema

Fetch the associated workbook schema and data using the associate workspace Id.
2

Select Record

User selects associated record(s) to link.
3

Send Payload

Send linking payload with sourceRecordId, destinationRecordId, and linkColumnId.
4

Backend Resolves

Backend resolves link metadata from linkColumnId — relation type, associated table, and direction/constraints.
5

Store Relation

Backend applies relation rules and stores the link relation.

​
Record Linking Contract

Backend derives all remaining relation metadata from the link configuration.

​
Important Notes

LINK and LOOKUP are column-level constructs first — record linking is a data-level operation built on top.
  • LOOKUP behavior depends on LINK existence and metadata integrity
  • With multiple links to the same associated table, each LOOKUP must bind to the correct linkColumnId
  • Always treat the associated row ID as the associated table PK for linking UI selection