保存檢視，或執行一次性搜尋

情境：客服每天都要找「待處理」的急件訂單，但臨時調查也需要更自由的搜尋條件。

前置條件

你需要資料表 read 權限；任何 reader 都能建立自己的 private view，只有 table moderator 能建立 shared view。本例使用聊天室 11111111-1111-4111-8111-111111111111 的訂單表 22222222-2222-4222-8222-222222222222。以下 private 請求使用使用者 access token。

先從表格的 settings.column_mapping 取得內部欄位 ID。本例假設「狀態」是 col_33333333_3333_4333_8333_333333333333，「優先序」是 col_44444444_4444_4444_8444_444444444444。

步驟

1. 載入 default view

views.default 會合併讀取表格、目前頁資料列與 my_permissions；它不是已儲存的 view，適合初次開頁。

GET /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/view?skip=0&limit=20&sort_by=updated_at&sort_order=desc&expand_links=false

2. 先以一次性 search 驗證條件

需要 request body 的 typed filters、全文字串 q、computed filters 或複合排序時，使用 records.search。stored_filters.column 與 sort_by 使用內部 ID；q 只在目前使用者可見的 string/text 欄位做不分大小寫的子字串搜尋。

POST /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/records/search?expand_links=false
Content-Type: application/json
 
{
  "stored_filters": [
    {
      "column": "col_33333333_3333_4333_8333_333333333333",
      "op": "eq",
      "value": "待處理"
    }
  ],
  "q": "急件",
  "sort_by": "col_44444444_4444_4444_8444_444444444444",
  "sort_order": "desc",
  "limit": 20,
  "offset": 0
}

先看回傳 records 與 total 是否符合預期，再把條件保存。這能避免建立一個合法但沒有命中資料的 view。

3. 把查詢保存成 view

views.create 的 config 會儲存 filters、搜尋字串、排序與要顯示的欄位，但不儲存分頁；columns 使用顯示名稱。

POST /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/views
Content-Type: application/json
 
{
  "name": "客服待處理急件",
  "is_shared": true,
  "config": {
    "kind": "list",
    "filters": {},
    "stored_filters": [
      {
        "column": "col_33333333_3333_4333_8333_333333333333",
        "op": "eq",
        "value": "待處理"
      }
    ],
    "computed_filters": null,
    "q": "急件",
    "sort_by": "col_44444444_4444_4444_8444_444444444444",
    "sort_order": "desc",
    "columns": ["訂單編號", "狀態", "優先序"]
  }
}

不是 moderator 時，把 is_shared 改為 false。若之後更新 config，請送出完整新 config；不要假設巢狀欄位會 patch 合併。

4. 選擇 list、matrix 或 timeline layout

kind 預設為 list。List view 沒有 layout 子設定，行為與加入 layout kinds 之前建立的 saved view 相同。

Matrix view 會以一個欄位分組資料列，另一軸則使用 date／datetime／select bucket：

{
  "kind": "matrix",
  "matrix": {
    "row_column": "負責人",
    "bucket_column": "到期日",
    "column_bucket": "week",
    "cell_column": "訂單編號"
  }
}

bucket_column 必須是 date、datetime 或 select。Date 與 datetime bucket 接受 day、week 或 month；select 本來就按離散 options 分桶，因此必須使用預設的 column_bucket: "day"。

Timeline view 會把每筆紀錄排成一段 date 或 datetime 範圍：

{
  "kind": "timeline",
  "timeline": {
    "lane_column": "負責人",
    "start_column": "開始時間",
    "end_column": "結束時間",
    "label_column": "訂單編號",
    "slot_minutes": 30
  }
}

start_column 與 end_column 必須是同一類別——兩者都是 date，或兩者都是 datetime。label_column 可省略；slot_minutes 是 5 到 1440 的整數，預設 30。

這些 shape 會 fail closed：kind: "matrix" 必須有 matrix 且禁止 timeline；kind: "timeline" 必須有 timeline 且禁止 matrix；kind: "list" 則禁止兩者。Layout column refs 可使用顯示名稱或內部鍵輸入，持久化為內部鍵，回應時再 echo 為顯示名稱。

後端會保存並驗證這些 layout，但不會執行 pivot 或繪圖。套用任何 kind 都會執行同一個 saved record query 並回傳一般 records；matrix 與 timeline 完全由前端渲染。

5. 列出並套用 saved view

先以 views.list 列出目前使用者可見的 private/shared views 並保留目標 view_id，再把分頁與 link 展開選項交給 views.applyGet。

GET /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/views

GET /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/views/55555555-5555-4555-8555-555555555555/records?skip=0&limit=20&expand_links=false

每次 apply 都會用呼叫者當下的 ACL 重新驗證；shared view 不會讓使用者讀到隱藏欄位或原本不可見的資料列。

6. 為其他讀取選擇正確端點

若只需要翻頁、基本排序、日期區間與可選 link 展開，使用 records.list 的 GET，較容易快取與觀察。若條件只用一次或由使用者即時組合，使用 records.search。只有在條件要命名、分享或重複套用時才建立 saved view；default view 則用於初始頁面 composite load。

你會看到什麼

default view 會同時提供表格、資料與權限；search 會回傳符合條件的資料列；saved view 清單會出現「客服待處理急件」，套用後得到相同條件但由每次請求決定分頁的結果。Matrix 或 timeline view 仍然回傳這些一般 records；client 依回傳的 layout config 自行渲染。

常見錯誤

請直接查看搜尋錯誤表、建立檢視錯誤表、列出檢視錯誤表與套用檢視錯誤表。

試試看

在 API Playground 先送出 records.search，確認命中資料後再依序執行 views.create、views.list 與 views.applyGet。