This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/main by this push:
new 0737c61e76 Add examples of using `Field::try_extension_type` (#8475)
0737c61e76 is described below
commit 0737c61e76057b127312dd8058887649ece702b8
Author: Andrew Lamb <[email protected]>
AuthorDate: Sun Sep 28 06:24:05 2025 -0700
Add examples of using `Field::try_extension_type` (#8475)
# Which issue does this PR close?
We generally require a GitHub issue to be filed for all bug fixes and
enhancements and this helps us generate change logs for our releases.
You can link an issue to this PR using the GitHub syntax.
- Part of https://github.com/apache/arrow-rs/issues/8474
# Rationale for this change
The implications of using `Field::try_extension_type` may not be clear,
so let's document it better. See
https://github.com/apache/arrow-rs/issues/8474 for more background
# What changes are included in this PR?
Add some clarifying comments and a doc example
Here is an example of it rendered
<img width="1049" height="988" alt="Screenshot 2025-09-26 at 12 14
31 PM"
src="https://github.com/user-attachments/assets/f7c8fc99-9204-4d9b-83ee-94ddd77abd02";
/>
# Are these changes tested?
Yes new doc example tets
# Are there any user-facing changes?
No API / code changes
---
arrow-schema/src/field.rs | 58 ++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 57 insertions(+), 1 deletion(-)
diff --git a/arrow-schema/src/field.rs b/arrow-schema/src/field.rs
index c0dcaff45c..e40917614b 100644
--- a/arrow-schema/src/field.rs
+++ b/arrow-schema/src/field.rs
@@ -491,7 +491,12 @@ impl Field {
/// Returns an instance of the given [`ExtensionType`] of this [`Field`],
/// if set in the [`Field::metadata`].
///
- /// # Error
+ /// Note that using `try_extension_type` with an extension type that does
+ /// not match the name in the metadata will return an `ArrowError` which
can
+ /// be slow due to string allocations. If you only want to check if a
+ /// [`Field`] has a specific [`ExtensionType`], see the example below.
+ ///
+ /// # Errors
///
/// Returns an error if
/// - this field does not have the name of this extension type
@@ -502,6 +507,57 @@ impl Field {
/// - the construction of the extension type ([`ExtensionType::try_new`])
/// fail (for example when the [`Field::data_type`] is not supported by
/// the extension type ([`ExtensionType::supports_data_type`]))
+ ///
+ /// # Examples: Check and retrieve an extension type
+ /// You can use this to check if a [`Field`] has a specific
+ /// [`ExtensionType`] and retrieve it:
+ /// ```
+ /// # use arrow_schema::{DataType, Field, ArrowError};
+ /// # use arrow_schema::extension::ExtensionType;
+ /// # struct MyExtensionType;
+ /// # impl ExtensionType for MyExtensionType {
+ /// # const NAME: &'static str = "my_extension";
+ /// # type Metadata = String;
+ /// # fn supports_data_type(&self, data_type: &DataType) -> Result<(),
ArrowError> { Ok(()) }
+ /// # fn try_new(data_type: &DataType, metadata: Self::Metadata) ->
Result<Self, ArrowError> { Ok(Self) }
+ /// # fn serialize_metadata(&self) -> Option<String> { unimplemented!() }
+ /// # fn deserialize_metadata(s: Option<&str>) -> Result<Self::Metadata,
ArrowError> { unimplemented!() }
+ /// # fn metadata(&self) -> &<Self as ExtensionType>::Metadata { todo!() }
+ /// # }
+ /// # fn get_field() -> Field { Field::new("field", DataType::Null, false)
}
+ /// let field = get_field();
+ /// if let Ok(extension_type) =
field.try_extension_type::<MyExtensionType>() {
+ /// // do something with extension_type
+ /// }
+ /// ```
+ ///
+ /// # Example: Checking if a field has a specific extension type first
+ ///
+ /// Since `try_extension_type` returns an error, it is more
+ /// efficient to first check if the name matches before calling
+ /// `try_extension_type`:
+ /// ```
+ /// # use arrow_schema::{DataType, Field, ArrowError};
+ /// # use arrow_schema::extension::ExtensionType;
+ /// # struct MyExtensionType;
+ /// # impl ExtensionType for MyExtensionType {
+ /// # const NAME: &'static str = "my_extension";
+ /// # type Metadata = String;
+ /// # fn supports_data_type(&self, data_type: &DataType) -> Result<(),
ArrowError> { Ok(()) }
+ /// # fn try_new(data_type: &DataType, metadata: Self::Metadata) ->
Result<Self, ArrowError> { Ok(Self) }
+ /// # fn serialize_metadata(&self) -> Option<String> { unimplemented!() }
+ /// # fn deserialize_metadata(s: Option<&str>) -> Result<Self::Metadata,
ArrowError> { unimplemented!() }
+ /// # fn metadata(&self) -> &<Self as ExtensionType>::Metadata { todo!() }
+ /// # }
+ /// # fn get_field() -> Field { Field::new("field", DataType::Null, false)
}
+ /// let field = get_field();
+ /// // First check if the name matches before calling the potentially
expensive `try_extension_type`
+ /// if field.extension_type_name() == Some(MyExtensionType::NAME) {
+ /// if let Ok(extension_type) =
field.try_extension_type::<MyExtensionType>() {
+ /// // do something with extension_type
+ /// }
+ /// }
+ /// ```
pub fn try_extension_type<E: ExtensionType>(&self) -> Result<E,
ArrowError> {
// Check the extension name in the metadata
match self.extension_type_name() {
