Skip to content

Complex Type Expressions

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

arrays

Classes

ArrayValue (Value)

Methods
length(self)

Compute the length of an array.

Returns

IntegerValue The integer length of self

Examples

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

unnest(self)

Unnest an array.

Returns

ir.Value Unnested array

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

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

maps

Classes

MapValue (Value)

Methods
get(self, key, default=None)

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

Parameters

key Expression to use for key default Expression to return if key is not a key in expr

Returns

Value The element type of self

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)

keys(self)

Extract the keys of a map.

Returns

ArrayValue The keys of self

Examples

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

length(self)

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

Returns

IntegerValue The number of elements in self

Examples

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

values(self)

Extract the values of a map.

Returns

ArrayValue The values of self

Examples

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

Functions

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

structs

Classes

StructColumn (Column, StructValue)

Methods
destructure(self)

Destructure self into a DestructColumn.

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

Returns

DestructColumn A destruct column expression.

StructScalar (Scalar, StructValue)

Methods
destructure(self)

Destructure self into a DestructScalar.

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

Returns

DestructScalar A destruct scalar expression.

StructValue (Value)

Attributes
fields: Mapping[str, dt.DataType] cached property writable

Return a mapping from field name to field type of the struct.

names: Sequence[str] cached property writable

Return the field names of the struct.

types: Sequence[dt.DataType] cached property writable

Return the field types of the struct.

Methods
__getattr__(self, name) special

Extract the name field from this struct.

__getitem__(self, name) special

Extract the name field from this struct.

Parameters

name The name of the field to access.

Returns

Value An expression with the type of the field being accessed.

Examples

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

destructure(self)

Destructure self into a DestructValue.

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

Returns

DestructValue A destruct value expression.

Functions

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


Last update: March 3, 2022