數值型別：integer 與 float

用途

integer 適合件數、庫存量與優先級等離散數量；float 適合單價、重量與轉換率等可能有小數的數值。例如訂單明細用 integer 儲存數量 2，再用 float 儲存單價 1290.5，公式欄即可算出小計。若價格或稅率必須精確到固定小數位數，請改用 decimal。

建立 schema

整數欄的 columns.create body：


{
  "name": "數量",
  "type": "integer",
  "required": true,
  "default_value": 1,
  "description": "本次訂購件數"
}

浮點數欄的 body：


{
  "name": "單價",
  "type": "float",
  "required": true,
  "default_value": 0.0,
  "description": "未稅單價"
}

合法與不合法的值

原生 JSON 數字是最穩定的寫法；float 同時接受整數與小數。選填欄也接受 null 或空字串作為空值，整合端建議固定送 null。


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

REST 寫入路徑也會把可解析的數字字串轉成數字，兩種型別皆然。把小數送到 integer 時，會先依 Python round() 規則捨入再轉換，所以正好位於 .5 時會取最近偶數：2.5 變成 2，-1.5 變成 -2。數字字串會先當成二進位浮點數解析，所以大於 2^53 的整數字串可能改變（"9007199254740993" 會存成 9007199254740992）；需要精確值時請送 JSON 整數。捨入後超出帶號 64 位元範圍的小數或數字字串不會被轉換，並會被拒絕。agent 工具組的列寫入工具對 integer 套用相同的轉換，但那裡的 float 欄位只接受 JSON 數字，不接受數字字串。前端仍應先正規化，以免使用者看不出值已改變。以下值無法轉成所需型別：


{
  "data": {
    "數量": true,
    "單價": "一千二百九十"
  }
}

布林值不會因 Python 的型別關係被當成 1 或 0；非數字字串也會收到 must be an integer 或 must be a number，在 integer 欄位上，捨入後超出帶號 64 位元範圍（−9223372036854775808 到 9223372036854775807）的小數或數字字串也一樣。這些都是 400。

顯示與回傳

紀錄回應保留 JSON number，不會加千分位、幣別符號或單位：


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

幣別符號、千分位與百分比屬於顯示層責任；不要把格式化後的 "NT$1,290.50" 寫回數值 cell。若儲存的金額本身必須精確到固定小數位數，請使用 decimal 欄位，而不是 float。

注意事項

integer 只有在捨入後的值落在帶號 64 位元範圍內時，才會把小數與數字字串轉成整數；超出範圍時寫入會以 400 失敗。如果產品不能接受自動捨入，前端應先拒絕非整數輸入。
float 拒絕 NaN、正負 Infinity 等非有限數，避免產生無法儲存的 JSON。
true / false 對兩種數值型別都不合法。
float 儲存的是二進位近似值，0.1 + 0.2 不會恰好等於 0.3；需要精確金額時請用 decimal。
default_value 也必須符合欄位型別；它會用於既有紀錄的新增欄位遷移。

試試看

到 API Playground 建立兩個數值欄，再用 records.create 比較原生數字與數字字串的回傳結果。