Struct Field 

pub struct Field {
    name: String,
    data_type: DataType,
    nullable: bool,
    dict_id: i64,
    dict_is_ordered: bool,
    metadata: HashMap<String, String>,
}

Describes a single column in a Schema.

A Schema is an ordered collection of Field objects. Fields contain:

• name: the name of the field
• data_type: the type of the field
• nullable: if the field is nullable
• metadata: a map of key-value pairs containing additional custom metadata

Arrow Extension types, are encoded in Fields metadata. See Self::try_extension_type to retrieve the [ExtensionType], if any.

Fields

name: String

data_type: DataType

nullable: bool

dict_id: i64

👎Deprecated since 54.0.0: The ability to preserve dictionary IDs will be removed. With it, all fields related to it.

dict_is_ordered: bool

metadata: HashMap<String, String>

Implementations

impl Field

pub const LIST_FIELD_DEFAULT_NAME: &'static str = "item"

Default list member field name

pub fn new( name: impl Into<String>, data_type: DataType, nullable: bool, ) -> Field

Creates a new field with the given name, data type, and nullability

Example

Field::new("field_name", DataType::Int32, true);

pub fn new_list_field(data_type: DataType, nullable: bool) -> Field

Creates a new Field suitable for DataType::List and DataType::LargeList

While not required, this method follows the convention of naming the Field "item".

Example

assert_eq!(
  Field::new("item", DataType::Int32, true),
  Field::new_list_field(DataType::Int32, true)
);

pub fn new_dict( name: impl Into<String>, data_type: DataType, nullable: bool, dict_id: i64, dict_is_ordered: bool, ) -> Field

👎Deprecated since 54.0.0: The ability to preserve dictionary IDs will be removed. With the dict_id field disappearing this function signature will change by removing the dict_id parameter.

Creates a new field that has additional dictionary information

pub fn new_dictionary( name: impl Into<String>, key: DataType, value: DataType, nullable: bool, ) -> Field

Create a new Field with DataType::Dictionary

Use Self::new_dict for more advanced dictionary options

Panics

Panics if !key.is_dictionary_key_type

pub fn new_struct( name: impl Into<String>, fields: impl Into<Fields>, nullable: bool, ) -> Field

Create a new Field with DataType::Struct

• name: the name of the DataType::Struct field
• fields: the description of each struct element
• nullable: if the DataType::Struct array is nullable

pub fn new_list( name: impl Into<String>, value: impl Into<Arc<Field>>, nullable: bool, ) -> Field

Create a new Field with DataType::List

• name: the name of the DataType::List field
• value: the description of each list element
• nullable: if the DataType::List array is nullable

pub fn new_large_list( name: impl Into<String>, value: impl Into<Arc<Field>>, nullable: bool, ) -> Field

Create a new Field with DataType::LargeList

• name: the name of the DataType::LargeList field
• value: the description of each list element
• nullable: if the DataType::LargeList array is nullable

pub fn new_fixed_size_list( name: impl Into<String>, value: impl Into<Arc<Field>>, size: i32, nullable: bool, ) -> Field

Create a new Field with DataType::FixedSizeList

• name: the name of the DataType::FixedSizeList field
• value: the description of each list element
• size: the size of the fixed size list
• nullable: if the DataType::FixedSizeList array is nullable

pub fn new_map( name: impl Into<String>, entries: impl Into<String>, keys: impl Into<Arc<Field>>, values: impl Into<Arc<Field>>, sorted: bool, nullable: bool, ) -> Field

Create a new Field with DataType::Map

• name: the name of the DataType::Map field
• entries: the name of the inner DataType::Struct field
• keys: the map keys
• values: the map values
• sorted: if the DataType::Map array is sorted
• nullable: if the DataType::Map array is nullable

pub fn new_union<S, F, T>( name: S, type_ids: T, fields: F, mode: UnionMode, ) -> Field

where S: Into<String>, F: IntoIterator, <F as IntoIterator>::Item: Into<Arc<Field>>, T: IntoIterator<Item = i8>,

Create a new Field with DataType::Union

• name: the name of the DataType::Union field
• type_ids: the union type ids
• fields: the union fields
• mode: the union mode

pub fn set_metadata(&mut self, metadata: HashMap<String, String>)

Sets the Field’s optional custom metadata.

pub fn with_metadata(self, metadata: HashMap<String, String>) -> Field

