geoparquet-testing

GeoParquet格式的官方测试语料库，包含用于测试GeoParquet 2.0-dev规范的数据集，分为三个层级：data/（小型系统一致性测试文件）、samples/（模拟真实数据集以测试规范特性）和bad_data/（故意违反规范的文件）。语料库旨在验证GeoParquet格式的兼容性和错误处理。

Official test corpus in GeoParquet format, containing datasets dedicated to validating the GeoParquet 2.0-dev specification. It is divided into three hierarchical directories: data/ (small-scale system conformance test files), samples/ (simulated real-world datasets for testing specification features), and bad_data/ (files that intentionally violate the specification). This corpus aims to verify the compatibility and error handling capabilities of the GeoParquet format.

原始信息汇总

GeoParquet 测试数据集概述

该数据集是 GeoParquet 格式的官方测试语料库，对标 apache/parquet-testing 的设计理念。目标版本为 GeoParquet 2.0（开发中，geo 元数据中版本号为 "2.0-dev"）。

数据集结构

数据集分为三个层级，共包含 65 个文件：

层级	用途	文件数量
data/	针对每个规范维度的系统性小型合规测试用例	34
samples/	模拟真实场景、以非平凡规模展示规范特性的数据集	9
bad_data/	故意违反规范的文件，附带机器可读的 manifest.json 清单	22

每个层级目录均包含独立的 README 文件，索引并说明每个文件所测试的具体内容。

当前状态

• 所有 data/ 和 samples/ 中的文件均通过 GeoParquet 2.0-dev JSON Schema 验证（CI 持续强制执行）。
• 少量测试用例被有意推迟，包括：原生逻辑类型 CRS 变体（srid:0 + null geo crs；PROJJSON geo crs + authority:code），等待工具链支持将自定义 CRS 字符串写入 Parquet 原生 GEOMETRY/GEOGRAPHY 逻辑类型。

使用方式

1. Git 子模块（推荐）：git submodule add https://github.com/geoparquet/geoparquet-testing tests/data/geoparquet-testing，可切换到指定发布标签。
2. 标签发布压缩包：从 releases 页面 下载，适用于不希望引入子模块依赖的项目。
3. 对 bad_data 的验证：读取 bad_data/manifest.json，尝试打开每个文件，并断言失败模式与清单中的 expected_failure 代码一致。

文件再生

所有合规测试文件（data/）和负面测试文件（bad_data/）均为确定性的，重新生成可产生字节一致的结果。真实的 samples/ 文件（从上游获取实时数据）以快照形式提交。使用 uv 工具链运行 scripts/generate_all.py 可重新生成全部文件。

贡献

1. 在 scripts/ 下编辑或添加生成器。
2. 运行 uv run python generate_all.py。
3. 确保相关 README 表格包含新文件。
4. 对于新的 bad_data 文件，向 bad_data/manifest.json 添加条目（生成器在调用 register(...) 时自动完成）。
5. 提交 PR，CI 将验证可重现性、模式有效性、README 索引完整性以及 5 MB 的样本预算限制。

许可协议

本仓库生成的所有文件采用 Apache 2.0 许可。samples/ 下的真实样本保留其上游许可，具体引文要求参见 samples/README.md 及各匹配 scripts/samples/<name>.py 文件的头部注释。

搜集汇总

数据集介绍

构建方式

在空间数据标准化的浪潮中，GeoParquet格式的规范化测试需求日益迫切。geoparquet-testing数据集作为官方测试语料库，基于精细化的三级架构进行构建。其中data/层级包含34个小型系统性合规测试文件，逐一验证规范的各个维度；samples/层级提供9个接近真实的非平凡规模数据集，灵活展示规范特性；bad_data/层级则收录22个刻意违反规范的样本文件，并辅以机器可读的manifest.json清单。所有文件均通过确定性脚本在scripts/目录下自动生成，确保重现性，其中高频更新的samples/数据则通过快照方式维持稳定。

使用方法

使用者可通过三种方式接入该测试语料库。推荐采用Git子模块机制：执行git submodule add命令并将其锚定至特定发行版标签，实现版本可控的集成。对于不便引入子模块依赖的项目，可直接从发行版页面下载归档压缩包。验证bad_data/时，可循环解析manifest.json中的每条记录，尝试读取文件后断言失败模式是否匹配expected_failure代码。数据集的重新生成通过运行uv sync --all-extras与uv run python generate_all.py完成，支持针对单一类别（如CRS或样本）进行选择性再生，极大提升了开发与测试的灵活性。

背景与挑战

背景概述

