tiny-db API 文件

所有請求需帶 X-API-Key: <key> header。

資料集管理 / 寫入

端點說明
GET /datasets 列出所有資料集
PUT /datasets/{slug} 建立或更新資料集（含寫入 records）
  • dataset 不存在：建立資料集（需 meta.title、schema）→ 201
  • dataset 已存在：meta 中任何 key 皆可增加或覆蓋（schema 不可變更），records 依 _id upsert → 200
{
  "meta": {                        // 選填於更新；新建時需 title
    "title": "台灣縣市列表",
    "description": "全台縣市代碼與名稱對照",
    "source": [{"name": "政府資料開放平臺", "url": "https://data.gov.tw/..."}],
    "license": "OGDL-Taiwan-1.0",
    "language": "zh-TW",
    "checked_at": "2026-04-27"
  },
  "schema": [                      // 新建必填，更新忽略（schema 不可變更）
    { "name": "county_id",   "type": "number"  },
    { "name": "county_name", "type": "keyword" }
  ],
  "records": [                     // 選填；依 _id upsert（_id 相同→更新，不同→新增）
    { "_id": "TPE", "_name": "臺北市", "_valid_start": "2010-01-01", "county_id": 1, "county_name": "臺北市" },
    { "_id": "NWT", "_name": "新北市", "_valid_start": "2010-12-25", "county_id": 2, "county_name": "新北市" }
  ]
}
回應（201 create）：
{ "created": true,  "slug": "tw.geo.county", "upserted": 2, "record_count": 2, "elapsed": 0.04 }
回應（200 update）：
{ "created": false, "slug": "tw.geo.county", "upserted": 2, "record_count": 5, "elapsed": 0.03 }
GET /datasets/{slug} 取得資料集 metadata
DELETE /datasets/{slug} 刪除資料集（同時刪除 ES index）

標準 meta 欄位

欄位必填格式說明
系統自動管理（不應由外部覆蓋）
created_at 自動 ISO 8601 資料集首次建立時間
updated_at 自動 ISO 8601 最後一次 PUT 寫入時間
必填（新建時）
title 必填 string 資料集顯示名稱
選填標準欄（前後台可識別並顯示）
description 選填 string 自由文字說明
source 選填 [{"name":"...","url":"..."}] 資料來源陣列（允許多筆）
license 選填 string 授權條款（自由文字，如 CC0、OGDL-Taiwan-1.0）
language 選填 BCP 47 資料語系（如 zh-TW）
checked_at 選填 日期字串 資料最後一次人工或自動驗證時間

系統欄位（每筆 record 必須包含）

欄位必填型別說明
_id 必填 keyword 唯一識別碼；相同 _id 再次寫入會更新該筆資料
_name 必填 keyword 顯示名稱（支援精確篩選與排序）
_valid_start 選填 datetime 資料生效起始時間（ISO 8601，null 或省略表示無限制）
_valid_end 選填 datetime 資料失效時間（ISO 8601，null 或省略表示無限制）

資料查詢

GET /datasets/{slug}

參數說明範例
q全文搜尋（僅搜尋 text 型別欄位）?q=臺北
_id依唯一識別碼精確查詢?_id=TPE
{field}精確篩選（keyword / number / datetime 欄位）?county_id=1
{field}:min,max 範圍篩選，任一端可留空
:2,5 → 2 ≤ 值 ≤ 5   :2, → 值 ≥ 2   :,5 → 值 ≤ 5 		?_valid_start:2020-01-01,
fields選擇回傳欄位（逗號分隔）?fields=_id,_name,county_id
sort 排序；欄位名後加 > 降序，< 升序 ?sort=county_id>
page頁數（從 1 開始）?page=2
per_page 每頁筆數（預設 20，上限 500）；設為 0 時只回傳 dataset metadata 與 schema，不查詢 ES ?per_page=0
schema是否回傳 schema（預設 1，設為 0 可省略以節省流量）?schema=0

回應格式（一般查詢）：

{
  "total": 22,
  "page": 1,
  "per_page": 20,
  "schema": [                              // schema=0 時省略
    { "name": "county_id", "type": "number" },
    ...
  ],
  "records": [
    { "_id": "TPE", "_name": "臺北市", "_valid_start": "2010-01-01", "county_id": 1, ... },
    ...
  ]
}

回應格式（?per_page=0，只要 metadata / schema）：

{
  "id": 1,
  "slug": "tw.geo.county",
  "schema": [ ... ],
  "record_count": 22,
  "meta": {
    "title": "台灣縣市列表",
    "description": "...",
    "created_at": "2026-04-24 00:00:00",
    "updated_at": "2026-04-24 12:00:00"
  }
}

curl 範例

# 建立資料集並寫入資料（dataset 不存在時）
curl -X PUT https://openfun-tinydb.ronny-test.openfun.dev/datasets/tw.geo.county \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "meta": {
      "title": "台灣縣市列表",
      "description": "全台縣市代碼與名稱對照"
    },
    "schema": [
      { "name": "county_id",   "type": "number"  },
      { "name": "county_name", "type": "keyword" }
    ],
    "records": [
      { "_id": "TPE", "_name": "臺北市", "_valid_start": "2010-01-01", "county_id": 1, "county_name": "臺北市" },
      { "_id": "NWT", "_name": "新北市", "_valid_start": "2010-12-25", "county_id": 2, "county_name": "新北市" }
    ]
  }'

# 更新 meta 並追加 records（dataset 已存在時）
curl -X PUT https://openfun-tinydb.ronny-test.openfun.dev/datasets/tw.geo.county \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "meta": { "checked_at": "2026-04-24" },
    "records": [
      { "_id": "TPE", "_name": "臺北市（修正）", "_valid_start": "2010-01-01", "county_id": 1, "county_name": "臺北市" },
      { "_id": "TXG", "_name": "台中市",         "_valid_start": "2010-12-25", "county_id": 4, "county_name": "台中市" }
    ]
  }'

# 查詢：依 _id 精確查詢
curl "https://openfun-tinydb.ronny-test.openfun.dev/datasets/tw.geo.county?_id=TPE" \
  -H "X-API-Key: YOUR_KEY"

# 查詢：_valid_start 在 2014 年後，依 county_id 降序
curl "https://openfun-tinydb.ronny-test.openfun.dev/datasets/tw.geo.county?_valid_start:2014-01-01,&sort=county_id>" \
  -H "X-API-Key: YOUR_KEY"

# 只取 metadata + schema，不撈資料
curl "https://openfun-tinydb.ronny-test.openfun.dev/datasets/tw.geo.county?per_page=0" \
  -H "X-API-Key: YOUR_KEY"

Schema 型別

type說明ES mapping
number整數或浮點數；支援精確比對、範圍查詢與排序long
text全文搜尋（?q=）；不支援精確比對與排序text
keyword精確比對與排序；不支援全文搜尋keyword
datetimeISO 8601 日期時間；支援精確比對、範圍查詢與排序date

資料匯入 Prompt

將以下 markdown 貼到 AI 對話，即可開始撰寫資料匯入程式。

tiny-db © OpenFun Ltd.