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