Struct Field
pub struct Field {
name: String,
data_type: DataType,
nullable: bool,
dict_id: i64,
dict_is_ordered: bool,
metadata: HashMap<String, String>,
}Expand description
Describes a single column in a Schema.
A Schema is an ordered collection of
Field objects. Fields contain:
name: the name of the fielddata_type: the type of the fieldnullable: if the field is nullablemetadata: 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: i64dict_is_ordered: bool§metadata: HashMap<String, String>Implementations§
§impl Field
impl Field
pub const LIST_FIELD_DEFAULT_NAME: &'static str = "item"
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
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
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.
pub fn new_dict( name: impl Into<String>, data_type: DataType, nullable: bool, dict_id: i64, dict_is_ordered: bool, ) -> Field
Creates a new field that has additional dictionary information
pub fn new_dictionary(
name: impl Into<String>,
key: DataType,
value: DataType,
nullable: bool,
) -> Field
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
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 theDataType::Structfieldfields: the description of each struct elementnullable: if theDataType::Structarray is nullable
pub fn new_list(
name: impl Into<String>,
value: impl Into<Arc<Field>>,
nullable: bool,
) -> Field
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 theDataType::Listfieldvalue: the description of each list elementnullable: if theDataType::Listarray is nullable
pub fn new_large_list(
name: impl Into<String>,
value: impl Into<Arc<Field>>,
nullable: bool,
) -> Field
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 theDataType::LargeListfieldvalue: the description of each list elementnullable: if theDataType::LargeListarray is nullable
pub fn new_fixed_size_list(
name: impl Into<String>,
value: impl Into<Arc<Field>>,
size: i32,
nullable: bool,
) -> Field
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 theDataType::FixedSizeListfieldvalue: the description of each list elementsize: the size of the fixed size listnullable: if theDataType::FixedSizeListarray 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
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 theDataType::Mapfieldentries: the name of the innerDataType::Structfieldkeys: the map keysvalues: the map valuessorted: if theDataType::Maparray is sortednullable: if theDataType::Maparray is nullable
pub fn new_union<S, F, T>(
name: S,
type_ids: T,
fields: F,
mode: UnionMode,
) -> Fieldwhere
S: Into<String>,
F: IntoIterator,
<F as IntoIterator>::Item: Into<Arc<Field>>,
T: IntoIterator<Item = i8>,
pub fn new_union<S, F, T>(
name: S,
type_ids: T,
fields: F,
mode: UnionMode,
) -> Fieldwhere
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 theDataType::Unionfieldtype_ids: the union type idsfields: the union fieldsmode: the union mode
pub fn set_metadata(&mut self, metadata: HashMap<String, String>)
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
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>
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>
pub fn metadata_mut(&mut self) -> &mut HashMap<String, String>
Returns a mutable reference to the Field’s optional custom metadata.
pub fn with_name(self, name: impl Into<String>) -> 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 fn set_data_type(&mut self, data_type: DataType)
pub fn set_data_type(&mut self, data_type: DataType)
pub fn with_data_type(self, data_type: DataType) -> Field
pub fn with_data_type(self, data_type: DataType) -> Field
pub fn extension_type_name(&self) -> Option<&str>
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>
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,
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 theField::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 theField::data_typeis 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) -> Ewhere
E: ExtensionType,
pub fn extension_type<E>(&self) -> Ewhere
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,
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) -> Fieldwhere
E: ExtensionType,
pub fn with_extension_type<E>(self, extension_type: E) -> Fieldwhere
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>
pub fn try_canonical_extension_type( &self, ) -> Result<CanonicalExtensionType, ArrowError>
pub const fn is_nullable(&self) -> bool
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)
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
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.
pub const fn dict_id(&self) -> Option<i64>
Returns the dictionary ID, if this is a dictionary type.
pub const fn dict_is_ordered(&self) -> Option<bool>
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
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>
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());Trait Implementations§
§impl<'de> Deserialize<'de> for Field
impl<'de> Deserialize<'de> for Field
§fn deserialize<__D>(
__deserializer: __D,
) -> Result<Field, <__D as Deserializer<'de>>::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(
__deserializer: __D,
) -> Result<Field, <__D as Deserializer<'de>>::Error>where
__D: Deserializer<'de>,
§impl Extend<Field> for SchemaBuilder
impl Extend<Field> for SchemaBuilder
§fn extend<T>(&mut self, iter: T)where
T: IntoIterator<Item = Field>,
fn extend<T>(&mut self, iter: T)where
T: IntoIterator<Item = Field>,
Source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one)Source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one)§impl FromIterator<Field> for Fields
impl FromIterator<Field> for Fields
§impl FromPyArrow for Field
impl FromPyArrow for Field
§fn from_pyarrow_bound(value: &Bound<'_, PyAny>) -> Result<Field, PyErr>
fn from_pyarrow_bound(value: &Bound<'_, PyAny>) -> Result<Field, PyErr>
§impl Ord for Field
impl Ord for Field
§impl PartialOrd for Field
impl PartialOrd for Field
§impl Serialize for Field
impl Serialize for Field
§fn serialize<__S>(
&self,
__serializer: __S,
) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>where
__S: Serializer,
fn serialize<__S>(
&self,
__serializer: __S,
) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>where
__S: Serializer,
§impl ToPyArrow for Field
impl ToPyArrow for Field
§fn to_pyarrow<'py>(&self, py: Python<'py>) -> Result<Bound<'py, PyAny>, PyErr>
fn to_pyarrow<'py>(&self, py: Python<'py>) -> Result<Bound<'py, PyAny>, PyErr>
§impl TryFrom<&FFI_ArrowSchema> for Field
impl TryFrom<&FFI_ArrowSchema> for Field
§type Error = ArrowError
type Error = ArrowError
§fn try_from(c_schema: &FFI_ArrowSchema) -> Result<Field, ArrowError>
fn try_from(c_schema: &FFI_ArrowSchema) -> Result<Field, ArrowError>
§impl TryFrom<&Field> for FFI_ArrowSchema
impl TryFrom<&Field> for FFI_ArrowSchema
§type Error = ArrowError
type Error = ArrowError
§fn try_from(field: &Field) -> Result<FFI_ArrowSchema, ArrowError>
fn try_from(field: &Field) -> Result<FFI_ArrowSchema, ArrowError>
§impl TryFrom<Field> for FFI_ArrowSchema
impl TryFrom<Field> for FFI_ArrowSchema
§type Error = ArrowError
type Error = ArrowError
§fn try_from(field: Field) -> Result<FFI_ArrowSchema, ArrowError>
fn try_from(field: Field) -> Result<FFI_ArrowSchema, ArrowError>
impl Eq for Field
Auto Trait Implementations§
impl Freeze for Field
impl RefUnwindSafe for Field
impl Send for Field
impl Sync for Field
impl Unpin for Field
impl UnwindSafe for Field
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
§impl<Q, K> Comparable<K> for Q
impl<Q, K> Comparable<K> for Q
§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key and return true if they are equal.