Enum polars_lazy::dsl::Expr

pub enum Expr {
    Alias(Box<Expr>, Arc<String>),
    Column(Arc<String>),
    Columns(Vec<String>),
    DtypeColumn(Vec<DataType>),
    Literal(LiteralValue),
    BinaryExpr {
        left: Box<Expr>,
        op: Operator,
        right: Box<Expr>,
    },
    Not(Box<Expr>),
    IsNotNull(Box<Expr>),
    IsNull(Box<Expr>),
    Cast {
        expr: Box<Expr>,
        data_type: DataType,
        strict: bool,
    },
    Sort {
        expr: Box<Expr>,
        reverse: bool,
    },
    Take {
        expr: Box<Expr>,
        idx: Box<Expr>,
    },
    SortBy {
        expr: Box<Expr>,
        by: Box<Expr>,
        reverse: bool,
    },
    Agg(AggExpr),
    Ternary {
        predicate: Box<Expr>,
        truthy: Box<Expr>,
        falsy: Box<Expr>,
    },
    Function {
        input: Vec<Expr>,
        function: NoEq<Arc<dyn SeriesUdf>>,
        output_type: GetOutput,
        options: FunctionOptions,
    },
    Shift {
        input: Box<Expr>,
        periods: i64,
    },
    Reverse(Box<Expr>),
    Duplicated(Box<Expr>),
    IsUnique(Box<Expr>),
    Explode(Box<Expr>),
    Filter {
        input: Box<Expr>,
        by: Box<Expr>,
    },
    Window {
        function: Box<Expr>,
        partition_by: Vec<Expr>,
        order_by: Option<Box<Expr>>,
        options: WindowOptions,
    },
    Wildcard,
    Slice {
        input: Box<Expr>,
        offset: i64,
        length: usize,
    },
    BinaryFunction {
        input_a: Box<Expr>,
        input_b: Box<Expr>,
        function: NoEq<Arc<dyn SeriesBinaryUdf>>,
        output_field: NoEq<Arc<dyn BinaryUdfOutputField>>,
    },
    Exclude(Box<Expr>, Vec<Arc<String>>),
    KeepName(Box<Expr>),
    SufPreFix {
        is_suffix: bool,
        value: String,
        expr: Box<Expr>,
    },
}

This is supported on crate feature compile only.

Queries consists of multiple expressions.

Variants

Alias(Box<Expr>, Arc<String>)

Tuple Fields of Alias

0: Box<Expr>1: Arc<String>

Column(Arc<String>)

Tuple Fields of Column

0: Arc<String>

Columns(Vec<String>)

Tuple Fields of Columns

0: Vec<String>

DtypeColumn(Vec<DataType>)

Tuple Fields of DtypeColumn

0: Vec<DataType>

Literal(LiteralValue)

Tuple Fields of Literal

0: LiteralValue

BinaryExpr

Fields of BinaryExpr

left: Box<Expr>op: Operatorright: Box<Expr>

Not(Box<Expr>)

Tuple Fields of Not

0: Box<Expr>

IsNotNull(Box<Expr>)

Tuple Fields of IsNotNull

0: Box<Expr>

IsNull(Box<Expr>)

Tuple Fields of IsNull

0: Box<Expr>

Cast

Fields of Cast

expr: Box<Expr>data_type: DataTypestrict: bool

Sort

Fields of Sort

expr: Box<Expr>reverse: bool

Take

Fields of Take

expr: Box<Expr>idx: Box<Expr>

SortBy

Fields of SortBy

expr: Box<Expr>by: Box<Expr>reverse: bool

Agg(AggExpr)

Tuple Fields of Agg

0: AggExpr

Ternary

A ternary operation if true then “foo” else “bar”

Fields of Ternary

predicate: Box<Expr>truthy: Box<Expr>falsy: Box<Expr>

Function

Fields of Function

input: Vec<Expr>

function arguments

function: NoEq<Arc<dyn SeriesUdf>>

function to apply

output_type: GetOutput

output dtype of the function

options: FunctionOptions

Shift

Fields of Shift

input: Box<Expr>periods: i64

Reverse(Box<Expr>)

