PARQUET-2471: Add geometry logical type

src/main/thrift/parquet.thrift

@@ -237,6 +237,78 @@ struct SizeStatistics {
    3: optional list<i64> definition_level_histogram;
 }
 
+/**
+ * Interpretation for edges of GEOMETRY logical type, i.e. whether the edge
+ * between points represent a straight cartesian line or the shortest line on
+ * the sphere.
+ */
+enum Edges {
+  PLANAR = 0;
+  SPHERICAL = 1;
+}
+
+/**
+ * A custom WKB-encoded geometry data to be used in geometry statistics.
+ * The geometry may be a polygon to encode an s2 or h3 covering to provide
+ * vendor-agnostic coverings, or an evelope of geometries when a bounding
+ * box cannot be built (e.g. a geometry has spherical edges, or if an edge
+ * of geographic coordinates crosses the antimeridian).
+ */
+struct Geometry {
+  /** Bytes of a WKB-encoded geometry */
+  1: required binary geometry;
+  /**
+   * Edges of the geometry if it is a polygon. It may be different to the
+   * edges attribute from the GEOMETRY logical type.
+   */
+  2: optional Edges edges;
+}
+
+/**
+ * Bounding box of geometries in the representation of min/max value pair of
+ * coordinates from each axis. Values of Z and M are omitted for 2D geometries.
+ */
+struct BoundingBox {
+  1: required double xmin;
+  2: required double xmax;
+  3: required double ymin;
+  4: required double ymax;
+  5: optional double zmin;
+  6: optional double zmax;
+  7: optional double mmin;
+  8: optional double mmax;
+}
+
+struct Covering {
+  optional BoundingBox bbox    // A bounding box of geometries if it can be built.
+  optional Geometry covering   // A covering polygon of geometries if bbox is unavailable.
+}
+
+/** Statistics specific to GEOMETRY logical type */
+struct GeometryStatistics {
+  /** Covering of geometries */
+  1: optional Covering covering;
+
+  /**
+   * The geometry types of all geometries, or an empty array if they are not
+   * known. It follows the same rule of `geometry_types` column metadata of
+   * GeoParquet. Accepted geometry types are: "Point", "LineString", "Polygon",
+   * "MultiPoint", "MultiLineString", "MultiPolygon", "GeometryCollection".
+   *
+   * In addition, the following rules are used:
+   * - In case of 3D geometries, a `" Z"` suffix gets added (e.g. `["Point Z"]`).
+   * - A list of multiple values indicates that multiple geometry types are
+   *   present (e.g. `["Polygon", "MultiPolygon"]`).
+   * - An empty array explicitly signals that the geometry types are not known.
+   * - The geometry types in the list must be unique (e.g. `["Point", "Point"]`
+   *   is not valid).
+   *
+   * Please refer to link below for more detail:
+   * https://github.com/opengeospatial/geoparquet/blob/v1.0.0/format-specs/geoparquet.md?plain=1#L91
+   */
+  2: optional list<string> geometry_types;
+}
+
 /**
  * Statistics per row group and per page
  * All fields are optional.
@@ -279,6 +351,9 @@ struct Statistics {
    7: optional bool is_max_value_exact;
    /** If true, min_value is the actual minimum value for a column */
    8: optional bool is_min_value_exact;
+
+   /** statistics specific to geometry logical type */
+   9: optional GeometryStatistics geometry_stats;
 }
 
 /** Empty structs to use as logical type annotations */
@@ -373,6 +448,51 @@ struct JsonType {
 struct BsonType {
 }
 
+/**
+ * Phyiscal type and encoding for the geometry type.
+ */
+enum GeometryEncoding {
+  /**
+   * Allowed for phyiscal type: BYTE_ARRAY.
+   *
+   * Well-known binary (WKB) representations of geometries. It supports 2D or
+   * 3D geometries of the standard geometry types (Point, LineString, Polygon,
+   * MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection). This
+   * is the preferred option for maximum portability.
+   *
+   * This encoding enables GeometryStatistics to be set in the column chunk
+   * and page index.
+   */
+  WKB = 0;
+
+  // TODO: add native encoding from GeoParquet/GeoArrow
+}
+
+/**
+ * Geometry logical type annotation (added in 2.11.0)
+ */
+struct GeometryType {
+  /**
+   * Phyiscal type and encoding for the geometry type. Please refer to the
+   * definition of GeometryEncoding for more detail.
+   */
+  1: required GeometryEncoding encoding;
+  /**
+   * Coordinate Reference System, i.e. mapping of how coordinates refer to
+   * precise locations on earth, e.g. OGC:CRS84
+   */
+  2: optional string crs;
+  /**
+   * Edges of polygon.
+   */
+  3: optional Edges edges;
+  /**
+   * Additional informative metadata.
+   * It can be used by GeoParquet to offload some of the column metadata.
+   */
+  4: optional string metadata;
+}
+
 /**
  * LogicalType annotations to replace ConvertedType.
  *
@@ -403,6 +523,7 @@ union LogicalType {
   13: BsonType BSON           // use ConvertedType BSON
   14: UUIDType UUID           // no compatible ConvertedType
   15: Float16Type FLOAT16     // no compatible ConvertedType
+  16: GeometryType GEOMETRY   // no compatible ConvertedType
 }
 
 /**
@@ -954,6 +1075,7 @@ union ColumnOrder {
    *   ENUM - unsigned byte-wise comparison
    *   LIST - undefined
    *   MAP - undefined
+   *   GEOMETRY - undefined, use GeometryStatistics instead.
    *
    * In the absence of logical types, the sort order is determined by the physical type:
    *   BOOLEAN - false, true
@@ -1084,6 +1206,9 @@ struct ColumnIndex {
     * Same as repetition_level_histograms except for definitions levels.
     **/
    7: optional list<i64> definition_level_histograms;
+
+   /** A list containing statistics of GEOMETRY logical type for each page */
+   8: optional list<GeometryStatistics> geometry_stats;
 }
 
 struct AesGcmV1 {