Feedback

Author: tschwarzinger

datafusion-examples/examples/extension_types/temperature.rs

@@ -56,7 +56,7 @@ fn create_session_context() -> Result<SessionContext> {
         |storage_type, metadata| {
             Ok(Arc::new(TemperatureExtensionType::try_new(
                 storage_type,
-                TemperatureUnit::try_from(metadata)?,
+                TemperatureUnit::deserialize(metadata)?,
             )?))
         },
     );
@@ -181,14 +181,10 @@ impl TemperatureUnit {
         };
         result.to_owned()
     }
-}
-
-/// Inverse operation of [`TemperatureUnit::serialize`]. This creates the [`TemperatureUnit`]
-/// value from the serialized string.
-impl TryFrom<Option<&str>> for TemperatureUnit {
-    type Error = ArrowError;
 
-    fn try_from(value: Option<&str>) -> std::result::Result<Self, Self::Error> {
+    /// Inverse operation of [`TemperatureUnit::serialize`]. This creates the [`TemperatureUnit`]
+    /// value from the serialized string.
+    pub fn deserialize(value: Option<&str>) -> std::result::Result<Self, ArrowError> {
         match value {
             Some("celsius") => Ok(TemperatureUnit::Celsius),
             Some("fahrenheit") => Ok(TemperatureUnit::Fahrenheit),

datafusion/common/src/types/canonical_extensions/bool8.rs

@@ -24,19 +24,28 @@ use arrow::util::display::{ArrayFormatter, DisplayIndex, FormatOptions, FormatRe
 use arrow_schema::extension::{Bool8, ExtensionType};
 use std::fmt::Write;
 
-/// Defines the extension type logic for the canonical `arrow.bool8` extension type.
+/// Defines the extension type logic for the canonical `arrow.bool8` extension type. This extension
+/// type allows storing a Boolean value in a single byte, instead of a single bit.
 ///
-/// See [`DFExtensionType`] for information on DataFusion's extension type mechanism.
+/// See [`DFExtensionType`] for information on DataFusion's extension type mechanism. See also
+/// [`Bool8`] for the implementation of arrow-rs, which this type uses internally.
+///
+/// <https://arrow.apache.org/docs/format/CanonicalExtensions.html#bit-boolean>
 #[derive(Debug, Clone)]
 pub struct DFBool8(Bool8);
 
 impl DFBool8 {
     /// Creates a new [`DFBool8`], validating that the storage type is compatible with the
     /// extension type.
+    ///
+    /// Even though [`DFBool8`] only supports a single storage type ([`DataType::Int8`]), passing-in
+    /// the storage type allows conveniently validating whether this extension type is compatible
+    /// with a given [`DataType`].
     pub fn try_new(
         data_type: &DataType,
         metadata: <Bool8 as ExtensionType>::Metadata,
     ) -> Result<Self> {
+        // Validates the storage type
         Ok(Self(<Bool8 as ExtensionType>::try_new(
             data_type, metadata,
         )?))
@@ -72,7 +81,7 @@ impl DFExtensionType for DFBool8 {
     }
 }
 
-/// Pretty printer for binary UUID values.
+/// Pretty printer for binary bool8 values.
 #[derive(Debug, Clone, Copy)]
 struct Bool8ValueDisplayIndex<'a> {
     array: &'a Int8Array,

datafusion/common/src/types/canonical_extensions/fixed_shape_tensor.rs

@@ -21,8 +21,13 @@ use arrow::datatypes::DataType;
 use arrow_schema::extension::{ExtensionType, FixedShapeTensor};
 
 /// Defines the extension type logic for the canonical `arrow.fixed_shape_tensor` extension type.
+/// This extension type can be used to store a [tensor](https://en.wikipedia.org/wiki/Tensor) of
+/// a fixed shape.
 ///
-/// See [`DFExtensionType`] for information on DataFusion's extension type mechanism.
+/// See [`DFExtensionType`] for information on DataFusion's extension type mechanism. See also
+/// [`FixedShapeTensor`] for the implementation of arrow-rs, which this type uses internally.
+///
+/// <https://arrow.apache.org/docs/format/CanonicalExtensions.html#fixed-shape-tensor>
 #[derive(Debug, Clone)]
 pub struct DFFixedShapeTensor {
     inner: FixedShapeTensor,

datafusion/common/src/types/canonical_extensions/json.rs

@@ -20,9 +20,13 @@ use crate::types::extension::DFExtensionType;
 use arrow::datatypes::DataType;
 use arrow_schema::extension::{ExtensionType, Json};
 
-/// Defines the extension type logic for the canonical `arrow.json` extension type.
+/// Defines the extension type logic for the canonical `arrow.json` extension type. This extension
+/// type defines that a particular string field stores JSON values.
 ///
-/// See [`DFExtensionType`] for information on DataFusion's extension type mechanism.
+/// See [`DFExtensionType`] for information on DataFusion's extension type mechanism. See also
+/// [`Json`] for the implementation of arrow-rs, which this type uses internally.
+///
+/// <https://arrow.apache.org/docs/format/CanonicalExtensions.html#json>
 #[derive(Debug, Clone)]
 pub struct DFJson {
     inner: Json,

datafusion/common/src/types/canonical_extensions/opaque.rs

@@ -20,9 +20,13 @@ use crate::types::extension::DFExtensionType;
 use arrow::datatypes::DataType;
 use arrow_schema::extension::{ExtensionType, Opaque};
 
-/// Defines the extension type logic for the canonical `arrow.opaque` extension type.
+/// Defines the extension type logic for the canonical `arrow.opaque` extension type. This extension
+/// type represents types that DataFusion cannot interpret.
 ///
-/// See [`DFExtensionType`] for information on DataFusion's extension type mechanism.
+/// See [`DFExtensionType`] for information on DataFusion's extension type mechanism. See also
+/// [`Opaque`] for the implementation of arrow-rs, which this type uses internally.
+///
+/// <https://arrow.apache.org/docs/format/CanonicalExtensions.html#opaque>
 #[derive(Debug, Clone)]
 pub struct DFOpaque {
     inner: Opaque,

datafusion/common/src/types/canonical_extensions/timestamp_with_offset.rs

@@ -32,8 +32,12 @@ use arrow_schema::extension::{ExtensionType, TimestampWithOffset};
 use std::fmt::Write;
 
 /// Defines the extension type logic for the canonical `arrow.timestamp_with_offset` extension type.
+/// This extension type allows associating a different offset for each timestamp in a column.
 ///
-/// See [`DFExtensionType`] for information on DataFusion's extension type mechanism.
+/// See [`DFExtensionType`] for information on DataFusion's extension type mechanism. See also
+/// [`TimestampWithOffset`] for the implementation of arrow-rs, which this type uses internally.
+///
+/// <https://arrow.apache.org/docs/format/CanonicalExtensions.html#timestamp-with-offset>
 #[derive(Debug, Clone)]
 pub struct DFTimestampWithOffset {
     inner: TimestampWithOffset,

datafusion/common/src/types/canonical_extensions/uuid.rs

@@ -25,9 +25,14 @@ use arrow_schema::extension::{ExtensionType, Uuid};
 use std::fmt::Write;
 use uuid::Bytes;
 
-/// Defines the extension type logic for the canonical `arrow.uuid` extension type.
+/// Defines the extension type logic for the canonical `arrow.uuid` extension type. This extension
+/// type defines that a field should be interpreted as a
+/// [UUID](https://de.wikipedia.org/wiki/Universally_Unique_Identifier).
 ///
-/// See [`DFExtensionType`] for information on DataFusion's extension type mechanism.
+/// See [`DFExtensionType`] for information on DataFusion's extension type mechanism. See also
+/// [`Uuid`] for the implementation of arrow-rs, which this type uses internally.
+///
+/// <https://arrow.apache.org/docs/format/CanonicalExtensions.html#uuid>
 #[derive(Debug, Clone)]
 pub struct DFUuid(Uuid);
 

datafusion/common/src/types/canonical_extensions/variable_shape_tensor.rs

@@ -21,8 +21,13 @@ use arrow::datatypes::DataType;
 use arrow_schema::extension::{ExtensionType, VariableShapeTensor};
 
 /// Defines the extension type logic for the canonical `arrow.variable_shape_tensor` extension type.
+/// This extension type can be used to store a [tensor](https://en.wikipedia.org/wiki/Tensor) with
+/// variable shape that can change for each element.
 ///
-/// See [`DFExtensionType`] for information on DataFusion's extension type mechanism.
+/// See [`DFExtensionType`] for information on DataFusion's extension type mechanism. See also
+/// [`VariableShapeTensor`] for the implementation of arrow-rs, which this type uses internally.
+///
+/// <https://arrow.apache.org/docs/format/CanonicalExtensions.html#variable-shape-tensor>
 #[derive(Debug, Clone)]
 pub struct DFVariableShapeTensor {
     inner: VariableShapeTensor,