Skip to content

Generic Expression APIs

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

generic

Classes

AnyColumn (Value)

Methods
approx_median(self, where=None)

Return an approximate of the median of self.

The result may or may not be exact

Whether the result is an approximation depends on the backend.

Do not depend on the results being exact

Parameters

where Filter in values when where is True

Returns

Scalar An approximation of the median of self

approx_nunique(self, where=None)

Return the approximate number of distinct elements in self.

The result may or may not be exact

Whether the result is an approximation depends on the backend.

Do not depend on the results being exact

Parameters

where Filter in values when where is True

Returns

Scalar An approximate count of the distinct elements of self

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

Select an arbitrary value in a column.

Parameters

where A filter expression how The method to use for selecting the element.

* `"first"`: Select the first non-`NULL` element
* `"last"`: Select the last non-`NULL` element
* `"heavy"`: Select a frequently occurring value using the heavy
  hitters algorithm. `"heavy"` is only supported by Clickhouse
  backend.
Returns

Scalar An expression

count(self, where=None)

Compute the number of rows in an expression.

Parameters

where Filter expression

Returns

IntegerScalar Number of elements in an expression

nth(self, n)

Return the nth value over a window.

Parameters

n Desired rank value

Returns

Column The nth value over a window

parent(self)

DEPRECATED: parent is deprecated as of v4.0.0;

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

Compute a set of summary metrics.

Parameters

exact_nunique Compute the exact number of distinct values. Typically slower if True. prefix String prefix for metric names suffix String suffix for metric names

Returns

list[NumericScalar] Metrics list

to_projection(self)

Promote this column expression to a projection.

topk(self, k, by=None)

Return a "top k" expression.

Parameters

k Return this number of rows by An expression. Defaults to the count

Returns

TopK A top-k expression

value_counts(self, metric_name='count')

Compute a frequency table.

Returns

Table Frequency table expression

AnyScalar (Value)

Methods
to_projection(self)

Promote this scalar expression to a projection.

AnyValue (Expr)

Base class for a data generating expression having a fixed and known type, either a single value (scalar)

Methods
between(self, lower, upper)

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

Parameters

lower Lower bound upper Upper bound

Returns

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

Returns

SimpleCaseBuilder A case builder

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

cases(self, case_result_pairs, default=None)

Create a case expression in one shot.

Parameters

case_result_pairs Conditional-result pairs default Value to return if none of the case conditions are true

Returns

Value Value expression

cast(self, target_type)

Cast expression to indicated data type.

Parameters

target_type Type to cast to

Returns

Value Casted expression

coalesce(self, *args)

Return the first non-null value from args.

Parameters

args Arguments from which to choose the first non-null value

Returns

Value Coalesced expression

Examples

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

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

fill_value Value with which to replace NA values in self

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

Value self filled with fill_value where it is NA

greatest(self, *args)

Compute the largest value among the supplied arguments.

Parameters

args Arguments to choose from

Returns

Value Maximum of the passed arguments

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

Concatenate values using the indicated separator to produce a string.

Parameters

sep Separator will be used to join strings where Filter expression

Returns

StringScalar Concatenated string expression

hash(self, how='fnv')

Compute an integer hash value.

Parameters

how Hash algorithm to use

Returns

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

other Expression to compare to

Returns

BooleanValue Whether this expression is not distinct from other

isin(self, values)

Check whether this expression's values are in values.

Parameters

values Values or expression to check for membership

Returns

BooleanValue Expression indicating membership

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)

isnull(self)

Return whether this expression is NULL.

least(self, *args)

Compute the smallest value among the supplied arguments.

Parameters

args Arguments to choose from

Returns

Value Minimum of the passed arguments

name(self, name)

Rename an expression to name.

Parameters

name The new name of the expression

Returns

Value self with name name

Examples

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

notin(self, values)

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

Parameters

values Values or expression to check for lack of membership

Returns

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

window Window specification

Returns

Value A window function expression

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

Replace one or more values in a value expression.

Parameters

value Expression or mapping replacement Expression. If an expression is passed to value, this must be passed. else_ Expression

Returns

Value Replaced values

typeof(self)

Return the data type of the expression.

The values of the returned strings are necessarily backend dependent.

Returns

