Struct Cube

#[repr(C, align(64))]
pub struct Cube {
    pub tables: Vec<Table>,
    pub n_rows: Vec<usize>,
    pub name: String,
    pub third_dim_index: Option<Vec<String>>,
}

Cube - 3D Type for Advanced Analysis Use Cases

Holds a vector of tables unified by some value, often Time, for special indexing. Useful for data analysis.

Purpose

Useful when the tables represent discrete time snapshots, or a category dimension. This enables comparing data without losing the underlying grain through aggregation, whilst still supporting that.

Description

This is an optional extra enabled by the cube feature, and is not part of the Apache Arrow framework.

Under Development

⚠️ Unstable API and WIP: expect future development. Breaking changes will be minimised, but avoid using this in production unless you are ready to wear API adjustments.

Fields

tables: Vec<Table>

Table entries forming the cube (rectangular prism)

n_rows: Vec<usize>

Number of rows in each table

name: String

Cube name

third_dim_index: Option<Vec<String>>

Implementations

impl Cube

pub fn new( name: String, cols: Option<Vec<FieldArray>>, third_dim_index: Option<Vec<String>>, ) -> Self

Constructs a new Cube with a specified name and optional set of columns. If cols is provided, the columns are used to create the first table. The number of rows will be inferred from the first column. If the name is empty or whitespace, a unique default name is assigned. If no columns are provided, the Cube will be empty.

pub fn new_empty() -> Self

Constructs a new, empty Cube with a globally unique name.

pub fn add_table(&mut self, table: Table)

Adds a table to the cube.

pub fn schema(&self) -> Vec<Arc<Field>>

Gets the schemea from the first table as representative of the rest

pub fn n_tables(&self) -> usize

Returns the number of tables.

pub fn n_cols(&self) -> usize

Returns the number of columns.

pub fn is_empty(&self) -> bool

Returns true if the cube is empty (no tables, no columns or no rows).

pub fn table(&self, idx: usize) -> Option<&Table>

Returns a reference to a table by index.

pub fn table_mut(&mut self, idx: usize) -> Option<&mut Table>

Returns a mutable reference to a table by index.

pub fn table_names(&self) -> Vec<&str>

Returns the names of all tables in the cube.

pub fn table_index(&self, name: &str) -> Option<usize>

Returns the index of a table by name.

pub fn has_table(&self, name: &str) -> bool

Checks if a table with the given name exists.

pub fn remove_table_at(&mut self, idx: usize) -> bool

Removes a table by index.

pub fn remove_table(&mut self, name: &str) -> bool

Removes a table by name.

pub fn clear(&mut self)

Clears all tables and resets row counts.

pub fn tables(&self) -> &[Table]

Returns an immutable reference to all tables.

pub fn tables_mut(&mut self) -> &mut [Table]

Returns a mutable reference to all tables.

pub fn iter_tables(&self) -> Iter<'_, Table>

Returns an iterator over all tables.

pub fn iter_tables_mut(&mut self) -> IterMut<'_, Table>

pub fn col_names(&self) -> Vec<&str>

Returns the list of column names (from the first table).

pub fn col_index(&self, name: &str) -> Option<usize>

Returns the index of a column by name (from the first table).

pub fn has_col(&self, name: &str) -> bool

Returns true if the cube has a column of the given name (in all tables).

pub fn col(&self, idx: usize) -> Option<Vec<&FieldArray>>

Returns all columns (FieldArrays) with the given index across all tables.

pub fn col_by_name(&self, name: &str) -> Option<Vec<&FieldArray>>

Returns all columns (FieldArrays) with the given name across all tables.

pub fn cols(&self) -> Vec<Vec<&FieldArray>>

Returns all columns for all tables as Vec<Vec<&FieldArray>>.

pub fn remove_col(&mut self, name: &str) -> bool

Removes a column by name from all tables. Returns true if removed from all.

pub fn remove_col_at(&mut self, idx: usize) -> bool

Removes a column by index from all tables. Returns true if removed from all.

pub fn iter_cols( &self, col_idx: usize, ) -> Option<impl Iterator<Item = &FieldArray>>

Returns an iterator over the specified column across all tables.

pub fn iter_cols_by_name<'a>( &'a self, name: &'a str, ) -> Option<impl Iterator<Item = &'a FieldArray> + 'a>

Returns an iterator over the named column across all tables.

pub fn set_third_dim_index<S: Into<String>>(&mut self, cols: Vec<S>)

Sets the third dimensional index

pub fn third_dim_index(&self) -> Option<&[String]>

Retrieves the third dimensional index

pub fn slice_clone(&self, offset: usize, len: usize) -> Self

Returns a new owned Cube containing rows [offset, offset+len) for all tables.

pub fn slice(&self, offset: usize, len: usize) -> CubeV

Returns a zero-copy view over rows [offset, offset+len) for all tables.

pub fn par_iter_tables(&self) -> Iter<'_, Table>

Returns a parallel iterator over all tables.

pub fn par_iter_tables_mut(&mut self) -> IterMut<'_, Table>

Returns a parallel mutable iterator over all tables.

Trait Implementations

impl Clone for Cube

fn clone(&self) -> Cube

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Cube

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

Formats the value using the given formatter.

impl Default for Cube

fn default() -> Cube

Returns the “default value” for a type.

impl From<Cube> for Value

fn from(v: Cube) -> Self

Converts to this type from the input type.

impl<'a> IntoIterator for &'a Cube

type Item = &'a Table

The type of the elements being iterated over.

type IntoIter = Iter<'a, Table>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for &'a mut Cube

type Item = &'a mut Table

The type of the elements being iterated over.

type IntoIter = IterMut<'a, Table>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for Cube

type Item = Table

The type of the elements being iterated over.

type IntoIter = <Vec<Table> as IntoIterator>::IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for Cube

fn eq(&self, other: &Cube) -> 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 TryFrom<Value> for Cube

type Error = MinarrowError

The type returned in the event of a conversion error.

fn try_from(v: Value) -> Result<Self, Self::Error>

Performs the conversion.

impl StructuralPartialEq for Cube