Struct Field

Source

pub struct Field {
    pub name: String,
    pub dtype: ArrowType,
    pub nullable: bool,
    pub metadata: BTreeMap<String, String>,
}

Expand description

§Field

§Description

Field struct supporting:

Array metadata such as type, name, nullability, etc.
Light metadata, e.g. a few key-value pairs.
Later Schema construction during Arrow FFI.

§Tips:

Field is cloned often, so it is best kept any metadata lightweight to avoid performance penalties. SuperTable wraps it in Arc.
For Datetime arrays, Field carries the logical Arrow type. The physical type remains a single integer-backed Datetime, while the logical type specifies its intended semantics. i.e.: Date32 Date64 Time32(TimeUnit) Time64(TimeUnit) Duration32(TimeUnit) Duration64(TimeUnit) Timestamp(TimeUnit) Interval(IntervalUnit)
This ensures that when sent over Arrow C-FFI (or to_apache_arrow()), it converts to the correct external type. Whilst, avoiding proliferating many specialised types prematurely, keeping the API and binary size minimal.

Fields§

§name: String§dtype: ArrowType§nullable: bool§metadata: BTreeMap<String, String>

Implementations§

Source §

impl Field

Source

pub fn new<T>( name: T, dtype: ArrowType, nullable: bool, metadata: Option<BTreeMap<String, String>>, ) -> Field
where T: Into<String>,

Constructs a new Field. If the provided name is empty or only whitespace, a globally unique name like UnnamedField1 will generate.

Examples found in repository ?

examples/pycapsule_exchange.rs (line 107)

97fn example_1_export_array(py: Python<'_>) -> PyResult<()> {
98    println!("Example 1: Export MinArrow array -> PyArrow via __arrow_c_array__");
99    println!("----------------------------------------------------------------");
100
101    // Build an array in Rust
102    let mut arr = IntegerArray::<i64>::default();
103    for i in 0..5 {
104        arr.push(i * 10);
105    }
106    let array = Array::from_int64(arr);
107    let field = Field::new("values", ArrowType::Int64, false, None);
108    println!("  Created MinArrow i64 array: [0, 10, 20, 30, 40]");
109
110    // Export as PyCapsules (i.e., schema + array)
111    let (schema_capsule, array_capsule) =
112        to_py::array_to_capsules(Arc::new(array), &field, py)?;
113    println!("  Exported as PyCapsules");
114
115    // Build a wrapper that implements __arrow_c_array__ so PyArrow can consume it.
116    // In a real #[pyfunction] you'd return ArrowArrayWrapper directly;
117    // here we simulate by calling __arrow_c_array__ manually.
118    let pyarrow = py.import("pyarrow")?;
119
120    // PyArrow.Array._import_from_c expects (array_ptr, schema_ptr) as integers,
121    // but we can extract the raw pointers from the capsules properly:
122    let array_ptr = unsafe {
123        pyo3::ffi::PyCapsule_GetPointer(
124            array_capsule.as_ptr(),
125            c"arrow_array".as_ptr(),
126        )
127    } as usize;
128    let schema_ptr = unsafe {
129        pyo3::ffi::PyCapsule_GetPointer(
130            schema_capsule.as_ptr(),
131            c"arrow_schema".as_ptr(),
132        )
133    } as usize;
134
135    let pa_array = pyarrow
136        .getattr("Array")?
137        .call_method1("_import_from_c", (array_ptr, schema_ptr))?;
138
139    let repr: String = pa_array.call_method0("__repr__")?.extract()?;
140    println!("  PyArrow received: {}", repr.lines().next().unwrap_or(""));
141    println!("  Done.\n");
142    Ok(())
143}
144
145/// Export a MinArrow table as a stream PyCapsule, then consume in PyArrow.
146///
147/// For multi-column data, the stream interface is more natural - the
148/// consumer gets a single capsule and pulls batches from it.
149fn example_2_export_table_stream(py: Python<'_>) -> PyResult<()> {
150    println!("Example 2: Export MinArrow table -> PyArrow via __arrow_c_stream__");
151    println!("------------------------------------------------------------------");
152
153    let mut ids = IntegerArray::<i32>::default();
154    ids.push(1);
155    ids.push(2);
156    ids.push(3);
157
158    let mut scores = FloatArray::<f64>::default();
159    scores.push(9.5);
160    scores.push(8.3);
161    scores.push(7.1);
162
163    let table = Table::new(
164        "results".to_string(),
165        Some(vec![
166            FieldArray::new(
167                Field::new("id", ArrowType::Int32, false, None),
168                Array::from_int32(ids),
169            ),
170            FieldArray::new(
171                Field::new("score", ArrowType::Float64, false, None),
172                Array::from_float64(scores),
173            ),
174        ]),
175    );
176    println!("  Created MinArrow table: 3 rows x 2 columns (id, score)");
177
178    // Export as a stream capsule and extract the raw pointer for PyArrow
179    let stream_capsule = to_py::table_to_stream_capsule(&table, py)?;
180    let stream_ptr = unsafe {
181        pyo3::ffi::PyCapsule_GetPointer(
182            stream_capsule.as_ptr(),
183            c"arrow_array_stream".as_ptr(),
184        )
185    } as usize;
186
187    let pyarrow = py.import("pyarrow")?;
188    let reader = pyarrow
189        .getattr("RecordBatchReader")?
190        .call_method1("_import_from_c", (stream_ptr,))?;
191    let pa_table = reader.call_method0("read_all")?;
192
193    let num_rows: usize = pa_table.getattr("num_rows")?.extract()?;
194    let schema_repr: String = pa_table.getattr("schema")?.call_method0("__repr__")?.extract()?;
195    println!("  PyArrow received: {} rows", num_rows);
196    println!("  Schema: {}", schema_repr.lines().next().unwrap_or(""));
197    println!("  Done.\n");
198    Ok(())
199}