欄位

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

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`
部門	可使用	`CustomTableAccessRequired`
公司	可使用	`CustomTableAccessRequired`

參數

欄位	位置	型別	必填	說明
`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": "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"
  }
]

錯誤

狀態	發生條件	錯誤本文
404	資料表不存在，或不屬於指定範圍。	`{ "detail": "Table 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`
部門	可使用	`CustomTableAccessRequired`
公司	可使用	`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.
`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 columns only: arithmetic / comparison / conditional over same-table numeric columns, plus inline cross-table refs. Column refs in [square brackets] (display names OR internal col_<hex> keys); bare numbers, + - * /, unary minus, parentheses, comparisons < <= > >= == !=, IF(condition, then, else), AND(a, b, ...), OR(a, b, ...). Cross-table ref [LinkCol -> TargetNumericCol] reads a numeric column on a cardinality-one link's target table (gated like a LOOKUP, eval-only — not sortable/filterable). Max 1000 chars, 20 nesting levels, 20 column refs.
`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 columns only, optional: turn a cardinality-many lookup into a single scalar (argmax). {order_column, direction}. order_column is an ORDERABLE stored column (integer/float/date/datetime) on the link TARGET table; direction "desc" surfaces the max (latest/highest) linked row, "asc" the min (earliest/lowest). Ties break by link position then id; NULL order values sort last. Omit for the default list result on a many-link (a cardinality-one lookup is already scalar).
`required`	`boolean`	否	Whether the column is required when creating a record (not allowed for computed columns)
`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 columns (not needed for count): column to aggregate — target-table column for outgoing, source-table column for incoming (sum/avg: integer/float; min/max: also date/datetime; count_distinct: any scalar). LOOKUP columns: scalar field of the target table to surface. Accepted as a display name on input; persisted as 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" \| "boolean" \| "date" \| "datetime" \| "text" \| "select" \| "multi_select" \| "link" \| "rollup" \| "lookup" \| "formula" \| "attachment" \| "json" \| "user" \| "social_client" \| "principal" \| "interval"`	是	Data type: string \| integer \| float \| boolean \| date \| datetime \| text \| select \| multi_select \| link \| rollup \| lookup \| formula \| attachment \| json \| user \| social_client (user/social_client hold ONE tenant-scoped principal id string) \| principal (ONE tagged cell user:<id> \| smc:<id> \| room:<id>; a room assigns every member) \| interval

回應結構

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
  }
}

錯誤

狀態	發生條件	錯誤本文
400	欄位設定不合法、名稱重複、使用保留名稱，或既有資料需要但未提供預設值。	`{ "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." }`
409	兩筆寫入爭用同一批資料列，InnoDB 中止了這一筆。交易已回滾，欄位不會只加到一半——直接重送請求即可。	`{ "detail": "Concurrent write conflict (lock); please retry the request." }`
423	另一個結構遷移正在鎖定資料表。	`{ "detail": "Table is currently locked for migration operation: add_column" }`

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.
`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 columns only: arithmetic / comparison / conditional over same-table numeric columns, plus inline cross-table refs. Column refs in [square brackets] (display names OR internal col_<hex> keys); bare numbers, + - * /, unary minus, parentheses, comparisons < <= > >= == !=, IF(condition, then, else), AND(a, b, ...), OR(a, b, ...). Cross-table ref [LinkCol -> TargetNumericCol] reads a numeric column on a cardinality-one link's target table (gated like a LOOKUP, eval-only — not sortable/filterable). Max 1000 chars, 20 nesting levels, 20 column refs.
`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 columns only, optional: turn a cardinality-many lookup into a single scalar (argmax). {order_column, direction}. order_column is an ORDERABLE stored column (integer/float/date/datetime) on the link TARGET table; direction "desc" surfaces the max (latest/highest) linked row, "asc" the min (earliest/lowest). Ties break by link position then id; NULL order values sort last. Omit for the default list result on a many-link (a cardinality-one lookup is already scalar).
`required`	`boolean`	否	Whether the column is required when creating a record (not allowed for computed columns)
`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 columns (not needed for count): column to aggregate — target-table column for outgoing, source-table column for incoming (sum/avg: integer/float; min/max: also date/datetime; count_distinct: any scalar). LOOKUP columns: scalar field of the target table to surface. Accepted as a display name on input; persisted as 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" \| "boolean" \| "date" \| "datetime" \| "text" \| "select" \| "multi_select" \| "link" \| "rollup" \| "lookup" \| "formula" \| "attachment" \| "json" \| "user" \| "social_client" \| "principal" \| "interval"`	是	Data type: string \| integer \| float \| boolean \| date \| datetime \| text \| select \| multi_select \| link \| rollup \| lookup \| formula \| attachment \| json \| user \| social_client (user/social_client hold ONE tenant-scoped principal id string) \| principal (ONE tagged cell user:<id> \| smc:<id> \| room:<id>; a room assigns every member) \| interval

回應結構

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": {
    "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,
    "name": "優先級",
    "type": "integer",
    "required": false,
    "default_value": 0,
    "max_length": null,
    "description": null,
    "options": null
  },
  "sample": [],
  "errors": [],
  "hint": null
}

錯誤

狀態	發生條件	錯誤本文
404	資料表不存在，或不屬於指定範圍。	`{ "detail": "Table not found in this chatroom" }`

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

欄位	型別	必填	說明
`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).
`required`	`boolean \| null`	否	Whether the column is required
`type`	`"string" \| "integer" \| "float" \| "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)

回應結構

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
}

錯誤

狀態發生條件錯誤本文

狀態	發生條件	錯誤本文
409	有計算欄位相依於此欄位，因而無法執行指定變更。	`{ "detail": { "detail": "Column is referenced by computed columns", "conflicts": [ { "column": "訂單金額", "type": "formula" } ] } }`
423	資料表目前正被資料遷移鎖定。	`{ "detail": "Table is currently locked for migration operation: update_column" }`

409

有計算欄位相依於此欄位，因而無法執行指定變更。

{
  "detail": {
    "detail": "Column is referenced by computed columns",
    "conflicts": [
      {
        "column": "訂單金額",
        "type": "formula"
      }
    ]
  }
}

423

資料表目前正被資料遷移鎖定。

{
  "detail": "Table is currently locked for migration operation: update_column"
}

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

欄位	型別	必填	說明
`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).
`required`	`boolean \| null`	否	Whether the column is required
`type`	`"string" \| "integer" \| "float" \| "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)

回應結構

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
}

錯誤

狀態	發生條件	錯誤本文
404	呼叫者公司內找不到指定資料表或欄位。	`{ "detail": "Table not found in this company" }`

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
  }
}

錯誤

狀態	發生條件	錯誤本文
409	一個或多個計算欄位仍相依於此欄位。	`{ "detail": { "detail": "Column has dependent computed columns", "conflicts": [ { "column": "訂單金額", "type": "formula" } ] } }`
409	兩筆寫入爭用同一批資料列，InnoDB 中止了這一筆。交易已回滾，欄位與各筆記錄中的欄位資料都不會只刪到一半——直接重送請求即可。	`{ "detail": "Concurrent write conflict (lock); please retry the request." }`
423	資料表目前正被資料遷移鎖定。	`{ "detail": "Table is currently locked for migration operation: delete_column" }`