---
title: "DuckDBのST_AsMVTでベクタタイルを生成する手順｜2.0の座標変換エラー・索引・Flask配信を実測"
url: "https://www.issoh.co.jp/tech/details/9060/"
published: 2025-09-30
updated: 2026-11-08
categories: ["データベース"]
publisher: "株式会社一創"
---

# DuckDBのST\_AsMVTでベクタタイルを生成する手順｜2.0の座標変換エラー・索引・Flask配信を実測

DuckDBのspatial拡張には、PostGISと同じ名前の `ST_AsMVT`・`ST_AsMVTGeom`・`ST_TileEnvelope` があり、データベースサーバーを立てずにMapbox Vector Tile（MVT）を1枚ずつ生成できます。MVTは地図の図形と属性をタイル単位のバイナリ（Protocol Buffers）に詰めた形式で、MapLibre GL JSなどのブラウザ側ライブラリが描画します。

この記事では、2026年10月21日に公開されたDuckDB 2.0.0（LTS）でタイルを生成し、デコードして中身を確かめた結果をもとに、SQLの組み立て方、2.0で変わった座標変換の扱い、1タイルの応答時間を左右する索引の条件、Flaskでの配信、PostGISとの違いを順に説明します。1.5系から上げる場合に動かなくなる箇所も併記しています。ベクタタイルとラスタタイルの違いや配信方式の選び方は[Web GISとは？タイル配信とベクタタイル・ライブラリ選定を実装目線で解説【2026年8月時点】](/tech/details/16812/)で扱っています。

## まとめ｜DuckDBでMVTを生成するときの要点

- `ST_AsMVT` と `ST_AsMVTGeom` はDuckDB 1.4.0から使えます。現在のLTSは2.0.0で、1.4系のLTSは2026年11月17日にサポートが終わります。spatial拡張は `LOAD spatial` で読み込みます。
- 2.0.0では、`always_xy` を指定しない `ST_Transform(geom, 'EPSG:4326', 'EPSG:3857')` がエラーで止まります。`SET geometry_always_xy = true;` を最初に実行するか、`always_xy := true` を毎回付けます。1.5系では同じSQLがエラーにならず、日本の座標が `inf` になって空のタイルが返っていました。
- 2.0.0では、保存したDBファイルを開き直すとR-tree索引が使われず、z14の1タイルが194msかかりました。起動時にメモリ上へテーブルを複製して索引を作り直すと2.4msです。1.5.6では開き直しても索引が使われていました。
- 低ズームは1枚に点が集中します。z7では28,867点・432,219バイトになり、格子に集約して202,969バイトまで減らしました。
- Flaskで配信するときは、リクエストごとに `cursor()` で接続を分けます。1つの接続を共有すると、2.0.0では16並列200リクエストのうち175件が `ResourceInUseException` の500エラーになりました。

## DuckDBで使えるMVT関連関数と対応バージョン

