Enum datafusion_common::scalar::ScalarValue

Null

represents DataType::Null (castable to/from any other type)

Boolean(Option<bool>)

true or false value

Float32(Option<f32>)

32bit float

Float64(Option<f64>)

64bit float

Decimal128(Option<i128>, u8, i8)

128bit decimal, using the i128 to represent the decimal, precision scale

Decimal256(Option<i256>, u8, i8)

256bit decimal, using the i256 to represent the decimal, precision scale

UInt8(Option<u8>)

unsigned 8bit int

UInt16(Option<u16>)

unsigned 16bit int

UInt32(Option<u32>)

unsigned 32bit int

UInt64(Option<u64>)

unsigned 64bit int

LargeUtf8(Option<String>)

utf-8 encoded string representing a LargeString’s arrow type.

Binary(Option<Vec<u8>>)

binary

FixedSizeBinary(i32, Option<Vec<u8>>)

fixed size binary

LargeBinary(Option<Vec<u8>>)

large binary

Fixedsizelist(Option<Vec<ScalarValue>>, FieldRef, i32)

Fixed size list of nested ScalarValue

List(Option<Vec<ScalarValue>>, FieldRef)

List of nested ScalarValue

Date32(Option<i32>)

Date stored as a signed 32bit int days since UNIX epoch 1970-01-01

Date64(Option<i64>)

Date stored as a signed 64bit int milliseconds since UNIX epoch 1970-01-01

Time32Second(Option<i32>)

Time stored as a signed 32bit int as seconds since midnight

Time32Millisecond(Option<i32>)

Time stored as a signed 32bit int as milliseconds since midnight

Time64Microsecond(Option<i64>)

Time stored as a signed 64bit int as microseconds since midnight

Time64Nanosecond(Option<i64>)

Time stored as a signed 64bit int as nanoseconds since midnight

TimestampSecond(Option<i64>, Option<Arc<str>>)

Timestamp Second

TimestampMillisecond(Option<i64>, Option<Arc<str>>)

Timestamp Milliseconds

TimestampMicrosecond(Option<i64>, Option<Arc<str>>)

Timestamp Microseconds

TimestampNanosecond(Option<i64>, Option<Arc<str>>)

Timestamp Nanoseconds

IntervalYearMonth(Option<i32>)

Number of elapsed whole months

IntervalDayTime(Option<i64>)

Number of elapsed days and milliseconds (no leap seconds) stored as 2 contiguous 32-bit signed integers

IntervalMonthDayNano(Option<i128>)

A triple of the number of elapsed months, days, and nanoseconds. Months and days are encoded as 32-bit signed integers. Nanoseconds is encoded as a 64-bit signed integer (no leap seconds).

DurationSecond(Option<i64>)

Duration in seconds

DurationMillisecond(Option<i64>)

Duration in milliseconds

DurationMicrosecond(Option<i64>)

Duration in microseconds

DurationNanosecond(Option<i64>)

Duration in nanoseconds

Struct(Option<Vec<ScalarValue>>, Fields)

struct of nested ScalarValue

Dictionary(Box<DataType>, Box<ScalarValue>)

Dictionary type: index type and value

Implementations§

impl ScalarValue

pub fn new_primitive<T: ArrowPrimitiveType>( a: Option<T::Native>, d: &DataType ) -> Self

Create a ScalarValue with the provided value and datatype

Panics

Panics if d is not compatible with T

pub fn try_new_decimal128(value: i128, precision: u8, scale: i8) -> Result<Self>

Create a decimal Scalar from value/precision and scale.

pub fn new_utf8(val: impl Into<String>) -> Self

Returns a ScalarValue::Utf8 representing val

pub fn new_interval_ym(years: i32, months: i32) -> Self

Returns a ScalarValue::IntervalYearMonth representing years years and months months

pub fn new_interval_dt(days: i32, millis: i32) -> Self

Returns a ScalarValue::IntervalDayTime representing days days and millis milliseconds

pub fn new_interval_mdn(months: i32, days: i32, nanos: i64) -> Self

Returns a ScalarValue::IntervalMonthDayNano representing months months and days days, and nanos nanoseconds

pub fn new_list(scalars: Option<Vec<Self>>, child_type: DataType) -> Self

Create a new nullable ScalarValue::List with the specified child_type

pub fn new_zero(datatype: &DataType) -> Result<ScalarValue>

Create a zero value in the given type.

pub fn new_one(datatype: &DataType) -> Result<ScalarValue>

Create an one value in the given type.

pub fn new_negative_one(datatype: &DataType) -> Result<ScalarValue>

Create a negative one value in the given type.

pub fn new_ten(datatype: &DataType) -> Result<ScalarValue>

pub fn data_type(&self) -> DataType

return the [DataType] of this ScalarValue

pub fn get_datatype(&self) -> DataType

Getter for the DataType of the value.

Suggest using Self::data_type as a more standard API

