geoparquet-validation

GeoParquet 検証スキル

gpio を優先するアプローチで、GeoParquet ファイルの確認、検証、最適化、配布を最新のベストプラクティスに沿って行うワークフローを案内します。

このスキルの用途

ユーザーが GeoParquet ファイルを扱っており、次のことが必要な場合にこのスキルを使用します。

• メタデータの確認
• 検証と自動修正のワークフロー
• gpio による変換と最適化
• パーティション分割と公開
• より複雑な SQL 変換での DuckDB サポート

このスキルは、GeoParquet に関するあらゆる事柄を扱う汎用スキルではありません。gpio ツールチェーンを中心にしています。

ツール

gpio (geoparquet-io) - 推奨

GeoParquet の操作には、常に gpio を優先してください。重要なベストプラクティスがデフォルトで適用されます。

インストール：

pipx install --pre geoparquet-io
pip install --pre geoparquet-io
uv pip install --pre geoparquet-io

gpio が見つからない場合は、作業を進める前にインストール方法を案内してください。

DuckDB - 高度な操作向け

複雑な SQL、結合、集計、またはジオメトリ操作には DuckDB を使用してください。

pip install "duckdb>=1.5"

DuckDB を使用する場合は、GeoParquet のベストプラクティスを手動で適用してください。

• ORDER BY ST_Hilbert(geometry)
• COMPRESSION ZSTD と COMPRESSION_LEVEL 15
• ROW_GROUP_SIZE 100000
• gpio check all で出力を検証

ワークフロー

1. 確認

gpio inspect <file>
gpio inspect stats <file>

行数、ジオメトリタイプ、CRS、列、ファイルサイズを報告してください。

gpio inspect と gpio check が受け付けるのは (Geo)Parquet ファイルのみです。 非 Parquet ソース（シェープファイル、GPKG、GeoJSON、FGB）の場合は、事前確認を省略し、まず変換してから出力を確認してください。変換に失敗しない限り、非 Parquet ソースの事前確認に呼び出しを費やさないでください。どうしても先にソースのメタデータを確認する必要がある場合は、pyogrio.read_info("<src>") を使用してください。

2. 変換または最適化

gpio convert geoparquet <input> <output>   # input: any OGR-readable format (shp, gpkg, geojson, fgb, csv)
gpio convert geoparquet <input> <output> --compression-level 15

convert はデフォルトでベストプラクティス（Hilbert ソート、bbox カバリング列、ZSTD）を適用し、出力も検証します。そのため、正常に完了した convert の後に --fix が必要になることはほとんどありません。

3. 検証

gpio check all <file>
gpio check all <file> --fix --output <fixed>

Spec Validation で、すべてのチェックにチェックマークが付いていれば check all は合格です。情報として表示される行（特に「GeoParquet 2.0 is available」という案内）は失敗ではありません。ユーザーが明示的に 2.0 を求めない限り、最も幅広い互換性を持つバージョンである 1.1.0 を使用してください。convert と check all はファイルサイズと行グループの統計情報もすでに表示します。報告には、最終出力に対して gpio inspect を 1 回実行すれば十分です。

4. サイズに応じて拡張

• 小規模：単一ファイル、Hilbert ソート、bbox 列
• 中規模：単一ファイル、カバリングメタデータ、圧縮レベル 15
• 大規模：kdtree/admin/quadkey でパーティション分割し、STAC を生成

5. 公開

gpio publish stac <input> <output.json>
gpio publish upload <file> s3://bucket/path/

クイックリファレンス

# Inspect (Parquet input only)
gpio inspect <file>
gpio inspect stats <file>

# Convert (input: any OGR-readable format — shp, gpkg, geojson, fgb, csv)
gpio convert geoparquet <input> <output>
gpio convert geoparquet <input> <output> --compression-level 15

# Validate
gpio check all <file>
gpio check all <file> --fix --output <fixed>

# Extract
gpio extract <input> <output> --bbox "minx,miny,maxx,maxy"
gpio extract <input> <output> --where "column > value"

# Partition and publish
gpio partition kdtree <input> <output_dir> --max-rows-per-file 500000
gpio publish stac <input> <output.json>

参考資料

• references/gpio-commands.md
• references/distribution-best-practices.md
• references/tool-comparison.md