欄位

管理一般與計算欄位、預覽結構變更，並掌握資料遷移行為。

同步型別轉換會在母表鎖內一併提交轉換後的資料列、歷史與 schema；失敗不會留下部分已轉換的資料列搭配舊 schema。持鎖期間會檢查目前規則。REST 對超過 10,000 筆資料列的表改走背景轉換，該路徑不屬於這項同步原子性保證；IaC 則同步轉換。編號序列是 string 欄位的頂層 sequence 設定，不是 options.sequence，也不是新的欄位型別。

儲存 decimal 可選用幣別／計量單位中繼資料，無單位 decimal 仍有效。單位設定、受保護的型別轉換及 selector 刪除維持型別化拒絕。

預覽既有欄位更新

已合併 #1941（160f5409d307ea0aef073737878a282ceacbb63e）新增綁定既有 identity 的 update preview，與 columns.preview 的 create preview 不同。此補充來源說明不改離線 OpenAPI pin，也不代表部署驗收。


POST /private/module/custom_tables/company/tables/{table_id}/columns/{column_id}/preview
POST /private/module/custom_tables/department/{department_id}/tables/{table_id}/columns/{column_id}/preview
POST /private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/columns/{column_id}/preview

讀取 columns response，保留內部 column key，不是 display name。改名保留 identity；刪除／重建不能以舊名稱找回原欄位。
POST 預計的 ColumnUpdate body，只更動提供的欄位，unknown field 拒絕。已有數值 Qty 引用的 formula，可用以下更新示例：


{"expression":"[Qty]*3","formula_version":2,"computation_mode":"stored"}

檢查 valid: true、normalized、sample、errors: []、hint。normalized 不含 id、created_at、updated_at。Sample 最多五筆 live、caller-visible {record_id, value}，依 sort_order 再依 record ID 排序，可以遮罩/null 或為空；驗證檢查 bounded projected rows，不只五筆顯示樣本。
若 UI 需要先取得 client-side confirmation，再將原本保留的 update body PATCH 到不含 /preview 的 URL。不要 PATCH 整個 normalized response；PATCH 回 {column, migration_info}，不是 preview sample。

流程沒有 plan_hash、ticket、凍結 row/schema version 或 server-enforced confirmation token。Preview 不修改 schema、record、history、event、version，也不取得 writer migration lock。PATCH 在原本鎖內重新檢查現行 rule、ACL、schema、dependency。Preview 可能過時但不回 plan_stale；以 PATCH 當前結果／拒絕為準。IaC plan hash 是另一流程。

權限、上限與拒絕

Preview 與 PATCH 需相同 moderator 權限，僅可讀不夠。API-key scope 檢查對應 PATCH URL。Sample 保留 row ACL、column masking、來源表 read gate 與 transitive computed restriction，受限定義可帶 normalized.restricted: true。

Preview 取代既有 schema slot，因此在合計 20 個 computed column 上限更新，不是建立第 21 欄。純 metadata 修改不會驗證不相關歷史 formula/rule 或重算 stored cell；formula 變更檢查受影響 dependency、prospective stored result/rule。Required-link、unique、used-option、unit/calendar、reference 限制仍有效。見公式版本、欄位 identity、遷移。

僅 preview 的上限為每個 checked projected table 200 筆 live row（包括 aggregate-rule source table）、共用 2,000 ms projection/remaining-query budget、每個資料表一個加上每位使用者一個 nonblocking preview。自 backend 5.21.0 起，資料表名額只以解析後的資料表作 key，所以 scope 別名與 ID 大小寫共用它，而使用者名額橫跨所有資料表與 scope；不同使用者預覽不同資料表不會互相阻擋。名額在 preview 結束時釋放，worker 終止時 30 秒後到期。Metadata preview 也受限；不裁切 projection、不啟動背景 preview，亦不改 PATCH migration threshold。

目標表本身，或呼叫者可讀的相依表，超過 200 筆上限時回 422 preview_projection_too_large。呼叫者無權讀取的相依 aggregate-rule 表則改回通用的 409 {"detail":{"error":"aggregate_limit_violation","rule_id":"<rule id>","message":"Aggregate constraint cannot be satisfied."}}，因此回應不會洩漏該表的大小。

Status	拒絕
`400`	無效 update/configuration 或 projected rule 失敗，沿用 validator detail
`403`	Moderator/tenant 或 API-key PATCH-scope 拒絕
`404`	刪除／不存在的欄位：`{"detail":"Column not found"}`；table/scope gate 各保留自身訊息
`409`	Dependency/uniqueness 衝突、無權讀取且超過上限的相依表所回的 `detail.error: "aggregate_limit_violation"`，或 `detail.code: "preview_busy"`，訊息為 `Another column update preview is running for this table.` 或 `... for this user.`
`422`	Identifier/body 驗證，或 `detail.code: "preview_projection_too_large"`、`max_rows: 200`
`423`	既有 migration lock，或 `detail.error: "approval_holds_pending"`、`pending_count`
`503`	`detail.code: "preview_projection_timeout"`、`budget_ms: 2000`，或 `"preview_unavailable"`

無效 update preview 使用 HTTP 拒絕，不是 create-preview 的 valid: false 慣例。先檢查現況再重試 busy/temporary failure，不能盲目重試語意衝突。PATCH 對 missing column 也改回 404，不是 400。

新增、更新與刪除：容量與背景新增

欄位新增、更新（PATCH 與公司 scope 的 PUT 別名）與刪除都在 request loop 之外執行，並依 API worker 進行准入。自 backend 5.21.0 起，一個 worker 預設同時最多接納四個；再來的請求會立即被拒絕，不會排隊，回 429、Retry-After: 1 與 {"detail":{"code":"ct.column_operation_busy","message":"Column operation capacity is full on this worker; retry after an operation finishes.","concurrency_limit":4}}。Preview 不使用這些名額。對超過 500 筆 live 紀錄的表新增欄位，會回 migration_info.background_migration: true 與 migration_id（原本是 10,000 筆，且不回 id）；狀態、ct.column_add_* 錯誤碼與由輪詢驅動的復原見遷移。自後端 5.22.0 起，該回填中的死結或鎖等待逾時不會讓新增永久失敗：工作會重跑死結，鎖等待逾時後由狀態輪詢接續，只有第三次因鎖衝突而結束的嘗試，才會把它結束為 ct.column_add_failed。

GET

路由範本/private/module/custom_tables/{scope}/tables/{table_id}/columns

列出資料表欄位

用途

回傳每個欄位的內部 ID、顯示名稱、型別、限制，以及計算欄位設定。

適用時機

適合建立結構編輯器，或把顯示名稱解析成內部欄位 ID。

實際掛載路徑

聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/columns
部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/columns
公司/private/module/custom_tables/company/tables/{table_id}/columns

範圍

範圍	是否提供	驗證與權限
聊天室	可使用	`ChatRoomJoinedRequired + ChatroomTableMetadataReadRequired`
部門	可使用	`DepartmentTableMetadataReadRequired`
公司	可使用	`CompanyTableMetadataReadRequired`

參數

欄位	位置	型別	必填	說明
`table_id`	path	`uuid`	是	要列出欄位的資料表 UUID。

回應結構

List[ColumnResponse]

OpenAPI 快照中沒有此模型的頂層元件欄位。

範例

列出資料表所有欄位

請求

{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}

回應200

