geoparquet-validation

GeoParquet 验证技能

通过以 gpio 为先的方式，引导用户完成 GeoParquet 工作流：按照当前最佳实践检查、验证、优化和分发 GeoParquet 文件。

此技能的用途

当用户正在处理 GeoParquet 文件，并需要以下操作时，请使用此技能：

• 检查元数据
• 验证和自动修复工作流
• 使用 gpio 转换和优化
• 分区和发布
• 使用 DuckDB 处理更复杂的 SQL 转换

这不是一个泛泛讨论“任何 GeoParquet 相关内容”的技能，而是专注于 gpio 工具链。

工具

gpio (geoparquet-io) - 首选

始终优先使用 gpio 执行 GeoParquet 操作。它默认采用重要的最佳实践。

安装：

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 源文件（shapefile、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），并验证自身输出——转换结果干净时，通常无需再使用 --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。

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