Struct Field

pub struct Field { /* private fields */ }

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.

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) -> Self

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) -> Self

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, ) -> Self

👎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, ) -> Self

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, ) -> Self

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<FieldRef>, nullable: bool, ) -> Self

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<FieldRef>, nullable: bool, ) -> Self

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<FieldRef>, size: i32, nullable: bool, ) -> Self

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<FieldRef>, values: impl Into<FieldRef>, sorted: bool, nullable: bool, ) -> Self

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, ) -> Self

where S: Into<String>, F: IntoIterator, F::Item: Into<FieldRef>, 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>) -> Self

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>) -> Self

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) -> Self

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: ExtensionType>(&self) -> Result<E, ArrowError>

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

Error

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))

pub fn extension_type<E: ExtensionType>(&self) -> E

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: ExtensionType>( &mut self, extension_type: E, ) -> Result<(), ArrowError>

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: ExtensionType>(self, extension_type: E) -> Self

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 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) -> Self

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) -> Self

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 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

Formats the value using the given formatter.

impl Display for Field

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

Formats the value using the given formatter.

impl Extend<Field> for SchemaBuilder

fn extend<T: IntoIterator<Item = Field>>(&mut self, iter: T)

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 FromIterator<Field> for Fields

fn from_iter<T: IntoIterator<Item = Field>>(iter: T) -> Self

Creates a value from an iterator.

impl Hash for Field

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

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: &Self) -> 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: &Self) -> 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: &Self) -> 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 Eq for Field