Trait DynArray

Source

pub trait DynArray:
    'static
    + Sealed
    + Send
    + Sync
    + Debug
    + DynArrayEq
    + DynArrayHash
    + ArrayVisitor
    + ReduceNode {
Show 24 methods    // Required methods
    fn as_any(&self) -> &dyn Any;
    fn as_any_arc(self: Arc<Self>) -> Arc<dyn Any + Send + Sync>;
    fn to_array(&self) -> ArrayRef;
    fn len(&self) -> usize;
    fn dtype(&self) -> &DType;
    fn vtable(&self) -> &dyn DynVTable;
    fn encoding_id(&self) -> ArrayId;
    fn slice(&self, range: Range<usize>) -> VortexResult<ArrayRef>;
    fn filter(&self, mask: Mask) -> VortexResult<ArrayRef>;
    fn take(&self, indices: ArrayRef) -> VortexResult<ArrayRef>;
    fn scalar_at(&self, index: usize) -> VortexResult<Scalar>;
    fn is_valid(&self, index: usize) -> VortexResult<bool>;
    fn is_invalid(&self, index: usize) -> VortexResult<bool>;
    fn all_valid(&self) -> VortexResult<bool>;
    fn all_invalid(&self) -> VortexResult<bool>;
    fn valid_count(&self) -> VortexResult<usize>;
    fn invalid_count(&self) -> VortexResult<usize>;
    fn validity(&self) -> VortexResult<Validity>;
    fn validity_mask(&self) -> VortexResult<Mask>;
    fn to_canonical(&self) -> VortexResult<Canonical>;
    fn append_to_builder(
        &self,
        builder: &mut dyn ArrayBuilder,
        ctx: &mut ExecutionCtx,
    ) -> VortexResult<()>;
    fn statistics(&self) -> StatsSetRef<'_>;
    fn with_children(&self, children: Vec<ArrayRef>) -> VortexResult<ArrayRef>;

    // Provided method
    fn is_empty(&self) -> bool { ... }
}

Expand description

The public API trait for all Vortex arrays.

Required Methods§

Source

fn as_any(&self) -> &dyn Any

Returns the array as a reference to a generic Any trait object.

Source

fn as_any_arc(self: Arc<Self>) -> Arc<dyn Any + Send + Sync>

Returns the array as an Arc<dyn Any + Send + Sync>.

Source

fn to_array(&self) -> ArrayRef

Returns the array as an ArrayRef.

Source

fn len(&self) -> usize

Returns the length of the array.

Source

fn dtype(&self) -> &DType

Returns the logical Vortex DType of the array.

Source

fn vtable(&self) -> &dyn DynVTable

Returns the vtable of the array.

Source

fn encoding_id(&self) -> ArrayId

Returns the encoding ID of the array.

Source

fn slice(&self, range: Range<usize>) -> VortexResult<ArrayRef>

Performs a constant-time slice of the array.

Source

fn filter(&self, mask: Mask) -> VortexResult<ArrayRef>

Wraps the array in a FilterArray such that it is logically filtered by the given mask.

Source

fn take(&self, indices: ArrayRef) -> VortexResult<ArrayRef>

Wraps the array in a DictArray such that it is logically taken by the given indices.

Source

fn scalar_at(&self, index: usize) -> VortexResult<Scalar>

Fetch the scalar at the given index.

This method panics if the index is out of bounds for the array.

Source

fn is_valid(&self, index: usize) -> VortexResult<bool>

Returns whether the item at index is valid.

Source

fn is_invalid(&self, index: usize) -> VortexResult<bool>

Returns whether the item at index is invalid.

Source

fn all_valid(&self) -> VortexResult<bool>

Returns whether all items in the array are valid.

This is usually cheaper than computing a precise valid_count, but may return false negatives.

Source

fn all_invalid(&self) -> VortexResult<bool>

Returns whether the array is all invalid.

This is usually cheaper than computing a precise invalid_count, but may return false negatives.

Source

fn valid_count(&self) -> VortexResult<usize>

Returns the number of valid elements in the array.

Source

fn invalid_count(&self) -> VortexResult<usize>

Returns the number of invalid elements in the array.

Source

fn validity(&self) -> VortexResult<Validity>

