API, Parquet: Map geometry and geography to Parquet logical types

[huan233usc]

Summary

Map Iceberg geometry and geography primitive types to and from Parquet's geometry / geography logical type annotations on a BINARY column, so the geo types survive a schema round-trip through ParquetSchemaUtil.convert in both directions.

• TypeToMessageType: emit geometry / geography as BINARY annotated with LogicalTypeAnnotation.geometryType / geographyType, passing the resolved CRS and edge-interpolation algorithm through directly. Iceberg and Parquet use the same algorithm names (SPHERICAL, VINCENTY, THOMAS, ANDOYER, KARNEY), so the algorithm is mapped by name.
• MessageTypeToType: read those annotations back into Types.GeometryType / Types.GeographyType. An unset crs / algorithm maps to the Iceberg default (the Parquet defaults are the same: OGC:CRS84 / SPHERICAL), and algorithm names are resolved with EdgeAlgorithm.fromName, the same conversion used when parsing geography type strings (Types.fromPrimitiveString).
• Types.GeometryType / Types.GeographyType: serialize with explicit CRS / edge algorithm defaults (geometry(OGC:CRS84), geography(OGC:CRS84, spherical)) so table metadata preserves the concrete defaults being used, while equals / hashCode compare resolved defaults so default-equivalent forms remain semantically equal. No public signature changes.

This is the first step of plumbing the geo value path through Parquet. It is intentionally schema mapping only — the generic value read/write path (BaseParquetReaders / BaseParquetWriter) and the ParquetMetrics guard for geo columns are separate follow-ups, so this PR stays small and easy to review. It is purely additive: no behavior changes for non-geo types.

This is 1/N for #16650

Test plan

• TestParquetSchemaUtil#testGeospatialTypeRoundTrip round-trips a schema with default-CRS geometry, an explicit-CRS geometry, default geography, and a geography per edge algorithm (all five, so the by-name mapping is exercised for every constant in both directions) through ParquetSchemaUtil.convert.
• TestParquetSchemaUtil#testGeospatialAnnotationsWithOmittedParameters reads hand-built MessageTypes with unset / explicit / explicit-default CRS and algorithm — covering files written by engines that omit defaults — and confirms each maps to the expected Iceberg type and serializes with explicit defaults.
• TestTypes#testGeospatialTypeDefaultNormalization covers equals() / hashCode() parity for the default-CRS and default-algorithm geography forms, that algorithm() still reports SPHERICAL, and that a non-default algorithm stays distinct; testGeospatialTypeToString covers explicit-default rendering.
• ./gradlew :iceberg-api:check :iceberg-parquet:check — clean (tests, checkstyle, revapi, spotless).
• ./gradlew :iceberg-core:test — full core suite green; no regressions in TestSchemaParser / TestSingleValueParser / TestGeospatialTable or anywhere geography types are serialized.

[huan233usc]

Hi @szehon-ho , can you help reviewing when you have a chance? Thank you very much!

[szehon-ho]

A couple of clarifying notes (not blocking — just flagging for discussion):

1. Write path isn't blocked, only the read path.

Now that TypeToMessageType emits geometry/geography, ParquetSchemaUtil.convert succeeds where it previously threw, so the failure point moves into the value path and the two sides behave asymmetrically:

• Read: BaseParquetReaders.primitive runs the logical-type visitor and .orElseThrow(...), so a geo column fails fast with UnsupportedOperationException.
• Write: BaseParquetWriter.primitive runs its logical-type visitor, but when it returns empty it falls through to case BINARY -> ParquetValueWriters.byteBuffers(desc) rather than throwing. So a geo write no longer fails at writer setup — it silently degrades to the generic binary writer.

Since the value path is an explicit follow-up, it'd be safer to also reject GEOMETRY/GEOGRAPHY on the write side here, so we don't produce files the reader then refuses to read.

2. Serialization effect of the toString change (default algorithm dropped).

For reference, here's what gets written into table metadata before/after this PR. CRS is unchanged (the constructor already collapses the default to the bare form); only the algorithm changes.

CRS — no change:

User action	Before	After
Sets default explicitly (OGC:CRS84)	"geography"	"geography"
Doesn't set it	"geography"	"geography"

Algorithm — changed:

User action	Before	After
Sets default explicitly (spherical)	"geography(OGC:CRS84, spherical)"	"geography"
Doesn't set it	"geography"	"geography"

So explicitly setting spherical is no longer persisted — it now serializes identically to not setting it. Semantically fine (the spec defaults an unspecified algorithm to spherical), but re-serializing an existing table that stored "...,spherical)" will produce the shorter string (same type, different bytes). Worth calling out in the PR description.

[huan233usc]

Updated again in ca4e1a689 to make the behavior fully explicit by default:

• GeometryType.crs84() now serializes as geometry(OGC:CRS84)
• GeographyType.crs84() now serializes as geography(OGC:CRS84, spherical)
• bare input like geometry / geography is still accepted and resolves to those defaults
• equals / hashCode still compare resolved defaults, so default-equivalent forms remain equal

This keeps Iceberg table metadata aligned with the concrete defaults written into Parquet annotations and avoids depending on future default interpretation.

[szehon-ho]

One small consistency follow-up on the geo toString() changes (non-blocking). Overall the schema mapping and write-rejection look good.

[huan233usc]

Thanks @szehon-ho! Applied both suggestions in 9432405 — GeometryType.toString() now formats from crs() and GeographyType.toString() from crs() / algorithm(), so toString() stays consistent with equals/hashCode and emits canonical CRS casing. The divergence you flagged (geometry(ogc:crs84) was .equals() to crs84() but serialized non-canonically) is fixed, and since SchemaParser writes toString() into metadata, the canonical form is now what gets persisted. Added assertions in testGeospatialTypeToString covering the casing case.

[szehon-ho]

Since the default-CRS match is case-insensitive (DEFAULT_CRS.equalsIgnoreCase(...)), a default column written by another engine/version in any casing — geometry, geometry(OGC:CRS84), or geometry(ogc:crs84) — all resolve to the same default-equal type. That's good behavior and worth keeping.

Minor suggestion: instead of resolving in crs() and routing equals/hashCode/toString through the getter, could we canonicalize once in the constructor and keep the stored field canonical?

private GeometryType(String crs) {
  Preconditions.checkArgument(crs == null || !crs.isEmpty(), "Invalid CRS: (empty string)");
  this.crs = crs == null || DEFAULT_CRS.equalsIgnoreCase(crs) ? DEFAULT_CRS : crs;
}

Then crs() is just return crs;, equals/hashCode compare the field directly, and toString becomes String.format("%s(%s)", NAME, crs) — no getter indirection and the explanatory comments drop out. Same idea for GeographyType (you already resolve the algorithm default in the constructor). Observable behavior of crs(), equals, hashCode, and toString is identical to the current approach for every input (null, OGC:CRS84, ogc:crs84, non-default), so the added tests still pass.

[huan233usc]

Good call — done in 6ec2544. Both GeometryType and GeographyType now canonicalize the default CRS (omitted or any casing) in the constructor, so crs() is a plain field getter and equals/hashCode/toString compare/format the stored field directly. The getter indirection and the explanatory comments are gone, and TestTypes (incl. the ogc:crs84 -> OGC:CRS84 cases) still passes since the observable behavior is identical.

[szehon-ho]

discussed offline, lets clean this part up :) and also make sure we are case preserving if the user provides some default that is not upper case

[huan233usc]

Done now we just has this.crs = crs, the pervious impl for normalizing is gone