連結型別：link

用途

link 建立兩張表之間的紀錄關係，例如每張訂單連到一位客戶，或每個專案連到多位成員。它保存的是目標紀錄 ID，而不是客戶名稱的副本；名稱改變時，來源紀錄仍指向同一筆目標資料。

建立 schema

目標表必須先存在於同一家公司。Link 可以留在來源 scope，也可以沿該公司的 scope 階層向上指向目標：

Link 不可向下（company→department/chatroom 或 department→chatroom）、不可指向同層的其他 department/chatroom，也不可跨公司。以下是 columns.create body：

{
  "name": "客戶",
  "type": "link",
  "target_table_id": "22222222-2222-4222-8222-222222222222",
  "cardinality": "one",
  "description": "這張訂單所屬的客戶"
}

target_table_id 必填。cardinality 可為 "one" 或 "many"；省略時預設 "many"，建立後不可更改。

Wire shape 與內部鍵

link cell 的標準 wire shape 一律是目標紀錄 ID 陣列。建立紀錄時可用顯示名稱作為 key：

{
  "data": {
    "訂單編號": "SO-2026-001",
    "客戶": ["33333333-3333-4333-8333-333333333333"]
  }
}

更新紀錄時使用欄位內部鍵；以下會整組取代現有連結：

{
  "col_c3333333_3333_4333_8333_333333333333": [
    "44444444-4444-4444-8444-444444444444"
  ]
}

後端也接受 cardinality-one 的單一字串，並正規化為一個元素的清單；前端固定使用陣列，可以讓 one / many 共用同一套 cell 型別。

合法與不合法的值

cardinality: "many" 可包含多個非空紀錄 ID，也可用空陣列或 null 清空。更新 many link 時還可使用差量：

{
  "col_c3333333_3333_4333_8333_333333333333": {
    "add": ["55555555-5555-4555-8555-555555555555"],
    "remove": ["44444444-4444-4444-8444-444444444444"]
  }
}

one link 送兩個 ID 不合法：

{
  "data": {
    "客戶": [
      "33333333-3333-4333-8333-333333333333",
      "44444444-4444-4444-8444-444444444444"
    ]
  }
}

建立紀錄時使用 add / remove、在 one link 使用差量，或讓 add 與 remove 重疊，也都會被拒。

顯示與回傳

一般紀錄回應以 link 的顯示名稱為 key，值仍是依連結順序排列的 ID 陣列；即使 cardinality 是 one 也不會折成字串：

{
  "data": {
    "客戶": ["33333333-3333-4333-8333-333333333333"]
  }
}

軟刪除的目標會在讀取時從清單排除。需要人類可讀的標籤時，可在紀錄讀取開啟 expand_links=true，不要把 link cell 誤當成目標列的顯示名稱。

注意事項

• link 值存在獨立的關聯表，永不寫進 record.data；新增 link 欄是 metadata-only，不會回填舊紀錄。
• target_table_id 必須符合上面的同公司向上 scope 矩陣。新增目標 ID 時，後端也會驗證目標存在、未軟刪且呼叫者可讀。
• Link 設定建立後不可變更：PATCH columns/{column_id} 只能修改 name 或 description，不能改 target_table_id、cardinality 或欄位型別。要改關係必須刪除並重建欄位。
• link 不可 required、不可有 default_value 或 max_length；link_field、aggregation、target_column 也不是 link 的設定欄位。
• 顯示名稱可改，但設定與後續推導欄會保存 col_<hex> 內部鍵。請用 column.id 當前端穩定身分。
• 刪除被 rollup、lookup 或 formula 引用的 link 欄會收到 409 依賴衝突，應先處理依賴欄。

試試看

用連結與彙總流程精靈依序建立目標表、來源表與 link，再對照 columns.create 的正式契約。