feat(geoarrow-schema)!: Better distinction of creating GeoArrowType depending on extension metadata (#1275)

### Change list

- Creates new `GeoArrowType::from_extension_field` which will only work
if the field explicitly has a GeoArrow extension name set.
- Creates new `GeoArrowType::from_arrow_field` which takes the old
behavior of `TryFrom<&Field>`, allowing inference from string and binary
columns.
- **Breaking**: Changes `TryFrom<&Field> for GeoArrowType` to require
explicit GeoArrow metadata on the field.

Closes #1274

Author: kylebarron

rust/geoarrow-array/src/array/mod.rs

@@ -50,7 +50,7 @@ pub fn from_arrow_array(
 ) -> GeoArrowResult<Arc<dyn GeoArrowArray>> {
     use GeoArrowType::*;
 
-    let result: Arc<dyn GeoArrowArray> = match GeoArrowType::try_from(field)? {
+    let result: Arc<dyn GeoArrowArray> = match GeoArrowType::from_arrow_field(field)? {
         Point(_) => Arc::new(PointArray::try_from((array, field))?),
         LineString(_) => Arc::new(LineStringArray::try_from((array, field))?),
         Polygon(_) => Arc::new(PolygonArray::try_from((array, field))?),

rust/geoarrow-array/src/geozero/export/data_source/mod.rs

@@ -414,13 +414,8 @@ fn process_geometry_n<P: GeomProcessor>(
 fn geometry_columns(schema: &Schema) -> Vec<usize> {
     let mut geom_indices = vec![];
     for (field_idx, field) in schema.fields().iter().enumerate() {
-        // We first check that an extension type name is set and then check that we can coerce to a
-        // GeoArrowType so that we don't accept columns that are _compatible_ with geoarrow storage
-        // but aren't set as geoarrow extension types.
-        if let Some(_ext_name) = field.extension_type_name() {
-            if let Ok(_geoarrow_type) = GeoArrowType::try_from(field.as_ref()) {
-                geom_indices.push(field_idx);
-            }
+        if GeoArrowType::from_extension_field(field.as_ref()).is_ok() {
+            geom_indices.push(field_idx);
         }
     }
     geom_indices

rust/geoarrow-array/src/trait_.rs

@@ -630,7 +630,8 @@ mod test {
         for (list_size, dim) in test_cases.into_iter() {
             let array = FixedSizeListBuilder::new(Float64Builder::new(), list_size).finish();
             let t =
-                GeoArrowType::try_from(&Field::new("", array.data_type().clone(), true)).unwrap();
+                GeoArrowType::from_arrow_field(&Field::new("", array.data_type().clone(), true))
+                    .unwrap();
             assert_eq!(
                 t,
                 GeoArrowType::Point(
@@ -686,7 +687,8 @@ mod test {
         for (fields, builders, dim) in test_cases.into_iter() {
             let array = StructBuilder::new(fields, builders).finish();
             let t =
-                GeoArrowType::try_from(&Field::new("", array.data_type().clone(), true)).unwrap();
+                GeoArrowType::from_arrow_field(&Field::new("", array.data_type().clone(), true))
+                    .unwrap();
             assert_eq!(
                 t,
                 GeoArrowType::Point(

rust/geoarrow-schema/src/datatype.rs

@@ -287,73 +287,71 @@ impl GeoArrowType {
             WktView(t) => WktView(t.with_metadata(meta)),
         }
     }
-}
-
-macro_rules! impl_into_geoarrowtype {
-    ($source_type:ident, $variant:expr) => {
-        impl From<$source_type> for GeoArrowType {
-            fn from(value: $source_type) -> Self {
-                $variant(value)
-            }
-        }
-    };
-}
-
-impl_into_geoarrowtype!(PointType, GeoArrowType::Point);
-impl_into_geoarrowtype!(LineStringType, GeoArrowType::LineString);
-impl_into_geoarrowtype!(PolygonType, GeoArrowType::Polygon);
-impl_into_geoarrowtype!(MultiPointType, GeoArrowType::MultiPoint);
-impl_into_geoarrowtype!(MultiLineStringType, GeoArrowType::MultiLineString);
-impl_into_geoarrowtype!(MultiPolygonType, GeoArrowType::MultiPolygon);
-impl_into_geoarrowtype!(GeometryCollectionType, GeoArrowType::GeometryCollection);
-impl_into_geoarrowtype!(BoxType, GeoArrowType::Rect);
-impl_into_geoarrowtype!(GeometryType, GeoArrowType::Geometry);
 
-impl TryFrom<&Field> for GeoArrowType {
-    type Error = GeoArrowError;
+    /// Create a new [`GeoArrowType`] from an Arrow [`Field`], requiring GeoArrow metadata to be
+    /// set.
+    ///
+    /// If the field does not have at least a GeoArrow extension name, an error will be returned.
+    ///
+    /// See also [`GeoArrowType::from_arrow_field`].
+    pub fn from_extension_field(field: &Field) -> GeoArrowResult<Self> {
+        let extension_name = field.extension_type_name().ok_or(GeoArrowError::InvalidGeoArrow(
+                "Expected GeoArrow extension metadata, but found none, and `require_geoarrow_metadata` is `true`.".to_string(),
+            ))?;
 
-    fn try_from(field: &Field) -> GeoArrowResult<Self> {
         use GeoArrowType::*;
-        if let Some(extension_name) = field.extension_type_name() {
-            let data_type = match extension_name {
-                PointType::NAME => Point(field.extension_type()),
-                LineStringType::NAME => LineString(field.extension_type()),
-                PolygonType::NAME => Polygon(field.extension_type()),
-                MultiPointType::NAME => MultiPoint(field.extension_type()),
-                MultiLineStringType::NAME => MultiLineString(field.extension_type()),
-                MultiPolygonType::NAME => MultiPolygon(field.extension_type()),
-                GeometryCollectionType::NAME => GeometryCollection(field.extension_type()),
-                BoxType::NAME => Rect(field.extension_type()),
-                GeometryType::NAME => Geometry(field.extension_type()),
-                WkbType::NAME | "ogc.wkb" => match field.data_type() {
-                    DataType::Binary => Wkb(field.extension_type()),
-                    DataType::LargeBinary => LargeWkb(field.extension_type()),
-                    DataType::BinaryView => WkbView(field.extension_type()),
-                    _ => {
-                        return Err(GeoArrowError::InvalidGeoArrow(format!(
-                            "Expected binary type for geoarrow.wkb, got '{}'",
-                            field.data_type()
-                        )));
-                    }
-                },
-                WktType::NAME => match field.data_type() {
-                    DataType::Utf8 => Wkt(field.extension_type()),
-                    DataType::LargeUtf8 => LargeWkt(field.extension_type()),
-                    DataType::Utf8View => WktView(field.extension_type()),
-                    _ => {
-                        return Err(GeoArrowError::InvalidGeoArrow(format!(
-                            "Expected string type for geoarrow.wkt, got '{}'",
-                            field.data_type()
-                        )));
-                    }
-                },
-                name => {
+        let data_type = match extension_name {
+            PointType::NAME => Point(field.try_extension_type()?),
+            LineStringType::NAME => LineString(field.try_extension_type()?),
+            PolygonType::NAME => Polygon(field.try_extension_type()?),
+            MultiPointType::NAME => MultiPoint(field.try_extension_type()?),
+            MultiLineStringType::NAME => MultiLineString(field.try_extension_type()?),
+            MultiPolygonType::NAME => MultiPolygon(field.try_extension_type()?),
+            GeometryCollectionType::NAME => GeometryCollection(field.try_extension_type()?),
+            BoxType::NAME => Rect(field.try_extension_type()?),
+            GeometryType::NAME => Geometry(field.try_extension_type()?),
+            WkbType::NAME => match field.data_type() {
+                DataType::Binary => Wkb(field.try_extension_type()?),
+                DataType::LargeBinary => LargeWkb(field.try_extension_type()?),
+                DataType::BinaryView => WkbView(field.try_extension_type()?),
+                _ => {
                     return Err(GeoArrowError::InvalidGeoArrow(format!(
-                        "Expected GeoArrow type, got Arrow extension type with name: '{name}'.",
+                        "Expected binary type for a field with extension name 'geoarrow.wkb', got '{}'",
+                        field.data_type()
                     )));
                 }
-            };
-            Ok(data_type)
+            },
+            WktType::NAME => match field.data_type() {
+                DataType::Utf8 => Wkt(field.try_extension_type()?),
+                DataType::LargeUtf8 => LargeWkt(field.try_extension_type()?),
+                DataType::Utf8View => WktView(field.try_extension_type()?),
+                _ => {
+                    return Err(GeoArrowError::InvalidGeoArrow(format!(
+                        "Expected string type for a field with extension name 'geoarrow.wkt', got '{}'",
+                        field.data_type()
+                    )));
+                }
+            },
+            name => {
+                return Err(GeoArrowError::InvalidGeoArrow(format!(
+                    "Expected a GeoArrow extension name, got an Arrow extension type with name: '{name}'.",
+                )));
+            }
+        };
+        Ok(data_type)
+    }
+
+    /// Create a new [`GeoArrowType`] from an Arrow [`Field`], inferring the GeoArrow type if
+    /// GeoArrow metadata is not present.
+    ///
+    /// This will first try [`GeoArrowType::from_extension_field`], and if that fails, will try to
+    /// infer the GeoArrow type from the field's [DataType]. This only works for Point, WKB, and
+    /// WKT types, as those are the only types that can be unambiguously inferred from an Arrow
+    /// [DataType].
+    pub fn from_arrow_field(field: &Field) -> GeoArrowResult<Self> {
+        use GeoArrowType::*;
+        if let Ok(geo_type) = Self::from_extension_field(field) {
+            Ok(geo_type)
         } else {
             let metadata = Arc::new(Metadata::try_from(field)?);
             let data_type = match field.data_type() {
@@ -389,7 +387,36 @@ impl TryFrom<&Field> for GeoArrowType {
                 DataType::Utf8View => WktView(WktType::new(metadata)),
                 _ => return Err(GeoArrowError::InvalidGeoArrow("Only FixedSizeList, Struct, Binary, LargeBinary, BinaryView, String, LargeString, and StringView arrays are unambigously typed for a GeoArrow type and can be used without extension metadata.\nEnsure your array input has GeoArrow metadata.".to_string())),
             };
+
             Ok(data_type)
         }
     }
 }
+
+macro_rules! impl_into_geoarrowtype {
+    ($source_type:ident, $variant:expr) => {
+        impl From<$source_type> for GeoArrowType {
+            fn from(value: $source_type) -> Self {
+                $variant(value)
+            }
+        }
+    };
+}
+
+impl_into_geoarrowtype!(PointType, GeoArrowType::Point);
+impl_into_geoarrowtype!(LineStringType, GeoArrowType::LineString);
+impl_into_geoarrowtype!(PolygonType, GeoArrowType::Polygon);
+impl_into_geoarrowtype!(MultiPointType, GeoArrowType::MultiPoint);
+impl_into_geoarrowtype!(MultiLineStringType, GeoArrowType::MultiLineString);
+impl_into_geoarrowtype!(MultiPolygonType, GeoArrowType::MultiPolygon);
+impl_into_geoarrowtype!(GeometryCollectionType, GeoArrowType::GeometryCollection);
+impl_into_geoarrowtype!(BoxType, GeoArrowType::Rect);
+impl_into_geoarrowtype!(GeometryType, GeoArrowType::Geometry);
+
+impl TryFrom<&Field> for GeoArrowType {
+    type Error = GeoArrowError;
+
+    fn try_from(field: &Field) -> GeoArrowResult<Self> {
+        Self::from_extension_field(field)
+    }
+}

rust/geodatafusion/src/udf/geo/processing/centroid.rs

@@ -9,7 +9,7 @@ use datafusion::logical_expr::{
 };
 use geoarrow_array::GeoArrowArray;
 use geoarrow_array::array::from_arrow_array;
-use geoarrow_schema::{CoordType, Dimension, GeoArrowType, PointType};
+use geoarrow_schema::{CoordType, Dimension, Metadata, PointType};
 
 use crate::data_types::any_single_geometry_type_input;
 use crate::error::GeoDataFusionResult;
@@ -79,9 +79,8 @@ fn return_field_impl(
     args: ReturnFieldArgs,
     coord_type: CoordType,
 ) -> GeoDataFusionResult<FieldRef> {
-    let input_type = GeoArrowType::try_from(args.arg_fields[0].as_ref())?;
-    let output_type =
-        PointType::new(Dimension::XY, input_type.metadata().clone()).with_coord_type(coord_type);
+    let metadata = Arc::new(Metadata::try_from(args.arg_fields[0].as_ref()).unwrap_or_default());
+    let output_type = PointType::new(Dimension::XY, metadata).with_coord_type(coord_type);
     Ok(Arc::new(output_type.to_field("", true)))
 }
 

rust/geodatafusion/src/udf/geo/processing/convex_hull.rs

@@ -9,7 +9,7 @@ use datafusion::logical_expr::{
 };
 use geoarrow_array::GeoArrowArray;
 use geoarrow_array::array::from_arrow_array;
-use geoarrow_schema::{CoordType, Dimension, GeoArrowType, PolygonType};
+use geoarrow_schema::{CoordType, Dimension, Metadata, PolygonType};
 
 use crate::data_types::any_single_geometry_type_input;
 use crate::error::GeoDataFusionResult;
@@ -79,9 +79,8 @@ fn return_field_impl(
     args: ReturnFieldArgs,
     coord_type: CoordType,
 ) -> GeoDataFusionResult<FieldRef> {
-    let input_type = GeoArrowType::try_from(args.arg_fields[0].as_ref())?;
-    let output_type =
-        PolygonType::new(Dimension::XY, input_type.metadata().clone()).with_coord_type(coord_type);
+    let metadata = Arc::new(Metadata::try_from(args.arg_fields[0].as_ref()).unwrap_or_default());
+    let output_type = PolygonType::new(Dimension::XY, metadata).with_coord_type(coord_type);
     Ok(Arc::new(output_type.to_field("", true)))
 }
 

rust/geodatafusion/src/udf/geo/processing/oriented_envelope.rs

@@ -9,7 +9,7 @@ use datafusion::logical_expr::{
 };
 use geoarrow_array::GeoArrowArray;
 use geoarrow_array::array::from_arrow_array;
-use geoarrow_schema::{CoordType, Dimension, GeoArrowType, PolygonType};
+use geoarrow_schema::{CoordType, Dimension, Metadata, PolygonType};
 
 use crate::data_types::any_single_geometry_type_input;
 use crate::error::GeoDataFusionResult;
@@ -79,9 +79,8 @@ fn return_field_impl(
     args: ReturnFieldArgs,
     coord_type: CoordType,
 ) -> GeoDataFusionResult<FieldRef> {
-    let input_type = GeoArrowType::try_from(args.arg_fields[0].as_ref())?;
-    let output_type =
-        PolygonType::new(Dimension::XY, input_type.metadata().clone()).with_coord_type(coord_type);
+    let metadata = Arc::new(Metadata::try_from(args.arg_fields[0].as_ref()).unwrap_or_default());
+    let output_type = PolygonType::new(Dimension::XY, metadata).with_coord_type(coord_type);
     Ok(Arc::new(output_type.to_field("", true)))
 }
 

rust/geodatafusion/src/udf/geo/processing/point_on_surface.rs

@@ -9,7 +9,7 @@ use datafusion::logical_expr::{
 };
 use geoarrow_array::GeoArrowArray;
 use geoarrow_array::array::from_arrow_array;
-use geoarrow_schema::{CoordType, Dimension, GeoArrowType, PointType};
+use geoarrow_schema::{CoordType, Dimension, Metadata, PointType};
 
 use crate::data_types::any_single_geometry_type_input;
 use crate::error::GeoDataFusionResult;
@@ -79,9 +79,8 @@ fn return_field_impl(
     args: ReturnFieldArgs,
     coord_type: CoordType,
 ) -> GeoDataFusionResult<FieldRef> {
-    let input_type = GeoArrowType::try_from(args.arg_fields[0].as_ref())?;
-    let output_type =
-        PointType::new(Dimension::XY, input_type.metadata().clone()).with_coord_type(coord_type);
+    let metadata = Arc::new(Metadata::try_from(args.arg_fields[0].as_ref()).unwrap_or_default());
+    let output_type = PointType::new(Dimension::XY, metadata).with_coord_type(coord_type);
     Ok(Arc::new(output_type.to_field("", true)))
 }
 

rust/geodatafusion/src/udf/geohash/box2d_from_geohash.rs

@@ -13,7 +13,7 @@ use datafusion::logical_expr::{
 use geoarrow_array::GeoArrowArray;
 use geoarrow_array::array::RectArray;
 use geoarrow_array::builder::RectBuilder;
-use geoarrow_schema::{BoxType, Dimension, GeoArrowType};
+use geoarrow_schema::{BoxType, Dimension, Metadata};
 
 use crate::error::GeoDataFusionResult;
 
@@ -81,8 +81,8 @@ impl ScalarUDFImpl for Box2DFromGeoHash {
 }
 
 fn return_field_impl(args: ReturnFieldArgs) -> GeoDataFusionResult<FieldRef> {
-    let input_type = GeoArrowType::try_from(args.arg_fields[0].as_ref())?;
-    let output_type = BoxType::new(Dimension::XY, input_type.metadata().clone());
+    let metadata = Arc::new(Metadata::try_from(args.arg_fields[0].as_ref()).unwrap_or_default());
+    let output_type = BoxType::new(Dimension::XY, metadata);
     Ok(Arc::new(output_type.to_field("", true)))
 }
 

rust/geodatafusion/src/udf/geohash/point_from_geohash.rs

@@ -13,7 +13,7 @@ use datafusion::logical_expr::{
 use geoarrow_array::GeoArrowArray;
 use geoarrow_array::array::PointArray;
 use geoarrow_array::builder::PointBuilder;
-use geoarrow_schema::{CoordType, Dimension, GeoArrowType, PointType};
+use geoarrow_schema::{CoordType, Dimension, Metadata, PointType};
 
 use crate::error::GeoDataFusionResult;
 
@@ -86,9 +86,8 @@ fn return_field_impl(
     args: ReturnFieldArgs,
     coord_type: CoordType,
 ) -> GeoDataFusionResult<FieldRef> {
-    let input_type = GeoArrowType::try_from(args.arg_fields[0].as_ref())?;
-    let output_type =
-        PointType::new(Dimension::XY, input_type.metadata().clone()).with_coord_type(coord_type);
+    let metadata = Arc::new(Metadata::try_from(args.arg_fields[0].as_ref()).unwrap_or_default());
+    let output_type = PointType::new(Dimension::XY, metadata).with_coord_type(coord_type);
     Ok(Arc::new(output_type.to_field("", true)))
 }