StringValue A string indicating the type of the value

Column (Value)

Methods
approx_median(self, where=None)

Return an approximate of the median of self.

The result may or may not be exact

Whether the result is an approximation depends on the backend.

Do not depend on the results being exact

Parameters

where Filter in values when where is True

Returns

Scalar An approximation of the median of self

approx_nunique(self, where=None)

Return the approximate number of distinct elements in self.

The result may or may not be exact

Whether the result is an approximation depends on the backend.

Do not depend on the results being exact

Parameters

where Filter in values when where is True

Returns

Scalar An approximate count of the distinct elements of self

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

Select an arbitrary value in a column.

Parameters

where A filter expression how The method to use for selecting the element.

* `"first"`: Select the first non-`NULL` element
* `"last"`: Select the last non-`NULL` element
* `"heavy"`: Select a frequently occurring value using the heavy
  hitters algorithm. `"heavy"` is only supported by Clickhouse
  backend.
Returns

Scalar An expression

count(self, where=None)

Compute the number of rows in an expression.

Parameters

where Filter expression

Returns

IntegerScalar Number of elements in an expression

nth(self, n)

Return the nth value over a window.

Parameters

n Desired rank value

Returns

Column The nth value over a window

parent(self)

DEPRECATED: parent is deprecated as of v4.0.0;

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

Compute a set of summary metrics.

Parameters

exact_nunique Compute the exact number of distinct values. Typically slower if True. prefix String prefix for metric names suffix String suffix for metric names

Returns

list[NumericScalar] Metrics list

to_projection(self)

Promote this column expression to a projection.

topk(self, k, by=None)

Return a "top k" expression.

Parameters

k Return this number of rows by An expression. Defaults to the count

Returns

TopK A top-k expression

value_counts(self, metric_name='count')

Compute a frequency table.

Returns

Table Frequency table expression

ColumnExpr (Value)

Methods
approx_median(self, where=None)

Return an approximate of the median of self.

The result may or may not be exact

Whether the result is an approximation depends on the backend.

Do not depend on the results being exact

Parameters

where Filter in values when where is True

Returns

Scalar An approximation of the median of self

approx_nunique(self, where=None)

Return the approximate number of distinct elements in self.

The result may or may not be exact

Whether the result is an approximation depends on the backend.

Do not depend on the results being exact

Parameters

where Filter in values when where is True

Returns

Scalar An approximate count of the distinct elements of self

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

Select an arbitrary value in a column.

Parameters

where A filter expression how The method to use for selecting the element.

* `"first"`: Select the first non-`NULL` element
* `"last"`: Select the last non-`NULL` element
* `"heavy"`: Select a frequently occurring value using the heavy
  hitters algorithm. `"heavy"` is only supported by Clickhouse
  backend.
Returns

Scalar An expression

count(self, where=None)

Compute the number of rows in an expression.

Parameters

where Filter expression

Returns

IntegerScalar Number of elements in an expression

nth(self, n)

Return the nth value over a window.

Parameters

n Desired rank value

Returns

Column The nth value over a window

parent(self)

DEPRECATED: parent is deprecated as of v4.0.0;

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

Compute a set of summary metrics.

Parameters

exact_nunique Compute the exact number of distinct values. Typically slower if True. prefix String prefix for metric names suffix String suffix for metric names

Returns

list[NumericScalar] Metrics list

to_projection(self)

Promote this column expression to a projection.

topk(self, k, by=None)

Return a "top k" expression.

Parameters

k Return this number of rows by An expression. Defaults to the count

Returns

TopK A top-k expression

value_counts(self, metric_name='count')

Compute a frequency table.

Returns

Table Frequency table expression

Scalar (Value)

Methods
to_projection(self)

Promote this scalar expression to a projection.

ScalarExpr (Value)

Methods
to_projection(self)

Promote this scalar expression to a projection.

Value (Expr)

Base class for a data generating expression having a fixed and known type, either a single value (scalar)

Methods
between(self, lower, upper)

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

Parameters

lower Lower bound upper Upper bound

Returns

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

Returns

SimpleCaseBuilder A case builder

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

cases(self, case_result_pairs, default=None)

Create a case expression in one shot.

Parameters

