Skip to content

Complex Type Expressions

These APIs are available on complex data types such as arrays, maps, and structs.

arrays

Classes

ArrayValue (AnyValue)

Methods
length(self)

Compute the length of an array.

Examples:

>>> import ibis
>>> a = ibis.array([1, 2, 3])
>>> a.length()
ArrayLength((1, 2, 3))

Returns:

Type Description
ir.IntegerValue

The integer length of self

Functions

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)

maps

Classes

MapValue (AnyValue)

Methods
get(self, key, default=None)

Return the value for key from expr or the default if key is not in the map.

Parameters:

Name Type Description Default
key ir.ValueExpr

Expression to use for key

required
default ir.ValueExpr | None

Expression to return if key is not a key in expr

None

Examples:

>>> import ibis
>>> m = ibis.map({"a": 1, "b": 2})
>>> m.get("a")
MapValueOrDefaultForKey(frozendict({'a': 1, 'b': 2}), key='a', default=None)
>>> m.get("c", 3)
MapValueOrDefaultForKey(frozendict({'a': 1, 'b': 2}), key='c', default=3)
>>> m.get("d")
MapValueOrDefaultForKey(frozendict({'a': 1, 'b': 2}), key='d', default=None)

Returns:

Type Description
ir.ValueExpr

The element type of self

keys(self)

Extract the keys of a map.

Examples:

>>> import ibis
>>> m = ibis.map({"a": 1, "b": 2})
>>> m.keys()
MapKeys(frozendict({'a': 1, 'b': 2}))

Returns:

Type Description
ir.ArrayValue

The keys of self

length(self)

Return the number of key-value pairs in the map.

Examples:

>>> import ibis
>>> m = ibis.map({"a": 1, "b": 2})
>>> m.length()
MapLength(frozendict({'a': 1, 'b': 2}))

Returns:

Type Description
ir.IntegerValue

The number of elements in self

values(self)

Extract the values of a map.

Examples:

>>> import ibis
>>> m = ibis.map({"a": 1, "b": 2})
>>> m.keys()
MapKeys(frozendict({'a': 1, 'b': 2}))

Returns:

Type Description
ir.ArrayValue

The values of self

Functions

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)

structs

Classes

StructColumn (AnyColumn, StructValue)

Methods
destructure(self)

Destructure self into a DestructColumn.

When assigned, a destruct column will be destructured and assigned to multiple columns.

Returns:

Type Description
DestructColumn

A destruct column expression.

StructScalar (AnyScalar, StructValue)

Methods
destructure(self)

Destructure self into a DestructScalar.

When assigned, a destruct scalar will be destructured and assigned to multiple columns.

Returns:

Type Description
DestructScalar

A destruct scalar expression.

StructValue (AnyValue)

Methods
__getitem__(self, name) special

Extract the name field from this struct.

Parameters:

Name Type Description Default
name str

The name of the field to access.

required

Examples:

>>> import ibis
>>> s = ibis.struct(dict(fruit="pear", weight=0))
>>> s['fruit']
fruit: StructField(frozendict({'fruit': 'pear', 'weight': 0}), field='fruit')

Returns:

Type Description
ir.ValueExpr

An expression with the type of the field being accessed.

destructure(self)

Destructure self into a DestructValue.

When assigned, a destruct value will be destructured and assigned to multiple columns.

Returns:

Type Description
DestructValue

A destruct value expression.

Functions

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)


Last update: March 3, 2022