pub fn arithmetic_negate(&self) -> Result<Self>

Calculate arithmetic negation for a scalar value

pub fn add<T: Borrow<ScalarValue>>(&self, other: T) -> Result<ScalarValue>

Wrapping addition of ScalarValue

NB: operating on ScalarValue directly is not efficient, performance sensitive code should operate on Arrays directly, using vectorized array kernels

pub fn add_checked<T: Borrow<ScalarValue>>( &self, other: T ) -> Result<ScalarValue>

Checked addition of ScalarValue

NB: operating on ScalarValue directly is not efficient, performance sensitive code should operate on Arrays directly, using vectorized array kernels

pub fn sub<T: Borrow<ScalarValue>>(&self, other: T) -> Result<ScalarValue>

Wrapping subtraction of ScalarValue

NB: operating on ScalarValue directly is not efficient, performance sensitive code should operate on Arrays directly, using vectorized array kernels

pub fn sub_checked<T: Borrow<ScalarValue>>( &self, other: T ) -> Result<ScalarValue>

Checked subtraction of ScalarValue

NB: operating on ScalarValue directly is not efficient, performance sensitive code should operate on Arrays directly, using vectorized array kernels

pub fn is_unsigned(&self) -> bool

pub fn is_null(&self) -> bool

whether this value is null or not.

pub fn distance(&self, other: &ScalarValue) -> Option<usize>

Absolute distance between two numeric values (of the same type). This method will return None if either one of the arguments are null. It might also return None if the resulting distance is greater than usize::MAX. If the type is a float, then the distance will be rounded to the nearest integer.

Note: the datatype itself must support subtraction.

pub fn to_array(&self) -> ArrayRef

Converts a scalar value into an 1-row array.

pub fn to_scalar(&self) -> Scalar<ArrayRef>

Converts a scalar into an arrow Scalar (which implements the Datum interface).

This can be used to call arrow compute kernels such as lt

Example

use datafusion_common::ScalarValue;
use arrow::array::{BooleanArray, Int32Array};

let arr = Int32Array::from(vec![Some(1), None, Some(10)]);
let five = ScalarValue::Int32(Some(5));

let result = arrow::compute::kernels::cmp::lt(
  &arr,
  &five.to_scalar(),
).unwrap();

let expected = BooleanArray::from(vec![
    Some(true),
    None,
    Some(false)
  ]
);

assert_eq!(&result, &expected);

pub fn iter_to_array( scalars: impl IntoIterator<Item = ScalarValue> ) -> Result<ArrayRef>

Converts an iterator of references ScalarValue into an ArrayRef corresponding to those values. For example,

Returns an error if the iterator is empty or if the ScalarValues are not all the same type

Example

use datafusion_common::ScalarValue;
use arrow::array::{ArrayRef, BooleanArray};

let scalars = vec![
  ScalarValue::Boolean(Some(true)),
  ScalarValue::Boolean(None),
  ScalarValue::Boolean(Some(false)),
];

// Build an Array from the list of ScalarValues
let array = ScalarValue::iter_to_array(scalars.into_iter())
  .unwrap();

let expected: ArrayRef = std::sync::Arc::new(
  BooleanArray::from(vec![
    Some(true),
    None,
    Some(false)
  ]
));

assert_eq!(&array, &expected);

pub fn to_array_of_size(&self, size: usize) -> ArrayRef

Converts a scalar value into an array of size rows.

pub fn try_from_array(array: &dyn Array, index: usize) -> Result<Self>

Converts a value in array at index into a ScalarValue

pub fn try_from_string(value: String, target_type: &DataType) -> Result<Self>

Try to parse value into a ScalarValue of type target_type

pub fn eq_array(&self, array: &ArrayRef, index: usize) -> bool

Compares a single row of array @ index for equality with self, in an optimized fashion.

This method implements an optimized version of:

    let arr_scalar = Self::try_from_array(array, index).unwrap();
    arr_scalar.eq(self)

Performance note: the arrow compute kernels should be preferred over this function if at all possible as they can be vectorized and are generally much faster.

This function has a few narrow usescases such as hash table key comparisons where comparing a single row at a time is necessary.

pub fn size(&self) -> usize

Estimate size if bytes including Self. For values with internal containers such as String includes the allocated size (capacity) rather than the current length (len)

pub fn size_of_vec(vec: &Vec<Self>) -> usize

Estimates size of Vec in bytes.

Includes the size of the Vec container itself.

pub fn size_of_hashset<S>(set: &HashSet<Self, S>) -> usize

Estimates size of HashSet in bytes.

Includes the size of the HashSet container itself.

Trait Implementations§

impl Clone for ScalarValue

fn clone(&self) -> ScalarValue

Returns a copy of the value. Read more

1.0.0 · source§

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

Performs copy-assignment from source. Read more

impl Debug for ScalarValue

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

Formats the value using the given formatter. Read more

impl Display for ScalarValue

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

Formats the value using the given formatter. Read more