Enum polars_lazy::dsl::Expr

pub enum Expr {
    Alias(Box<Expr>, Arc<String>),
    Column(Arc<String>),
    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,
    },
    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: Option<DataType>,
        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>>,
    },
    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>),
}

Queries consists of multiple expressions.

Variants

Alias

Tuple Fields of Alias

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

Column

Tuple Fields of Column

0: Arc<String>

Literal

Tuple Fields of Literal

0: LiteralValue

BinaryExpr

Fields of BinaryExpr

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

Not

Tuple Fields of Not

0: Box<Expr>

IsNotNull

Tuple Fields of IsNotNull

0: Box<Expr>

IsNull

Tuple Fields of IsNull

0: Box<Expr>

Cast

Fields of Cast

expr: Box<Expr>data_type: DataType

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

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: Option<DataType>

output dtype of the function

options: FunctionOptions

Shift

Fields of Shift

input: Box<Expr>periods: i64

Reverse

Tuple Fields of Reverse

0: Box<Expr>

Duplicated

Tuple Fields of Duplicated

0: Box<Expr>

IsUnique

Tuple Fields of IsUnique

0: Box<Expr>

Explode

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

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

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

Set root name as Alias

Tuple Fields of KeepName

0: 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 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 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: Option<DataType>) -> 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 apply<F>(self, function: F, output_type: Option<DataType>) -> 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 valus in the array by some period and fill the resulting empty values.

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

Get an array with the cumulative sum computed at every element

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

Get an array with the cumulative min computed at every element

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

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 over(self, partition_by: Vec<Expr>) -> 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(vec![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_none(self, fill_value: Expr) -> Self

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

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

Get the year of a Date32/Date64

pub fn month(self) -> Expr

Get the month of a Date32/Date64

pub fn day(self) -> Expr

Get the month of a Date32/Date64

pub fn ordinal_day(self) -> Expr

Get the ordinal_day of a Date32/Date64

pub fn hour(self) -> Expr

Get the hour of a Date64/Time64

pub fn minute(self) -> Expr

Get the minute of a Date64/Time64

pub fn second(self) -> Expr

Get the second of a Date64/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

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. These 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(vec![
// 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 exclude<'a, S, J>(self, columns: S) -> Expr where
    S: Selection<'a, J>, 

Exclude a column from a wildcard selection

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"])
                ])
}

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