Sets the metadata of this Field to be metadata and returns self

pub const fn metadata(&self) -> &HashMap<String, String>

Returns the immutable reference to the Field’s optional custom metadata.

pub fn metadata_mut(&mut self) -> &mut HashMap<String, String>

Returns a mutable reference to the Field’s optional custom metadata.

pub const fn name(&self) -> &String

Returns an immutable reference to the Field’s name.

pub fn set_name(&mut self, name: impl Into<String>)

Set the name of this Field

pub fn with_name(self, name: impl Into<String>) -> Field

Set the name of the Field and returns self.

let field = Field::new("c1", DataType::Int64, false)
   .with_name("c2");

assert_eq!(field.name(), "c2");

pub const fn data_type(&self) -> &DataType

Returns an immutable reference to the Field’s DataType.

pub fn set_data_type(&mut self, data_type: DataType)

Set DataType of the Field

let mut field = Field::new("c1", DataType::Int64, false);
field.set_data_type(DataType::Utf8);

assert_eq!(field.data_type(), &DataType::Utf8);

pub fn with_data_type(self, data_type: DataType) -> Field

Set DataType of the Field and returns self.

let field = Field::new("c1", DataType::Int64, false)
   .with_data_type(DataType::Utf8);

assert_eq!(field.data_type(), &DataType::Utf8);

pub fn extension_type_name(&self) -> Option<&str>

Returns the extension type name of this Field, if set.

This returns the value of [EXTENSION_TYPE_NAME_KEY], if set in Field::metadata. If the key is missing, there is no extension type name and this returns None.

Example

let field = Field::new("", DataType::Null, false);
assert_eq!(field.extension_type_name(), None);

let field = Field::new("", DataType::Null, false).with_metadata(
   [(EXTENSION_TYPE_NAME_KEY.to_owned(), "example".to_owned())]
       .into_iter()
       .collect(),
);
assert_eq!(field.extension_type_name(), Some("example"));

pub fn extension_type_metadata(&self) -> Option<&str>

Returns the extension type metadata of this Field, if set.

This returns the value of [EXTENSION_TYPE_METADATA_KEY], if set in Field::metadata. If the key is missing, there is no extension type metadata and this returns None.

Example

let field = Field::new("", DataType::Null, false);
assert_eq!(field.extension_type_metadata(), None);

let field = Field::new("", DataType::Null, false).with_metadata(
   [(EXTENSION_TYPE_METADATA_KEY.to_owned(), "example".to_owned())]
       .into_iter()
       .collect(),
);
assert_eq!(field.extension_type_metadata(), Some("example"));

pub fn try_extension_type<E>(&self) -> Result<E, ArrowError>

where E: ExtensionType,

Returns an instance of the given [ExtensionType] of this Field, if set in the Field::metadata.

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 ([ExtensionType::NAME]) in the Field::metadata (mismatch or missing)
• the deserialization of the metadata ([ExtensionType::deserialize_metadata]) fails
• 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:

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:

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 extension_type<E>(&self) -> E

where E: ExtensionType,

Returns an instance of the given [ExtensionType] of this Field, panics if this Field does not have this extension type.

Panic

This calls Field::try_extension_type and panics when it returns an error.

pub fn try_with_extension_type<E>( &mut self, extension_type: E, ) -> Result<(), ArrowError>

where E: ExtensionType,

Updates the metadata of this Field with the [ExtensionType::NAME] and [ExtensionType::metadata] of the given [ExtensionType], if the given extension type supports the Field::data_type of this field ([ExtensionType::supports_data_type]).

If the given extension type defines no metadata, a previously set value of [EXTENSION_TYPE_METADATA_KEY] is cleared.

Error

This functions returns an error if the data type of this field does not match any of the supported storage types of the given extension type.

pub fn with_extension_type<E>(self, extension_type: E) -> Field

where E: ExtensionType,

Updates the metadata of this Field with the [ExtensionType::NAME] and [ExtensionType::metadata] of the given [ExtensionType].

Panics

This calls Field::try_with_extension_type and panics when it returns an error.

pub fn try_canonical_extension_type( &self, ) -> Result<CanonicalExtensionType, ArrowError>

Returns the [CanonicalExtensionType] of this Field, if set.

Error

Returns an error if

• this field does not have a canonical extension type (mismatch or missing)
• the canonical extension is not supported
• the construction of the extension type fails

pub const fn is_nullable(&self) -> bool