Tuple Fields of Reverse

0: Box<Expr>

Duplicated(Box<Expr>)

Tuple Fields of Duplicated

0: Box<Expr>

IsUnique(Box<Expr>)

Tuple Fields of IsUnique

0: Box<Expr>

Explode(Box<Expr>)

Tuple Fields of Explode

0: Box<Expr>

Filter

Fields of Filter

input: Box<Expr>by: Box<Expr>

Window

See postgres window functions

Fields of Window

function: Box<Expr>

Also has the input. i.e. avg(“foo”)

partition_by: Vec<Expr>order_by: Option<Box<Expr>>options: WindowOptions

Wildcard

Slice

Fields of Slice

input: Box<Expr>offset: i64

length is not yet known so we accept negative offsets

length: usize

BinaryFunction

Fields of BinaryFunction

input_a: Box<Expr>input_b: Box<Expr>function: NoEq<Arc<dyn SeriesBinaryUdf>>output_field: NoEq<Arc<dyn BinaryUdfOutputField>>

Delays output type evaluation until input schema is known.

Exclude(Box<Expr>, Vec<Arc<String>>)

Can be used in a select statement to exclude a column from selection

Tuple Fields of Exclude

0: Box<Expr>1: Vec<Arc<String>>

KeepName(Box<Expr>)

Set root name as Alias

Tuple Fields of KeepName

0: Box<Expr>

SufPreFix

Fields of SufPreFix

is_suffix: boolvalue: Stringexpr: Box<Expr>

Implementations

impl Expr

pub fn eq(self, other: Expr) -> Expr

Compare Expr with other Expr on equality

pub fn neq(self, other: Expr) -> Expr

Compare Expr with other Expr on non-equality

pub fn lt(self, other: Expr) -> Expr

Check if Expr < Expr

pub fn gt(self, other: Expr) -> Expr

Check if Expr > Expr

pub fn gt_eq(self, other: Expr) -> Expr

Check if Expr >= Expr

pub fn lt_eq(self, other: Expr) -> Expr

Check if Expr <= Expr

pub fn not(self) -> Expr

Negate Expr

pub fn alias(self, name: &str) -> Expr

Rename Column.

pub fn is_null(self) -> Self

Run is_null operation on Expr.

pub fn is_not_null(self) -> Self

Run is_not_null operation on Expr.

pub fn min(self) -> Self

Reduce groups to minimal value.

pub fn max(self) -> Self

Reduce groups to maximum value.

pub fn mean(self) -> Self

Reduce groups to the mean value.

pub fn median(self) -> Self

Reduce groups to the median value.

pub fn sum(self) -> Self

Reduce groups to the sum of all the values.

pub fn n_unique(self) -> Self

Get the number of unique values in the groups.

pub fn first(self) -> Self

Get the first value in the group.

pub fn last(self) -> Self

Get the last value in the group.

pub fn list(self) -> Self

Aggregate the group to a Series

pub fn quantile(self, quantile: f64) -> Self

Compute the quantile per group.

pub fn agg_groups(self) -> Self

Get the group indexes of the group by operation.

pub fn flatten(self) -> Self

Alias for explode

pub fn explode(self) -> Self

Explode the utf8/ list column

pub fn slice(self, offset: i64, length: usize) -> Self

Slice the Series.

pub fn head(self, length: Option<usize>) -> Self

Get the first n elements of the Expr result

pub fn tail(self, length: Option<usize>) -> Self

Get the last n elements of the Expr result

pub fn unique(self) -> Self

Get unique values of this expression.

pub fn arg_unique(self) -> Self

Get the first index of unique values of this expression.

pub fn arg_sort(self, reverse: bool) -> Self

Get the index values that would sort this expression.

pub fn strict_cast(self, data_type: DataType) -> Self

Cast expression to another data type. Throws an error if conversion had overflows

pub fn cast(self, data_type: DataType) -> Self

Cast expression to another data type.

pub fn take(self, idx: Expr) -> Self

Take the values by idx.

pub fn sort(self, reverse: bool) -> Self

Sort in increasing order. See the eager implementation.

Can be used in default and aggregation context.

pub fn reverse(self) -> Self