[
  {
    "id": "id",
    "name": "id",
    "type": "string",
    "required": true,
    "default_value": null,
    "description": "Auto-generated unique identifier",
    "max_length": null,
    "target_table_id": null,
    "cardinality": null,
    "link_field": null,
    "aggregation": null,
    "target_column": null,
    "direction": null,
    "source_table_id": null,
    "match": null,
    "filter": null,
    "expression": null,
    "options": null,
    "restricted": null,
    "created_at": "2026-07-19T01:10:00",
    "updated_at": "2026-07-19T01:15:00"
  },
  {
    "id": "col_c3333333_3333_4333_8333_333333333333",
    "name": "狀態",
    "type": "string",
    "required": false,
    "default_value": "待處理",
    "description": "訂單處理狀態",
    "max_length": 32,
    "target_table_id": null,
    "cardinality": null,
    "direction": null,
    "source_table_id": null,
    "link_field": null,
    "aggregation": null,
    "target_column": null,
    "match": null,
    "filter": null,
    "expression": null,
    "options": null,
    "restricted": null,
    "created_at": "2026-07-19T01:10:00",
    "updated_at": "2026-07-19T01:15:00"
  }
]

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態	發生條件	錯誤本文
403	聊天室範圍：呼叫者不是該聊天室成員，也不是其部門的部門主管或公司管理者。其他公司的資料表不是 403：自後端 5.21.0 起，它與 id 不存在一樣回 404 CustomTable Not found。	`{ "detail": "Insufficient permissions, not a member, and not at the same department (Required company manager)." }`
404	資料表不存在、已進垃圾桶、不屬於指定範圍，或呼叫者對它沒有任何權限（沒有讀取、編輯或新增層級，也不是 moderator）；每一種情況的回應都和找不到 ID 完全相同。在聊天室範圍中，不存在或已刪除的聊天室 ID 會在查詢資料表之前先回 Chatroom Not found。	`{ "detail": "CustomTable Not found" }`

POST

路由範本/private/module/custom_tables/{scope}/tables/{table_id}/columns

新增資料表欄位

用途

驗證並新增一般欄位或計算欄位；必要時會替既有資料列進行欄位遷移。

適用時機

欄位預覽通過，且已確認資料遷移影響後使用。

實際掛載路徑

聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/columns
部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/columns
公司/private/module/custom_tables/company/tables/{table_id}/columns

範圍

範圍	是否提供	驗證與權限
聊天室	可使用	`CustomTableModeratorRequired`
部門	可使用	`CustomTableModeratorRequired`
公司	可使用	`CustomTableModeratorRequired`

參數

欄位	位置	型別	必填	說明
`table_id`	path	`uuid`	是	要新增欄位的資料表 UUID。

請求結構

ColumnCreate

欄位	型別	必填	說明
`aggregation`	`"count" \| "count_distinct" \| "sum" \| "avg" \| "min" \| "max" \| null`	否	ROLLUP columns only: "count" \| "count_distinct" \| "sum" \| "avg" \| "min" \| "max" over the aggregated rows.
`allow_negative`	`boolean \| null`	否	DECIMAL only: whether negative values are permitted
`allowed_mime_types`	`string[] \| null`	否	ATTACHMENT columns only: allow-list of content types (None/empty = any).
`cardinality`	`"one" \| "many" \| null`	否	LINK columns only: "one" (single linked record) or "many" (default). Immutable after creation.
`default_value`	`string \| integer \| number \| boolean \| null`	否	Default value applied to existing records during migration (not allowed for computed columns)
`description`	`string \| null`	否	Human-readable column description
`direction`	`"outgoing" \| "incoming" \| null`	否	ROLLUP columns only: "outgoing" (default — aggregates this row's link targets, v1 semantics) or "incoming" (aggregates rows of source_table whose link columns point at the same targets as this row's link columns).
`expression`	`string \| null`	否	FORMULA: [column] references, arithmetic (+ - * / and unary minus), comparison (< <= > >= == !=), IF, AND, OR, CONCAT, UPPER, LOWER, LEN, TODAY, YEAR, MONTH, DATEDIFF, DECIMAL, QUANTIZE and DIVIDE. Decimal division uses DIVIDE with explicit scale and rounding mode. [Link -> Target] references read integer/float values through a cardinality-one link and are evaluation-only. At most 1000 characters, 20 nesting levels, 20 field references, and 20 arguments per AND/OR/CONCAT call. See the formula page for operand and exact-decimal rules.
`fallback`	`LookupFallbackConfig \| null`	否	LOOKUP columns only, optional: defaults-table fallback (scope-inheritance resolution). {table_id, match, target_column}. When the primary lookup resolves to null (unlinked row or a genuinely null target cell — never a permission denial), the cell falls back to target_column of the first live row (id order) of the same-scope-or-broader defaults table whose match columns equal the given values ({defaults column: "$row.<my column>" or a scalar literal}, 1-2 equality pairs). Only valid on a cardinality-one link or a picked (argmax) many-lookup. Eval-only: a lookup carrying fallback cannot be used in computed_filters or computed sort (400).
`filter`	`FilterPredicate[] \| null`	否	ROLLUP columns (both directions), optional: scalar predicates on the aggregated rows. Max 10 predicates; "in" value lists max 100 entries.
`link_field`	`string \| null`	否	ROLLUP (outgoing) / LOOKUP columns: the LINK column this column aggregates/looks up over. Accepted as a display name on input; persisted as the internal col_<hex> key (rename-stable).
`match`	`Record<string, string> \| null`	否	ROLLUP direction=incoming only: {source link column -> my link column OR "$self"} (1..3 keys). Each pair's two link columns must target the SAME table; for "$self" the source column must target THIS table. My-side columns must be cardinality "one".
`max_count`	`integer \| null`	否	ATTACHMENT columns only: max files per cell (1 = single-file).
`max_file_bytes`	`integer \| null`	否	ATTACHMENT columns only: per-file size cap in bytes (<=5 GiB).
`max_length`	`integer \| null`	否	Maximum character length (only applicable to string/text types)
`name`	`string`	是	Column display name (unique within the table, non-ASCII allowed)
`options`	`string[] \| null`	否	SELECT/MULTI_SELECT columns only (v1.2): allowed option strings (1-50 options, each 1-64 chars, unique).
`pick`	`ComputedPickConfig \| null`	否	LOOKUP on a cardinality-many link: optional {order_column, direction} selecting one scalar. order_column is a stored integer/float/decimal/date/datetime column on the target table. desc selects the maximum, asc the minimum; ties use link position then id, and null order values sort last. Omit for a list result; cardinality-one lookups are already scalar.
`precision`	`integer \| null`	否	DECIMAL only: maximum significant digits (1..38)
`required`	`boolean`	否	Whether the column is required when creating a record (not allowed for computed columns)
`result_scale`	`integer \| null`	否	DECIMAL rollup avg only: explicit output scale
`rounding_mode`	`"half_even" \| "half_up" \| "down" \| "floor" \| "ceiling" \| null`	否	DECIMAL rollup avg only: explicit rounding mode
`scale`	`integer \| null`	否	DECIMAL only: fixed fractional digits (0..min(18, precision))
`sequence`	`SequenceColumnConfig \| null`	否	STRING only (ct.calendars): server-assigned number series. The value is assigned on insert and never supplied by clients; the config is immutable after creation.
`source_table_id`	`string \| null`	否	ROLLUP direction=incoming only: UUID of the table whose rows are aggregated. The source must belong to the same company and be in the rollup table scope or an allowed ancestor scope: a chatroom rollup may source its own chatroom, owning department, or company; a department rollup may source its own department or company; and a company rollup may source its own company. Downward, sibling, unrelated-department, and cross-company sources are rejected.
`target_column`	`string \| null`	否	ROLLUP: target-table column for outgoing, source-table column for incoming; omitted for count. sum/avg accept integer/float/decimal; min/max also date/datetime; count_distinct accepts a stored scalar. A one-level numeric formula is eligible with the restrictions documented on the rollup page. LOOKUP: a stored scalar target, or a one-level exact decimal formula with no fallback. Input accepts a display name; storage uses the internal col_<hex> key.
`target_table_id`	`string \| null`	否	LINK columns only: UUID of the target table. The target must belong to the same company and be in the source table scope or an allowed ancestor scope: a chatroom table may target its own chatroom, owning department, or company; a department table may target its own department or company; and a company table may target its own company. Downward, sibling, unrelated-department, and cross-company targets are rejected.
`type`	`"string" \| "integer" \| "float" \| "decimal" \| "boolean" \| "date" \| "datetime" \| "text" \| "select" \| "multi_select" \| "link" \| "rollup" \| "lookup" \| "formula" \| "attachment" \| "json" \| "user" \| "social_client" \| "principal" \| "interval"`	是	Data type: string \| integer \| float \| decimal \| boolean \| date \| datetime \| text \| select \| multi_select \| link \| rollup \| lookup \| formula \| attachment \| json \| user \| social_client \| principal \| interval. Decimal values use exact plain strings; user/social_client hold one tenant-scoped id, principal one tagged user:<id> \| smc:<id> \| room:<id> cell.
`unit`	`DecimalUnit \| null`	否	Opt-in currency/UOM dimension; no implicit conversion

