Skip to Content
核心概念欄位型別彙總

彙總型別：rollup

用途

rollup 沿著 link 對一組相關紀錄做聚合，例如在客戶表顯示該客戶所有訂單的總金額，或在專案表計算工作項目數。它適合「多筆來源濃縮成一個指標」，而不是複製某一筆目標列的欄位。

建立 schema

先建立 link，再送出 columns.create body。以下 outgoing rollup 沿「訂單」link 加總目標表的「金額」欄：

{
  "name": "訂單總金額",
  "type": "rollup",
  "link_field": "訂單",
  "aggregation": "sum",
  "target_column": "金額",
  "description": "目前連結訂單的總金額"
}

link_field 與 target_column 都接受顯示名稱或 col_<hex> 內部鍵；伺服器解析後以內部鍵保存，使欄位改名不會破壞依賴。

方向與聚合

direction 省略時為 "outgoing"：從本列的 link_field 走到目標列。"incoming" 則對另一張來源表中「連回本列或與本列 link 相符」的紀錄聚合，改用 source_table_id 與 1–3 組 match，不能再設定 link_field。

aggregationtarget_column可用目標型別空集合
count不可設定不讀值欄0
count_distinct必填儲存型純量欄0
sum / avg必填integer、floatnull
min / max必填integer、float、date、datetimenull

另有一個單層例外：需要 target_column 的聚合可以指向數值 formula，但該目標公式只能引用同表的儲存型數值欄，不能再引用 rollup、lookup、其他 formula 或跨表欄位，而且輸出必須是數字。伺服器會把這一層公式內嵌到聚合中。

可選的 filter 會在聚合前篩選來源列，最多 10 個純量 predicate；in 的值清單最多 100 項。

合法與不合法的值

rollup 是唯讀欄。建立或更新紀錄時，合法做法是完全省略它：

{
  "data": {
    "客戶名稱": "青鳥設計"
  }
}

即使數字看起來正確，也不能自行寫入計算結果：

{
  "data": {
    "客戶名稱": "青鳥設計",
    "訂單總金額": 3880.5
  }
}

設定面也有明確限制：count 帶 target_column、sum 缺 target_column，或讓 link_field 指到非 link 欄都不合法。

顯示與回傳

讀取紀錄時，rollup 值會併入 data 並使用顯示名稱：

{
  "data": {
    "客戶名稱": "青鳥設計",
    "訂單總金額": 3880.5
  }
}

count / count_distinct 回數字；數值 sum / avg / min / max 回數字；日期的 min / max 回固定格式字串。空集合的 count 是 0，但沒有讀取權限或依賴失效時是 null，兩者不可混為一談。

注意事項

  • rollup、lookup、formula 每表合計最多 20 欄；link 不計入這個上限。
  • Rollup 設定建立後不可變更。PATCH columns/{column_id} 只能修改 name 或 description；要改 direction、link/source/match、aggregation、target、filter 或型別，必須刪除並重建欄位。
  • rollup 不可 required、不可有 default_value 或 max_length，記錄 payload 的任何非 null 值都會以唯讀錯誤拒絕。
  • 呼叫者無權讀取被聚合表時，cell 為 null，欄位回應會標記 restricted: true；即使 aggregation 是 count 也不回 0。
  • target_column 或 link_field 被刪除時，既有欄位會降級成 null；正常刪欄流程會先用 409 依賴衝突阻擋這種情況。
  • 在本次稽核的後端 source 中，count_distinct、incoming、filter 與全部 v1.1 計算功能都不再受條件控制，舊的 COMPUTED_COLUMNS_V11 gate 已移除。部署環境仍可能執行較舊的 source revision，因此把這份 source contract 當成 live-environment 證據之前，必須另行核對 deployed SHA。

試試看

用連結與彙總流程精靈建立可讀取的 rollup，再用 columns.preview 在落地前查看前 5 筆 sample。

Last updated on
連結查找