Twinkle HubTwinkle Hub

香港資料集查詢(結構化條件)

hk_query_dataset

🇭🇰 香港

關鍵字 / Keywords: 香港 查詢 篩選 過濾 聚合 統計 加總 計數 分組 排序 資料列 Hong Kong query filter aggregate group count sum rows dataset

Scope: Hong Kong public datasets and government data.

用結構化條件查香港資料集的列(不寫 SQL)。條件寫法與 tw_query_dataset 相同。

參數: dataset_id: 香港資料集 ID(由 hk_search_datasets / hk_list_mirrors 取得,例 "hk-hko-rss-daily-total-rainfall") resource_index: 第幾個 CSV 檔(從 0 起,只數 CSV;由 hk_list_resources 查)。本機鏡像資料集不適用 resource_name: 改用檔名挑 CSV 檔(與檔名完全相同,不分大小寫) select: 要回的欄位名(照表頭原文) filters: 條件清單,每個 {"field", "operator", "value"}。 operator:eq / ne / gt / gte / lt / lte / in(value 是清單)/ between(value 是 [下限, 上限])/ contains(包含字串) value 是字串 → 以文字比較(ISO 日期 "2024-01-01" 照字典序就對);是數字 → 以數值比較 例:[{"field": "station_id", "operator": "eq", "value": "HKO"}, {"field": "year", "operator": "gte", "value": 2020}] aggregate: 聚合清單,每個 {"function", "field", "alias", "as"};function:count / sum / avg / min / max (count 可用 field="*")。例:[{"function": "avg", "field": "value", "alias": "平均"}] min / max 預設當數字比;日期或文字要寫 "as": "text" 當數字用時,純數字與標準千分位(1,234,567)都認;其他值不算數字 —— sum / avg 有這種列時 _meta.aggregate_hints 會說有幾列沒算進去 group_by: 分組欄位(配合 aggregate) order_by: 排序,每個 {"field": 欄位或 alias, "direction": "asc" | "desc", "as": "text" | "number"}。 欄位值都是文字:要依數值排請給 "as": "number";aggregate 的 alias 本來就是數字 limit: 最多回幾列(1–500;部分方案有更低上限)

回傳 {dataset_id, source, columns, rows, row_count_returned, limit, truncated}。truncated=true 代表還有更多列 —— 加條件縮小範圍。欄位名不存在時錯誤會列出可用欄位(經 execute_tool 呼叫時在 data.result.error.details.allowed_columns)。

パラメータ

名前型説明
dataset_id *string—
resource_indexinteger—
resource_namestring—
selectarray—
filtersarray—
aggregatearray—
group_byarray—
order_byarray—
limitinteger—
生の JSON schema
{
  "properties": {
    "dataset_id": {
      "title": "Dataset Id",
      "type": "string"
    },
    "resource_index": {
      "default": 0,
      "title": "Resource Index",
      "type": "integer"
    },
    "resource_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Resource Name"
    },
    "select": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Select"
    },
    "filters": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Filters"
    },
    "aggregate": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Aggregate"
    },
    "group_by": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Group By"
    },
    "order_by": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Order By"
    },
    "limit": {
      "default": 100,
      "title": "Limit",
      "type": "integer"
    }
  },
  "required": [
    "dataset_id"
  ],
  "title": "hk_query_datasetArguments",
  "type": "object",
  "additionalProperties": false
}

呼び出し方

スターター——パラメータは​上表参照
hk_query_dataset({ dataset_id: "…" })