Apache DataFusion SQL Query Engine
Improve docs and examples for `DataTypeExt` and `FieldExt` (#18271)
Andrew Lamb4309b85133f2
diff --git a/datafusion/common/src/datatype.rs b/datafusion/common/src/datatype.rsindex 85ffcf689c..544ec0c246 100644--- a/datafusion/common/src/datatype.rs+++ b/datafusion/common/src/datatype.rs@@ -15,7 +15,7 @@// specific language governing permissions and limitations// under the License.-//! [DataTypeExt] extension trait for converting DataTypes to Fields+//! [`DataTypeExt`] and [`FieldExt`] extension trait for working with DataTypes to Fieldsuse crate::arrow::datatypes::{DataType, Field, FieldRef};use std::sync::Arc;@@ -27,9 +27,23 @@ pub trait DataTypeExt {/// This is used to track the places where we convert a [`DataType`]/// into a nameless field to interact with an API that is/// capable of representing an extension type and/or nullability.+ ///+ /// For example, it will convert a `DataType::Int32` into+ /// `Field::new("", DataType::Int32, true)`.+ ///+ /// ```+ /// # use datafusion_common::datatype::DataTypeExt;+ /// # use arrow::datatypes::DataType;+ /// let dt = DataType::Utf8;+ /// let field = dt.into_nullable_field();+ /// // result is a nullable Utf8 field with "" name+ /// assert_eq!(field.name(), "");+ /// assert_eq!(field.data_type(), &DataType::Utf8);+ /// assert!(field.is_nullable());+ /// ```fn into_nullable_field(self) -> Field;- /// Convert the type to field ref with nullable type and "" name+ /// Convert the type to [`FieldRef`] with nullable type and "" name////// Concise wrapper around [`DataTypeExt::into_nullable_field`] that/// constructs a [`FieldRef`].@@ -46,20 +60,74 @@ impl DataTypeExt for DataType {}}-/// DataFusion extension methods for Arrow [`Field`]+/// DataFusion extension methods for Arrow [`Field`] and [`FieldRef`]pub trait FieldExt {/// Returns a new Field representing a List of this Field's DataType.+ ///+ /// For example if input represents an `Int32`, the return value will+ /// represent a `List<Int32>`.+ ///+ /// Example:+ /// ```+ /// # use std::sync::Arc;+ /// # use arrow::datatypes::{DataType, Field};+ /// # use datafusion_common::datatype::FieldExt;+ /// // Int32 field+ /// let int_field = Field::new("my_int", DataType::Int32, true);+ /// // convert to a List field+ /// let list_field = int_field.into_list();+ /// // List<Int32>+ /// // Note that the item field name has been renamed to "item"+ /// assert_eq!(list_field.data_type(), &DataType::List(Arc::new(+ /// Field::new("item", DataType::Int32, true)+ /// )));+ ///fn into_list(self) -> Self;- /// Return a new Field representing this Field as the item type of a FixedSizeList+ /// Return a new Field representing this Field as the item type of a+ /// [`DataType::FixedSizeList`]+ ///+ /// For example if input represents an `Int32`, the return value will+ /// represent a `FixedSizeList<Int32, size>`.+ ///+ /// Example:+ /// ```+ /// # use std::sync::Arc;+ /// # use arrow::datatypes::{DataType, Field};+ /// # use datafusion_common::datatype::FieldExt;+ /// // Int32 field+ /// let int_field = Field::new("my_int", DataType::Int32, true);+ /// // convert to a FixedSizeList field of size 3+ /// let fixed_size_list_field = int_field.into_fixed_size_list(3);+ /// // FixedSizeList<Int32, 3>+ /// // Note that the item field name has been renamed to "item"+ /// assert_eq!(+ /// fixed_size_list_field.data_type(),+ /// &DataType::FixedSizeList(Arc::new(+ /// Field::new("item", DataType::Int32, true)),+ /// 3+ /// ));+ ///fn into_fixed_size_list(self, list_size: i32) -> Self;- /// Create a field with the default list field name ("item")+ /// Update the field to have the default list field name ("item")+ ///+ /// Lists are allowed to have an arbitrarily named field; however, a name+ /// other than 'item' will cause it to fail an == check against a more+ /// idiomatically created list in arrow-rs which causes issues.+ ///+ /// For example, if input represents an `Int32` field named "my_int",+ /// the return value will represent an `Int32` field named "item".///- /// Note that lists are allowed to have an arbitrarily named field;- /// however, a name other than 'item' will cause it to fail an- /// == check against a more idiomatically created list in- /// arrow-rs which causes issues.+ /// Example:+ /// ```+ /// # use arrow::datatypes::Field;+ /// # use datafusion_common::datatype::FieldExt;+ /// let my_field = Field::new("my_int", arrow::datatypes::DataType::Int32, true);+ /// let item_field = my_field.into_list_item();+ /// assert_eq!(item_field.name(), Field::LIST_FIELD_DEFAULT_NAME);+ /// assert_eq!(item_field.name(), "item");+ /// ```fn into_list_item(self) -> Self;}