Reverse column

pub fn map<F>(self, function: F, output_type: GetOutput) -> Self where
    F: Fn(Series) -> Result<Series> + 'static + Send + Sync, 

Apply a function/closure once the logical plan get executed.

This function is very similar to apply, but differs in how it handles aggregations.

• map should be used for operations that are independent of groups, e.g. multiply * 2, or raise to the power
• apply should be used for operations that work on a group of data. e.g. sum, count, etc.

It is the responsibility of the caller that the schema is correct by giving the correct output_type. If None given the output type of the input expr is used.

pub fn map_list<F>(self, function: F, output_type: GetOutput) -> Self where
    F: Fn(Series) -> Result<Series> + 'static + Send + Sync, 

Apply a function/closure once the logical plan get executed.

This function is very similar to apply, but differs in how it handles aggregations.

• map should be used for operations that are independent of groups, e.g. multiply * 2, or raise to the power
• apply should be used for operations that work on a group of data. e.g. sum, count, etc.
• map_list should be used when the function expects a list aggregated series.

pub fn apply<F>(self, function: F, output_type: GetOutput) -> Self where
    F: Fn(Series) -> Result<Series> + 'static + Send + Sync, 

Apply a function/closure over the groups. This should only be used in a groupby aggregation.

It is the responsibility of the caller that the schema is correct by giving the correct output_type. If None given the output type of the input expr is used.

This difference with map is that apply will create a separate Series per group.

• map should be used for operations that are independent of groups, e.g. multiply * 2, or raise to the power
• apply should be used for operations that work on a group of data. e.g. sum, count, etc.

pub fn is_finite(self) -> Self

Get mask of finite values if dtype is Float

pub fn is_infinite(self) -> Self

Get mask of infinite values if dtype is Float

pub fn is_nan(self) -> Self

Get mask of NaN values if dtype is Float

pub fn is_not_nan(self) -> Self

Get inverse mask of NaN values if dtype is Float

pub fn shift(self, periods: i64) -> Self

Shift the values in the array by some period. See the eager implementation.

pub fn shift_and_fill(self, periods: i64, fill_value: Expr) -> Self

Shift the values in the array by some period and fill the resulting empty values.

pub fn cumsum(self, reverse: bool) -> Self

This is supported on crate feature cum_agg only.

Get an array with the cumulative sum computed at every element

pub fn cumprod(self, reverse: bool) -> Self

This is supported on crate feature cum_agg only.

Get an array with the cumulative product computed at every element

pub fn cummin(self, reverse: bool) -> Self

This is supported on crate feature cum_agg only.

Get an array with the cumulative min computed at every element

pub fn cummax(self, reverse: bool) -> Self

This is supported on crate feature cum_agg only.

Get an array with the cumulative max computed at every element

pub fn backward_fill(self) -> Self

Fill missing value with next non-null.

pub fn forward_fill(self) -> Self

Fill missing value with previous non-null.

pub fn round(self, decimals: u32) -> Self

This is supported on crate feature round_series only.

Round underlying floating point array to given decimal numbers.

pub fn floor(self) -> Self

This is supported on crate feature round_series only.

Floor underlying floating point array to the lowest integers smaller or equal to the float value.

pub fn over<E: AsRef<[Expr]>>(self, partition_by: E) -> Self

Apply window function over a subgroup. This is similar to a groupby + aggregation + self join. Or similar to window functions in Postgres.

Example

#[macro_use] extern crate polars_core;
use polars_core::prelude::*;
use polars_lazy::prelude::*;

fn example() -> Result<()> {
    let df = df! {
            "groups" => &[1, 1, 2, 2, 1, 2, 3, 3, 1],
            "values" => &[1, 2, 3, 4, 5, 6, 7, 8, 8]
        }?;

    let out = df
     .lazy()
     .select(&[
         col("groups"),
         sum("values").over([col("groups")]),
     ])
     .collect()?;
    dbg!(&out);
    Ok(())
}

Outputs:

╭────────┬────────╮
│ groups ┆ values │
│ ---    ┆ ---    │
│ i32    ┆ i32    │
╞════════╪════════╡
│ 1      ┆ 16     │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│ 1      ┆ 16     │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│ 2      ┆ 13     │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│ 2      ┆ 13     │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│ ...    ┆ ...    │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│ 1      ┆ 16     │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│ 2      ┆ 13     │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│ 3      ┆ 15     │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│ 3      ┆ 15     │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
│ 1      ┆ 16     │
╰────────┴────────╯

pub fn fill_null(self, fill_value: Expr) -> Self

Replace the null values by a value.

pub fn fill_nan(self, fill_value: Expr) -> Self

Replace the floating point NaN values by a value.

pub fn count(self) -> Self

Count the values of the Series or Get counts of the group by operation.

pub fn std(self) -> Self

Standard deviation of the values of the Series

pub fn var(self) -> Self

Variance of the values of the Series

pub fn is_duplicated(self) -> Self

Get a mask of duplicated values

pub fn is_unique(self) -> Self

Get a mask of unique values

pub fn and(self, expr: Expr) -> Self

and operation

pub fn xor(self, expr: Expr) -> Self

pub fn or(self, expr: Expr) -> Self

or operation

pub fn pow(self, exponent: f64) -> Self

Raise expression to the power exponent

pub fn filter(self, predicate: Expr) -> Self

Filter a single column Should be used in aggregation context. If you want to filter on a DataFrame level, use LazyFrame::filter

pub fn is_in(self, other: Expr) -> Self

This is supported on crate feature is_in only.

Check if the values of the left expression are in the lists of the right expr.

pub fn year(self) -> Expr

This is supported on crate feature temporal only.

Get the year of a Date/Datetime

pub fn month(self) -> Expr

This is supported on crate feature temporal only.

Get the month of a Date/Datetime

pub fn week(self) -> Expr

This is supported on crate feature temporal only.

Extract the week from the underlying Date representation. Can be performed on Date and Datetime Returns the ISO week number starting from 1. The return value ranges from 1 to 53. (The last week of year differs by years.)

pub fn weekday(self) -> Expr

This is supported on crate feature temporal only.

Extract the week day from the underlying Date representation. Can be performed on Date and Datetime. Returns the weekday number where monday = 0 and sunday = 6

pub fn day(self) -> Expr

This is supported on crate feature temporal only.

Get the month of a Date/Datetime

pub fn ordinal_day(self) -> Expr

This is supported on crate feature temporal only.

Get the ordinal_day of a Date/Datetime

pub fn hour(self) -> Expr

This is supported on crate feature temporal only.

Get the hour of a Datetime/Time64

pub fn minute(self) -> Expr

This is supported on crate feature temporal only.

Get the minute of a Datetime/Time64

pub fn second(self) -> Expr

This is supported on crate feature temporal only.

Get the second of a Datetime/Time64

pub fn nanosecond(self) -> Expr

This is supported on crate feature temporal only.

Get the nanosecond of a Time64

pub fn sort_by(self, by: Expr, reverse: bool) -> Expr

Sort this column by the ordering of another column. Can also be used in a groupby context to sort the groups.

pub fn repeat_by(self, by: Expr) -> Expr

This is supported on crate feature repeat_by only.

pub fn is_first(self) -> Expr

This is supported on crate feature is_first only.

Get a mask of the first unique value.

pub fn dot(self, other: Expr) -> Expr

This is supported on crate feature dot_product only.

pub fn mode(self) -> Expr

This is supported on crate feature mode only.

Compute the mode(s) of this column. This is the most occurring value.

pub fn keep_name(self) -> Expr

Keep the original root name

use polars_core::prelude::*;
use polars_lazy::prelude::*;

fn example(df: LazyFrame) -> LazyFrame {
    df.select([
// even thought the alias yields a different column name,
// `keep_name` will make sure that the original column name is used
        col("*").alias("foo").keep_name()
])
}

pub fn suffix(self, suffix: &str) -> Expr

Add a suffix to the root column name.

pub fn prefix(self, prefix: &str) -> Expr

Add a prefix to the root column name.

pub fn exclude<'a, S, J>(self, columns: S) -> Expr where
    S: Selection<'a, J>, 

Exclude a column from a wildcard/regex selection.