回應結構

ColumnCreateResponse

欄位	型別	必填	說明
`column`	`ColumnResponse`	是	The created column details
`migration_info`	`MigrationInfo`	是	Information about record migration

範例

新增帶有預設值的狀態欄位

請求

{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  },
  "body": {
    "name": "狀態",
    "type": "string",
    "required": false,
    "default_value": "待處理",
    "description": "訂單處理狀態",
    "max_length": 32
  }
}

回應200

{
  "column": {
    "id": "col_c3333333_3333_4333_8333_333333333333",
    "name": "狀態",
    "type": "string",
    "required": false,
    "default_value": "待處理",
    "description": "訂單處理狀態",
    "max_length": 32,
    "target_table_id": null,
    "cardinality": null,
    "direction": null,
    "source_table_id": null,
    "link_field": null,
    "aggregation": null,
    "target_column": null,
    "match": null,
    "filter": null,
    "expression": null,
    "options": null,
    "restricted": null,
    "created_at": "2026-07-19T01:10:00",
    "updated_at": "2026-07-19T01:15:00"
  },
  "migration_info": {
    "background_migration": false,
    "migration_id": null,
    "records_migrated": 0,
    "estimated_records": null,
    "default_value_applied": "待處理",
    "message": "Successfully migrated 0 existing records with default value '待處理'",
    "note": null
  }
}

新增 decimal 單價欄位

請求

{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  },
  "body": {
    "name": "單價",
    "type": "decimal",
    "precision": 12,
    "scale": 2,
    "allow_negative": false,
    "required": false,
    "default_value": "0.00",
    "description": "未稅單價"
  }
}

回應200

{
  "column": {
    "id": "col_d4444444_4444_4444_8444_444444444444",
    "name": "單價",
    "type": "decimal",
    "required": false,
    "default_value": "0.00",
    "max_length": null,
    "description": "未稅單價",
    "precision": 12,
    "scale": 2,
    "allow_negative": false,
    "target_table_id": null,
    "cardinality": null,
    "link_field": null,
    "aggregation": null,
    "target_column": null,
    "direction": null,
    "source_table_id": null,
    "match": null,
    "filter": null,
    "expression": null,
    "options": null,
    "restricted": null,
    "created_at": "2026-07-19T01:10:00",
    "updated_at": "2026-07-19T01:15:00"
  },
  "migration_info": {
    "background_migration": false,
    "migration_id": null,
    "records_migrated": 0,
    "estimated_records": null,
    "default_value_applied": "0.00",
    "message": "Successfully migrated 0 existing records with default value '0.00'",
    "note": null
  }
}

新增選用固定 TWD 的 decimal；無單位仍有效

請求

{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  },
  "body": {
    "name": "單價",
    "type": "decimal",
    "precision": 12,
    "scale": 2,
    "allow_negative": false,
    "default_value": "0.00",
    "description": "未稅單價",
    "unit": {
      "kind": "currency",
      "fixed": "TWD"
    }
  }
}

回應200

