Expr#

The Expr class represents an expression that can be used to select, filter, and transform DataFrame columns. Expressions are lazily evaluated and can be composed to build complex operations.

Constructor#

Create a literal expression from a PHP value.

param mixed $value:

int, float, string, bool, or null

raises Polars\Exception:

If value type is not supported

Example:

$literal = new Expr(42);
$literal = new Expr("hello");
$literal = new Expr(3.14);

Static Methods#

col#

Reference a column by name.

param string $name:

Column name

returns:

Expr

Example:

$expr = Expr::col('age');

cols#

Reference multiple columns by name.

param array $names:

Array of column names

returns:

Expr

Example:

$expr = Expr::cols(['name', 'age', 'city']);

all#

Select all columns.

returns:

Expr

Example:

$expr = Expr::all();

Aggregation Methods#

All aggregation methods return a new Expr and can be chained.

any#

Return whether any value is true.

param bool $ignoreNulls:

Whether to ignore null values (default: true)

returns:

Expr

count#

Count the number of values.

returns:

Expr

first#

Get the first value.

returns:

Expr

last#

Get the last value.

returns:

Expr

len#

Get the length of the column.

returns:

Expr

max#

Get the maximum value.

returns:

Expr

mean#

Get the mean value.

returns:

Expr

median#

Get the median value.

returns:

Expr

min#

Get the minimum value.

returns:

Expr

nUnique#

Count unique values.

returns:

Expr

nanMax#

Get the maximum value, propagating NaN.

returns:

Expr

nanMin#

Get the minimum value, propagating NaN.

returns:

Expr

nullCount#

Count null values.

returns:

Expr

product#

Get the product of all values.

returns:

Expr

std#

Get the standard deviation.

param int $ddof:

Delta degrees of freedom (default: 1)

returns:

Expr

sum#

Get the sum of all values.

returns:

Expr

variance#

Get the variance.

param int $ddof:

Delta degrees of freedom (default: 1)

returns:

Expr

Example:

use Polars\Expr;

$df = new DataFrame(['values' => [1, 2, 3, 4, 5]]);

$result = $df->select([
    Expr::col('values')->sum(),
    Expr::col('values')->mean(),
    Expr::col('values')->max(),
]);

Comparison Operators#

All comparison methods accept int, float, string, bool, null, or another Expr object.

eq#

Equal to.

param mixed $other:

Value to compare

returns:

Expr - Boolean expression

eqMissing#

Equal to, treating null as a value.

param mixed $other:

Value to compare

returns:

Expr - Boolean expression

ne#

Not equal to.

param mixed $other:

Value to compare

returns:

Expr - Boolean expression

neqMissing#

Not equal to, treating null as a value.

param mixed $other:

Value to compare

returns:

Expr - Boolean expression

gt#

Greater than.

param mixed $other:

Value to compare

returns:

Expr - Boolean expression

ge#

Greater than or equal to.

param mixed $other:

Value to compare

returns:

Expr - Boolean expression

lt#

Less than.

param mixed $other:

Value to compare

returns:

Expr - Boolean expression

le#

Less than or equal to.

param mixed $other:

Value to compare

returns:

Expr - Boolean expression

Example:

use Polars\Expr;

// Filter rows where age > 25
$expr = Expr::col('age')->gt(25);
$result = $df->select([$expr]);

// Compare columns
$expr = Expr::col('a')->gt(Expr::col('b'));

Arithmetic Operators#

All arithmetic methods accept int, float, string, bool, null, or another Expr object.

add#

Addition.

param mixed $other:

Value to add

returns:

Expr

sub#

Subtraction.

param mixed $other:

Value to subtract

returns:

Expr

mul#

Multiplication.

param mixed $other:

Value to multiply by

returns:

Expr

div#

Division.

param mixed $other:

Value to divide by

returns:

Expr

floorDiv#

Floor division (integer division).

param mixed $other:

Value to divide by

returns:

Expr

modulo#

Modulo (remainder).

param mixed $other:

Divisor

returns:

Expr

pow#

Power/exponentiation.

param mixed $other:

Exponent

returns:

Expr

neg#

Negation (multiply by -1).

returns:

Expr

xxor#

Exclusive OR (XOR).

param mixed $other:

Value to XOR with

returns:

Expr

and_#

Bitwise AND operation (equivalent to & operator).

param mixed $other:

Value to AND with

returns:

Expr

or_#

Bitwise OR operation (equivalent to | operator).

param mixed $other:

Value to OR with

returns:

Expr

Example:

use Polars\Expr;

$df = new DataFrame([
    'a' => [1, 2, 3],
    'b' => [4, 5, 6]
]);

// Add columns
$sum = Expr::col('a')->add(Expr::col('b'));

// Multiply by constant
$doubled = Expr::col('a')->mul(2);

// Complex expression
$result = Expr::col('a')->add(Expr::col('b'))->div(2);

Boolean Methods#

hasNulls#

Check if the column has any null values.

returns:

Expr - Boolean expression

isBetween#

Check if values are between lower and upper bounds.

param mixed $lowerBound:

Lower bound value

param mixed $upperBound:

Upper bound value

param ClosedInterval $closed:

Which bounds are inclusive

returns:

Expr - Boolean expression

Example:

use Polars\Expr;
use Polars\ClosedInterval;

$df = new DataFrame(['age' => [18, 25, 30, 45, 60]]);

// Check if age is between 20 and 40 (inclusive)
$expr = Expr::col('age')->isBetween(20, 40, ClosedInterval::Both);
$result = $df->select([$expr]);

Method Chaining#

Expressions can be chained to build complex operations:

use Polars\Expr;

// Chain multiple operations
$expr = Expr::col('price')
    ->mul(Expr::col('quantity'))
    ->sum();

// Filter and aggregate
$expr = Expr::col('value')
    ->gt(0)
    ->sum();