Skip to content

Top-level APIs

These methods and objects are available directly in the ibis module.

NA

NA is the null scalar.

array(values, type=None)

Create an array expression.

If the input expressions are all column expressions, then the output will be an ArrayColumn. The input columns will be concatenated row-wise to produce each array in the output array column. Each array will have length n, where n is the number of input columns. All input columns should be of the same datatype.

If the input expressions are Python literals, then the output will be a single ArrayScalar of length n, where n is the number of input values. This is equivalent to

values = [1, 2, 3]
ibis.literal(values)

Parameters:

Name Type Description Default
values Iterable[V]

An iterable of Ibis expressions or a list of Python literals

required
type str | dt.DataType | None

An instance of ibis.expr.datatypes.DataType or a string indicating the ibis type of value.

None

Examples:

Create an array column from column expressions

>>> import ibis
>>> t = ibis.table([('a', 'int64'), ('b', 'int64')], name='t')
>>> result = ibis.array([t.a, t.b])

Create an array scalar from Python literals

>>> import ibis
>>> result = ibis.array([1.0, 2.0, 3.0])

Returns:

Type Description
ArrayValue

An array column (if the inputs are column expressions), or an array scalar (if the inputs are Python literals)

case()

Begin constructing a case expression.

Examples:

>>> import ibis
>>> cond1 = ibis.literal(1) == 1
>>> cond2 = ibis.literal(2) == 1
>>> result1 = 3
>>> result2 = 4
>>> expr = (ibis.case()
...         .when(cond1, result1)
...         .when(cond2, result2).end())

Returns:

Type Description
bl.SearchedCaseBuilder

A builder object to use for constructing a case 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

cumulative_window(group_by=None, order_by=None)

Create a cumulative window for use with window functions.

All window frames / ranges are inclusive.

Parameters:

Name Type Description Default
group_by None

Grouping key

None
order_by None

Ordering key

None

Returns:

Type Description
Window

A window frame

date(value)

Return a date literal if value is coercible to a date.

Parameters:

Name Type Description Default
value None

Date string

required

Returns:

Type Description
DateValue

A date expression

desc(expr)

Create a descending sort key from expr or column name.

Parameters:

Name Type Description Default
expr ir.ColumnExpr | str

The expression or column name to use for sorting

required

Examples:

>>> import ibis
>>> t = ibis.table([('g', 'string')])
>>> result = t.group_by('g').size('count').sort_by(ibis.desc('count'))

Returns:

Type Description
ir.SortExpr | ops.DeferredSortKey

A deferred sort key

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

ifelse(self, true_expr, false_expr)

Construct a ternary conditional expression.

Parameters:

Name Type Description Default
true_expr ir.ValueExpr

Expression to return if self evaluates to True

required
false_expr ir.ValueExpr

Expression to return if self evaluates to False

required

Examples:

>>> import ibis
>>> t = ibis.table([("is_person", "boolean")], name="t")
>>> expr = t.is_person.ifelse("yes", "no")
>>> print(ibis.impala.compile(expr))
SELECT CASE WHEN `is_person` THEN 'yes' ELSE 'no' END AS `tmp`
FROM t

Returns:

Type Description
ir.ValueExpr

The value of true_expr if arg is True else false_expr

interval(value=None, unit='s', years=None, quarters=None, months=None, weeks=None, days=None, hours=None, minutes=None, seconds=None, milliseconds=None, microseconds=None, nanoseconds=None)

Return an interval literal expression.

Parameters:

Name Type Description Default
value int | datetime.timedelta | None

Interval value. If passed, must be combined with unit.

None
unit str

Unit of value

's'
years int | None

Number of years

None
quarters int | None

Number of quarters

None
months int | None

Number of months

None
weeks int | None

Number of weeks

None
days int | None

Number of days

None
hours int | None

Number of hours

None
minutes int | None

Number of minutes

None
seconds int | None

Number of seconds

None
milliseconds int | None

Number of milliseconds

None
microseconds int | None

Number of microseconds

None
nanoseconds int | None

Number of nanoseconds

None

Returns:

Type Description
ir.IntervalScalar

An interval expression

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

literal(value, type=None)

Create a scalar expression from a Python value.

Use specific functions for arrays, structs and maps

Ibis supports literal construction of arrays using the following functions:

  1. ibis.array
  2. ibis.struct
  3. ibis.map

Constructing these types using literal will be deprecated in a future release.

Parameters:

Name Type Description Default
value Any

A Python value

required
type dt.DataType | str | None

An instance of DataType or a string indicating the ibis type of value. This parameter can be used in cases where ibis's type inference isn't sufficient for discovering the type of value.

None

Examples:

Construct an integer literal

>>> import ibis
>>> x = ibis.literal(42)
>>> x.type()
Int8(nullable=True)

Construct a float64 literal from an int

>>> y = ibis.literal(42, type='double')
>>> y.type()
Float64(nullable=True)

Ibis checks for invalid types

>>> ibis.literal('foobar', type='int64')
Traceback (most recent call last):
  ...
TypeError: Value 'foobar' cannot be safely coerced to int64

Returns:

Type Description
ScalarExpr

An expression representing a literal value

map(value, type=None)

Create a map literal from a dict or other mapping.

Parameters:

Name Type Description Default
value Iterable[tuple[K, V]] | Mapping[K, V]

the literal map value

required
type str | dt.DataType | None

An instance of ibis.expr.datatypes.DataType or a string indicating the ibis type of value.

None

Examples:

Create a map literal from a dict with the type inferred

>>> import ibis
>>> t = ibis.map(dict(a=1, b=2))

