Skip to content

Generic Expression APIs

These expressions are available on scalars and columns of any element type.

generic

Classes

AnyColumn (ColumnExpr, AnyValue)

Methods
arbitrary(self, where=None, how=None)

Select an arbitrary value in a column.

Parameters:

Name Type Description Default
where ir.BooleanValue | None

A filter expression

None
how str | None

Heavy selects a frequently occurring value using the heavy hitters algorithm. Heavy is only supported by Clickhouse backend.

None

Returns:

Type Description
ScalarExpr

An expression

count(self, where=None)

Compute the number of rows in an expression.

Parameters:

Name Type Description Default
where ir.BooleanValue | None

Filter expression

None

Returns:

Type Description
ir.IntegerScalar

Number of elements in an expression

nth(self, n)

Return the nth value over a window.

Parameters:

Name Type Description Default
n int | ir.IntegerValue

Desired rank value

required

Returns:

Type Description
ColumnExpr

The nth value over a window

summary(self, exact_nunique=False, prefix='', suffix='')

Compute a set of summary metrics.

Parameters:

Name Type Description Default
exact_nunique bool

Compute the exact number of distinct values. Typically slower if True.

False
prefix str

String prefix for metric names

''
suffix str

String suffix for metric names

''

Returns:

Type Description
list[ir.NumericScalar]

Metrics list

topk(self, k, by=None)

Return a "top k" expression.

Parameters:

Name Type Description Default
k int

Return this number of rows

required
by ir.ValueExpr | None

An expression. Defaults to the count

None

Returns:

Type Description
ir.TopKExpr

A top-k expression

value_counts(self, metric_name='count')

Compute a frequency table.

Returns:

Type Description
ir.TableExpr

Frequency table expression

AnyValue (ValueExpr)

Methods
between(self, lower, upper)

Check if this expression is between lower and upper, inclusive.

Parameters:

Name Type Description Default
lower ValueExpr

Lower bound

required
upper ValueExpr

Upper bound

required

Returns:

Type Description
ir.BooleanValue

Expression indicating membership in the provided range

case(self)

Create a SimpleCaseBuilder to chain multiple if-else statements.

Add new search expressions with the .when() method. These must be comparable with this column expression. Conclude by calling .end()

Examples:

>>> import ibis
>>> t = ibis.table([('string_col', 'string')], name='t')
>>> expr = t.string_col
>>> case_expr = (expr.case()
...              .when('a', 'an a')
...              .when('b', 'a b')
...              .else_('null or (not a and not b)')
...              .end())
>>> case_expr
r0 := UnboundTable[t]
  string_col string
SimpleCase(base=r0.string_col, cases=[ValueList(values=['a', 'b'])], results=[ValueList(values=['an a', 'a b'])], default='null or (not a and not b)')

Returns:

Type Description
SimpleCaseBuilder

A case builder

cases(self, case_result_pairs, default=None)

Create a case expression in one shot.

Parameters:

Name Type Description Default
case_result_pairs Iterable[tuple[ir.BooleanValue, ValueExpr]]

Conditional-result pairs

required
default ValueExpr | None

Value to return if none of the case conditions are true

None

Returns:

Type Description
ValueExpr

Value expression

cast(self, target_type)

Cast expression to indicated data type.

Parameters:

Name Type Description Default
target_type dt.DataType

Type to cast to

required

Returns:

Type Description
ValueExpr

Casted expression

coalesce(self, *args)

Return the first non-null value from args.

Parameters:

Name Type Description Default
args ValueExpr

Arguments from which to choose the first non-null value

()

Examples:

>>> import ibis
>>> expr1 = None
>>> expr2 = 4
>>> result = ibis.coalesce(expr1, expr2, 5)

Returns:

Type Description
ValueExpr

Coalesced expression

collect(self)

Return an array of the elements of this expression.

fillna(self, fill_value)

Replace any null values with the indicated fill value.

Parameters:

Name Type Description Default
fill_value ScalarExpr