{
  "column": {
    "id": "col_d4444444_4444_4444_8444_444444444444",
    "name": "單價",
    "type": "decimal",
    "required": false,
    "default_value": "0.00",
    "max_length": null,
    "description": "未稅單價",
    "precision": 12,
    "scale": 2,
    "allow_negative": false,
    "target_table_id": null,
    "cardinality": null,
    "link_field": null,
    "aggregation": null,
    "target_column": null,
    "direction": null,
    "source_table_id": null,
    "match": null,
    "filter": null,
    "expression": null,
    "options": null,
    "restricted": null,
    "created_at": "2026-07-19T01:10:00",
    "updated_at": "2026-07-19T01:15:00",
    "unit": {
      "kind": "currency",
      "fixed": "TWD"
    }
  },
  "migration_info": {
    "background_migration": false,
    "migration_id": null,
    "records_migrated": 0,
    "estimated_records": null,
    "default_value_applied": "0.00",
    "message": "Successfully migrated 0 existing records with default value '0.00'",
    "note": null
  }
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態	發生條件	錯誤本文
400	欄位設定不合法、名稱與既有欄位重複（不分大小寫比較）、使用保留名稱 id、既有資料需要但未提供預設值、資料表屬於其他範圍（Table not found；公司路由會接受同公司的部門資料表），或並行的結構異動先取得了遷移鎖（Table is currently locked for operation: …）。	`{ "detail": "Cannot add required column '狀態' without a default value to a table with 3 existing records. Please provide a default value for the new required column." }`
400	缺少／不相容／無效單位以 detail.code 拒絕，不換算。	`{ "detail": { "code": "ct.unit_config_invalid", "message": "Decimal units are missing or incompatible" } }`
403	呼叫者不是這張資料表的 moderator。moderator 包含明確指定的資料表 moderator，以及依角色而定的人員：聊天室資料表是聊天室建立者或該聊天室所屬部門的主管，部門資料表是該資料表所屬部門的主管，公司資料表是公司管理者（公司管理者是公司所有資料表的 moderator）。讀取、資料列編輯與分享授權都不會賦予結構權限，部門資料表也一樣。403 的 detail 依資料表範圍與呼叫者而不同：聊天室資料表對該聊天室所屬部門內的呼叫者回 Insufficient permissions. Required: table moderator, chatroom creator, or department management rights.，對其他人回 Insufficient permissions. Required: table moderator, chatroom creator, or management rights.；部門資料表對該部門內的呼叫者回 Insufficient permissions. Required: table moderator or department management rights.，對部門外的呼叫者回 Insufficient permissions. Required: table moderator, department manager, or company management rights.；公司資料表回 Insufficient permissions. Required: table moderator or company management rights.；其他公司的資料表不是 403——自後端 5.21.0 起，它與 id 不存在一樣回 404 CustomTable Not found。	`{ "detail": "Insufficient permissions. Required: table moderator, chatroom creator, or department management rights." }`
404	資料表 ID 不存在或已進垃圾桶：moderator 閘門會在查找任何欄位之前回 CustomTable Not found（資料表所屬聊天室已刪除時則回 Chatroom Not found）。	`{ "detail": "CustomTable Not found" }`
409	兩個寫入爭用同一批資料列，InnoDB 中止了這一個。失敗的 transaction 已回滾。計算欄或空表不會新增任何東西；對已有資料列的表，結構異動會和第一批回填一起 commit，其餘回填再逐批 commit，所以請先重新讀取欄位：如果欄位已在清單中，代表結構異動已成功，但回填可能只完成一部分，而重新送出同一份定義會因名稱已存在而回 400。後續批次發生 deadlock 時伺服器會自行重試，因此原本的請求也可能直接回這個 400（Column with name '<name>' already exists），而不是這個 409。超過背景門檻（預設 500 筆 live 紀錄）時，回填改在背景工作中進行：新增回 200 並帶 migration_info.background_migration 為 true，而工作中的鎖衝突不會變成這個 409（自後端 5.22.0 起，工作會重跑 deadlock，並在鎖等待逾時後由下一次狀態輪詢接續）。	`{ "detail": "Concurrent write conflict (lock); please retry the request." }`
422	body 沒通過 ColumnCreate 驗證，這一步在寫入任何欄位之前執行：未知的 key（extra_forbidden）；type、cardinality、aggregation、direction 或 rounding_mode 等列舉值不合法；各型別的欄位矩陣，例如在 link、rollup、lookup 或 formula 欄位上設定 required、default_value 或 max_length，或設定該型別不接受的計算欄、decimal 或 attachment 設定；缺少必要設定，例如沒有 target_table_id 的 link、沒有 link_field 或 target_column 的 lookup，或沒有 aggregation 的 rollup；count 帶 target_column；result_scale 沒有 rounding_mode，或用在非 avg 的 rollup；格式錯誤的 pick、fallback 或 filter；或 formula 語法錯誤（invalid formula expression: …）。detail 會列出每一個欄位層級的錯誤；各型別矩陣檢查遇到第一個失敗就停止，所以一次只回報一個。	`{ "detail": [ { "type": "value_error", "loc": [ "body" ], "msg": "Value error, computed (link/rollup/lookup/formula) columns cannot be required" } ] }`
423	另一個結構遷移正在鎖定資料表。	`{ "detail": "Table is currently locked for migration operation: add_column" }`
423	這張資料表上有待覆核或套用中的暫存變更；在它處理完之前，結構異動會被拒絕。	`{ "detail": { "error": "approval_holds_pending", "pending_count": 1 } }`
429	這個 API worker 已在執行上限數量的欄位操作（預設四個，operator 可設為 1 到 16）。請求會立即被拒絕，不會排隊：請在 Retry-After 指示的延遲（1 秒）後重試。背景新增在回填結束前會一直佔用它的名額。	`{ "detail": { "code": "ct.column_operation_busy", "message": "Column operation capacity is full on this worker; retry after an operation finishes.", "concurrency_limit": 4 } }`

注意事項

每個範圍都需要 CustomTableModeratorRequired。過去部門資料表允許任何能開啟該表的呼叫者新增欄位；現在需要明確指定的資料表 moderator、該表所屬部門的主管，或公司管理者。
回傳的 column.id 是系統產生的 col_<hex> 鍵值；column.name 仍是顯示名稱。
伺服器配置的 sequence 是 string 欄位的頂層 sequence 物件，不是 options.sequence，也不是新欄位型別。既有資料列不會補編號；insert 時省略產生的儲存格。pattern、維度、bucket、gap policy 與拒絕碼見 sequence 概念頁。
一般欄位會回填既有資料：預設不超過 500 筆 live 紀錄時同步進行（operator 可設為 0 到 10,000），超過則在背景進行（background_migration 為 true，並帶 estimated_records；自 backend 5.21.0 起也帶 migration_id）。回填結束前紀錄寫入會回 423，請輪詢 GET …/migrations/{migration_id}/status（status）或 GET …/tables/{table_id}/migration/status（migration_status），直到該筆新增為 completed，或為 failed 並帶 ct.column_add_failed。不要在 is_locked 為 false 時就停止：遺失的 worker 所持有的表鎖會在新增仍是 queued 或 processing 時失效，而且只有之後經授權的輪詢才會重新啟動它。這些輪詢也會重新啟動中斷的回填；新增工作會回報 ct.column_add_interrupted 或 ct.column_add_timeout（由這些輪詢重新啟動），或最終的 ct.column_add_failed。計算欄位不會改走背景，一律同步回應：link、rollup、lookup 與 live formula 欄位只寫入中繼資料，stored formula 則會在請求內重新計算並寫入每一筆 live 紀錄。
decimal 欄位必須提供 precision（1–38）、scale（0 到 min(18, precision)）與 allow_negative，三者都嚴格檢查型別（否則 422）。default_value 必須是純小數字串，並以欄位的 scale 儲存；max_length 與 options 會被拒絕。目標為 decimal 欄位、或結果為 decimal 的 formula 欄位的 avg rollup，也必須同時設定 result_scale（0–18）與 rounding_mode（half_even、half_up、down、floor 或 ceiling）：兩者都省略是 400；只送其中一個、result_scale 不是 0 到 18 的整數，或使用其他 rounding_mode 是 422，把任一欄位用在非 avg 的 rollup 也是 422；把這一對用在其他目標的 avg 上則是 400。
Stored decimal unit 為選用：currency／uom，fixed 或 unit_column 二擇一（string／select／cardinality-one link）。Computed 維度由運算推導，不換算。任何有效／垃圾桶列存在時變更／移除單位，以及受保護型別變更／selector 刪除均拒絕。
ColumnResponse 會省略 attachment 的 max_count/max_file_bytes/allowed_mime_types，以及 lookup 的 pick 與 fallback。要重建完整持久化欄位設定，請以資料表回應的 schema_definition.columns 為準。

POST

路由範本/private/module/custom_tables/{scope}/tables/{table_id}/columns/preview

預覽欄位設定

用途

執行新增欄位的名稱、預設值、連結目標與計算欄位檢查，並取最多五筆既有資料試算，全程不寫入資料。

適用時機

欄位編輯器送出正式新增請求前，先用此端點檢查。

實際掛載路徑

聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/columns/preview
部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/columns/preview
公司/private/module/custom_tables/company/tables/{table_id}/columns/preview

範圍

範圍	是否提供	驗證與權限
聊天室	可使用	`CustomTableModeratorRequired`
部門	可使用	`CustomTableModeratorRequired`
公司	可使用	`CustomTableModeratorRequired`

參數

欄位	位置	型別	必填	說明
`table_id`	path	`uuid`	是	用來檢查目前結構與既有資料的資料表 UUID。

請求結構

ColumnCreate

欄位	型別	必填	說明
`aggregation`	`"count" \| "count_distinct" \| "sum" \| "avg" \| "min" \| "max" \| null`	否	ROLLUP columns only: "count" \| "count_distinct" \| "sum" \| "avg" \| "min" \| "max" over the aggregated rows.
`allow_negative`	`boolean \| null`	否	DECIMAL only: whether negative values are permitted
`allowed_mime_types`	`string[] \| null`	否	ATTACHMENT columns only: allow-list of content types (None/empty = any).
`cardinality`	`"one" \| "many" \| null`	否	LINK columns only: "one" (single linked record) or "many" (default). Immutable after creation.
`default_value`	`string \| integer \| number \| boolean \| null`	否	Default value applied to existing records during migration (not allowed for computed columns)
`description`	`string \| null`	否	Human-readable column description
`direction`	`"outgoing" \| "incoming" \| null`	否	ROLLUP columns only: "outgoing" (default — aggregates this row's link targets, v1 semantics) or "incoming" (aggregates rows of source_table whose link columns point at the same targets as this row's link columns).
`expression`	`string \| null`	否	FORMULA: [column] references, arithmetic (+ - * / and unary minus), comparison (< <= > >= == !=), IF, AND, OR, CONCAT, UPPER, LOWER, LEN, TODAY, YEAR, MONTH, DATEDIFF, DECIMAL, QUANTIZE and DIVIDE. Decimal division uses DIVIDE with explicit scale and rounding mode. [Link -> Target] references read integer/float values through a cardinality-one link and are evaluation-only. At most 1000 characters, 20 nesting levels, 20 field references, and 20 arguments per AND/OR/CONCAT call. See the formula page for operand and exact-decimal rules.
`fallback`	`LookupFallbackConfig \| null`	否	LOOKUP columns only, optional: defaults-table fallback (scope-inheritance resolution). {table_id, match, target_column}. When the primary lookup resolves to null (unlinked row or a genuinely null target cell — never a permission denial), the cell falls back to target_column of the first live row (id order) of the same-scope-or-broader defaults table whose match columns equal the given values ({defaults column: "$row.<my column>" or a scalar literal}, 1-2 equality pairs). Only valid on a cardinality-one link or a picked (argmax) many-lookup. Eval-only: a lookup carrying fallback cannot be used in computed_filters or computed sort (400).
`filter`	`FilterPredicate[] \| null`	否	ROLLUP columns (both directions), optional: scalar predicates on the aggregated rows. Max 10 predicates; "in" value lists max 100 entries.
`link_field`	`string \| null`	否	ROLLUP (outgoing) / LOOKUP columns: the LINK column this column aggregates/looks up over. Accepted as a display name on input; persisted as the internal col_<hex> key (rename-stable).
`match`	`Record<string, string> \| null`	否	ROLLUP direction=incoming only: {source link column -> my link column OR "$self"} (1..3 keys). Each pair's two link columns must target the SAME table; for "$self" the source column must target THIS table. My-side columns must be cardinality "one".
`max_count`	`integer \| null`	否	ATTACHMENT columns only: max files per cell (1 = single-file).
`max_file_bytes`	`integer \| null`	否	ATTACHMENT columns only: per-file size cap in bytes (<=5 GiB).
`max_length`	`integer \| null`	否	Maximum character length (only applicable to string/text types)
`name`	`string`	是	Column display name (unique within the table, non-ASCII allowed)
`options`	`string[] \| null`	否	SELECT/MULTI_SELECT columns only (v1.2): allowed option strings (1-50 options, each 1-64 chars, unique).
`pick`	`ComputedPickConfig \| null`	否	LOOKUP on a cardinality-many link: optional {order_column, direction} selecting one scalar. order_column is a stored integer/float/decimal/date/datetime column on the target table. desc selects the maximum, asc the minimum; ties use link position then id, and null order values sort last. Omit for a list result; cardinality-one lookups are already scalar.
`precision`	`integer \| null`	否	DECIMAL only: maximum significant digits (1..38)
`required`	`boolean`	否	Whether the column is required when creating a record (not allowed for computed columns)
`result_scale`	`integer \| null`	否	DECIMAL rollup avg only: explicit output scale
`rounding_mode`	`"half_even" \| "half_up" \| "down" \| "floor" \| "ceiling" \| null`	否	DECIMAL rollup avg only: explicit rounding mode
`scale`	`integer \| null`	否	DECIMAL only: fixed fractional digits (0..min(18, precision))
`sequence`	`SequenceColumnConfig \| null`	否	STRING only (ct.calendars): server-assigned number series. The value is assigned on insert and never supplied by clients; the config is immutable after creation.
`source_table_id`	`string \| null`	否	ROLLUP direction=incoming only: UUID of the table whose rows are aggregated. The source must belong to the same company and be in the rollup table scope or an allowed ancestor scope: a chatroom rollup may source its own chatroom, owning department, or company; a department rollup may source its own department or company; and a company rollup may source its own company. Downward, sibling, unrelated-department, and cross-company sources are rejected.
`target_column`	`string \| null`	否	ROLLUP: target-table column for outgoing, source-table column for incoming; omitted for count. sum/avg accept integer/float/decimal; min/max also date/datetime; count_distinct accepts a stored scalar. A one-level numeric formula is eligible with the restrictions documented on the rollup page. LOOKUP: a stored scalar target, or a one-level exact decimal formula with no fallback. Input accepts a display name; storage uses the internal col_<hex> key.
`target_table_id`	`string \| null`	否	LINK columns only: UUID of the target table. The target must belong to the same company and be in the source table scope or an allowed ancestor scope: a chatroom table may target its own chatroom, owning department, or company; a department table may target its own department or company; and a company table may target its own company. Downward, sibling, unrelated-department, and cross-company targets are rejected.
`type`	`"string" \| "integer" \| "float" \| "decimal" \| "boolean" \| "date" \| "datetime" \| "text" \| "select" \| "multi_select" \| "link" \| "rollup" \| "lookup" \| "formula" \| "attachment" \| "json" \| "user" \| "social_client" \| "principal" \| "interval"`	是	Data type: string \| integer \| float \| decimal \| boolean \| date \| datetime \| text \| select \| multi_select \| link \| rollup \| lookup \| formula \| attachment \| json \| user \| social_client \| principal \| interval. Decimal values use exact plain strings; user/social_client hold one tenant-scoped id, principal one tagged user:<id> \| smc:<id> \| room:<id> cell.
`unit`	`DecimalUnit \| null`	否	Opt-in currency/UOM dimension; no implicit conversion

回應結構

ColumnPreviewResponse

欄位	型別	必填	說明
`errors`	`ColumnPreviewError[]`	否	Validation rejections (empty when valid)
`hint`	`string \| null`	否	Extra §2.3-style context for a VALID config (e.g. why the sample is all-null under a 'none' read gate)
`normalized`	`object \| null`	否	The config with resolved refs, display-named (bracket-containing column names echo as internal keys — always re-submittable). Carries restricted: true when the caller cannot read the gated table (sample renders all-null, count included).
`sample`	`ColumnPreviewSample[]`	否	Computed values for the first 5 records, through the same permission-gated compute path as real reads
`valid`	`boolean`	是	Whether the submitted column config validates against CURRENT table state

範例

預覽整數欄位

請求

{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  },
  "body": {
    "name": "優先級",
    "type": "integer",
    "default_value": 0
  }
}

