Skip to main content

​
Overview

LINK and LOOKUP are special workbook column types that enable relational data modeling across tables.
Column TypePurpose
LINKDefines a relationship between two tables
LOOKUPProjects columns from an associated table via a link
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:
FieldDescription
workbookIdCurrent table
associatedTableIdAssociated (linked) table
relationTypeType of relationship
linkColumnIdLink column identifier
associateWorkspaceIdAssociated Workspace identifier
Supported relation patterns:
PatternDescription
ONE_TO_ONEEach record in the source maps to one record in the destination
HAS_MANYOne source record maps to many destination records
MANY_TO_MANYMany source records map to many destination records

​
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.
FieldDescription
columnIdCurrent column ID
tableIdCurrent table ID
associatedTableIdAssociated workbook ID
associateWorkspaceIdAssociated workspace ID for the destination workbook
linkColumnIdLink column ID — used by LOOKUP; references the LINK column’s columnId
relationTypeRelation semantics for LINK

​
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

FieldDescription
sourceRecordIdPK of the current table row
destinationRecordIdPK of the associated table row
linkColumnIdLINK column identifier
tableIdCurrent table ID
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