PARQUET-2471: Add GEOMETRY and GEOGRAPHY logical types

[wgtmac]

Apache Iceberg is adding geospatial support: https://docs.google.com/document/d/1iVFbrRNEzZl8tDcZC81GFt01QJkLJsI9E2NBOt21IRI. It would be good if Apache Parquet can support geometry type natively.

[jiayuasu]

@wgtmac Thanks for the work. On the other hand, I'd like to highlight that GeoParquet (https://github.com/opengeospatial/geoparquet/tree/main) has been there for a while and many geospatial software has started to support reading and writing it.

Is the ultimate goal of this PR to merge GeoParquet spec into Parquet completely, or it might end up creating a new spec that is not compatible with GeoParquet?

[jiayuasu]

Geo Iceberg does not need to conform to GeoParquet because people should not directly use a parquet reader to read iceberg parquet files anyways. So that's a separate story.

[wgtmac]

Is the ultimate goal of this PR to merge GeoParquet spec into Parquet completely, or it might end up creating a new spec that is not compatible with GeoParquet?

@jiayuasu That's why I've asked the possibility of direct compliance to the GeoParquet spec in the Iceberg design doc. I don't intend to create a new spec. Instead, it would be good if the proposal here can meet the requirement of both Iceberg and GeoParquet, or share the common stuff to make the conversion between Iceberg Parquet and GeoParquet lightweight. We do need advice from the GeoParquet community to make it possible.

[szehon-ho]

From Iceberg side, I am excited about this, I think it will make Geospatial inter-op easier in the long run to define the type formally in parquet-format, and also unlock row group filtering. For example, Iceberg's add_file for parquet file. Perhaps there can be conversion utils for GeoParquet if we go ahead with this, and definitely like to see what they think.

Im new in parquet side, so had some questions

[pitrou]

@paleolimbot is quite knowledgeable on the topic and could probably be give useful feedback.

[pitrou]

I wonder if purely informative metadata really needs to be represented as Thrift types. When we define canonical extension types in Arrow, metadata is generally serialized as a standalone JSON string.

Doing so in Parquet as well would lighten the maintenance workload on the serialization format, and would also allow easier evolution of geometry metadata to support additional information.

Edit: this seems to be the approach adopted by GeoParquet as well.

[paleolimbot]

I wonder if purely informative metadata really needs to be represented as Thrift types. When we define canonical extension types in Arrow, metadata is generally serialized as a standalone JSON string.