回應200

{
  "valid": true,
  "normalized": {
    "max_count": null,
    "max_file_bytes": null,
    "allowed_mime_types": null,
    "target_table_id": null,
    "cardinality": null,
    "link_field": null,
    "aggregation": null,
    "target_column": null,
    "direction": null,
    "source_table_id": null,
    "match": null,
    "filter": null,
    "expression": null,
    "pick": null,
    "fallback": null,
    "name": "優先級",
    "type": "integer",
    "required": false,
    "default_value": 0,
    "max_length": null,
    "description": null,
    "options": null
  },
  "sample": [],
  "errors": [],
  "hint": null
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態	發生條件	錯誤本文
400	抽樣的精確 decimal 計算值溢位或含無效運算。回應為 400，detail 字串帶計算錯誤訊息。	`{ "detail": "ct.numeric_overflow: decimal formula aggregate exceeds the exact SQL domain" }`
403	呼叫者不是這張資料表的 moderator；哪些人算 moderator 請見 columns.create。	`{ "detail": "Insufficient permissions. Required: table moderator, chatroom creator, or department management rights." }`
404	資料表 ID 不存在或已進垃圾桶，或（聊天室範圍）資料表屬於另一個聊天室；回應內容為 CustomTable Not found（資料表所屬聊天室已刪除時則回 Chatroom Not found）。在部門與公司範圍，屬於其他範圍但呼叫者有 moderator 權限的資料表，則會分別回 Table not found in this department 或 Table not found in this company。	`{ "detail": "CustomTable Not found" }`
422	body 沒通過與 columns.create 相同的 ColumnCreate 驗證（見它的 422 那一列）。這些檢查在 preview handler 之前執行，所以回應是 422，而不是 200 加 valid=false。	`{ "detail": [ { "type": "value_error", "loc": [ "body" ], "msg": "Value error, invalid formula expression: chained comparisons are not supported" } ] }`

PATCH

路由範本/private/module/custom_tables/{scope}/tables/{table_id}/columns/{column_id}

更新資料表欄位

用途

修改可變更的欄位屬性；型別改變時，也會處理既有資料的遷移。

適用時機

重新命名、修改說明或限制，或已規劃好型別遷移時使用。

實際掛載路徑

聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/columns/{column_id}
部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/columns/{column_id}
公司/private/module/custom_tables/company/tables/{table_id}/columns/{column_id}

範圍

範圍	是否提供	驗證與權限
聊天室	可使用	`CustomTableModeratorRequired`
部門	可使用	`CustomTableModeratorRequired`
公司	可使用	`CustomTableModeratorRequired`

參數

欄位	位置	型別	必填	說明
`table_id`	path	`uuid`	是	欄位所屬資料表 UUID。
`column_id`	path	`string (col_<hex>)`	是	col_<hex> 格式的系統內部欄位 ID。

請求結構

ColumnUpdate

欄位	型別	必填	說明
`allow_negative`	`boolean \| null`	否	DECIMAL only: permit negative values
`default_value`	`string \| integer \| number \| boolean \| null`	否	New default value
`description`	`string \| null`	否	Human-readable column description
`max_length`	`integer \| null`	否	Maximum character length (string/text types only)
`name`	`string \| null`	否	New column display name
`option_renames`	`Record<string, string> \| null`	否	SELECT/MULTI_SELECT columns (v1.2): rename options ({"old": "new"}) — rewrites every live record cell (data migration, table-level history entry). Cannot be combined with options in one request.
`options`	`string[] \| null`	否	SELECT/MULTI_SELECT columns (v1.2): replace the allowed option list. Removing an option that live records still use is rejected with 409 (usage count included). To rename an option use option_renames instead (cannot be combined with options in one request).
`precision`	`integer \| null`	否	DECIMAL only: maximum significant digits
`required`	`boolean \| null`	否	Whether the column is required
`scale`	`integer \| null`	否	DECIMAL only: fixed fractional digits
`sequence`	`SequenceColumnConfig \| null`	否	ct.calendars: the sequence config is immutable; supplying a config equal to the stored one is a no-op, anything else is refused (409 ct.sequence_config_immutable).
`type`	`"string" \| "integer" \| "float" \| "decimal" \| "boolean" \| "date" \| "datetime" \| "text" \| "select" \| "multi_select" \| "link" \| "rollup" \| "lookup" \| "formula" \| "attachment" \| "json" \| "user" \| "social_client" \| "principal" \| "interval" \| null`	否	New data type (triggers data migration if changed)
`unit`	`DecimalUnit \| null`	否	未指定

回應結構

ColumnUpdateResponse

欄位	型別	必填	說明
`column`	`ColumnResponse`	是	The updated column details
`migration_info`	`MigrationInfo \| null`	否	Information about record migration (only present if type changed or background migration needed)

範例

重新命名狀態欄位

請求

{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "column_id": "col_c3333333_3333_4333_8333_333333333333"
  },
  "body": {
    "name": "處理狀態",
    "description": "目前的訂單處理階段"
  }
}