case_result_pairs Conditional-result pairs default Value to return if none of the case conditions are true

Returns

Value Value expression

cast(self, target_type)

Cast expression to indicated data type.

Parameters

target_type Type to cast to

Returns

Value Casted expression

coalesce(self, *args)

Return the first non-null value from args.

Parameters

args Arguments from which to choose the first non-null value

Returns

Value Coalesced expression

Examples

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

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

fill_value Value with which to replace NA values in self

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

Value self filled with fill_value where it is NA

greatest(self, *args)

Compute the largest value among the supplied arguments.

Parameters

args Arguments to choose from

Returns

Value Maximum of the passed arguments

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

Concatenate values using the indicated separator to produce a string.

Parameters

sep Separator will be used to join strings where Filter expression

Returns

StringScalar Concatenated string expression

hash(self, how='fnv')

Compute an integer hash value.

Parameters

how Hash algorithm to use

Returns

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

other Expression to compare to

Returns

BooleanValue Whether this expression is not distinct from other

isin(self, values)

Check whether this expression's values are in values.

Parameters

values Values or expression to check for membership

Returns

BooleanValue Expression indicating membership

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)

isnull(self)

Return whether this expression is NULL.

least(self, *args)

Compute the smallest value among the supplied arguments.

Parameters

args Arguments to choose from

Returns

Value Minimum of the passed arguments

name(self, name)

Rename an expression to name.

Parameters

name The new name of the expression

Returns

Value self with name name

Examples

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

notin(self, values)

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

Parameters

values Values or expression to check for lack of membership

Returns

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

window Window specification

Returns

Value A window function expression

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

Replace one or more values in a value expression.

Parameters

value Expression or mapping replacement Expression. If an expression is passed to value, this must be passed. else_ Expression

Returns

Value Replaced values

typeof(self)

Return the data type of the expression.

The values of the returned strings are necessarily backend dependent.

Returns

StringValue A string indicating the type of the value

ValueExpr (Expr)

Base class for a data generating expression having a fixed and known type, either a single value (scalar)

Methods
between(self, lower, upper)

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

Parameters

lower Lower bound upper Upper bound

Returns

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

Returns

SimpleCaseBuilder A case builder

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

cases(self, case_result_pairs, default=None)

Create a case expression in one shot.

Parameters

case_result_pairs Conditional-result pairs default Value to return if none of the case conditions are true

Returns

Value Value expression

cast(self, target_type)

Cast expression to indicated data type.

Parameters

target_type Type to cast to

Returns

Value Casted expression

coalesce(self, *args)

Return the first non-null value from args.

Parameters

args Arguments from which to choose the first non-null value

Returns

Value Coalesced expression

Examples

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

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

fill_value Value with which to replace NA values in self

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

Value self filled with fill_value where it is NA

greatest(self, *args)

Compute the largest value among the supplied arguments.

Parameters

args Arguments to choose from

Returns

Value Maximum of the passed arguments

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

Concatenate values using the indicated separator to produce a string.

Parameters

sep Separator will be used to join strings where Filter expression

Returns

StringScalar Concatenated string expression

hash(self, how='fnv')

Compute an integer hash value.

Parameters

how Hash algorithm to use

Returns

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

other Expression to compare to

Returns

BooleanValue Whether this expression is not distinct from other

isin(self, values)

Check whether this expression's values are in values.

Parameters

values Values or expression to check for membership

Returns

BooleanValue Expression indicating membership

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)

isnull(self)

Return whether this expression is NULL.

least(self, *args)

Compute the smallest value among the supplied arguments.

Parameters

args Arguments to choose from

Returns

Value Minimum of the passed arguments

name(self, name)

Rename an expression to name.

Parameters

name The new name of the expression

Returns

Value self with name name

Examples

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

notin(self, values)

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

Parameters

values Values or expression to check for lack of membership

Returns

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

window Window specification

Returns

Value A window function expression

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

Replace one or more values in a value expression.

Parameters

value Expression or mapping replacement Expression. If an expression is passed to value, this must be passed. else_ Expression

Returns

Value Replaced values

typeof(self)

Return the data type of the expression.

The values of the returned strings are necessarily backend dependent.

Returns

StringValue A string indicating the type of the value


Last update: February 3, 2022