Enum datafusion_common::scalar::ScalarValue

pub enum ScalarValue {
    Null,
    Boolean(Option<bool>),
    Float32(Option<f32>),
    Float64(Option<f64>),
    Decimal128(Option<i128>, usize, usize),
    Int8(Option<i8>),
    Int16(Option<i16>),
    Int32(Option<i32>),
    Int64(Option<i64>),
    UInt8(Option<u8>),
    UInt16(Option<u16>),
    UInt32(Option<u32>),
    UInt64(Option<u64>),
    Utf8(Option<String>),
    LargeUtf8(Option<String>),
    Binary(Option<Vec<u8>>),
    LargeBinary(Option<Vec<u8>>),
    List(Option<Vec<ScalarValue>>, Box<Field>),
    Date32(Option<i32>),
    Date64(Option<i64>),
    Time64(Option<i64>),
    TimestampSecond(Option<i64>, Option<String>),
    TimestampMillisecond(Option<i64>, Option<String>),
    TimestampMicrosecond(Option<i64>, Option<String>),
    TimestampNanosecond(Option<i64>, Option<String>),
    IntervalYearMonth(Option<i32>),
    IntervalDayTime(Option<i64>),
    IntervalMonthDayNano(Option<i128>),
    Struct(Option<Vec<ScalarValue>>, Box<Vec<Field>>),
    Dictionary(Box<DataType>, Box<ScalarValue>),
}

Represents a dynamically typed, nullable single value. This is the single-valued counter-part of arrow’s Array. https://arrow.apache.org/docs/python/api/datatypes.html https://github.com/apache/arrow/blob/master/format/Schema.fbs#L354-L375

Variants

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>, usize, usize)

128bit decimal, using the i128 to represent the decimal

Int8(Option<i8>)

signed 8bit int

Int16(Option<i16>)

signed 16bit int

Int32(Option<i32>)

signed 32bit int

Int64(Option<i64>)

signed 64bit int

UInt8(Option<u8>)

unsigned 8bit int

UInt16(Option<u16>)

unsigned 16bit int

UInt32(Option<u32>)

unsigned 32bit int

UInt64(Option<u64>)

unsigned 64bit int

Utf8(Option<String>)

utf-8 encoded string.

LargeUtf8(Option<String>)

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

Binary(Option<Vec<u8>>)

binary

LargeBinary(Option<Vec<u8>>)

large binary

List(Option<Vec<ScalarValue>>, Box<Field>)

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

Time64(Option<i64>)

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

TimestampSecond(Option<i64>, Option<String>)

Timestamp Second

TimestampMillisecond(Option<i64>, Option<String>)

Timestamp Milliseconds

TimestampMicrosecond(Option<i64>, Option<String>)

Timestamp Microseconds

TimestampNanosecond(Option<i64>, Option<String>)

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).

Struct(Option<Vec<ScalarValue>>, Box<Vec<Field>>)

struct of nested ScalarValue

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

Dictionary type: index type and value

Implementations

impl ScalarValue

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

Create a decimal Scalar from value/precision and scale.

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 get_datatype(&self) -> DataType

Getter for the DataType of the value

pub fn arithmetic_negate(&self) -> Self

Calculate arithmetic negation for a scalar value

pub fn is_null(&self) -> bool

whether this value is null or not.

pub fn to_array(&self) -> ArrayRef

Converts a scalar value into an 1-row array.

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: &ArrayRef, 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.

Trait Implementations

impl Clone for ScalarValue

fn clone(&self) -> ScalarValue

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ScalarValue

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

Formats the value using the given formatter.

impl Display for ScalarValue

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

Formats the value using the given formatter.

impl From<&str> for ScalarValue

fn from(value: &str) -> Self

Converts to this type from the input type.

impl From<Option<&str>> for ScalarValue

fn from(value: Option<&str>) -> Self

Converts to this type from the input type.

impl From<Option<bool>> for ScalarValue

fn from(value: Option<bool>) -> Self

Converts to this type from the input type.

impl From<Option<f32>> for ScalarValue

fn from(value: Option<f32>) -> Self

Converts to this type from the input type.

impl From<Option<f64>> for ScalarValue

fn from(value: Option<f64>) -> Self

Converts to this type from the input type.

impl From<Option<i16>> for ScalarValue

fn from(value: Option<i16>) -> Self

Converts to this type from the input type.

impl From<Option<i32>> for ScalarValue

fn from(value: Option<i32>) -> Self

Converts to this type from the input type.

impl From<Option<i64>> for ScalarValue

fn from(value: Option<i64>) -> Self

Converts to this type from the input type.

impl From<Option<i8>> for ScalarValue

fn from(value: Option<i8>) -> Self

Converts to this type from the input type.

impl From<Option<u16>> for ScalarValue

fn from(value: Option<u16>) -> Self

Converts to this type from the input type.

impl From<Option<u32>> for ScalarValue

fn from(value: Option<u32>) -> Self

Converts to this type from the input type.

impl From<Option<u64>> for ScalarValue

fn from(value: Option<u64>) -> Self

Converts to this type from the input type.

impl From<Option<u8>> for ScalarValue

fn from(value: Option<u8>) -> Self

Converts to this type from the input type.

impl From<Vec<(&str, ScalarValue), Global>> for ScalarValue

fn from(value: Vec<(&str, ScalarValue)>) -> Self

Converts to this type from the input type.

impl From<bool> for ScalarValue

fn from(value: bool) -> Self

Converts to this type from the input type.

impl From<f32> for ScalarValue

fn from(value: f32) -> Self

Converts to this type from the input type.

impl From<f64> for ScalarValue

fn from(value: f64) -> Self

Converts to this type from the input type.

impl From<i16> for ScalarValue

fn from(value: i16) -> Self

Converts to this type from the input type.

impl From<i32> for ScalarValue

fn from(value: i32) -> Self

Converts to this type from the input type.

impl From<i64> for ScalarValue

fn from(value: i64) -> Self

Converts to this type from the input type.

impl From<i8> for ScalarValue

fn from(value: i8) -> Self

Converts to this type from the input type.

impl From<u16> for ScalarValue

fn from(value: u16) -> Self

Converts to this type from the input type.

impl From<u32> for ScalarValue

fn from(value: u32) -> Self

Converts to this type from the input type.

impl From<u64> for ScalarValue

fn from(value: u64) -> Self

Converts to this type from the input type.

impl From<u8> for ScalarValue

fn from(value: u8) -> Self

Converts to this type from the input type.

impl FromStr for ScalarValue

type Err = Infallible

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for ScalarValue

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl PartialEq<ScalarValue> for ScalarValue

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<ScalarValue> for ScalarValue

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl TryFrom<&DataType> for ScalarValue

fn try_from(datatype: &DataType) -> Result<Self>

Create a Null instance of ScalarValue for this datatype

type Error = DataFusionError

The type returned in the event of a conversion error.

impl TryFrom<ScalarValue> for bool

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for f32

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for f64

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for i128

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for i16

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for i32

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for i64

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for i8

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for u16

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for u32

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for u64

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for u8

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl Eq for ScalarValue