Enum polars::prelude::Expr

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

Queries consists of multiple expressions.

Variants

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

Tuple Fields of Alias

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

Column(Arc<String>)

Tuple Fields of Column

0: Arc<String>

Columns(Vec<String, Global>)

Tuple Fields of Columns

0: Vec<String, Global>

DtypeColumn(Vec<DataType, Global>)

Tuple Fields of DtypeColumn

0: Vec<DataType, Global>

Literal(LiteralValue)

Tuple Fields of Literal

0: LiteralValue

BinaryExpr

Fields of BinaryExpr

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

Not(Box<Expr, Global>)

Tuple Fields of Not

0: Box<Expr, Global>

IsNotNull(Box<Expr, Global>)

Tuple Fields of IsNotNull

0: Box<Expr, Global>

IsNull(Box<Expr, Global>)

Tuple Fields of IsNull

0: Box<Expr, Global>

Cast

Fields of Cast

expr: Box<Expr, Global>data_type: DataTypestrict: bool

Sort

Fields of Sort

expr: Box<Expr, Global>reverse: bool

Take

Fields of Take

expr: Box<Expr, Global>idx: Box<Expr, Global>

SortBy

Fields of SortBy

expr: Box<Expr, Global>by: Box<Expr, Global>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, Global>truthy: Box<Expr, Global>falsy: Box<Expr, Global>

Function

Fields of Function

input: Vec<Expr, Global>

function arguments

function: NoEq<Arc<dyn SeriesUdf + 'static>>

function to apply

output_type: NoEq<Arc<dyn FunctionOutputField + 'static>>

output dtype of the function

options: FunctionOptions

Shift

Fields of Shift

input: Box<Expr, Global>periods: i64

Reverse(Box<Expr, Global>)

Tuple Fields of Reverse

0: Box<Expr, Global>

Duplicated(Box<Expr, Global>)

Tuple Fields of Duplicated

0: Box<Expr, Global>

IsUnique(Box<Expr, Global>)

Tuple Fields of IsUnique

0: Box<Expr, Global>

Explode(Box<Expr, Global>)

Tuple Fields of Explode

0: Box<Expr, Global>

Filter

Fields of Filter

input: Box<Expr, Global>by: Box<Expr, Global>

Window

See postgres window functions

Fields of Window

function: Box<Expr, Global>

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

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

Wildcard

Slice

Fields of Slice

input: Box<Expr, Global>offset: i64

length is not yet known so we accept negative offsets

length: usize

BinaryFunction

Fields of BinaryFunction

input_a: Box<Expr, Global>input_b: Box<Expr, Global>function: NoEq<Arc<dyn SeriesBinaryUdf + 'static>>output_field: NoEq<Arc<dyn BinaryUdfOutputField + 'static>>

Delays output type evaluation until input schema is known.

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

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

Tuple Fields of Exclude

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

KeepName(Box<Expr, Global>)

Set root name as Alias

Tuple Fields of KeepName

0: Box<Expr, Global>

SufPreFix

Fields of SufPreFix

is_suffix: boolvalue: Stringexpr: Box<Expr, Global>

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

Run is_null operation on Expr.

pub fn is_not_null(self) -> Expr

Run is_not_null operation on Expr.

pub fn min(self) -> Expr

Reduce groups to minimal value.

pub fn max(self) -> Expr

Reduce groups to maximum value.

pub fn mean(self) -> Expr

Reduce groups to the mean value.

pub fn median(self) -> Expr

Reduce groups to the median value.

pub fn sum(self) -> Expr

Reduce groups to the sum of all the values.

pub fn n_unique(self) -> Expr

Get the number of unique values in the groups.

pub fn first(self) -> Expr

Get the first value in the group.

pub fn last(self) -> Expr

Get the last value in the group.

pub fn list(self) -> Expr

Aggregate the group to a Series

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

Compute the quantile per group.

pub fn agg_groups(self) -> Expr

Get the group indexes of the group by operation.

pub fn flatten(self) -> Expr

Alias for explode

pub fn explode(self) -> Expr

Explode the utf8/ list column

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

Slice the Series.

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

Get the first n elements of the Expr result

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

Get the last n elements of the Expr result

pub fn unique(self) -> Expr

Get unique values of this expression.

pub fn arg_unique(self) -> Expr

Get the first index of unique values of this expression.

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

Get the index values that would sort this expression.

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

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

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

Cast expression to another data type.

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

Take the values by idx.

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

Sort in increasing order. See the eager implementation.

