DuckDB CLI からの接続

DuckDB CLI から DuckLake カタログに接続して都道府県別の統計データを分析する手順

DuckDB CLI を起動し、3ステップで「触る → 覗く → 分析する」を体験します。例として e-Stat 政府統計データセット（e_stat）を使い、都道府県別の指標を引き出してみます。

1. 接続する

DuckLake 拡張をロードし、e-Stat カタログをアタッチします。

INSTALL ducklake;
LOAD ducklake;

ATTACH 'ducklake:https://data.queria.io/e_stat/ducklake.duckdb' AS e_stat (READ_ONLY);

2. 中身を覗く

e_stat には人口・経済・労働などのドメイン別に都道府県/市区町村の統計が入っています。ssds スキーマのテーブル一覧を確認します。

SELECT schema, name FROM (SHOW ALL TABLES) WHERE database = 'e_stat' AND schema = 'ssds' LIMIT 20;

3. 都道府県ランキングを引き出す

2024年度の総人口で都道府県を並べてみます。item_name の値（例: A1101_総人口）は e-Stat の分類コードと指標名がアンダースコアで連結されています。

SELECT DISTINCT area_name, value AS population
FROM e_stat.ssds.a_pref_population
WHERE item_name = 'A1101_総人口'
  AND year = 2024
  AND area_name != '全国'
ORDER BY value DESC
LIMIT 10;

東京・神奈川・大阪が並ぶ見慣れたランキングが返ってきます。

計算指標で分析する

「労働力人口」と「完全失業者数」を CASE で横持ちにして、完全失業率を都道府県別に計算します。

SELECT
  area_name,
  MAX(CASE WHEN item_name = 'F1101_労働力人口' THEN value END) AS labor_force,
  MAX(CASE WHEN item_name = 'F1107_完全失業者数' THEN value END) AS unemployed,
  ROUND(
    MAX(CASE WHEN item_name = 'F1107_完全失業者数' THEN value END)
    / MAX(CASE WHEN item_name = 'F1101_労働力人口' THEN value END) * 100,
    2
  ) AS unemployment_rate_pct
FROM e_stat.ssds.f_pref_labor
WHERE year = 2020 AND area_name != '全国'
GROUP BY area_name
ORDER BY unemployment_rate_pct DESC NULLS LAST
LIMIT 10;

複数のデータセットを同時に接続する

ATTACH を複数回呼べば、他のデータセットと並列にクエリできます。

ATTACH 'ducklake:https://data.queria.io/reinfolib/ducklake.duckdb' AS reinfolib (READ_ONLY);
ATTACH 'ducklake:https://data.queria.io/zipcode/ducklake.duckdb' AS zipcode (READ_ONLY);

カタログを SQL で探索する

どのデータセットにどの表と列があるかは、カタログを read_json_auto で読めば SQL から引けます。接続先を決める前の段階も DuckDB の中で済みます。limit の上限は 200 で、それを超える分は返りません。続きがあるときは has_more が真になるので、offset で次を引きます。

データセットの一覧です。ATTACH に渡すときは catalog_url の先頭に ducklake: を付けます。

SELECT name, title, 'ducklake:' || catalog_url AS attach_url, bytes, updated_at
FROM (SELECT unnest(datasets, recursive := true)
      FROM read_json_auto('https://queria.io/api/catalog/datasets?limit=200'))
ORDER BY bytes DESC;

語から表と列を探します。type には dataset / table / column を指定します。

SELECT e.qualified_name, e.schema_name, e.table_name, e.column_name, e.title
FROM (SELECT unnest(entries) AS e
      FROM read_json_auto('https://queria.io/api/catalog/search?q=人口&type=column&limit=200'));

1つのデータセットに含まれる表の一覧です。

SELECT t.schema, t.name, t.title, len(t.fields) AS fields
FROM (SELECT unnest(declaration.tables) AS t
      FROM read_json_auto('https://queria.io/api/catalog/datasets/queria/zipcode'))
WHERE t.published;

表の列は、型と NULL 許容まで入っています。

SELECT f.name, f.type, f.nullable, f.title
FROM (SELECT unnest(t.fields) AS f
      FROM (SELECT unnest(declaration.tables) AS t
            FROM read_json_auto('https://queria.io/api/catalog/datasets/queria/zipcode'))
      WHERE t.name = 'mart_zipcode');

シェルから直接1行で実行する

-c オプションでスクリプト全体を渡せば、ターミナルから即席で結果を得られます。

duckdb -c "
INSTALL ducklake;
LOAD ducklake;
ATTACH 'ducklake:https://data.queria.io/e_stat/ducklake.duckdb' AS e_stat (READ_ONLY);
SELECT DISTINCT area_name, value AS population
FROM e_stat.ssds.a_pref_population
WHERE item_name = 'A1101_総人口' AND year = 2024 AND area_name != '全国'
ORDER BY value DESC LIMIT 5;
"

注意点

DuckDB CLI の同梱 ducklake 拡張はバージョンによって古い場合があります。uvx duckdb などで 1.5.2 以上を使ってください。
https:// 越しのアクセスに必要な httpfs 拡張は初回アクセス時に自動ロードされます。拡張の自動インストールを無効にしている環境では INSTALL httpfs; LOAD httpfs; を先に実行してください。
GEOMETRY カラムを含むデータセット（nlftp、e_stat の境界データなど）には INSTALL spatial; LOAD spatial; が必要です。

このページの ATTACH はそのまま他の環境でも使えます。Queria のデータは標準の DuckLake 形式で公開されているため、duckdb 1.5.2 以上があればどの言語・環境からでも同じ書き方で読めます。