Value with which to replace NA values in self

required

Examples:

>>> import ibis
>>> table = ibis.table([('col', 'int64'), ('other_col', 'int64')])
>>> result = table.col.fillna(5)
>>> result2 = table.col.fillna(table.other_col * 3)

Returns:

Type Description
ValueExpr

self filled with fill_value where it is NA

greatest(self, *args)

Compute the largest value among the supplied arguments.

Parameters:

Name Type Description Default
args ir.ValueExpr

Arguments to choose from

()

Returns:

Type Description
ir.ValueExpr

Maximum of the passed arguments

group_concat(self, sep=',', where=None)

Concatenate values using the indicated separator to produce a string.

Parameters:

Name Type Description Default
sep str

Separator will be used to join strings

','
where ir.BooleanValue | None

Filter expression

None

Returns:

Type Description
ir.StringScalar

Concatenated string expression

hash(self, how='fnv')

Compute an integer hash value.

Parameters:

Name Type Description Default
how str

Hash algorithm to use

'fnv'

Returns:

Type Description
ir.IntegerValue

The hash value of self

identical_to(self, other)

Return whether this expression is identical to other.

Corresponds to IS NOT DISTINCT FROM in SQL.

Parameters:

Name Type Description Default
other ValueExpr

Expression to compare to

required

Returns:

Type Description
ir.BooleanValue

Whether this expression is not distinct from other

isin(self, values)

Check whether this expression's values are in values.

Parameters:

Name Type Description Default
values ValueExpr | Sequence[ValueExpr]

Values or expression to check for membership

required

Examples:

>>> import ibis
>>> table = ibis.table([('string_col', 'string')])
>>> table2 = ibis.table([('other_string_col', 'string')])
>>> expr = table.string_col.isin(['foo', 'bar', 'baz'])
>>> expr2 = table.string_col.isin(table2.other_string_col)

Returns:

Type Description
ir.BooleanValue

Expression indicating membership

isnull(self)

Return whether this expression is NULL.

least(self, *args)

Compute the smallest value among the supplied arguments.

Parameters:

Name Type Description Default
args ir.ValueExpr

Arguments to choose from

()

Returns:

Type Description
ir.ValueExpr

Minimum of the passed arguments

notin(self, values)

Check whether this expression's values are not in values.

Parameters:

Name Type Description Default
values ValueExpr | Sequence[ValueExpr]

Values or expression to check for lack of membership

required

Returns:

Type Description
ir.BooleanValue

Whether self's values are not contained in values

notnull(self)

Return whether this expression is not NULL.

over(self, window)

Construct a window expression.

Parameters:

Name Type Description Default
window win.Window

Window specification

required

Returns:

Type Description
ValueExpr

A window function expression

substitute(self, value, replacement=None, else_=None)

Replace one or more values in a value expression.

Parameters:

Name Type Description Default
value ValueExpr

Expression or mapping

required
replacement ValueExpr | None

Expression. If an expression is passed to value, this must be passed.

None
else_ ValueExpr | None

Expression

None

Returns:

Type Description
ValueExpr

Replaced values

typeof(self)

Return the data type of the expression.

The values of the returned strings are necessarily backend dependent.

Returns:

Type Description
ir.StringValue

A string indicating the type of the value

ColumnExpr (ValueExpr)

Methods
to_projection(self)

Promote this column expression to a table projection

ScalarExpr (ValueExpr)

Methods
to_projection(self)

Promote this column expression to a table projection

ValueExpr (Expr)

Base class for a data generating expression having a fixed and known type,

either a single value (scalar)

Methods
name(self, name)

Rename an expression to name.

Parameters:

Name Type Description Default
name None

The new name of the expression

required

Examples:

>>> import ibis
>>> t = ibis.table(dict(a="int64"))
>>> t.a.name("b")
r0 := UnboundTable[unbound_table_...]
  a int64
b: r0.a

Returns:

Type Description
ValueExpr

self with name name


Last update: February 3, 2022