Can be used in default and aggregation context.

pub fn reverse(self) -> Expr

Reverse column

pub fn map<F>(
    self,
    function: F,
    output_type: NoEq<Arc<dyn FunctionOutputField + 'static>>
) -> Expr where
    F: 'static + Fn(Series) -> Result<Series, PolarsError> + 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: NoEq<Arc<dyn FunctionOutputField + 'static>>
) -> Expr where
    F: 'static + Fn(Series) -> Result<Series, PolarsError> + 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: NoEq<Arc<dyn FunctionOutputField + 'static>>
) -> Expr where
    F: 'static + Fn(Series) -> Result<Series, PolarsError> + 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) -> Expr

Get mask of finite values if dtype is Float

pub fn is_infinite(self) -> Expr

Get mask of infinite values if dtype is Float

pub fn is_nan(self) -> Expr

Get mask of NaN values if dtype is Float

pub fn is_not_nan(self) -> Expr

Get inverse mask of NaN values if dtype is Float

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

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

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

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

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

Get an array with the cumulative sum computed at every element

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

Get an array with the cumulative product computed at every element

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

Get an array with the cumulative min computed at every element

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

Get an array with the cumulative max computed at every element

pub fn backward_fill(self) -> Expr

Fill missing value with next non-null.

pub fn forward_fill(self) -> Expr

Fill missing value with previous non-null.

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

Round underlying floating point array to given decimal numbers.

pub fn floor(self) -> Expr

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

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

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

Replace the null values by a value.

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

Replace the floating point NaN values by a value.

pub fn count(self) -> Expr

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

pub fn std(self) -> Expr

Standard deviation of the values of the Series

pub fn var(self) -> Expr

Variance of the values of the Series

pub fn is_duplicated(self) -> Expr

Get a mask of duplicated values

pub fn is_unique(self) -> Expr

Get a mask of unique values

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

and operation

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

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

or operation

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

Raise expression to the power exponent

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

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

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

pub fn year(self) -> Expr

Get the year of a Date/Datetime

pub fn month(self) -> Expr

Get the month of a Date/Datetime

pub fn week(self) -> Expr

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

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

Get the month of a Date/Datetime

pub fn ordinal_day(self) -> Expr

Get the ordinal_day of a Date/Datetime

pub fn hour(self) -> Expr

Get the hour of a Datetime/Time64

pub fn minute(self) -> Expr

Get the minute of a Datetime/Time64

pub fn second(self) -> Expr

Get the second of a Datetime/Time64

pub fn nanosecond(self) -> Expr

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

pub fn is_first(self) -> Expr

Get a mask of the first unique value.

pub fn mode(self) -> Expr

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

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

Apply a rolling min See: ChunkedArray::rolling_min.

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

Apply a rolling max See: ChunkedArray::rolling_max.

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

Apply a rolling mean See: ChunkedArray::rolling_mean.

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

Apply a rolling sum See: ChunkedArray::rolling_sum.

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

Apply a rolling variance

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

Apply a rolling std-dev

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

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(&ChunkedArray<Float64Type>) -> Option<f64> + Send + Sync + Copy, 

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

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

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

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.

pub fn add(self, rhs: Expr) -> <Expr as Add<Expr>>::Output

Performs the + operation.

impl AsRef<Expr> for AggExpr

pub fn as_ref(&self) -> &Expr

Performs the conversion.

impl Clone for Expr

pub 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

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

Formats the value using the given formatter.

impl Div<Expr> for Expr

type Output = Expr

The resulting type after applying the / operator.

pub fn div(self, rhs: Expr) -> <Expr as Div<Expr>>::Output

Performs the / operation.

impl From<AggExpr> for Expr

pub fn from(agg: AggExpr) -> Expr

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?

pub fn into_iter(self) -> <&'a Expr as IntoIterator>::IntoIter

Creates an iterator from a value.

impl Mul<Expr> for Expr

type Output = Expr

The resulting type after applying the * operator.

pub fn mul(self, rhs: Expr) -> <Expr as Mul<Expr>>::Output

Performs the * operation.

impl PartialEq<Expr> for Expr

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

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

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

pub fn rem(self, rhs: Expr) -> <Expr as Rem<Expr>>::Output

Performs the % operation.

impl Sub<Expr> for Expr

type Output = Expr

The resulting type after applying the - operator.

pub fn sub(self, rhs: Expr) -> <Expr as Sub<Expr>>::Output

Performs the - operation.

impl StructuralPartialEq for Expr