MVTの生成に使う関数は3つです。`ST_TileEnvelope` は2025年6月10日（[PR #594](https://github.com/duckdb/duckdb-spatial/pull/594)）、`ST_AsMVT` と `ST_AsMVTGeom` は2025年9月10日に[duckdb-spatialのリポジトリへマージ](https://github.com/duckdb/duckdb-spatial/pull/677)され、DuckDB 1.4.0から利用できます。2.0.0の[spatial拡張の関数リファレンス](https://duckdb.org/docs/2.0/core%5Fextensions/spatial/functions)でも引数の構成は同じで、1.4.5・1.5.6・2.0.0のいずれでも3関数が動くことを確認しました。

| 関数                                                      | 種類   | 役割                     | 既定値               |
| ------------------------------------------------------- | ---- | ---------------------- | ----------------- |
| ST\_TileEnvelope(z, x, y)                               | スカラー | タイルの範囲をEPSG:3857の矩形で返す | 引数は3つのみ           |
| ST\_AsMVTGeom(geom, bounds, extent, buffer, clip\_geom) | スカラー | 図形をタイル内の座標へ変換し切り抜く     | 4096 / 256 / true |
| ST\_AsMVT(row, layer\_name, extent, geom列名, ID列名)       | 集約   | 行の集合を1枚のタイル（BLOB）にする   | ‘layer’ / 4096    |

版を選ぶときに効くのはサポート期間と互換性です。[DuckDBのリリースカレンダー](https://duckdb.org/release%5Fcalendar)では、2.0.0がLTSでサポート終了は2027年10月22日、1.4.0 LTSのサポート終了は2026年11月17日です。1.5系は、[2.0.0の移行ガイド](https://duckdb.org/docs/2.0/operations%5Fmanual/migration)でサポートが2027年3月まで延長されています。同じガイドによると、2.0.0が既定設定で新しく作るDBファイルは2.0.0より前のDuckDBでは読めない保存形式になります。タイル用のDBを2.0.0で作るなら配信側も2.0.0にそろえるか、`storage_compatibility_version` などで保存形式を旧版向けに指定します。PyPIのduckdb 2.0.0はPython 3.11以上を求め、Python 3.10では1.5系、3.9では1.4系が入ります。DuckDB本体の特徴は[DuckDBとは？特徴・用途とSQLite・PostgreSQLとの違いを実測で解説【1.5.6対応】](/tech/details/5741/)、インストール手順は[DuckDBの使い方：インストールからCLI・Python・ファイル読み込みまでの手順【1.5.6対応】](/tech/details/15377/)を参照してください。

## 1枚のタイルを生成するSQLの組み立て方

タイルを1枚作るSQLは、範囲を決める、図形をタイル座標へ移す、行をまとめてバイナリにする、の3段で書きます。次の例は、GeoJSONの駅データからz14・x14552・y6451（東京駅周辺）のタイルを作ります。検証では、東京駅（東経139.767度・北緯35.681度）を中心に東西南北0.01度の範囲へ乱数で1,000点を置き、`name` 属性だけを持つ `stations.geojson` を作りました。手元で試すときは、点データのGeoJSONなら何でも同じSQLで動きます。

```
INSTALL spatial;
LOAD spatial;

-- EPSG:3857 に変換した列を持つテーブルを作る（2.0 では always_xy の指定が必須）
CREATE TABLE stations AS
SELECT OGC_FID AS id,
       name,
       ST_Transform(geom, 'EPSG:4326', 'EPSG:3857', always_xy := true) AS geom_3857
FROM ST_Read('stations.geojson');

-- z=14, x=14552, y=6451 のタイルを1枚作る
SELECT ST_AsMVT(
         {'geom': ST_AsMVTGeom(geom_3857, ST_Extent(ST_TileEnvelope(14, 14552, 6451)), 4096, 256, true),
          'id': id,
          'name': name},
         'stations', 4096, 'geom', 'id') AS tile
FROM stations
WHERE ST_Intersects(geom_3857, ST_TileEnvelope(14, 14552, 6451));
```

東京駅周辺に1,000点を置いたGeoJSONでこのSQLを2.0.0で実行すると、タイル内の456点が12,551バイトに収まりました。1.5.6で実行した結果と点数・バイト数とも同じです。

### ST\_TileEnvelopeとST\_AsMVTGeomによるタイル座標変換

`ST_AsMVTGeom` の第2引数はBOX\_2D型です。`ST_TileEnvelope` が返すのはGEOMETRY型のため、そのまま渡すと `Binder Error: No function matches the given name and argument types 'ST_AsMVTGeom(GEOMETRY, GEOMETRY)'` で止まります。`ST_Extent()` で包むのが正しい書き方で、`::BOX_2D` へのキャストは `Conversion Error: Unimplemented type for cast (GEOMETRY -> BOX_2D)` になります。

第4引数のbufferは、タイルの外側にどれだけ図形を残すかの幅です。半径3kmの円を同じタイルに入れると、`clip_geom` がtrueなら座標は-256〜4352の範囲に切り抜かれて40バイト、falseなら-1127〜8921まで残って156バイトになりました。線や面を隣のタイルと継ぎ目なく描くにはある程度のbufferが要り、点だけのレイヤーでも、円の半径やラベルの大きさによって必要なbufferは変わります。

### ST\_AsMVTに渡すSTRUCTと属性の型の制約

`ST_AsMVT` の第1引数は、図形1列と属性の列を並べたSTRUCTです。属性に使える型はVARCHAR・FLOAT・DOUBLE・INTEGER・BIGINT・BOOLEANに限られ、それ以外は実行時にエラーになります。

- DATE・DECIMAL(10,2)・SMALLINT・UTINYINT・HUGEINT・INTEGER\[\] は `ST_AsMVT: property column "p" has unsupported type "SMALLINT"` の形で拒否されました。SMALLINTも通らないため、`::INTEGER` へのキャストが要ります。日付は `strftime` で文字列にします。
- 値がNULLの属性はエラーにならず、その地物のプロパティから省かれます。
- 図形の列を2つ入れると `only one geometry column is allowed in the input row` で止まります。
- 第5引数に指定した列（INTEGERかBIGINT）は地物IDになり、属性には残りません。第2引数を省いたときのレイヤー名は `layer` です。

2つのレイヤーを1枚のタイルに入れたいときは、レイヤーごとに `ST_AsMVT` を呼び、BLOBを `||` で連結します。連結した42バイトのタイルをデコードすると、レイヤーaとbの2つが読めました。

### PythonによるMVTのデコードと地物・座標の確認

MVTはバイナリなので、生成結果を目で確かめるにはデコードします。Pythonでは `mapbox-vector-tile`（2.2.0で確認）がレイヤー名をキーにした辞書へ戻します。

```
import duckdb
import mapbox_vector_tile

con = duckdb.connect("tiles.duckdb", read_only=True)  # stations テーブルを作ったDB
con.execute("LOAD spatial")
blob = con.execute("""
SELECT ST_AsMVT({'geom': ST_AsMVTGeom(geom_3857, ST_Extent(ST_TileEnvelope(14, 14552, 6451))),
                 'name': name}, 'stations')
FROM stations
WHERE ST_Intersects(geom_3857, ST_TileEnvelope(14, 14552, 6451))
""").fetchone()[0]

tile = mapbox_vector_tile.decode(blob, default_options={"y_coord_down": True})
layer = tile["stations"]
print(layer["extent"], len(layer["features"]))   # 4096 456
print(layer["features"][0])
```

注意したいのはy軸の向きです。[MVTの仕様2.1](https://github.com/mapbox/vector-tile-spec/tree/master/2.1)ではタイル座標のyは下向きに増えますが、`mapbox_vector_tile.decode()` は既定でyを反転して返します。`ST_AsMVTGeom` が `POINT (3897 2753)` を返した点は、既定のデコードでは `[3897, 1343]`、`y_coord_down` をtrueにすると `[3897, 2753]` でした。SQL側の値と突き合わせるときはtrueを指定します。また、タイルサーバーから取ったファイルがgzip圧縮されている（先頭2バイトが `1f 8b`）場合は、`gzip.decompress()` を先に通さないと `DecodeError` になります。

### COPYによるMVTファイルの書き出し

配信サーバーを置かずに静的ファイルとして並べる場合は、`COPY ... TO` にBLOB形式を指定します。MVTの仕様は拡張子を `.mvt` とすることを推奨しています。

```
COPY (
  SELECT ST_AsMVT({'geom': ST_AsMVTGeom(geom_3857, ST_Extent(ST_TileEnvelope(10, 909, 403))),
                   'name': name}, 'stations')
  FROM stations
  WHERE ST_Intersects(geom_3857, ST_TileEnvelope(10, 909, 403))
) TO 'tiles/10/909/403.mvt' (FORMAT BLOB);
```

ディレクトリは自動では作られず、無い場合は `IO Error: Cannot open file` で止まるため、`tiles/10/909/` を先に作っておきます。全ズームを書き出すとファイル数はズームが1上がるごとに最大4倍になるので、静的に並べる用途は対象範囲とズームを絞った場合に限ります。

## DuckDB 2.0の座標変換と座標軸設定の明示

EPSG:4326は、定義上「緯度、経度」の順に座標を持つ座標系です。一方、GeoJSONや多くのデータは「経度、緯度」の順で持っています。この食い違いをどう扱うかについて、[DuckDB 1.5.0の発表](https://duckdb.org/2026/03/09/announcing-duckdb-150)は `geometry_always_xy` という設定を導入し、1.5では警告、2.0ではエラー、2.1では `geometry_always_xy = true` を既定にすると段階的な変更を予告していました。2.0.0で同じ点を変換した結果は次のとおりです。

| 書き方（東京駅の経度・緯度）                              | 設定なし            | SET … = true    | SET … = false   |
| ------------------------------------------- | --------------- | --------------- | --------------- |
| ST\_Transform(pt, ‘EPSG:4326’, ‘EPSG:3857’) | エラー             | 正しい値            | POINT (inf inf) |
| 同上＋always\_xy := true                       | 正しい値            | 正しい値            | 正しい値            |
| 同上＋always\_xy := false                      | POINT (inf inf) | POINT (inf inf) | POINT (inf inf) |

設定なしで出るエラーは `'ST_Transform' is sensitive to the coordinate axis order of the input geometry.` で始まり、`SET geometry_always_xy = true` を推奨する文が続きます。正しい値は `POINT (15558791.27 4256815.78)` です。1.5系で書いたSQLを2.0.0で動かす場合、接続の `geometry_always_xy` が未設定で、呼び出しにも `always_xy` を指定していない座標変換がここで止まります。経度・緯度の順のデータしか扱わないなら、接続直後に `SET geometry_always_xy = true;` を実行するのが手間の少ない移行方法です。

1.5系では同じSQLが止まらず、139.767を緯度として扱った結果 `POINT (inf inf)` が返っていました。経度が90度以下の地域では `inf` にもならず、`ST_Point(10, 20)` が `POINT (2226389.82 1118889.97)`（正しくは `POINT (1113194.91 2273030.93)`）のように経度と緯度が入れ替わった有限の値になります。座標が `inf` になった点はどのタイルとも交わらないため、`ST_AsMVT` には0行が渡り、NULLではなくレイヤー名だけを持つ23バイトのBLOBが返りました。NULLの判定ではこの失敗を検出できないため、タイルのバイト数か地物の数で確かめます。

### ST\_ReadとGeoParquetで型に付くCRSの違い

1.5以降のGEOMETRY型は座標参照系（CRS）を型に持てるため、読み込み元によって列の型が変わり、引数2つの `ST_Transform(geom, 'EPSG:3857')` の結果も変わります。

| 読み込み元                   | 列の型                   | 2.0・設定なし | 2.0・SET … = false | 1.5.6           |
| ----------------------- | --------------------- | -------- | ----------------- | --------------- |
| ST\_Read（GeoJSON）       | GEOMETRY(‘EPSG:4326’) | エラー      | POINT (inf inf)   | POINT (inf inf) |
| GeoParquet（DuckDBで書き出し） | GEOMETRY(‘OGC:CRS84’) | エラー      | 正しい値              | 正しい値            |

OGC:CRS84は経度・緯度の順で定義された座標系なので、軸の入れ替えが起きません。それでも2.0.0の設定なしではエラーになるため、読み込み元が混在するなら `SET geometry_always_xy = true` か `always_xy := true` で統一します。どちらの形式も、設定をtrueにすれば正しい値が返りました。

`ST_Read` はGDALを使ってGeoJSON・Shapefile・GeoPackage・FlatGeobufなどを読む関数で、公式の説明に「GDALはシングルスレッド」とあり並列化されません。GeoParquetはGDALを通らず、DuckDB本体のParquet読み込みで直接GEOMETRY列として読めます。繰り返し読む大きなデータではGeoParquetへの事前変換を候補にします。座標系の考え方そのものは[GISデータとは？形式・座標系・取り込み設計を実装目線で解説【2026年8月時点】](/tech/details/16814/)、Parquetの仕組みは[Parquetとは？読み方・仕組み・CSVとの違いとSnappy・Zstd圧縮の実測](/tech/details/5547/)で解説しています。

## 1タイルあたりの応答時間：R-tree索引が効く条件

日本付近の範囲（東経129.5〜145.5度、北緯31〜45度）にランダムな100万点を置き、2026年11月8日にDuckDB 2.0.0・spatial拡張a3dbcd1781で1タイルの生成時間を計りました（Intel Core i9-9880H・16GBメモリ、7回の中央値を3回取った中央値）。z14のタイルには3点、z10には456点が入ります。

| 条件                             | z14     | z10     | 実行計画               |
| ------------------------------ | ------- | ------- | ------------------ |
| 開き直したDB・リクエストごとに座標変換           | 310.7ms | –       | SEQ\_SCAN          |
| 開き直したDB・索引あり・3857の列            | 193.5ms | 195.3ms | SEQ\_SCAN          |
| 開き直したDB・ST\_Intersects\_Extent | 42.0ms  | –       | SEQ\_SCAN          |
| メモリへ複製して索引作成・列を直接WHERE         | 2.4ms   | 5.5ms   | RTREE\_INDEX\_SCAN |
| 同・サブクエリで列に別名                   | 2.1ms   | 5.2ms   | RTREE\_INDEX\_SCAN |

2.0.0で差を生んだのは、索引を作った接続かどうかです。`CREATE INDEX` を実行した接続では索引が使われますが、DBファイルを閉じて開き直すと、`duckdb_indexes()` に索引が残っているのに実行計画はSEQ\_SCANでした。読み書き・読み取り専用のどちらで開いても、`LOAD spatial` の後で `ATTACH` しても同じです。同じ手順を1.5.6で行うと、開き直した後も `RTREE_INDEX_SCAN` で2.1msでした。2026年11月8日時点で、duckdb-spatialのissueにこの挙動の報告は見当たりません。

逆に、1.5.6ではサブクエリで列に別名を付けると索引が使われませんでしたが、2.0.0では別名を挟んでも使われました。版によって効き方が変わるので、配信に使うSQLは必ず `EXPLAIN` で確かめます。

```
-- 変換済みの列に R-tree 索引を張る
CREATE INDEX stations_rtree ON stations USING RTREE (geom_3857);

-- 索引が使われているかを確かめる（Rtree Index Scan が出れば使われている）
EXPLAIN
SELECT count(*) FROM stations
WHERE ST_Intersects(geom_3857, ST_TileEnvelope(14, 14552, 6451));
```

2.0.0で開き直したDBの索引を使うには、起動時にメモリ上のDBへテーブルを複製し、そこで索引を作ります。100万点では複製が0.1秒以内、索引の作成が0.6〜2.1秒でした。メモリにはテーブルと索引の分が載るので、データ量に応じてサーバーのメモリを見積もります。

```
con = duckdb.connect()            # メモリ上のDB
con.execute("LOAD spatial")
con.execute("ATTACH 'tiles.duckdb' AS src (READ_ONLY)")
con.execute("CREATE TABLE stations AS SELECT id, name, geom_3857 FROM src.stations")
con.execute("CREATE INDEX stations_rtree ON stations USING RTREE (geom_3857)")
```

[R-tree索引の公式ドキュメント](https://duckdb.org/docs/2.0/core%5Fextensions/spatial/r-tree%5Findexes)は、索引が使われる条件を「WHERE句でST\_Intersectsなどの空間述語を使い、引数の一方がクエリ計画時に値の決まる定数であること」としています。z・x・yを `$z` のようなプレースホルダで渡した場合も `RTREE_INDEX_SCAN` になり、z14の1タイルは2.3msでした。また、索引は一度メモリに載ると削除するまで解放されず、その分は `memory_limit` に数えられます。

## 低ズームでタイルが大きくなる問題と間引き

ズームを下げるほど1枚のタイルが広い範囲を覆うため、点の数とバイト数が急増します。同じ100万点で、関東から中部にかかるz7のタイル（113, 50、東経137.8〜140.6度・北緯34.3〜36.6度）は28,867点・432,219バイトになり、gzipで圧縮しても149,399バイトありました。z14の1タイルが74バイトだったのと比べると、同じSQLのままでは低ズームだけが極端に重くなります。

低ズームでは個々の点を送らず、タイル座標上の格子にまとめて件数を属性にする方法が使えます。次のSQLは4096×4096のタイル座標を32座標単位四方の格子に区切り、格子ごとに1点と件数 `n` を出します。

```
WITH t AS (
  SELECT ST_AsMVTGeom(geom_3857, ST_Extent(ST_TileEnvelope(7, 113, 50)), 4096, 64, true) AS g
  FROM stations
  WHERE ST_Intersects(geom_3857, ST_TileEnvelope(7, 113, 50))
)
SELECT ST_AsMVT({'geom': ST_Point(gx * 32 + 16, gy * 32 + 16), 'n': n}, 'stations')
FROM (
  SELECT floor(ST_X(g) / 32)::INTEGER AS gx,
         floor(ST_Y(g) / 32)::INTEGER AS gy,
         count(*)::INTEGER AS n
  FROM t
  GROUP BY ALL
);
```

この方法でz7のタイルは13,556点・202,969バイトになりました。`ST_AsMVTGeom` を通した後の座標はすでにタイル座標なので、集約した点はそのまま `ST_AsMVT` に渡せます。格子を64座標単位四方に広げると4,099点・61,450バイトまで減りました。どのズームから集約に切り替えるかは、描画側で `n` を円の大きさに使うかどうかと合わせて決めます。

## Flaskでタイルを配信しMapLibreで表示する実装

配信前に、書き込み可能な接続で `tiles.duckdb` を開き、前述のSQLで `stations` テーブルを作って接続を閉じます。次のコードを `app.py` に保存し、duckdbとFlaskを導入した環境で `flask --app app run` を実行すると、z・x・yに対応するMVTを返せます。2.0.0の索引の挙動に合わせ、起動時にメモリへ複製して索引を作っています。MVTの仕様は、配信時のMIMEタイプを `application/vnd.mapbox-vector-tile` とすることを推奨しています。

```
import duckdb
from flask import Flask, Response

app = Flask(__name__)
db = duckdb.connect()
db.execute("LOAD spatial")
db.execute("ATTACH 'tiles.duckdb' AS src (READ_ONLY)")
db.execute("CREATE TABLE stations AS SELECT name, geom_3857 FROM src.stations")
db.execute("CREATE INDEX stations_rtree ON stations USING RTREE (geom_3857)")

SQL = """
SELECT ST_AsMVT({'geom': ST_AsMVTGeom(geom_3857, ST_Extent(ST_TileEnvelope($z, $x, $y)), 4096, 64, true),
                 'name': name}, 'stations')
FROM stations
WHERE ST_Intersects(geom_3857, ST_TileEnvelope($z, $x, $y))
"""

@app.get("/tiles/<int:z>/<int:x>/<int:y>.mvt")
def tile(z, x, y):
    if not (0 <= z <= 22 and 0 <= x < 2 ** z and 0 <= y < 2 ** z):
        return Response(status=404)
    cur = db.cursor()  # リクエストごとに接続を分ける
    try:
        blob = cur.execute(SQL, {"z": z, "x": x, "y": y}).fetchone()[0]
    finally:
        cur.close()
    return Response(blob, mimetype="application/vnd.mapbox-vector-tile",
                    headers={"Access-Control-Allow-Origin": "*",
                             "Cache-Control": "public, max-age=3600"})
```

ここで使うFlaskの開発サーバーは複数スレッドでリクエストを処理します。`flask run` は動作確認用とし、本番配信にはWSGIサーバーを使います。複数ワーカープロセスで動かす場合は、メモリ上のテーブルと索引がプロセスごとに作られる分も見積もります。100万点のテーブルで16並列・200リクエスト（z12）を送った結果は次のとおりでした。

- `cur = db.cursor()` の代わりに `db` を直接使う版は、2回の試行で175件と191件が500エラーになりました。エラーは `ResourceInUseException: connection is busy with another call` で、`cursor()` で接続を分けるよう求める文が付きます。1.5.6では同じコードで51件が `TypeError` になっていました。
- `cursor()` を使い、DBファイルを読み取り専用で開いて直接配信した版は200件すべて成功しましたが、索引が使われず26.4秒かかりました。
- 上のコード（メモリへ複製して索引を作る版）は200件すべて成功し、0.79秒でした。

ブラウザ側では、MapLibre GL JSのCSSと幅・高さを指定した `id="map"` の要素を用意します。この例では地図ページをタイルAPIと同じオリジンで配信し、vectorソースにタイルのURLを渡し、レイヤーの `source-layer` に `ST_AsMVT` で付けたレイヤー名を指定します。

```
import * as maplibregl from './maplibre-gl.mjs';

const map = new maplibregl.Map({
  container: 'map',
  center: [139.767, 35.681],
  zoom: 10,
  style: {
    version: 8,
    sources: {
      stations: { type: 'vector', tiles: [location.origin + '/tiles/{z}/{x}/{y}.mvt'], minzoom: 0, maxzoom: 14 }
    },
    layers: [
      { id: 'stations', type: 'circle', source: 'stations', 'source-layer': 'stations',
        paint: { 'circle-radius': 2, 'circle-color': '#d33' } }
    ]
  }
});
```

MapLibre GL JS 6.16.0をChrome 156（ヘッドレス）で開き、100万点を配信するサーバーにz10でつなぐと、6枚のタイルが要求され、`querySourceFeatures` で2,714地物が読み込まれました。MapLibre 6系はESM形式のみで配布されているため、npmパッケージ `maplibre-gl` の `dist` にある `.mjs` ファイル群（ワーカー用を含む）とCSSをページと同じ場所に置き、`<script type="module">` の中で上のimportを書きました。`source-layer` の名前が `ST_AsMVT` の第2引数と一致していないと、タイルは取得されても何も描かれません。

## PostGISのST\_AsMVTとの違い

関数名と引数の並びは[PostGISのST\_AsMVT](https://postgis.net/docs/ST%5FAsMVT.html)に合わせてありますが、PostGISのSQLをそのまま流すと動かない箇所があります。

| 項目                  | DuckDB spatial          | PostGIS                       |
| ------------------- | ----------------------- | ----------------------------- |
| ST\_AsMVTGeomの範囲指定  | BOX\_2D（ST\_Extentで包む）  | box2d（ST\_TileEnvelopeを直接渡せる） |
| ST\_TileEnvelopeの引数 | z, x, y のみ              | bounds指定可・marginは3.1.0〜       |
| レイヤー名の既定値           | layer                   | default                       |
| 属性に使える型             | 6型に限定                   | 任意の列（JSONBで可変属性も可）            |
| 地物IDの型              | INTEGER・BIGINT          | smallint・integer・bigint       |
| 範囲の絞り込み             | ST\_Intersects＋R-tree索引 | && 演算子＋GiST索引                 |

`ST_AsMVTGeom` の既定値（extent 4096・buffer 256・clip\_geom true）は両者で同じで、DuckDBで引数を省いた結果と明示した結果は一致しました。PostGISの公式例は `ST_TileEnvelope` の `margin` で絞り込み範囲をbuffer分だけ広げていますが、DuckDBには `margin` がないため、ラベルを隣のタイルにまたがって描きたい場合は `ST_Buffer` などで範囲を自分で広げます。

## DuckDBで動的に生成するか、事前に生成するかの判断

今回検証した100万点のような点データを、日次バッチで更新して社内ツールや分析用の地図へ配信する構成は、DuckDBでのタイル生成の候補です。サーバー1プロセスとDuckDBファイル1つで動き、PostGISを用意する必要がありません。索引が効いていれば、高ズームは1枚数msで返せます。ただし点と複雑なポリゴンでは負荷が違うため、採用前に実データの図形の複雑さ、低ズームの地物数、同時リクエスト数で応答時間を測ります。

反対に、DuckDBを配信サーバーにすべきでないのは、地図を見ている間にもデータが書き換わる場合です。タイルサーバーが読み取り専用でファイルを開いている間、別プロセスが同じファイルを読み書きで開くと `IO Error: Could not set lock on file` で失敗しました（読み取り専用どうしなら2つ目も開けます）。2.0.0で起動時にメモリへ複製する構成なら、複製を終えた後はファイルを閉じられますが、更新を反映するにはサーバーの再起動か複製のやり直しが要ります。

- 更新が頻繁で、書き込みと配信を同時に続ける必要がある場合は、PostGISで動的に生成する構成を選びます。
- 不特定多数に公開し、データがほぼ変わらない場合は、tippecanoeなどでPMTilesに事前生成し、HTTP Rangeリクエストに対応したストレージとCDNから配信する構成が候補です。MBTilesを使う場合は、通常、タイルを取り出して返す配信サーバーが必要です。
- Flaskを自分で書かずに配信したい場合は、タイルサーバーのMartinにDuckDBソースがあります。[Martinの公式ドキュメント](https://maplibre.org/martin/sources-duckdb/)は、この機能を不安定扱いで既定のバイナリ・Homebrew・Dockerイメージに含めず、`cargo install martin --locked --features=unstable-duckdb` でビルドするよう案内しています。本番に入れるならパッチ版での挙動変更を前提にします。
- ブラウザだけで完結させたい場合は、DuckDB-WASMで同じSQLを実行し、MapLibreに渡す方法もあります（[DuckDB WASMとは？ブラウザでSQL分析を実行する仕組みと実装・採用判断](/tech/details/15379/)）。

配信方式の比較と、PostGISやPMTilesを含む構成の選び方は[Web GISとは？タイル配信とベクタタイル・ライブラリ選定を実装目線で解説【2026年8月時点】](/tech/details/16812/)で詳しく扱っています。

## よくある質問

### ST\_AsMVTとは何をする関数ですか？

行の集合を1枚のMapbox Vector Tile（MVT）のバイナリにまとめる集約関数です。PostGISでは2.4.0から、DuckDBではspatial拡張を読み込んだ1.4.0以降で使えます。図形は事前に `ST_AsMVTGeom` でタイル内の座標（0〜4096）へ変換しておきます。

### DuckDBのどのバージョンからST\_AsMVTを使えますか？

1.4.0（2025年9月16日）からです。1.4.5・1.5.6・2.0.0で動作を確認しました。これから使うならサポートが2027年10月22日まで続く2.0.0 LTSが候補で、1.4 LTSのサポートは2026年11月17日に終わります。2.0.0はPython 3.11以上が必要です。

### DuckDB 2.0でST\_Transformがエラーになるのはなぜですか？

2.0では、座標の軸順に依存する関数について、`geometry_always_xy` が未設定のままだとエラーにする仕様になったためです。経度・緯度の順のデータなら `SET geometry_always_xy = true;` を実行するか、`ST_Transform(geom, 'EPSG:4326', 'EPSG:3857', always_xy := true)` と書きます。falseを設定した場合、経度・緯度順の日本の座標をEPSG:4326の緯度・経度順として解釈させると、緯度の範囲を超えて `inf` になります。

### MVTファイルの中身をPythonで確認するには？

`mapbox-vector-tile` の `decode()` にバイト列を渡すと、レイヤー名・extent・地物の座標と属性が辞書で返ります。既定ではy軸が反転するため、SQLの値と比べるときは `default_options={"y_coord_down": True}` を指定します。gzip圧縮されたタイルは先に `gzip.decompress()` を通します。

### ST\_AsMVTの結果が空のタイルになるのはなぜですか？

多くは座標変換の誤りで、図形がタイルの範囲と交わらず0行が集約されています。このとき結果はNULLではなく、レイヤー名だけを持つ20バイト前後のBLOBです。`ST_AsText` で変換後の座標が `inf` や度単位の小さな値になっていないか、`ST_AsMVT` の第2引数とMapLibreの `source-layer` が一致しているかを確かめてください。

## 関連記事

- [Web GISとは？タイル配信とベクタタイル・ライブラリ選定を実装目線で解説【2026年8月時点】](/tech/details/16812/)
- [GISデータとは？形式・座標系・取り込み設計を実装目線で解説【2026年8月時点】](/tech/details/16814/)
- [DuckDBとは？特徴・用途とSQLite・PostgreSQLとの違いを実測で解説【1.5.6対応】](/tech/details/5741/)
- [DuckDBの使い方：インストールからCLI・Python・ファイル読み込みまでの手順【1.5.6対応】](/tech/details/15377/)
- [DuckDB WASMとは？ブラウザでSQL分析を実行する仕組みと実装・採用判断](/tech/details/15379/)

---

出典: [DuckDBのST\_AsMVTでベクタタイルを生成する手順｜2.0の座標変換エラー・索引・Flask配信を実測](<https://www.issoh.co.jp/tech/details/9060/>)（株式会社一創）
