Skip to content

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.rs
index 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 Fields
use 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;
}