GeoParquet作为一种开放地理空间信息联盟（OGC）标准，旨在将地理空间数据高效集成于Apache Parquet列式存储格式，从而在分布式计算与数据湖架构中实现规模化的矢量数据处理。geoparquet-testing数据集由GeoParquet社区于开发版2.0规范推进期间创建，主要源自对格式一致性测试的迫切需求，其设计参照了Apache Parquet官方测试套件的架构。该数据集的核心研究问题在于为解析库与存储引擎提供一套全面的、可复现的合规性评估工具，以验证其对GeoParquet规范中各类几何类型、坐标参考系统及元数据表达的兼容性。通过系统性覆盖规范中34项维度与9个真实尺度样本及22个违规场景，这一语料库已成为GeoParquet生态互操作性的基石，显著降低了不同实现间的歧义，对推动地理空间大数据分析标准化进程具有深远影响。

当前挑战

该数据集所应对的核心挑战在于地理空间数据非结构化特性与Parquet列式聚簇存储之间的鸿沟——规范需精确定义几何对象如何编码为原生几何/地理逻辑类型并嵌入复杂坐标参考系统（CRS），同时保持与标准SQL查询引擎的无缝集成。构建过程中，开发者面临三大技术难题：其一，对于本地逻辑类型CRS变体（如srid=0搭配null geo crs，或PROJJSON crs叠加Parquet元数据中的authority:code），现有工具链无法写入自定义CRS字符串至Parquet原生类型，导致测试生成器必须依赖未来版本的工具升级。其二，真实样本（samples/）需从动态上游实时拉取并快照固化，而CI环境确保在5 MB预算约束下维持字节一致性，这对数据获取时效性与版本控制提出了精细权衡。其三，27份违规文件（bad_data/）需严格对应机器可读清单中特定失败码，要求生成器精准注入语义不合规数据，避免与解析器实现误报混淆。

常用场景

经典使用场景

在空间大数据生态系统中，GeoParquet作为高效的地理空间列式存储格式，其标准化与互操作性至关重要。geoparquet-testing数据集专为验证和测试GeoParquet格式的符合性而设计，涵盖三个层次：位于data/目录下的34个小型系统性符合性测试文件，精确检验规格的每一个维度；samples/目录中的9个接近真实的数据集，用于在大规模场景下测试格式特性；以及bad_data/目录中的22个故意违反规范的负面测试文件。研究者和开发者常利用此测试语料库验证自己的读写实现是否严格遵循GeoParquet 2.0-dev规范，确保格式的解析与编码无误。它如同一个权威的格式试金石，成为推动GeoParquet标准化进程中不可或缺的基准测试集。

解决学术问题

该数据集解决了地理空间数据格式标准化进程中一个核心的学术难题——如何系统性地验证不同实现之间的互操作性与一致性。在GeoParquet规范从1.0演进至2.0-dev的过程中，各种开源库和商业软件对该格式的支持参差不齐，容易产生解析歧义、元数据误读或几何数据变形等问题。geoparquet-testing通过精心设计的符合性测试与负面测试，为国际学术界提供了一个可复现、可审计的验证框架。其意义在于将格式的“规范”与“实现”之间的鸿沟用自动化测试弥合，降低了各单位开发和维护空间列式存储工具的门槛与风险，促进了地理空间大数据处理的学术研究向更精确、更高效的方向发展。

实际应用

在实际应用中，该数据集扮演着GeoParquet生态系统的“质量门禁”角色。空间数据引擎、地理信息系统（GIS）软件、云计算平台以及大数据分析框架的开发团队，在其持续集成（CI）流水线中可将此语料库作为自动化测试的输入。例如，一个支持GeoParquet的Spark插件或PostGIS扩展，在每次代码提交后运行测试，确保新版本不会引入破坏规范的回归错误。不同组织（如OGC、ESRI、Pangeo社区）也可借助它进行交叉验证，评估自家产品能否正确读写由其他工具生成的GeoParquet文件。这种广泛的实际运作不仅提升了数据交换的可靠性，更加速了GeoParquet格式在多云环境、边缘计算及实时分析中的部署落地。

数据集最近研究

最新研究方向

随着地理空间数据生态对互操作性与云原生架构的日益倚重，GeoParquet作为开放地理空间信息联盟（OGC）力推的列式存储格式，其测试语料库geoparquet-testing正成为保障格式规范落地质量的关键基础设施。当前前沿研究聚焦于三方面：其一，通过分层测试体系（一致性/真实采样/异常数据）系统性验证GeoParquet 2.0-dev版本中CRS变体、逻辑类型等新特性的实现正确性，尤其关注原生Parquet逻辑类型与PROJJSON投影描述的协同兼容性；其二，利用bad_data清单驱动负面测试自动化，推动读取器实现向容错性与错误语义收敛，这与近期GIS领域对大数据管道鲁棒性的强烈需求相呼应；其三，结合CI流水线的字节级确定性生成与模式校验，为卫星影像归档、物联网时空流处理等高频写入场景提供可复现的质量基准。该语料库的演进直接关联到OGC API - Records等云原生标准与Spark、DuckDB等引擎的异构互操作目标，对构建可信的地理空间数据湖仓库生态具有基础性支撑作用。