Class: Expression¶

Expression builder for DataFrame column predicates.

Enables creation of boolean filter conditions using chainable methods. Supports numeric comparisons, string operations, logical combinations, and null checks.

Remarks¶

Expressions are typically used with DataFrame.filter() to select rows matching specific conditions. Use method chaining to build complex predicates.

Logical operators (.and(), .or(), .not()) are combined left-associatively. To control evaluation order with multiple AND/OR operators, build conditions step-by-step using intermediate variables.

Examples¶

TypeScript

const adults = df.filter(new Expression('age').gt(18).toFunction());

TypeScript

const result = df.filter(
  new Expression('department').eq('Engineering')
  .and(new Expression('status').eq('active'))
  .toFunction()
);

TypeScript

const filtered = df.filter(Expression.col('email').contains('@').toFunction());

Since¶

0.37.0

Constructors¶

Constructor¶

new Expression(header): Expression

Create a new Expression for filtering a DataFrame column.

Parameters¶

string

Name of the column to filter

Returns¶

Expression

Throws¶

TypeError if header is not a string

Example¶

TypeScript

const ageExpr = new Expression('age').gt(18);
const filtered = df.filter(ageExpr);

Since¶

0.37.0

Expression¶

evaluate()¶

evaluate(row, options?): boolean

Evaluate this expression against a single row of data.

Parameters¶

row¶

Map\<string, Cell>

Row data as Map where keys are column names and values are cell values

options?¶

Optional evaluation settings (strict mode throws on missing columns)

strict?¶

boolean

Returns¶

boolean

Boolean result of the filter condition

Remarks¶

This method is typically called internally by DataFrame.filter() rather than directly. Use toFunction() to get a reusable row evaluator for better performance.

Example¶

TypeScript

const expr = new Expression('age').gt(30);
const row = new Map([['age', 35], ['name', 'John']]);
const result = expr.evaluate(row); // true

Since¶

0.37.0

gt()¶

gt(value): Expression

Filter rows where column value is greater than specified value.

Parameters¶

value¶

number

Threshold value for comparison

Returns¶

Expression

This expression for method chaining

Remarks¶

Returns false if the column value is null or undefined. Use isNotNull() for null checking.

Example¶

TypeScript

df.filter(new Expression('age').gt(30).toFunction());

Since¶

0.37.0

ge()¶

ge(value): Expression

Filter rows where column value is greater than or equal to specified value.

Parameters¶

value¶

number

Threshold value for comparison

Returns¶

Expression

This expression for method chaining

Remarks¶

Returns false if the column value is null or undefined. Use isNotNull() for null checking.

Example¶

TypeScript

df.filter(new Expression('age').ge(18).toFunction());

Since¶

0.37.0

lt()¶

lt(value): Expression

Filter rows where column value is less than specified value.

Parameters¶

value¶

number

Threshold value for comparison

Returns¶

Expression

This expression for method chaining

Remarks¶

Returns false if the column value is null or undefined. Use isNotNull() for null checking.

Example¶

TypeScript

df.filter(new Expression('temperature').lt(32).toFunction());

Since¶

0.37.0

le()¶

le(value): Expression

Filter rows where column value is less than or equal to specified value.

Parameters¶

value¶

number

Threshold value for comparison

Returns¶

Expression

This expression for method chaining

Remarks¶

Returns false if the column value is null or undefined. Use isNotNull() for null checking.

Example¶

TypeScript

df.filter(new Expression('age').le(18).toFunction());

Since¶

0.37.0

eq()¶

eq(value): Expression

Filter rows where column value equals specified value.

Parameters¶

value¶

Cell

Value to match

Returns¶

Expression

This expression for method chaining

Remarks¶

To match null values, use isNull() instead of eq(null).

Example¶

TypeScript

df.filter(new Expression('status').eq('active').toFunction());

Since¶

0.37.0

ne()¶

ne(value): Expression

Filter rows where column value does not equal specified value.

Parameters¶

value¶

Cell

Value to exclude

Returns¶

Expression

This expression for method chaining

Remarks¶

Returns false if the column value is null or undefined. Use isNotNull() for null checking.

Example¶

TypeScript

df.filter(new Expression('status').ne('deleted').toFunction());

Since¶

0.37.0

contains()¶

contains(substring): Expression

Filter rows where column value contains specified substring.

Parameters¶

substring¶

string

Text to search for within the value

Returns¶

Expression

This expression for method chaining

Throws¶

TypeError if substring is not a string

Remarks¶

Returns false if the column value is null, undefined, or not a string. Returns true if substring is empty string (every string contains empty string).

Example¶

TypeScript

df.filter(new Expression('name').contains('Smith').toFunction());

Since¶

0.37.0

startsWith()¶

startsWith(prefix): Expression

Filter rows where column value starts with specified prefix.