Indicates whether this Field supports null values.

If true, the field may contain null values.

pub fn set_nullable(&mut self, nullable: bool)

Set the nullable of this Field.

let mut field = Field::new("c1", DataType::Int64, false);
field.set_nullable(true);

assert_eq!(field.is_nullable(), true);

pub fn with_nullable(self, nullable: bool) -> Field

Set nullable of the Field and returns self.

let field = Field::new("c1", DataType::Int64, false)
   .with_nullable(true);

assert_eq!(field.is_nullable(), true);

pub const fn dict_id(&self) -> Option<i64>

👎Deprecated since 54.0.0: The ability to preserve dictionary IDs will be removed. With it, all fields related to it.

Returns the dictionary ID, if this is a dictionary type.

pub const fn dict_is_ordered(&self) -> Option<bool>

Returns whether this Field’s dictionary is ordered, if this is a dictionary type.

Example

// non dictionaries do not have a dict is ordered flat
let field = Field::new("c1", DataType::Int64, false);
assert_eq!(field.dict_is_ordered(), None);
// by default dictionary is not ordered
let field = Field::new("c1", DataType::Dictionary(Box::new(DataType::Int64), Box::new(DataType::Utf8)), false);
assert_eq!(field.dict_is_ordered(), Some(false));
let field = field.with_dict_is_ordered(true);
assert_eq!(field.dict_is_ordered(), Some(true));

pub fn with_dict_is_ordered(self, dict_is_ordered: bool) -> Field

Set the is ordered field for this Field, if it is a dictionary.

Does nothing if this is not a dictionary type.

See Field::dict_is_ordered for more information.

pub fn try_merge(&mut self, from: &Field) -> Result<(), ArrowError>

Merge this field into self if it is compatible.

Struct fields are merged recursively.

NOTE: self may be updated to a partial / unexpected state in case of merge failure.

Example:

let mut field = Field::new("c1", DataType::Int64, false);
assert!(field.try_merge(&Field::new("c1", DataType::Int64, true)).is_ok());
assert!(field.is_nullable());

pub fn contains(&self, other: &Field) -> bool

Check to see if self is a superset of other field. Superset is defined as:

• if nullability doesn’t match, self needs to be nullable
• self.metadata is a superset of other.metadata
• all other fields are equal

pub fn size(&self) -> usize

Return size of this instance in bytes.

Includes the size of Self.

Trait Implementations

impl AsRef<Field> for Field

fn as_ref(&self) -> &Field

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Field

fn clone(&self) -> Field

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Field

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Field

fn deserialize<__D>( __deserializer: __D, ) -> Result<Field, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Field

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Extend<Field> for SchemaBuilder

fn extend<T>(&mut self, iter: T)

where T: IntoIterator<Item = Field>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl From<Field<'_>> for Field

Convert an IPC Field to Arrow Field

fn from(field: Field<'_>) -> Field

Converts to this type from the input type.

impl FromIterator<Field> for Fields

fn from_iter<T>(iter: T) -> Fields

where T: IntoIterator<Item = Field>,

Creates a value from an iterator.

impl FromPyArrow for Field

fn from_pyarrow_bound(value: &Bound<'_, PyAny>) -> Result<Field, PyErr>

Convert a Python object to an arrow-rs type.

impl Hash for Field

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Field

fn cmp(&self, other: &Field) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Field

fn eq(&self, other: &Field) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Field

fn partial_cmp(&self, other: &Field) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Field

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl ToPyArrow for Field

fn to_pyarrow<'py>(&self, py: Python<'py>) -> Result<Bound<'py, PyAny>, PyErr>

Convert the implemented type into a Python object without consuming it.

impl TryFrom<&FFI_ArrowSchema> for Field

type Error = ArrowError

The type returned in the event of a conversion error.

fn try_from(c_schema: &FFI_ArrowSchema) -> Result<Field, ArrowError>

Performs the conversion.

impl TryFrom<&Field> for FFI_ArrowSchema

type Error = ArrowError

The type returned in the event of a conversion error.

fn try_from(field: &Field) -> Result<FFI_ArrowSchema, ArrowError>

Performs the conversion.

impl TryFrom<Field> for FFI_ArrowSchema

type Error = ArrowError

The type returned in the event of a conversion error.

fn try_from(field: Field) -> Result<FFI_ArrowSchema, ArrowError>

Performs the conversion.

impl Eq for Field