Create a map literal from a dict with the specified type

>>> import ibis
>>> t = ibis.map(dict(a=1, b=2), type='map<string, double>')

Returns:

Type Description
MapValue

An expression representing a literal map (associative array with key/value pairs of fixed types)

negate(self)

Negate a numeric expression.

Returns:

Type Description
NumericValue

A numeric value expression

now()

Return an expression that will compute the current timestamp.

Returns:

Type Description
ir.TimestampScalar

A "now" expression

null()

Create a NULL/NA scalar

param(type)

Create a deferred parameter of a given type.

Parameters:

Name Type Description Default
type dt.DataType

The type of the unbound parameter, e.g., double, int64, date, etc.

required

Examples:

>>> import ibis
>>> import ibis.expr.datatypes as dt
>>> start = ibis.param(dt.date)
>>> end = ibis.param(dt.date)
>>> schema = [('timestamp_col', 'timestamp'), ('value', 'double')]
>>> t = ibis.table(schema)
>>> predicates = [t.timestamp_col >= start, t.timestamp_col <= end]
>>> expr = t.filter(predicates).value.sum()

Returns:

Type Description
ir.ScalarExpr

A scalar expression backend by a parameter

random()

Return a random floating point number in the range [0.0, 1.0).

Similar to random.random in the Python standard library.

Returns:

Type Description
FloatingScalar

Random float value expression

range_window(preceding=None, following=None, group_by=None, order_by=None)

Create a range-based window clause for use with window functions.

This RANGE window clause aggregates rows based upon differences in the value of the order-by expression.

All window frames / ranges are inclusive.

Parameters:

Name Type Description Default
preceding None

Number of preceding rows in the window

None
following None

Number of following rows in the window

None
group_by None

Grouping key

None
order_by None

Ordering key

None

Returns:

Type Description
Window

A window frame

row_number()

Return an analytic function expression for the current row number.

Returns:

Type Description
ir.IntegerColumn

A column expression enumerating rows

schema(pairs=None, names=None, types=None)

Validate and return an Schema object.

Parameters:

Name Type Description Default
pairs Iterable[tuple[str, dt.DataType]] | Mapping[str, dt.DataType] | None

List or dictionary of name, type pairs. Mutually exclusive with names and types.

None
names Iterable[str] | None

Field names. Mutually exclusive with pairs.

None
types Iterable[str | dt.DataType] | None

Field types. Mutually exclusive with pairs.

None

Examples:

>>> from ibis import schema
>>> sc = schema([('foo', 'string'),
...              ('bar', 'int64'),
...              ('baz', 'boolean')])
>>> sc2 = schema(names=['foo', 'bar', 'baz'],
...              types=['string', 'int64', 'boolean'])

Returns:

Type Description
sch.Schema

An ibis schema

struct(value, type=None)

Create a struct literal from a dict or other mapping.

Parameters:

Name Type Description Default
value Iterable[tuple[str, V]] | Mapping[str, V]

The underlying data for literal struct value

required
type str | dt.DataType | None

An instance of ibis.expr.datatypes.DataType or a string indicating the ibis type of value.

None

Examples:

Create a struct literal from a dict with the type inferred

>>> import ibis
>>> t = ibis.struct(dict(a=1, b='foo'))

Create a struct literal from a dict with a specified type

>>> t = ibis.struct(dict(a=1, b='foo'), type='struct<a: float, b: string>')

Returns:

Type Description
StructValue

An expression representing a literal struct (compound type with fields of fixed types)

table(schema, name=None)

Create an unbound table for build expressions without data.

Parameters:

Name Type Description Default
schema sch.Schema

A schema for the table

required
name str | None

Name for the table

None

Returns:

Type Description
ir.TableExpr

An unbound table expression

time(value)

timestamp(value, *args, *, timezone=None)

Construct a timestamp literal if value is coercible to a timestamp.

Parameters:

Name Type Description Default
value None

The value to use for constructing the timestamp

required
timezone str | None

The timezone of the timestamp

None

Returns:

Type Description
ir.TimestampScalar

A timestamp expression

trailing_range_window(preceding, order_by, group_by=None)

Create a trailing range window for use with window functions.

Parameters:

Name Type Description Default
preceding None

A value expression

required
order_by None

Ordering key

required
group_by None

Grouping key

None

Returns:

Type Description
Window

A window frame

trailing_window(preceding, group_by=None, order_by=None)

Create a trailing window for use with aggregate window functions.

Parameters:

Name Type Description Default
preceding None

The number of preceding rows

required
group_by None

Grouping key

None
order_by None

Ordering key

None

Returns:

Type Description
Window

A window frame

where(boolean_expr, true_expr, false_null_expr)

Return true_expr if boolean_expr is True else false_null_expr.

Parameters:

Name Type Description Default
boolean_expr ir.BooleanValue

A boolean expression

required
true_expr ir.ValueExpr

Value returned if boolean_expr is True

required
false_null_expr ir.ValueExpr

Value returned if boolean_expr is False or NULL

required

Returns:

Type Description
ir.ValueExpr

An expression

window(preceding=None, following=None, group_by=None, order_by=None)

Create a window clause for use with window functions.

The ROWS window clause includes peer rows based on differences in row number whereas RANGE includes rows based on the differences in row value of a single order_by expression.

All window frame bounds are inclusive.

Parameters:

Name Type Description Default
preceding None

Number of preceding rows in the window

None
following None

Number of following rows in the window

None
group_by None

Grouping key

None
order_by None

Ordering key

None

Returns:

Type Description
Window

A window frame


Last update: March 1, 2022