Parameters¶

prefix¶

string

Text that must appear at the beginning

Returns¶

Expression

This expression for method chaining

Throws¶

TypeError if prefix is not a string

Remarks¶

Returns false if the column value is null, undefined, or not a string. Returns true if prefix is empty string (every string starts with empty string).

Example¶

TypeScript

df.filter(new Expression('email').startsWith('admin').toFunction());

Since¶

0.37.0

endsWith()¶

endsWith(suffix): Expression

Filter rows where column value ends with specified suffix.

Parameters¶

suffix¶

string

Text that must appear at the end

Returns¶

Expression

This expression for method chaining

Throws¶

TypeError if suffix is not a string

Remarks¶

Returns false if the column value is null, undefined, or not a string. Returns true if suffix is empty string (every string ends with empty string).

Example¶

TypeScript

df.filter(new Expression('email').endsWith('@example.com').toFunction());

Since¶

0.37.0

in()¶

in(values): Expression

Filter rows where column value is in specified collection.

Parameters¶

values¶

Cell[]

Array of values to match against

Returns¶

Expression

This expression for method chaining

Throws¶

TypeError if values is not an array

Remarks¶

Null or undefined values in the column are compared using exact equality. To check for null/undefined, use isNull() or isNotNull().

Example¶

TypeScript

df.filter(new Expression('status').in(['active', 'pending']).toFunction());

Since¶

0.37.0

isNull()¶

isNull(): Expression

Filter rows where column value is null or undefined.

Returns¶

Expression

This expression for method chaining

Example¶

TypeScript

df.filter(new Expression('endDate').isNull().toFunction());

Since¶

0.37.0

isNotNull()¶

isNotNull(): Expression

Filter rows where column value is not null and not undefined.

Returns¶

Expression

This expression for method chaining

Example¶

TypeScript

df.filter(new Expression('email').isNotNull().toFunction());

Since¶

0.37.0

and()¶

and(otherExpr): Expression

Combine two expressions with logical AND (both conditions must be true).

Parameters¶

otherExpr¶

Expression

Expression to combine with this expression

Returns¶

Expression

Combined expression (short-circuit evaluation)

Remarks¶

Left-associative: a.and(b).and(c) evaluates as (a AND b) AND c. Uses short-circuit evaluation: if the left side is false, the right side is not evaluated.

Example¶

TypeScript

df.filter(
  new Expression('age').gt(18)
  .and(new Expression('status').eq('active'))
);

Since¶

0.37.0

or()¶

or(otherExpr): Expression

Combine two expressions with logical OR (at least one condition must be true).

Parameters¶

otherExpr¶

Expression

Expression to combine with this expression

Returns¶

Expression

Combined expression (short-circuit evaluation)

Remarks¶

Left-associative: a.or(b).or(c) evaluates as (a OR b) OR c. Uses short-circuit evaluation: if the left side is true, the right side is not evaluated.

Example¶

TypeScript

df.filter(
  new Expression('department').eq('Sales')
  .or(new Expression('department').eq('Marketing'))
);

Since¶

0.37.0

not()¶

not(): Expression

Negate this expression (logical NOT).

Returns¶

Expression

New expression that negates this expression

Remarks¶

Returns a new Expression instance that logically negates the current expression. Multiple calls can be chained: .not().not() will negate twice (double negation).

Examples¶

TypeScript

df.filter(new Expression('status').eq('deleted').not().toFunction());

TypeScript

df.filter(new Expression('status').eq('active').not().not().toFunction());

TypeScript

// Rows where age > 18 AND status is NOT 'inactive'
df.filter(
  new Expression('age').gt(18)
  .and(new Expression('status').eq('inactive').not())
  .toFunction()
);

Since¶

0.37.0

toFunction()¶

toFunction(options?): (row) => boolean

Convert this expression to a reusable function for row evaluation.

Parameters¶

options?¶

Optional evaluation settings

strict?¶

boolean

If true, throws error if column is missing from row (does not apply to logical operators)

Returns¶

Evaluator function that returns a boolean result for each row

(row) => boolean

Remarks¶

The returned function encapsulates this expression's evaluation logic. It can be passed to DataFrame.filter() or called directly on row data. The function always returns a boolean value indicating whether the row matches the expression condition.

Example¶

TypeScript

const isAdult = new Expression('age').ge(18).toFunction();
const filtered = df.filter(isAdult);

Since¶

0.37.0

col()¶

static col(header): Expression

Create a new Expression for a column (static factory helper).

Convenience method equivalent to new Expression(header).

Parameters¶

header¶

string

Name of the column to filter

Returns¶

Expression

New Expression instance for the specified column

Throws¶

TypeError if header is not a string

Example¶

TypeScript

df.filter(Expression.col('age').gt(30));

Since¶

0.37.0