欄位型別：19 種資料的心智模型

欄位型別同時決定三件事：前端要呈現哪一種輸入控制項、API 接受哪一種 JSON 值，以及資料是直接儲存還是在讀取時推導。先選對型別，之後的驗證、查詢與顯示才不會互相矛盾。

19 種型別地圖

下表是目前後端 ColumnType 的完整集合：19 個值全部列出，沒有省略其他 enum 值。interval 以 {start, end} 物件保存一個半開日期時間範圍，json 直接存一份任意 JSON 文件，而三個 principal 型別各內嵌存一個本租戶的身分。現在該用的是 principal：它的 cell 是單一帶標籤的字串——user:<id>、smc:<id> 或 room:<id>——所以同一欄可以指向內部使用者、社群客戶，或整個聊天室（成員繼承該指派）。user 與 social_client 是較舊的單一種類型別，存的是裸 id。當你需要自己的人員 metadata 時，人員表加 link 仍然是正確模型，但它已經不是表示負責人的唯一方式。

注意 link、rollup、lookup、formula 都不把 cell 值寫進 record.data：link 值在關聯表，另外三種在讀取時計算。attachment 不屬於計算欄；它會把 blob ID 存在 record.data，讀取時再展開成已遮蔽 URL 的附件資料。interval、json 與三個 principal 型別都是直接內嵌儲存且可寫，但 principal cell 在讀取時會被轉換：寫進去是身分字串、讀回來是顯示物件，而在本租戶已無法解析的值會維持原始字串。只有 principal cell 讀取時會帶 ref 與 kind——user 與 social_client 逐位元維持原本的 dict 形狀，前端就是靠這點分辨兩者。

user 指三件不同的事 user 是 ACL 與 IaC 的授權對象種類（grant principal kind）——權限授予給誰。user 同時也是一種欄位型別——紀錄裡的一格。而 user: 還是 principal 欄位裡的一種 cell 標籤。三者只是共用同一個字。

19 種型別的用戶端能力矩陣

這是 schema editor 可直接採用的精簡跨介面模型。「Unique / IaC key」先表示能否成為 unique 規則成分，再表示是否適合當 IaC record natural key。

* 「包含某個 option」請使用舊版 filters map。後端也接受 multi_select 進入 stored_filters 或當 sort key，但兩條路都比較整個已儲存陣列的 JSON_UNQUOTE 字串形式，不理解個別元素，也不是穩定的產品篩選／排序合約。用戶端不應依賴這兩種 encoded-array 行為。

† 計算欄篩選／排序使用 computed_filters 與單欄 sort_by，不屬於 stored filter 或多欄排序。Lookup 必須呈現單一純量（cardinality-one 或帶 pick 的 many lookup），而且不能帶 eval-only 的 fallback；computed-sort guard 也會拒絕 live rows 超過 50,000 的表。

最後一欄談的是 key，不代表所有規則家族。其他規則各自有 operator 與型別 gates。IaC 請使用具有穩定等值表示的 inline scalar：string/text、數值、date/datetime、select 或 principal。Boolean、JSON 與複合 interval 物件會被明確拒絕；list-valued、relation、attachment 與 derived cell 都不是安全的 record-matching key。各介面的 wire rule 差異見檔案匯入、查詢與遷移。

JSON 與 principal 的特殊能力限制

json 刻意不算已儲存純量，而三種 principal 型別都算。這一個差異就決定了下表大部分內容：

這四種型別都一律拒絕 default_value、max_length、options，也都不接受任何附件或計算欄設定欄位。

建立欄位的共同形狀

對既有表新增欄位，使用 columns.create。每個型別頁的「建立 schema」都只顯示該端點的 JSON body；範圍與 table_id 由路徑提供。

{
  "name": "訂單編號",
  "type": "string",
  "required": true,
  "default_value": "待編號",
  "description": "外部 ERP 的訂單識別碼",
  "max_length": 32
}

純量欄可以使用 required、型別相符的 default_value，而 max_length 只適用於 string / text。推導欄是唯讀資料，因此不可設 required、default_value 或 max_length。interval、json、principal、user、social_client 只接受 required 與 description——在這五種型別上宣告 default_value、max_length 或 options，欄位在建立前就會被拒絕。

欄位身分：顯示名稱與內部鍵

建立時送出的 name 是給人看的顯示名稱，例如「訂單編號」。伺服器同時產生穩定的內部鍵，例如 col_c3333333_3333_4333_8333_333333333333，並放進 settings.column_mapping。顯示名稱可以改，內部鍵不變；查詢、更新紀錄與推導欄的持久化引用因此不會因改名失效。完整規則請見欄位身分。

選型原則

• 要讓使用者自由輸入：選 string、text、數值、布林或日期型別。
• 要把一組開始／結束日期時間當成單一值移動與驗證：選 interval。
• 要限制在受控字典：選 select 或 multi_select。
• 要附加檔案：選 attachment，先上傳 blob，再把 blob ID 寫入 cell。
• 要原樣保留一份半結構化資料——webhook body、ERP 封包、每列各自的設定——選 json。但要接受它不能排序、不能當鍵值，也不能餵給 formula。
• 要指向負責人：選 principal。一格可以放 user:<id>、smc:<id> 或 room:<id>，所以同一欄能指向同事、客戶的聊天身分，或整個聊天室（成員繼承該指派）。user 與 social_client 留給既有的單一種類欄位。三者都是 $me row policy 比對的對象。若你需要的是屬於自己 schema 的人員 metadata，改用人員表加 link。
• 要建立表間關係：先建 link；要顯示目標欄用 lookup，要彙總目標列用 rollup。
• 要用欄位組合出新值：選 formula；它與 lookup 一樣唯讀，但公式是運算，不是單純帶出目標值。

試試看

到 API Playground 選擇 columns.create，或用連結與彙總流程精靈實際建立跨表欄位。