Returns the Validity of the array.

Source

fn validity_mask(&self) -> VortexResult<Mask>

Returns the canonical validity mask for the array.

Source

fn to_canonical(&self) -> VortexResult<Canonical>

Returns the canonical representation of the array.

Source

fn append_to_builder( &self, builder: &mut dyn ArrayBuilder, ctx: &mut ExecutionCtx, ) -> VortexResult<()>

Writes the array into the canonical builder.

The DType of the builder must match that of the array.

Source

fn statistics(&self) -> StatsSetRef<'_>

Returns the statistics of the array.

Source

fn with_children(&self, children: Vec<ArrayRef>) -> VortexResult<ArrayRef>

Replaces the children of the array with the given array references.

Provided Methods§

Source

fn is_empty(&self) -> bool

Returns whether the array is empty (has zero rows).

Implementations§

Source §

impl dyn DynArray + '_

Source

pub fn is<M: Matcher>(&self) -> bool

Does the array match the given matcher.

Source

pub fn as_<M: Matcher>(&self) -> M::Match<'_>

Returns the array downcast by the given matcher.

Source

pub fn as_opt<M: Matcher>(&self) -> Option<M::Match<'_>>

Returns the array downcast by the given matcher.

Source

pub fn try_into<V: VTable>(self: Arc<Self>) -> Result<V::Array, Arc<Self>>

Returns the array downcast to the given A as an owned object.

Source

pub fn as_constant(&self) -> Option<Scalar>

Source

pub fn nbytes(&self) -> u64

Total size of the array in bytes, including all children and buffers.

Source

pub fn is_arrow(&self) -> bool

Returns whether this array is an arrow encoding.

Source

pub fn is_canonical(&self) -> bool

Whether the array is of a canonical encoding.

Source

pub fn with_child( &self, child_idx: usize, replacement: ArrayRef, ) -> VortexResult<ArrayRef>

Returns a new array with the child at child_idx replaced by replacement.

Source §

impl dyn DynArray + '_

Source

pub fn display_values(&self) -> impl Display

Display logical values of the array

For example, an i16 typed array containing the first five non-negative integers is displayed as: [0i16, 1i16, 2i16, 3i16, 4i16].

§Examples

let array = buffer![0_i16, 1, 2, 3, 4].into_array();
assert_eq!(
    format!("{}", array.display_values()),
    "[0i16, 1i16, 2i16, 3i16, 4i16]",
)

Source

pub fn display_as(&self, options: DisplayOptions) -> impl Display

Display the array as specified by the options.

See DisplayOptions for examples.

Source

pub fn display_tree_encodings_only(&self) -> impl Display

Display the tree of array encodings and lengths without metadata, buffers, or stats.

§Examples

let array = buffer![0_i16, 1, 2, 3, 4].into_array();
let expected = "root: vortex.primitive(i16, len=5)\n";
assert_eq!(format!("{}", array.display_tree_encodings_only()), expected);

let array = StructArray::from_fields(&[
    ("x", buffer![1, 2].into_array()),
    ("y", buffer![3, 4].into_array()),
]).unwrap().into_array();
let expected = "root: vortex.struct({x=i32, y=i32}, len=2)
  x: vortex.primitive(i32, len=2)
  y: vortex.primitive(i32, len=2)
";
assert_eq!(format!("{}", array.display_tree_encodings_only()), expected);

Source

pub fn display_tree(&self) -> impl Display

Display the tree of encodings of this array as an indented lists.

While some metadata (such as length, bytes and validity-rate) are included, the logical values of the array are not displayed. To view the logical values see Array::display_as and DisplayOptions.

§Examples

let array = buffer![0_i16, 1, 2, 3, 4].into_array();
let expected = "root: vortex.primitive(i16, len=5) nbytes=10 B (100.00%)
  metadata: EmptyMetadata
  buffer: values host 10 B (align=2) (100.00%)
";
assert_eq!(format!("{}", array.display_tree()), expected);

Source

pub fn display_table(&self) -> impl Display

Display the array as a formatted table.

For struct arrays, displays a column for each field in the struct. For regular arrays, displays a single column with values.

§Examples

