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

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

欄位型別地圖

編號序列 是 string 的伺服器指派選項，不是另一種 enum 值。設定最外層的 sequence 後，用戶端讀取格式化字串，但不能提供或替換編號；一般 string 欄位仍可寫入。

下表涵蓋已記錄的後端型別，包括已合併的 principal_list，以及已合併的座標型別。decimal 以字串保存精確定點數，scale 決定小數位數；interval 以 {start, end} 保存半開日期時間範圍；json 直接存任意 JSON 文件。三個單一 principal 型別各存一個本租戶身分：principal 是帶 user:<id>、smc:<id> 或 room:<id> 標籤的字串，較舊的 user 與 social_client 則存裸 id。principal_list 改存帶標籤身分的陣列。需要自己的人員 metadata 時，人員表加 link 仍是正確模型。

注意 Link 值在關聯表；rollup、lookup 與 live formula 在讀取時計算，不儲存在 record.data。Formula 預設為 formula_version: 1 與 computation_mode: "live"；v2 stored formula 必須同時設定 formula_version: 2 與 computation_mode: "stored"，才會在交易內於 record.data 維護受保護、唯讀的結果。attachment 不屬於計算欄；它會把 blob ID 存在 record.data，讀取時再展開成已遮蔽 URL 的附件資料。interval、json 與 principal 型別都是直接內嵌儲存且可寫，但 principal cell 在讀取時會被轉換：單一身分成為顯示物件，principal_list 則包含多個身分，而在本租戶已無法解析的值會維持原始字串。只有 principal cell 讀取時會帶 ref 與 kind——user 與 social_client 逐位元維持原本的 dict 形狀，前端就是靠這點分辨兩者。

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

用戶端能力矩陣

這是 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、integer／float／decimal、date/datetime、select 或 principal（decimal 鍵會先正規化到欄位的 scale 再比對）。Boolean、JSON 與複合 interval 物件會被明確拒絕；list-valued、relation、attachment 與 derived cell 都不是安全的 record-matching key。各介面的 wire rule 差異見檔案匯入、查詢與遷移。

JSON 與單一 principal 的特殊能力限制

json 刻意不算已儲存純量，而三種單一 principal 型別都算。principal_list 是陣列，不在這個純量比較表內。這個差異決定了下表大部分內容：

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

建立欄位的共同形狀

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

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

純量欄可以使用 required 與型別相符的 default_value，但 multi_select 與 attachment 不接受預設值。只有 string 與 text 會強制執行 max_length；integer、float、boolean、date 與 datetime 接受它但會忽略。select 與 multi_select 必須提供 options，而 select 的 default_value 必須是其中一個選項。decimal 欄位另外必須提供 precision、scale 與 allow_negative，其 default_value 要用小數字串，並拒絕 max_length 與 options。link 與推導欄不可設 required、default_value 或 max_length：columns.create、columns.preview 與 tables.create（針對 schema_definition 中的欄位）會以 422 驗證錯誤拒絕。對 rollup、lookup 或 formula 欄位送出非 null 值的紀錄 payload，會以 400 拒絕（<Type> column '<col_key>' is computed and read-only）。interval、json、principal、user、social_client 只接受 required 與 description。在 columns.create、columns.preview 與 tables.create 上，於這五種型別或 attachment 宣告 default_value、max_length 或 options，以及在 decimal 上宣告 max_length 或 options，都會在建立任何東西之前以 422 失敗，detail 會列出驗證錯誤。之後執行的檢查在 columns.create 上回 400：options 清單缺少、為空、超過 50 項，或含有空字串、超過 64 字或重複的選項（不是字串清單的 options 值會更早以 422 失敗）、select 或 multi_select 帶 max_length、string、text、integer、float、boolean、date、datetime、link 或推導欄帶 options、任何 multi_select 預設值、不在 options 內的 select 預設值，以及與 string、integer、float、boolean、date 或 datetime 欄位不相符的 default_value。columns.preview 只重跑其中與預設值型別相關的檢查：multi_select 預設值、非字串的 select 預設值，以及與 string、integer、float、boolean、date 或 datetime 欄位不相符的預設值會得到 valid: false；但缺少 options 清單或清單違反上述限制、select 或 multi_select 帶 max_length、上面列出的其他型別帶 options，以及不在 options 內的 select 預設字串，預覽結果都是 valid: true。在 columns.update 上，對不接受預設值的欄位型別送出非 null 的 default_value 是 400。對已有 live 紀錄的表新增 required 欄位時必須提供 default_value，因此必填的 multi_select、attachment、interval、json 或 principal 欄位只能加到沒有 live 紀錄的表。

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

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

選型原則

• 要讓使用者自由輸入：選 string、text、數值、布林或日期型別。
• 金額等必須精確到固定小數位數的數值：選 decimal，並以小數字串交換其值；只有在二進位捨入誤差可以接受時才用 float。
• 要把一組開始／結束日期時間當成單一值移動與驗證：選 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，或用連結與彙總流程精靈實際建立跨表欄位。