WIP: Add geometry logical type

src/main/thrift/parquet.thrift

@@ -270,8 +270,11 @@ struct Statistics {
  * may set min_value="B", max_value="C". Such more compact values must still be
  * valid values within the column's logical type.
  *
- * Values are encoded using PLAIN encoding, except that variable-length byte
- * arrays do not include a length prefix.
+ * Values are encoded using PLAIN encoding, except that:
+ * 1) variable-length byte arrays do not include a length prefix.
+ * 2) geometry logical type with BoundingBoxOrder uses max_value/min_value pair
+ * to store the bounding box for the column. Please refer to the definition
+ * of BoundingBoxOrder for detail.
  */
  5: optional binary max_value;
  6: optional binary min_value;
@@ -373,6 +376,69 @@ struct JsonType {
 struct BsonType {
 }
 
+/**
+ * A geometry can be any of the following subtypes.
+ * The list of geospatial subtypes is taken from the OGC (Open Geospatial Consortium)
+ * SFA (Simple Feature Access) Part 1- Common Architecture.
+ */
+enum GeometrySubType {
+ POINT = 0;
+ LINESTRING = 1;
+ POLYGON = 2;
+ MULTIPOINT = 3;
+ MULTILINESTRING = 4;
+ MULTIPOLYGON = 5;
+ GEOMETRY_COLLECTION = 6;
+}
+
+/**
+ * Interpretation for edges, 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; // not supported yet
+}
+
+/**
+ * Well-Known Binary. This is a well-known and popular binary representation regulated
+ * by the Open Geospatial Consortium (OGC). 
+ */
+struct WKB {}
+/**
+ * Encoding for geospatial data.
+ */
+union GeospatialEncoding {
+ 1: WKB WKB
+}
+
+/**
+ * Geometry logical type annotation
+ *
+ * Allowed for physical types: BINARY (added in 2.11.0)
+ */
+struct GeometryType {
+ /**
+ * The subtype of the geometry.
+ * If set, all values in the column must be of the same subtype.
+ * If not set, the column may contain values of any subtype.
+ */
+ 1: optional GeometrySubType subtype;
+ /**
+ * The dimension of the geometry.
+ * For now only 2D geometry is supported and the value must be 2 if set.
+ */
+ 2: optional byte dimension;
+ /**
+ * Coordinate Reference System, i.e. mapping of how coordinates refer to
+ * precise locations on earth.
+ * For now only OGC:CRS84 is supported.
+ */
+ 3: optional string crs;
+ 4: required Edges edges;
+ 5: required GeospatialEncoding encoding;
+}
+
 /**
  * LogicalType annotations to replace ConvertedType.
  *
@@ -403,6 +469,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
 }
 
 /**
@@ -916,6 +983,8 @@ struct RowGroup {
 
 /** Empty struct to signal the order defined by the physical or logical type */
 struct TypeDefinedOrder {}
+/** Empty struct to signal the order of GEOMETRY logical type */
+struct BoundingBoxOrder {}
 
 /**
  * Union to specify the order used for the min_value and max_value fields for a
@@ -925,6 +994,8 @@ struct TypeDefinedOrder {}
  * Possible values are:
  * * TypeDefinedOrder - the column uses the order defined by its logical or
  * physical type (if there is no logical type).
+ * * BoundingBoxOrder - the column uses the order to build bounding box
+ * (if the logical type is GEOMETRY).
  *
  * If the reader does not support the value of this union, min and max stats
  * for this column should be ignored.
@@ -954,6 +1025,7 @@ union ColumnOrder {
  * ENUM - unsigned byte-wise comparison
  * LIST - undefined
  * MAP - undefined
+ * GEOMETRY - undefined, as geometry objects cannot be compared directly
  *
  * In the absence of logical types, the sort order is determined by the physical type:
  * BOOLEAN - false, true
@@ -982,6 +1054,23 @@ union ColumnOrder {
  * `-0.0` should be written into the min statistics field.
  */
  1: TypeDefinedOrder TYPE_ORDER;
+
+ /**
+ * The order only applies to GEOMETRY logical type.
+ *
+ * Please note that geometry objects cannot be compared directly. This order aims to
+ * provide an approach to build a bounding box for geometry objects in the same page
+ * or column chunk.
+ *
+ * In this order, all 2D geometries are regarded as a collection of coordinate (x, y).
+ * For example, POINT has one coordinate, LINESTRING has two coordinates, and POLYGON
+ * might have three or more coordinates. A bounding box is the combination of x_min,
+ * x_max, y_min, and y_max of all coordinates from all geometry values. For simplexty,
+ * min_value field in the Statistics/ColumnIndex is encoded as the concatenation of
+ * PLAIN-encoded DOUBLE-typed x_min and y_min values. Similarly, max_value field is
+ * encoded as the concatenation of PLAIN-encoded DOUBLE-typed x_max and y_max values.
+ */
+ 2: BoundingBoxOrder BBOX_ORDER;
 }
 
 struct PageLocation {
@@ -1039,6 +1128,9 @@ struct ColumnIndex {
  * Such more compact values must still be valid values within the column's
  * logical type. Readers must make sure that list entries are populated before
  * using them by inspecting null_pages.
+ *
+ * For GEOMETRY logical type, these values are the bounding box of the column.
+ * Please refer to the definition of BoundingBoxOrder for detail.
  */
  2: required list<binary> min_values
  3: required list<binary> max_values
@@ -1048,6 +1140,8 @@ struct ColumnIndex {
  * which direction. This allows readers to perform binary searches in both
  * lists. Readers cannot assume that max_values[i] <= min_values[i+1], even
  * if the lists are ordered.
+ *
+ * For GEOMETRY type, UNORDERED is used at all times.
  */
  4: required BoundaryOrder boundary_order