let s = StructArray::from_fields(&[
    ("x", buffer![1, 2].into_array()),
    ("y", buffer![3, 4].into_array()),
]).unwrap().into_array();
let expected = "
┌──────┬──────┐
│  x   │  y   │
├──────┼──────┤
│ 1i32 │ 3i32 │
├──────┼──────┤
│ 2i32 │ 4i32 │
└──────┴──────┘".trim();
assert_eq!(format!("{}", s.display_table()), expected);

Source §

impl dyn DynArray + '_

Source

pub fn execute<E: Executable>( self: Arc<Self>, ctx: &mut ExecutionCtx, ) -> VortexResult<E>

Execute this array to produce an instance of E.

See the Executable implementation for details on how this execution is performed.

Source

pub fn execute_as<E: Executable>( self: Arc<Self>, _name: &'static str, ctx: &mut ExecutionCtx, ) -> VortexResult<E>

Execute this array, labeling the execution step with a name for tracing.

Source

pub fn execute_until<M: Matcher>( self: Arc<Self>, ctx: &mut ExecutionCtx, ) -> VortexResult<ArrayRef>

Iteratively execute this array until the Matcher matches, using an explicit work stack.

The scheduler repeatedly:

Checks if the current array matches M — if so, pops the stack or returns.
Runs execute_parent on each child for child-driven optimizations.
Calls execute which returns an ExecutionStep.

Note: the returned array may not match M. If execution converges to a canonical form that does not match M, the canonical array is returned since no further execution progress is possible.

For safety, we will error when the number of execution iterations reaches a configurable maximum (default 128, override with VORTEX_MAX_ITERATIONS).

Source §

impl dyn DynArray + '_

Source

pub fn apply(&self, expr: &Expression) -> VortexResult<ArrayRef>

Apply the expression to this array, producing a new array in constant time.

Source §

impl dyn DynArray + '_

Source

pub fn to_array_iterator(&self) -> impl ArrayIterator + 'static

Create an ArrayIterator over the array.

Source §

impl dyn DynArray + '_

Source

pub fn normalize( self: ArrayRef, options: &mut NormalizeOptions<'_>, ) -> VortexResult<ArrayRef>

Normalize the array according to given options.

This operation performs a recursive traversal of the array. Any non-allowed encoding is normalized per the configured operation.

Source §

impl dyn DynArray + '_

Source

pub fn serialize( &self, ctx: &ArrayContext, options: &SerializeOptions, ) -> VortexResult<Vec<ByteBuffer>>

Serialize the array into a sequence of byte buffers that should be written contiguously. This function returns a vec to avoid copying data buffers.

Optionally, padding can be included to guarantee buffer alignment and ensure zero-copy reads within the context of an external file or stream. In this case, the alignment of the first byte buffer should be respected when writing the buffers to the stream or file.

The format of this blob is a sequence of data buffers, possible with prefixed padding, followed by a flatbuffer containing an fba::Array message, and ending with a little-endian u32 describing the length of the flatbuffer message.

Source §

impl dyn DynArray + '_

Source

pub fn to_array_stream(&self) -> impl ArrayStream + 'static

Create an ArrayStream over the array.

Source §

impl dyn DynArray + '_

Source

pub fn as_null_typed(&self) -> NullTyped<'_>

Downcasts the array for null-specific behavior.

Source

pub fn as_bool_typed(&self) -> BoolTyped<'_>

Downcasts the array for bool-specific behavior.

Source

pub fn as_primitive_typed(&self) -> PrimitiveTyped<'_>

Downcasts the array for primitive-specific behavior.

Source

pub fn as_decimal_typed(&self) -> DecimalTyped<'_>

Downcasts the array for decimal-specific behavior.

Source

pub fn as_utf8_typed(&self) -> Utf8Typed<'_>

Downcasts the array for utf8-specific behavior.

Source

pub fn as_binary_typed(&self) -> BinaryTyped<'_>

Downcasts the array for binary-specific behavior.

Source

pub fn as_struct_typed(&self) -> StructTyped<'_>

Downcasts the array for struct-specific behavior.

Source

pub fn as_list_typed(&self) -> ListTyped<'_>

Downcasts the array for list-specific behavior.

Source

pub fn as_extension_typed(&self) -> ExtensionTyped<'_>

Downcasts the array for extension-specific behavior.

Source