回應200

{
  "column": {
    "id": "col_c3333333_3333_4333_8333_333333333333",
    "name": "處理狀態",
    "type": "string",
    "required": false,
    "default_value": "待處理",
    "description": "目前的訂單處理階段",
    "max_length": 32,
    "target_table_id": null,
    "cardinality": null,
    "direction": null,
    "source_table_id": null,
    "link_field": null,
    "aggregation": null,
    "target_column": null,
    "match": null,
    "filter": null,
    "expression": null,
    "options": null,
    "restricted": null,
    "created_at": "2026-07-19T01:10:00",
    "updated_at": "2026-07-19T01:15:00"
  },
  "migration_info": null
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態	發生條件	錯誤本文
404	內部 column key 不存在或已移除（已合併 #1941）；改名不改 identity。	`{ "detail": "Column not found" }`
400	缺少／不相容／無效單位以 detail.code 拒絕，不換算。	`{ "detail": { "code": "ct.unit_config_invalid", "message": "Decimal units are missing or incompatible" } }`
403	呼叫者不是這張資料表的 moderator；哪些人算 moderator 請見 columns.create。	`{ "detail": "Insufficient permissions. Required: table moderator, chatroom creator, or department management rights." }`
404	資料表 ID 不存在或已進垃圾桶：moderator 閘門會在查找任何欄位之前回 CustomTable Not found（資料表所屬聊天室已刪除時則回 Chatroom Not found）。你有 moderator 權限、屬於其他範圍的現行資料表會通過閘門，再被路由以 404 Table not found 拒絕；但公司路由會接受同公司的部門資料表，並更新它的欄位。	`{ "detail": "CustomTable Not found" }`
409	除了 integer↔float 之外的型別變更，會破壞引用該欄位的設定（計算欄位、lookup fallback、寫入規則、ACL row policy、public-read 篩選或 column_acl 項目，或 trigger）；conflicts[] 會逐項列出 {type, field, message}。轉換後的值會在 unique 規則下互相衝突的型別變更同樣是 409，帶 unique 規則的衝突 detail，且不會轉換任何東西。	`{ "detail": { "detail": "Column is referenced by computed columns", "conflicts": [ { "type": "dependent_formula", "field": "訂單金額", "message": "Formula column '訂單金額' references this column; delete it first" } ] } }`
409	options 清單移除了仍有 live 資料列在使用的選項：detail 為 {message, column, in_use}，其中 in_use 是各選項被多少筆 live 資料列使用。請先重新命名它們或更新這些資料列；已軟刪除的資料列不會擋住移除。	`{ "detail": { "message": "cannot remove options that live records still use — rename them or update the records first", "column": "col_e5555555_5555_4555_8555_555555555555", "in_use": { "待處理": 3 } } }`
409	有 `date_interval_exclusion` 規則把這個欄位當作起始或結束欄位，而這次更新會把起始欄位改為可選、或把結束欄位改為必填。請先移除規則再變更必填條件。變更邊界欄位的型別則是 `dependent_rule` 衝突；scope link 欄位本身完全不能改型別（`400 Only name/description can be updated on link columns (got: type)`）。	`{ "detail": { "error": "date_interval_exclusion_dependency", "message": "Remove the date interval rule before changing this bound column requirement." } }`
409	暫時性資料庫鎖衝突中止這次操作。同步型別轉換（REST 不超過 10,000 筆資料列；IaC）會在母表鎖內以同一個 transaction 提交轉換後資料列、歷史與 schema，失敗時全部 rollback。REST 超過 10,000 筆時改走背景轉換，不適用這項同步保證。	`{ "detail": "Concurrent write conflict (lock); please retry the request." }`
409	存在有效／垃圾桶列時不能變更 unit；受保護型別變更／selector 刪除也拒絕。	`{ "detail": { "code": "ct.unit_config_immutable", "message": "Decimal units are missing or incompatible" } }`
422	body 沒通過 ColumnUpdate 驗證：帶了 ColumnUpdate 沒有定義的 key，例如 pick、fallback、expression、link_field、target_column、cardinality，或 attachment 限制（extra_forbidden）；type 的值不是任何欄位型別；precision、scale、allow_negative 的型別不對或超出範圍；或其他欄位的值不符合它宣告的型別。	`{ "detail": [ { "type": "extra_forbidden", "loc": [ "body", "pick" ], "msg": "Extra inputs are not permitted", "input": { "order_column": "開立日期", "direction": "desc" } } ] }`
423	資料表目前正被資料遷移鎖定。	`{ "detail": "Table is currently locked for migration operation: update_column" }`
423	這張資料表上有待覆核或套用中的暫存變更；在它處理完之前，結構異動會被拒絕。	`{ "detail": { "error": "approval_holds_pending", "pending_count": 1 } }`
429	這個 API worker 已在執行上限數量的欄位操作（預設四個，operator 可設為 1 到 16）。請求會立即被拒絕，不會排隊：請在 Retry-After 指示的延遲（1 秒）後重試。	`{ "detail": { "code": "ct.column_operation_busy", "message": "Column operation capacity is full on this worker; retry after an operation finishes.", "concurrency_limit": 4 } }`

注意事項

型別遷移會盡力轉換支援的值組合；只有無法轉換的 cell 才退回新預設值或 null。大表可能在背景執行同一套轉換。
編號發出後 sequence 設定不可變更。使用中的 sequence 日期／scope 相依欄位與 period_fence 相依欄位，不能刪除或做不相容的 retype：ct.sequence_config_immutable、ct.sequence_dependency_in_use 或 ct.scope_dependency_in_use。若要刻意變更 fence 來源，先移除相依 fence。
Attachment cap 與多數 link/rollup/lookup 設定仍限建立時。明確 formula v2 可更新 expression、formula_version、computation_mode，仍檢查 dependency/rule；cardinality-one link 可修改 required，受 required-link 驗證限制。其他不支援設定仍為 extra_forbidden。PATCH 前使用欄位 reference 的 identity-bound update-preview 流程；離線 OpenAPI snapshot 保留舊來源 pin。
decimal 欄位的 precision、scale 與 allow_negative，只有在每個已儲存的值（含 live 與已進垃圾桶的資料列）都符合新形狀時才能變更；資料列超過 10,000 筆（含垃圾桶內的）的資料表會被拒絕。縮小 scale 只能捨去值為零的小數位。改寫會在結構 transaction 內為每筆被更動的資料列提升版本並寫入歷史；至少改寫了一個值時，migration_info 會顯示 "Decimal configuration updated; migrated N exact record value(s)"，否則為 null。把欄位改成或改離 decimal 時，資料表必須沒有任何資料列（含垃圾桶內的資料列）。
Stored decimal unit 為選用：currency／uom，fixed 或 unit_column 二擇一（string／select／cardinality-one link）。Computed 維度由運算推導，不換算。任何有效／垃圾桶列存在時變更／移除單位，以及受保護型別變更／selector 刪除均拒絕。

PUT

路由範本/private/module/custom_tables/{scope}/tables/{table_id}/columns/{column_id}

已淘汰

透過已棄用的 PUT 別名更新公司欄位

用途

保留舊版公司層級用戶端的相容性，實際執行內容與 PATCH 相同。

適用時機

只用於維護舊版用戶端；新的整合請改用 PATCH。

實際掛載路徑

公司/private/module/custom_tables/company/tables/{table_id}/columns/{column_id}

範圍

範圍	是否提供	驗證與權限
聊天室	未提供	`不適用`
部門	未提供	`不適用`
公司	可使用	`CustomTableModeratorRequired`

參數

欄位	位置	型別	必填	說明
`table_id`	path	`uuid`	是	公司層級資料表 UUID。
`column_id`	path	`string (col_<hex>)`	是	col_<hex> 格式的系統內部欄位 ID。

請求結構

ColumnUpdate

欄位	型別	必填	說明
`allow_negative`	`boolean \| null`	否	DECIMAL only: permit negative values
`default_value`	`string \| integer \| number \| boolean \| null`	否	New default value
`description`	`string \| null`	否	Human-readable column description
`max_length`	`integer \| null`	否	Maximum character length (string/text types only)
`name`	`string \| null`	否	New column display name
`option_renames`	`Record<string, string> \| null`	否	SELECT/MULTI_SELECT columns (v1.2): rename options ({"old": "new"}) — rewrites every live record cell (data migration, table-level history entry). Cannot be combined with options in one request.
`options`	`string[] \| null`	否	SELECT/MULTI_SELECT columns (v1.2): replace the allowed option list. Removing an option that live records still use is rejected with 409 (usage count included). To rename an option use option_renames instead (cannot be combined with options in one request).
`precision`	`integer \| null`	否	DECIMAL only: maximum significant digits
`required`	`boolean \| null`	否	Whether the column is required
`scale`	`integer \| null`	否	DECIMAL only: fixed fractional digits
`sequence`	`SequenceColumnConfig \| null`	否	ct.calendars: the sequence config is immutable; supplying a config equal to the stored one is a no-op, anything else is refused (409 ct.sequence_config_immutable).
`type`	`"string" \| "integer" \| "float" \| "decimal" \| "boolean" \| "date" \| "datetime" \| "text" \| "select" \| "multi_select" \| "link" \| "rollup" \| "lookup" \| "formula" \| "attachment" \| "json" \| "user" \| "social_client" \| "principal" \| "interval" \| null`	否	New data type (triggers data migration if changed)
`unit`	`DecimalUnit \| null`	否	未指定

回應結構

ColumnUpdateResponse

欄位	型別	必填	說明
`column`	`ColumnResponse`	是	The updated column details
`migration_info`	`MigrationInfo \| null`	否	Information about record migration (only present if type changed or background migration needed)

範例

透過舊版別名更新公司欄位

請求

{
  "pathParams": {
    "table_id": "22222222-2222-4222-8222-222222222222",
    "column_id": "col_c3333333_3333_4333_8333_333333333333"
  },
  "body": {
    "description": "目前的訂單處理階段"
  }
}

回應200

{
  "column": {
    "id": "col_c3333333_3333_4333_8333_333333333333",
    "name": "狀態",
    "type": "string",
    "required": false,
    "default_value": "待處理",
    "description": "目前的訂單處理階段",
    "max_length": 32,
    "target_table_id": null,
    "cardinality": null,
    "direction": null,
    "source_table_id": null,
    "link_field": null,
    "aggregation": null,
    "target_column": null,
    "match": null,
    "filter": null,
    "expression": null,
    "options": null,
    "restricted": null,
    "created_at": "2026-07-19T01:10:00",
    "updated_at": "2026-07-19T01:15:00"
  },
  "migration_info": null
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態	發生條件	錯誤本文
403	呼叫者不是這張資料表的 moderator；哪些人算 moderator 請見 columns.create。	`{ "detail": "Insufficient permissions. Required: table moderator or company management rights." }`
400	缺少／不相容／無效單位以 detail.code 拒絕，不換算。	`{ "detail": { "code": "ct.unit_config_invalid", "message": "Decimal units are missing or incompatible" } }`
409	存在有效／垃圾桶列時不能變更 unit；受保護型別變更／selector 刪除也拒絕。	`{ "detail": { "code": "ct.unit_config_immutable", "message": "Decimal units are missing or incompatible" } }`
404	資料表不存在或已進垃圾桶：moderator 門檻回 CustomTable Not found（資料表所屬聊天室已刪除時回 Chatroom Not found）。你擔任 moderator 的聊天室資料表會通過門檻，但會被以 404 Table not found 拒絕，而同一公司的部門資料表則會被接受，並更新它的欄位。欄位 ID 不存在是 400 Column not found，不是 404。其他所有拒絕都和 PATCH 路由相同：無效更新回 400，被依賴、選項使用中或鎖衝突回 409，body 沒通過 ColumnUpdate 驗證回 422，遷移鎖或待處理核准回 423。	`{ "detail": "CustomTable Not found" }`
422	body 沒通過 ColumnUpdate 驗證：帶了 ColumnUpdate 沒有定義的 key，例如 pick、fallback、expression、link_field、target_column、cardinality，或 attachment 限制（extra_forbidden）；type 的值不是任何欄位型別；precision、scale、allow_negative 的型別不對或超出範圍；或其他欄位的值不符合它宣告的型別。	`{ "detail": [ { "type": "extra_forbidden", "loc": [ "body", "max_count" ], "msg": "Extra inputs are not permitted", "input": 3 } ] }`
429	這個 API worker 已在執行上限數量的欄位操作（預設四個，operator 可設為 1 到 16）。請求會立即被拒絕，不會排隊：請在 Retry-After 指示的延遲（1 秒）後重試。	`{ "detail": { "code": "ct.column_operation_busy", "message": "Column operation capacity is full on this worker; retry after an operation finishes.", "concurrency_limit": 4 } }`

DELETE

路由範本/private/module/custom_tables/{scope}/tables/{table_id}/columns/{column_id}

刪除資料表欄位

用途

從結構移除欄位，並永久刪除所有資料列中的該欄位值。

適用時機

確認沒有計算欄位相依，且能接受資料遺失後再使用。

實際掛載路徑

聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/columns/{column_id}
部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/columns/{column_id}
公司/private/module/custom_tables/company/tables/{table_id}/columns/{column_id}

範圍

範圍	是否提供	驗證與權限
聊天室	可使用	`CustomTableModeratorRequired`
部門	可使用	`CustomTableModeratorRequired`
公司	可使用	`CustomTableModeratorRequired`

參數

欄位	位置	型別	必填	說明
`table_id`	path	`uuid`	是	欄位所屬資料表 UUID。
`column_id`	path	`string (col_<hex>)`	是	要刪除的系統內部欄位 ID。

回應結構

ColumnDeleteResponse

欄位	型別	必填	說明
`message`	`string`	是	Deletion status message
`migration_info`	`MigrationInfo \| null`	否	Information about migration for large datasets

範例

刪除測試用欄位

請求

{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "column_id": "col_c3333333_3333_4333_8333_333333333333"
  }
}

回應200

{
  "message": "Column deleted successfully",
  "migration_info": {
    "background_migration": false,
    "migration_id": null,
    "records_migrated": 0,
    "estimated_records": null,
    "default_value_applied": null,
    "message": "Synchronously removed column data from 0 records",
    "note": null
  }
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態	發生條件	錯誤本文
400	在不超過 10,000 筆資料列的資料表上，欄位 ID 是系統欄位 id（Cannot delete the 'id' column），或並行的 schema 變更在路由的 423 鎖檢查與刪除之間取得了資料表的遷移鎖（Table is locked for operation: <operation>）。資料列超過 10,000 筆時，id 欄位會先以 200 接受，改由背景工作失敗。	`{ "detail": "Cannot delete the 'id' column" }`
403	呼叫者不是這張資料表的 moderator；哪些人算 moderator 請見 columns.create。	`{ "detail": "Insufficient permissions. Required: table moderator, chatroom creator, or department management rights." }`
404	資料表 ID 不存在或已進垃圾桶：moderator 閘門會在查找任何欄位之前回 CustomTable Not found（資料表所屬聊天室已刪除時則回 Chatroom Not found）。	`{ "detail": "CustomTable Not found" }`
404	在不超過 10,000 筆資料列的資料表上，欄位 ID 不存在或資料表屬於其他範圍時回 Column or table not found，刪除系統欄位 id 則是 400；公司路由是例外，會刪除同公司部門資料表的欄位。資料列超過 10,000 筆時，屬於其他範圍的資料表會先被拒絕（聊天室範圍回 CustomTable Not found，部門範圍回 Table not found，公司範圍回 Table not found in this company），被鎖定的資料表（423）或有相依計算欄位（409）也會被拒絕；其他請求先以 200 接受，欄位 ID 不存在或刪除 id 欄位則改由背景工作失敗回報。	`{ "detail": "Column or table not found" }`
409	有東西引用了這個欄位：本表或其他表的 rollup、lookup（含其 fallback）或 formula、寫入規則（same_dimension_reference 規則另帶 code same_dimension_reference_dependency）、ACL row policy 或 column_acl 項目、public-read 篩選，或 trigger；conflicts[] 會逐項列出 {type, field, message}。資料列不超過 10,000 筆時，不論相依項目是什麼，外層 detail 都是 Column has dependent rollup columns；較大的表則以 Column has dependent computed columns 回傳同一份清單。	`{ "detail": { "detail": "Column has dependent rollup columns", "conflicts": [ { "type": "dependent_formula", "field": "訂單金額", "message": "Formula column '訂單金額' references this column; delete it first" } ] } }`
409	兩個寫入爭用同一批資料列，InnoDB 中止了這一個。失敗的 transaction 已回滾，但結構移除會在逐筆紀錄清理之前 commit，所以請先重新讀取欄位：如果欄位已消失，代表刪除已成功，重試會回 404。	`{ "detail": "Concurrent write conflict (lock); please retry the request." }`
409	存在有效／垃圾桶列時不能變更 unit；受保護型別變更／selector 刪除也拒絕。	`{ "detail": { "code": "ct.unit_config_immutable", "message": "Decimal units are missing or incompatible" } }`
423	資料表目前正被資料遷移鎖定。	`{ "detail": "Table is currently locked for migration operation: delete_column" }`
423	這張資料表上有待覆核或套用中的暫存變更，因此在它處理完之前，刪除會被拒絕。資料列超過 10,000 筆時，請求會回 200，同樣的拒絕改由背景工作失敗回報。	`{ "detail": { "error": "approval_holds_pending", "pending_count": 1 } }`
429	這個 API worker 已在執行上限數量的欄位操作（預設四個，operator 可設為 1 到 16）。請求會立即被拒絕，不會排隊：請在 Retry-After 指示的延遲（1 秒）後重試。	`{ "detail": { "code": "ct.column_operation_busy", "message": "Column operation capacity is full on this worker; retry after an operation finishes.", "concurrency_limit": 4 } }`

注意事項

這和資料表垃圾桶不同：欄位資料會從所有資料列移除，之後也無法靠資料表還原端點找回。
資料列超過 10,000 筆時，刪除會在背景執行：回 200 Column deletion started，並帶 migration_info.migration_id；請輪詢 GET …/migrations/{migration_id}/status（結果保留一小時）。
編號發出後 sequence 設定不可變更。使用中的 sequence 日期／scope 相依欄位與 period_fence 相依欄位，不能刪除或做不相容的 retype：ct.sequence_config_immutable、ct.sequence_dependency_in_use 或 ct.scope_dependency_in_use。若要刻意變更 fence 來源，先移除相依 fence。
Stored decimal unit 為選用：currency／uom，fixed 或 unit_column 二擇一（string／select／cardinality-one link）。Computed 維度由運算推導，不換算。任何有效／垃圾桶列存在時變更／移除單位，以及受保護型別變更／selector 刪除均拒絕。