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

values An iterable of Ibis expressions or a list of Python literals type An instance of ibis.expr.datatypes.DataType or a string indicating the ibis type of value.

Returns

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

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

case()

Begin constructing a case expression.

Notes

Use the .when method on the resulting object followed by .end to create a complete case.

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

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

cumulative_window(group_by=None, order_by=None)

Create a cumulative window for use with window functions.

All window frames / ranges are inclusive.

Parameters

group_by Grouping key order_by Ordering key

Returns

Window A window frame

date(value)

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

Parameters

value Date string

Returns

DateScalar A date expression

desc(expr)

Create a descending sort key from expr or column name.

Parameters

expr The expression or column name to use for sorting

Examples

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

Returns

ops.DeferredSortKey A deferred sort key

greatest(self, *args)

Compute the largest value among the supplied arguments.

Parameters

args Arguments to choose from

Returns

Value Maximum of the passed arguments

ifelse(self, true_expr, false_expr)

Construct a ternary conditional expression.

Parameters

true_expr Expression to return if self evaluates to True false_expr Expression to return if self evaluates to False

Returns

Value The value of true_expr if arg is True else false_expr

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

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

value Interval value. If passed, must be combined with unit. unit Unit of value years Number of years quarters Number of quarters months Number of months weeks Number of weeks days Number of days hours Number of hours minutes Number of minutes seconds Number of seconds milliseconds Number of milliseconds microseconds Number of microseconds nanoseconds Number of nanoseconds

Returns

IntervalScalar An interval expression

least(self, *args)

Compute the smallest value among the supplied arguments.

Parameters

args Arguments to choose from

Returns

Value 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

value A Python value type 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.

Returns

Scalar An expression representing a literal value

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') # doctest: +ELLIPSIS Traceback (most recent call last): ... TypeError: Value 'foobar' cannot be safely coerced to int64

map(value, type=None)

Create a map literal from a dict or other mapping.

Parameters

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

Returns

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

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

negate(self)

Negate a numeric expression.

Returns

NumericValue A numeric value expression

now()

Return an expression that will compute the current timestamp.

Returns

TimestampScalar A "now" expression

null()

Create a NULL/NA scalar

param(type)

Create a deferred parameter of a given type.

Parameters

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

Returns

Scalar A scalar expression backend by a parameter

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

random()

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

Similar to random.random in the Python standard library.

Returns

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

preceding Number of preceding rows in the window following Number of following rows in the window group_by Grouping key order_by Ordering key

Returns

Window A window frame

row_number()

Return an analytic function expression for the current row number.

Returns

IntegerColumn A column expression enumerating rows

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

Validate and return an Schema object.

Parameters

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

Examples

from ibis import schema, Schema sc = schema([('foo', 'string'), ... ('bar', 'int64'), ... ('baz', 'boolean')]) sc = schema(names=['foo', 'bar', 'baz'], ... types=['string', 'int64', 'boolean']) sc = schema(dict(foo="string")) sc = schema(Schema(['foo'], ['string'])) # no-op

Returns

Schema An ibis schema

struct(value, type=None)

Create a struct literal from a dict or other mapping.

Parameters

value The underlying data for literal struct value type An instance of ibis.expr.datatypes.DataType or a string indicating the ibis type of value.

Returns

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

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

table(schema, name=None)

Create an unbound table for building expressions without data.

Parameters

schema A schema for the table name Name for the table. One is generated if this value is None.

Returns

Table An unbound table expression

time(value)

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

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

Parameters

value The value to use for constructing the timestamp timezone The timezone of the timestamp

Returns

TimestampScalar A timestamp expression

trailing_range_window(preceding, order_by, group_by=None)

Create a trailing range window for use with window functions.

Parameters

preceding A value expression order_by Ordering key group_by Grouping key

Returns

Window A window frame

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

Create a trailing window for use with aggregate window functions.

Parameters

preceding The number of preceding rows group_by Grouping key order_by Ordering key

Returns

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

boolean_expr A boolean expression true_expr Value returned if boolean_expr is True false_null_expr Value returned if boolean_expr is False or NULL

Returns

ir.Value 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

preceding Number of preceding rows in the window following Number of following rows in the window group_by Grouping key order_by Ordering key

Returns

Window A window frame


Last update: March 1, 2022