Skip to content

[GH-3146] Write GeoParquet 2.0 files with the Parquet GEOMETRY type - #3553

Open
jiayuasu wants to merge 1 commit into
apache:masterfrom
jiayuasu:feature/geoparquet-2.0-write
Open

jiayuasu wants to merge 1 commit into
apache:masterfrom
jiayuasu:feature/geoparquet-2.0-write

Conversation

@jiayuasu

Copy link
Copy Markdown
Member

Did you read the Contributor Guide?

Is this PR related to a ticket?

What changes were proposed in this PR?

Setting geoparquet.version to a 2.x version used to change only the version string in the geo metadata. It now writes the layout GeoParquet 2.0 requires, on Spark 4.1 and 4.2:

  • A geometry column carries the GEOMETRY logical type of the Parquet format, and the CRS is a property of that type: absent for OGC:CRS84, authority:code for a CRS with an identifier, inline PROJJSON for a CRS without one, and srid:0 for an unknown CRS. The geo metadata repeats the CRS as PROJJSON, or null for an unknown CRS.
  • Geometries are stored as ISO WKB, which the logical type requires. The writer uses the EWKB flag bit for a Z coordinate in 1.x files (GeoParquet writer stores XYZ geometries with the EWKB Z flag instead of ISO WKB type codes #3545); 2.x files get the ISO type code.
  • parquet-java writes geospatial statistics (bounding box and geometry types) for each row group once the column is annotated, so no covering column is generated for a 2.x file. geoparquet.covering still declares a covering column the user provides.
  • The Spark schema metadata of a 2.x file keeps the native geometry type, as Spark's own writer does, so Spark 4.2's spark.read.parquet returns a geometry column for these files.

Limits of this PR:

  • The default version stays 1.1.0. A version string whose major part is not 2 is written as before.
  • A native Spark geometry type (Spark 4.2) names the SRID of the column, and the CRS comes from it. A GeometryUDT column (Spark 4.1) has an SRID on each geometry only, so a 2.x write of such a column needs geoparquet.crs or geoparquet.crs.<column_name> for now. Taking the CRS from the data is the next PR.
  • The Parquet library of Spark 3.5 and 4.0 has no GEOMETRY type. A 2.x write is rejected on the driver there, with a message that names geoparquet.version 1.1.0 as the alternative.

Not in this PR: the default version, CRS inference for GeometryUDT columns, geography columns, and reading on Spark 3.5/4.0.

How was this patch tested?

GeoParquetNativeTypesSuite has a new block that writes 2.x files and reads the footer back: the GEOMETRY annotation and its crs for the default CRS, an EPSG CRS, an unknown CRS and a CRS without an identifier, the CRS taken from the SRID of a native column, the row-group geospatial statistics, ISO WKB for a geometry with Z, the geo metadata, a 1.1.0 file that keeps plain binary and its covering column, and the rejection on a Parquet library without the geospatial types. ParquetGeospatialTypesTest covers the mapping from a CRS to the crs property and the version rule. NativeGeoParquetCrsSuite in the spark-4.2 module reads Sedona's 2.0 output with Spark's own Parquet reader for SRID 4326, 3857 and 0.

The GeoParquet suites pass locally on Spark 4.1 / Scala 2.13, Spark 4.2 / Scala 2.13 (including the GeoParquet suites of the spark-4.2 module) and Spark 3.5 / Scala 2.12.

Did this PR include necessary documentation updates?

  • Yes, I have updated the documentation.

…type

Setting geoparquet.version to a 2.x version now writes the layout that
GeoParquet 2.0 requires. The option used to change only the version
string in the file metadata.

A geometry column carries the GEOMETRY logical type, with the CRS as a
property of the type: absent for OGC:CRS84, authority:code for a CRS
with an identifier, inline PROJJSON for one without, and srid:0 for an
unknown CRS. The GeoParquet metadata repeats the CRS as PROJJSON.
Geometries are stored as ISO WKB, which the logical type requires; the
writer used the EWKB flag bit for a Z coordinate. The Parquet library
writes geospatial statistics for each row group once the column is
annotated, so no covering column is generated.

The Spark schema metadata of such a file keeps the native geometry
type, as Spark's own writer does, so that Spark 4.2's Parquet reader
returns a geometry column.

A native Spark geometry type names the SRID of the column. A
GeometryUDT column has an SRID on each geometry only, so for now a 2.x
write of such a column needs geoparquet.crs. The Parquet library of
Spark 3.5 and 4.0 has no GEOMETRY type, and a 2.x write is rejected on
the driver there.

The default version stays 1.1.0. Any version string that is not 2.x is
written as before.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant