公式型別：formula

用途

formula 用現有欄位推導數字、布林或字串，例如訂單明細的「小計 = 單價 × 數量」、庫存表的「需要補貨 = 庫存 < 安全水位」，或把姓氏與名字串成顯示名稱。公式不保存結果；每次讀取紀錄時由伺服器求值。

建立 schema

以下是 columns.create body。被引用欄位必須先存在：

{
  "name": "小計",
  "type": "formula",
  "expression": "[單價] * [數量]",
  "description": "未稅小計"
}

顯示名稱與 col_<hex> 都可放在方括號中。伺服器會把引用改寫成內部鍵保存，再於回應中盡可能轉回顯示名稱；名稱含 [、] 或 -> 時，必須直接使用內部鍵。

運算子與函式

例如把數值比較與條件組合：

{
  "name": "覆核等級",
  "type": "formula",
  "expression": "IF(AND([金額] > 10000, [折扣率] > 0.2), 2, 1)"
}

跨表引用

語法 [LinkCol -> TargetNumericCol] 可沿本表的 cardinality-one link 讀取目標表的 integer 或 float：

{
  "name": "可用額度",
  "type": "formula",
  "expression": "[客戶 -> 信用額度] - [本次金額]"
}

跨表引用與 lookup 使用同一套權限遮蔽，但它只是 formula 的求值輸入，不會額外建立可獨立顯示的 lookup 欄。many link 會產生清單，因此不允許直接跨表引用；請先建立 rollup，或改用 one link。每個公式最多 5 組不同跨表 hop，整張表最多 30 組。

合法與不合法的值

formula 是唯讀欄；寫紀錄時必須省略公式值：

{
  "data": {
    "數量": 2,
    "單價": 1290.5
  }
}

自行送出「小計」會被拒，即使值剛好等於伺服器計算結果：

{
  "data": {
    "數量": 2,
    "單價": 1290.5,
    "小計": 2581.0
  }
}

以下 expression 也不合法：單一 = 不是相等運算子，鏈式比較不支援。

{
  "name": "錯誤公式",
  "type": "formula",
  "expression": "[數量] = 2 < 3"
}

顯示與回傳

公式值在讀取時計算並併入 data。算術回數字、比較與 AND/OR 回布林、字串函式回字串：

{
  "data": {
    "數量": 2,
    "單價": 1290.5,
    "小計": 2581.0
  }
}

任一必要運算元為 null、除以 0、非有限結果、依賴失效、循環或超深時，cell 會降級為 null，不會讓整頁讀取失敗。公式鏈最多 5 層；expression 最長 1000 字、括號最深 20 層、欄位引用最多 20 個。

用 columns.preview 在伺服器試算

在真正建立前，把完全相同的 body 送到 columns.preview。成功時回正規化設定與前 5 筆 sample：

{
  "valid": true,
  "normalized": {
    "name": "小計",
    "type": "formula",
    "required": false,
    "default_value": null,
    "max_length": null,
    "description": "未稅小計",
    "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": "[單價] * [數量]",
    "options": null,
    "restricted": null
  },
  "sample": [
    {
      "record_id": "33333333-3333-4333-8333-333333333333",
      "value": 2581.0
    }
  ],
  "errors": [],
  "hint": null
}

引用型別、循環或跨表設定錯誤會以 valid: false 與 errors[].field/message/hint 回傳。純語法錯誤更早由伺服器的 ColumnCreate 驗證器解析，回應 detail 會包含 invalid formula expression:；這不是瀏覽器端自行產生的錯誤，因此前端仍應顯示伺服器訊息。

注意事項

• formula 只接受 expression，不可再帶 link_field、aggregation、target_column、required、default_value 或 max_length。
• Expression 是建立時設定。PATCH columns/{column_id} 只能修改 name 或 description；要改 expression 或型別，必須刪除並重建 formula 欄。
• 一般算術只能引用數值輸出。字串與日期欄可和同類輸出比較，也可放進相容的字串／日期函式，但不能當成算術運算元。cardinality-many lookup 不能作為純量公式輸入。
• IF 的條件為 null 時整個結果為 null；AND、OR 與列出的函式也會在任一參數為 null 時傳播 null。
• 公式引用會持久化為內部鍵，欄位改名安全；刪除或改型別時，後端會用 409 依賴衝突保護仍被引用的欄位。

試試看

到 API Playground 選擇 columns.preview，先觀察 sample 與結構化錯誤，再把同一份 body 送到 columns.create。