時間型別：date 與 datetime

用途

date 適合生日、到期日與會計日等只在乎日曆日期的資料；datetime 適合預約時段、交貨時間與班次開始時間。例如診所可用 date 記錄看診日，再用 datetime 精確記錄「2026-07-21 14:30」的預約時段。

建立 schema

日期欄的 columns.create body：


{
  "name": "到期日",
  "type": "date",
  "required": false,
  "default_value": "2026-07-31",
  "description": "付款到期日"
}

日期時間欄的 body：


{
  "name": "預約時間",
  "type": "datetime",
  "required": true,
  "default_value": "2026-07-21 14:30",
  "description": "診間預約開始時間"
}

合法與不合法的值

兩種值都是 JSON 字串。date 儲存為 YYYY-MM-DD，datetime 儲存為 YYYY-MM-DD HH:mm：


{
  "data": {
    "到期日": "2026-07-31",
    "預約時間": "2026-07-21 14:30"
  }
}

以下值不合法：第一個不是實際存在的日期，第二個帶有 UTC offset，datetime 一律不接受 offset。


{
  "data": {
    "到期日": "2026-02-30",
    "預約時間": "2026-07-21T14:30:00+08:00"
  }
}

date 必須嚴格是 YYYY-MM-DD。datetime 的紀錄寫入也可以使用 T 分隔與秒數（可帶小數秒）；後端確認它們構成真實的時間後，會把值截斷到分鐘，因此 "2026-07-21T14:30:59" 會儲存成 "2026-07-21 14:30"。結尾的 Z 或 UTC offset 會被拒絕。

顯示與回傳

API 會按原格式回傳字串，不會附加時區或自動轉換成本地時間：


{
  "data": {
    "到期日": "2026-07-31",
    "預約時間": "2026-07-21 14:30"
  }
}

datetime 是儲存時不含秒與時區的 wall-clock 值。前端如果使用 JavaScript Date，請在送出前格式化本地 wall-clock 時間；toISOString() 會轉成 UTC 並附加 Z，這個欄位會拒絕它。

僅遷移會出現的秒數 Schema 從 date 轉成 datetime 時，目前會附加 00:00:00，所以遷移後的資料列儲存並讀回的值含秒。把這個值再次寫入紀錄是安全的——寫入會把它截斷為 YYYY-MM-DD 00:00——但在該列被重寫之前，儲存的字串仍帶著秒：stored filter eq "2026-07-21 00:00" 比對不到它，lte "2026-07-21 00:00" 也會把它排除。

注意事項

date 嚴格使用 YYYY-MM-DD；datetime 儲存並回傳 YYYY-MM-DD HH:mm，中間是空白。
datetime 的紀錄寫入會截斷秒與小數秒（絕不四捨五入），並拒絕 Z 與 UTC offset。default_value、filter 界線與 interval 界線只接受精確的 YYYY-MM-DD HH:mm 形式。
紀錄寫入只儲存到分鐘；儲存的秒數只會來自上述 date 轉 datetime 的 retype。
default_value 不會被正規化就直接驗證；格式正確但不存在的日期仍會被拒。
選填欄的空字串會視為空值；必填欄不可在建立或明確更新時送空值。

試試看

到 API Playground 建立日期欄，再用 records.create 比較空白分隔、ISO T 分隔與帶 UTC offset 的結果。