In reading this I do wonder if there should just be an extension mechanism here instead of attempting to enumerate all possible encodings in this repo. The people that are engaged and working on implementations are the right people to engage here, which is why GeoParquet and GeoArrow have been successful (we've engaged the people who care about this, and they are generally not paying attention to apache/parquet-format nor apache/arrow).

There are a few things that this PR solves in a way that might not be possible using EXTENSION, which is that of column statistics. It would be nice to have some geo-specific things there (although maybe that can also be part of the extension mechanism). Another thing that comes up frequently is where to put a spatial index (rtree)...I don't think there's any good place for that at the moment.

It would be nice to allow the format to be extended in a way that does not depend on schema-level metadata...this metadata is typically propagated through projections and the things we do in the GeoParquet standard (store bounding boxes, refer to columns by name) become stale with the ways that schema metadata are typically propagated through projections and concatenations.

[wgtmac]

I wonder if purely informative metadata really needs to be represented as Thrift types. When we define canonical extension types in Arrow, metadata is generally serialized as a standalone JSON string.

Doing so in Parquet as well would lighten the maintenance workload on the serialization format, and would also allow easier evolution of geometry metadata to support additional information.

Edit: this seems to be the approach adopted by GeoParquet as well.

@pitrou Yes, that might be an option. Then we can perhaps use the same json string defined in the iceberg doc. @jiayuasu @szehon-ho WDYT?

EDIT: I think we can remove those informative attributes like subtype, orientation, edges. Perhaps encoding can be removed as well if we only support WKB. dimension is something that we must be aware of because we need to build bbox which depends on whether the coordinate is represented as xy, xyz, xym and xyzm.

[wgtmac]

Another thing that comes up frequently is where to put a spatial index (rtree)

I thought this can be something similar to the page index or bloom filter in parquet, which are stored somewhere between row groups or before the footer. It can be row group level or file level as well.

It would be nice to allow the format to be extended in a way that does not depend on schema-level metadata.

I think we really need your advise here. If you rethink the design of GeoParquet, how can it do better if parquet format has some geospatial knowledge? @paleolimbot @jiayuasu

[paleolimbot]

If you rethink the design of GeoParquet, how can it do better if parquet format has some geospatial knowledge?

The main reasons that the schema level metadata had to exist is because there was no way to put anything custom at the column level to give geometry-aware readers extra metadata about the column (CRS being the main one) and global column statistics (bbox). Bounding boxes at the feature level (worked around as a separate column) is the second somewhat ugly thing, which gives reasonable row group statistics for many things people might want to store. It seems like this PR would solve most of that.

I am not sure that a new logical type will catch on to the extent that GeoParquet will, although I'm new to this community and I may be very wrong. The GeoParquet working group is enthusiastic and encodings/strategies for storing/querying geospatial datasets in a data lake context are evolving rapidly. Even though it is a tiny bit of a hack, using extra columns and schema-level metadata to encode these things is very flexible and lets implementations be built on top of a number of underlying readers/underlying versions of the Parquet format.

[wgtmac]

@paleolimbot I'm happy to see the fast evolution of GeoParquet specs. I don't think the addition of geometry type aims to replace or deprecate something from GeoParquet. Instead, GeoParquet can simply ignore the new type as of now, or leverage the built-in bbox if beneficial. For additional (informative) attributes of the geometry type, if some of them are stable and make sense to store them natively into parquet column metadata, then perhaps we can work together to make it happen? I think the main goal of this addition is to enhance interoperability of geospatial data across systems and at the same time it takes little effort to convert to GeoParquet.

[Kontinuation]

Another thing that comes up frequently is where to put a spatial index (rtree)

I thought this can be something similar to the page index or bloom filter in parquet, which are stored somewhere between row groups or before the footer. It can be row group level or file level as well.

The bounding-box based sort order defined for geometry logical type is already good enough for performing row-level and page-level data skipping. Spatial index such as R-tree may not be suitable for Parquet. I am aware that flatgeobuf has optional static packed Hilbert R-tree index, but for the index to be effective, flatgeobuf supports random access of records and does not support compression. The minimal granularity of reading data in Parquet files is data pages, and the pages are usually compressed so it is impossible to access records within pages randomly.

[paleolimbot]

I'm happy to see the fast evolution of GeoParquet specs. I don't think the addition of geometry type aims to replace or deprecate something from GeoParquet.

I agree! I think first-class geometry support is great and I'm happy to help wherever I can. I see GeoParquet as a way for existing spatial libraries to leverage Parquet and is not well-suited to Parquet-native things like Iceberg (although others working on GeoParquet may have a different view).

Extension mechanisms are nice because they allow an external community to hash out the discipline-specific details where these evolve at an orthogonal rate to that of the format (e.g., GeoParquet), which generally results in buy-in. I'm not familiar with the speed at which the changes proposed here can evolve (or how long it generally takes readers to implement them), but if @pitrou's suggestion of encoding the type information or statistics in serialized form makes it easier for this to evolve it could provide some of that benefit.

Spatial index such as R-tree may not be suitable for Parquet

I also agree here (but it did come up a lot of times in the discussions around GeoParquet). I think developers of Parquet-native workflows are well aware that there are better formats for random access.

[paleolimbot]

I think we really need your advise here. If you rethink the design of GeoParquet, how can it do better if parquet format has some geospatial knowledge?

I opened up opengeospatial/geoparquet#222 to collect some thoughts on this...we discussed it at our community call and I think we mostly just never considered that the Parquet standard would be interested in supporting a first-class data type. I've put my thoughts there but I'll let others add their own opinions.

[jorisvandenbossche]

Just to ensure my understanding is correct:

• This is proposing to add a new logical type annotating the BYTE_ARRAY physical type. For readers that expect just such a BYTE_ARRAY column (e.g. existing GeoParquet implementations), that is compatible if the column would start having a logical type as well? (although I assume this might depend on how the specific parquet reader implementation deals with an unknown logical type, i.e. error about that or automatically fall back to the physical type).
• For such "legacy" readers (just reading the WKB values from a binary column), the only thing that actually changes (apart from the logical type annotation) are the values of the statistics? Now, I assume that right now no GeoParquet reader is using the statistics of the binary column, because the physical statistics for BYTE_ARRAY ("unsigned byte-wise comparison") are essentially useless in the case those binary blobs represent WKB geometries. So again that should probably not give any compatibility issues?

[jorisvandenbossche]

although I assume this might depend on how the specific parquet reader implementation deals with an unknown logical type, i.e. error about that or automatically fall back to the physical type

To answer this part myself, at least for the Parquet C++ implementation, it seems an error is raised for unknown logical types, and it doesn't fall back to the physical type. So that does complicate the compatibility story ..

[wgtmac]

@jorisvandenbossche I think your concern makes sense. It should be a bug if parquet-cpp fails due to unknown logical type and we need to fix that. I also have concern about a new ColumnOrder and need to do some testing. Adding a new logical type should not break anything from legacy readers.

[jornfranke]

Apache Iceberg is adding geospatial support: https://docs.google.com/document/d/1iVFbrRNEzZl8tDcZC81GFt01QJkLJsI9E2NBOt21IRI. It would be good if Apache Parquet can support geometry type natively.

On the geo integration into Iceberg no one has really worked since some time: apache/iceberg#2586

[szehon-ho]

On the geo integration into Iceberg no one has really worked since some time: apache/iceberg#2586

Yes there is now a concrete proposal apache/iceberg#10260 , and the plan currently is to bring it up in next community sync

[cholmes]

Thanks for doing this @wgtmac - it's awesome to see this proposal! I helped initiate GeoParquet, and hope we can fully support your effort.

@paleolimbot I'm happy to see the fast evolution of GeoParquet specs. I don't think the addition of geometry type aims to replace or deprecate something from GeoParquet. Instead, GeoParquet can simply ignore the new type as of now, or leverage the built-in bbox if beneficial.

That makes sense, but I think we're also happy to have GeoParquet replaced! As long as it can 'scale up' to meet all the crazy things that hard core geospatial people need, while also being accessible to everyone else. If Parquet had geospatial types from the start we wouldn't have started GeoParquet. We spent a lot of time and effort trying to get the right balance between making it easy to implement for those who don't care about the complexity of geospatial (edges, coordinate reference systems, epochs, winding), while also having the right options to handle it for those who do. My hope has been that the decisions we made there will make it easier to add geospatial support to any new format - like that a 'geo-ORC' could use the same fields and options that we added.

For additional (informative) attributes of the geometry type, if some of them are stable and make sense to store them natively into parquet column metadata, then perhaps we can work together to make it happen? I think the main goal of this addition is to enhance interoperability of geospatial data across systems and at the same time it takes little effort to convert to GeoParquet.

Sounds great! Happy to have GeoParquet be a place to 'try out' things. But I think ideally the surface area of 'GeoParquet' would be very minimal or not even exist, and that Parquet would just be the ideal format to store geospatial data in. And I think if we can align well between this proposal and GeoParquet that should be possible.

[jorisvandenbossche]

Related to the last major round of updates (summarized at #240 (comment)), considering the change for where to put the CRS description:

Offloaded the CRS representation to Parquet file metadata fields such that multiple geometry columns can refer to the same CRS. This also makes sure that the Parquet spec does not rely on another spec for CRS.

This seems like a very strange way to parameterize the CRS to me that doesn't simplify the specification

I agree with @paleolimbot that this indirection does not simplify the specification, and indeed does let any other discussion point (how should the CRS be described, PROJJSON or something else?) go away.
Could you provide some more rationale for why the spec would choose to put the CRS descriptions in the FileMetaData key_value_metadata, and then per column refer to a key in that metadata?
I understand that if you have many geometry columns with the same CRS that this saves some space, but are there other reasons for this design? (my feeling is that the many-geometry-columns use case is not worth the added complexity)

[redblackcoder]

(I work with Salesforce Data Cloud team, and evaluating GeoSpatial support in iceberg)
I am new to geospatial world, and wondering what does it mean for edges to be independent of underlying CRS? Can the edges be planar while the CRS is based on elliptic geometry?

[desruisseaux]

Can the edges be planar while the CRS is based on elliptic geometry?

In principle, no. First, talking about "planar edges" or "spherical edges" makes no sense and was a confusion of terms in the initial draft of this specification (the group reached an agreement to fix that in recent talks, I hope it will be done before release). An edge can be a straight line, a curve, a geodesic, etc., but cannot be a plane or a sphere (because of wrong number of dimensions).

What the initial draft intended to say with "planar edges" (sic) is "edges computed as if they were in a planar (two-dimensional Cartesian) coordinate system" (the thing that is planar is the coordinate system, not the edges). This is not really correct for geographic CRS, so you are right to said that they are not really independent. However, while it would be more exact to said that lines on a geographic CRS are geodesics, loxodrome, etc., it happens often that software ignore that physical reality and just perform linear interpolations of latitude and longitude values. The line on the ellipsoid surface obtained that way has no interesting properties, it is just easy to compute. We do not recommend doing that, but the use of "planar" word in this context was an acknowledgement that it happens in practice and an attempt to describe that.

[redblackcoder]

Thank you for the response. I do not understand what this parameter is used for in parquet. If it is the engine's property to treat the edges, how is this value helping? The engine capable of interpreting edges as geodesics should do so if the CRS reference indicates that the underlying geometry column belongs to an ellipsoid datum. Is this edge property forcing the engine to treat the values in a planar coordinate system?

In other words, is there something intrinsic to the data stored in the parquet file itself where edge parameter makes a difference?

[jiayuasu]

@redblackcoder

The Geo and Iceberg community are discussing the best way to describe this field. It is very likely that we will want to rename edges property to something else because this is not what we want to describe initially. We will post updates in a few days.

[mentin]

The engine capable of interpreting edges as geodesics should do so if the CRS reference indicates that the underlying geometry column belongs to an ellipsoid datum.

Consider the most common case, SRID 4326. It is Geographic coordinate system (GEOGCS) rather than Projected one.
https://www.esri.com/arcgis-blog/products/arcgis-pro/mapping/gcs_vs_pcs/

So the linestring from A to B should follow the geodesic line. But most systems treat 4326 as planar map. E.g. with Geometry type in PostGIS or MS SQL Server, they treat it as projected coordinate system, and the linestrings follow straight lines on flat surface. If you use latest MySQL or Geography type in PostGIS or MS SQL Server, the linestrings in 4326 follow geodesic lines on sphere. So there is ambiguity what exactly a linestring or polygon in 4326 describes. Is 'point(30 21) inside polygon((10 10, 50 10, 50 20, 10 20, 10 10))?

With geometry, in PostGIS, returns false:

select st_intersects(
  st_geomfromtext('polygon((10 10, 50 10, 50 20, 10 20, 10 10))', 4326), 
  st_geomfromtext('point(30 21)', 4326));

Same thing with geography (4326 is presumed), returns true:

 select st_intersects(
  st_geographyfromtext('srid=4326;polygon((10 10, 50 10, 50 20, 10 20, 10 10))'),
  st_geographyfromtext('srid=4326;point(30 21)'));

Unfortunately, there is no accepted way to describe the difference between geometry and geography in WKB format. You can encounter SRID=4326 with both interpretations. The edge attribute allows describing the difference between geometry and geography, and tells user how to interpret the data in a way consistent with the system that produced it.

[wgtmac]

I have removed edges and simplified crs to reflect changes from the iceberg PR. Could you please take a look? @rdblue @szehon-ho @jiayuasu

[emkornfield]

@wgtmac separate from the spec it might be good to start discussions on what the implementation for GeoParquet might look like (e.g. what new dependencies do we plan on taking on for reference implementation? What would APIs look like?)

[wgtmac]

@emkornfield The PoC implementations are apache/arrow#43977 and apache/parquet-java#2971

[paleolimbot]

separate from the spec it might be good to start discussions on what the implementation for GeoParquet might look like (e.g. what new dependencies do we plan on taking on for reference implementation? What would APIs look like?)

@emkornfield I think this is a good idea! The PoC implementations specifically may not handle writing statistics for non-planar edges depending on the final call on whether the statistics are always Cartesian min/max (i.e., lying for spherical edges and should be ignored), or whether the statistics take into curved edges for the non-planar case (requires non-trivial computational effort and complexity on behalf of the writer, but eliminates computational effort and complexity for the reader). Discussions in Iceberg have converged on the latter, which means we may have to figure out how to plug in S2 and/or Boost::Geometry when writing statistics in C++ (I can't speak for Java). Off the top of my head it could either be a Parquet-specific hook to override stats for a column chunk, the name of an Arrow compute UDF that can compute the required box, or willingness to put Boost or s2 as a dependency in that section of the code. (I don't think that's required for PoC , personally, but I'm also happy to prototype any of those if somebody does).

[mentin]

S2 C++ has S2LatLngRectBounder class which makes it very easy to compute the rectangular bound of a chain of geodesic edges, taking their curvature into account.

[paleolimbot]

Thank you for updating this! I know we have collectively been back and forth on a number of these concepts but I think what this has reduced to is very good. I took a read for consistency with the Iceberg PR and anything that might conflict when Parquet readers interact with spatial type implementations elsewhere. It looks great!

[jiayuasu]

In the Iceberg PR, the algorithm field is optional. If unset, it defaults to spherical. Should we follow it?

[wgtmac]

Yes, I can follow the same thing on the algorithm field.

[jiayuasu]

In the Iceberg PR, the crs and crs_encoding are merged to a single crs field and formatted as $type:$content, where type allows srid and projjson. Should we follow the same?

[wgtmac]

This is the only thing that I am hesitant to keep it consistent with the Iceberg PR. The mapping between them follows the table below:

Iceberg	Parquet
$type	crs_encoding
$content	crs

The reason is to provide a chance for non-Iceberg use cases to write full projjson content to the crs field. But this is not a strong opinion. Let me know what you think.

[paleolimbot]

I am happy with either (they encode equivalent information); however, I think separating them specifically for Parquet is a little nicer. I do like that there is a clear way for a writer to write an arbitrary string if it doesn't have the means to validate that it received PROJJSON (or doesn't have the ability to generate it). I also don't feel strongly about that 🙂

[jiayuasu]

Makes sense! I think the current way in Parquet is better and we can keep it.

[rdblue]

I'm strongly against the current type parameters. The CRS should not be embedded, it should be referenced like the spec in Iceberg. There's no need to duplicate these, require support for specific formats, or make type annotations huge. A CRS reference ID is cleaner, along with a way to store the CRS definition in file metadata if that's desired.

[paleolimbot]

I'm neutral conceptually (it's all the same information, it's just a matter of where to put it). The decision to put it as part of the LogicalType struct just makes a cleaner implementation (i.e., no need to add a reference to the global metadata to existing function signatures) to support conversions that need the CRS (almost all of them, as far as I know).