You may also use regexes in the exclude as long as they start with ^ and end with $/

Example

use polars_core::prelude::*;
use polars_lazy::prelude::*;

// Select all columns except foo.
fn example(df: DataFrame) -> LazyFrame {
      df.lazy()
        .select(&[
                col("*").exclude(&["foo"])
                ])
}

pub fn interpolate(self) -> Expr

This is supported on crate feature interpolate only.

pub fn rolling_min(self, options: RollingOptions) -> Expr

This is supported on crate feature rolling_window only.

Apply a rolling min See: ChunkedArray::rolling_min.

pub fn rolling_max(self, options: RollingOptions) -> Expr

This is supported on crate feature rolling_window only.

Apply a rolling max See: ChunkedArray::rolling_max.

pub fn rolling_mean(self, options: RollingOptions) -> Expr

This is supported on crate feature rolling_window only.

Apply a rolling mean See: ChunkedArray::rolling_mean.

pub fn rolling_sum(self, options: RollingOptions) -> Expr

This is supported on crate feature rolling_window only.

Apply a rolling sum See: ChunkedArray::rolling_sum.

pub fn rolling_var(self, options: RollingOptions) -> Expr

This is supported on crate feature rolling_window only.

Apply a rolling variance

pub fn rolling_std(self, options: RollingOptions) -> Expr

This is supported on crate feature rolling_window only.

Apply a rolling std-dev

pub fn rolling_apply(
    self,
    window_size: usize,
    f: Arc<dyn Fn(&Series) -> Series + Send + Sync>,
    output_type: GetOutput
) -> Expr

This is supported on crate feature rolling_window only.

Apply a custom function over a rolling/ moving window of the array. This has quite some dynamic dispatch, so prefer rolling_min, max, mean, sum over this.

pub fn rolling_apply_float<F>(self, window_size: usize, f: F) -> Expr where
    F: 'static + Fn(&Float64Chunked) -> Option<f64> + Send + Sync + Copy, 

This is supported on crate feature rolling_window only.

Apply a custom function over a rolling/ moving window of the array. Prefer this over rolling_apply in case of floating point numbers as this is faster. This has quite some dynamic dispatch, so prefer rolling_min, max, mean, sum over this.

pub fn rank(self, method: RankMethod) -> Expr

This is supported on crate feature rank only.

pub fn diff(self, n: usize, null_behavior: NullBehavior) -> Expr

This is supported on crate feature diff only.

pub fn skew(self, bias: bool) -> Expr

This is supported on crate feature moment only.

pub fn kurtosis(self, fisher: bool, bias: bool) -> Expr

This is supported on crate feature moment only.

pub fn str_concat(self, delimiter: &str) -> Expr

This is supported on crate feature concat_str only.

Concat the values into a string array.

Arguments

• delimiter - A string that will act as delimiter between values.

Trait Implementations

impl Add<Expr> for Expr

type Output = Expr

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self::Output

Performs the + operation.

impl AsRef<Expr> for AggExpr

fn as_ref(&self) -> &Expr

Performs the conversion.

impl Clone for Expr

fn clone(&self) -> Expr

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Expr

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

Formats the value using the given formatter.

impl Div<Expr> for Expr

type Output = Expr

The resulting type after applying the / operator.

fn div(self, rhs: Self) -> Self::Output

Performs the / operation.

impl From<AggExpr> for Expr

fn from(agg: AggExpr) -> Self

Performs the conversion.

impl<'a> IntoIterator for &'a Expr

type Item = &'a Expr

The type of the elements being iterated over.

type IntoIter = ExprIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl Mul<Expr> for Expr

type Output = Expr

The resulting type after applying the * operator.

fn mul(self, rhs: Self) -> Self::Output

Performs the * operation.

impl PartialEq<Expr> for Expr

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

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

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

This method tests for !=.

impl Rem<Expr> for Expr

type Output = Expr

The resulting type after applying the % operator.

fn rem(self, rhs: Self) -> Self::Output

Performs the % operation.

impl Sub<Expr> for Expr

type Output = Expr

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self::Output

Performs the - operation.

impl StructuralPartialEq for Expr