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

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, type, and nullability

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 const fn name(&self) -> &String

Returns an immutable reference to the Field’s name.

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

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>(&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 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.

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 Clone for Field

fn clone(&self) -> Field

Returns a copy 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>) -> PyResult<Self>

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(&self, py: Python<'_>) -> PyResult<PyObject>

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