Complex Type Expressions

These APIs are available on arrays, maps and structs.

ArrayValue

Bases: Value

Functions

length()

Compute the length of an array.

Returns:

Type	Description
IntegerValue	The integer length of self

Examples:

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

unnest()

Unnest an array.

Returns:

Type	Description
ir.Value	Unnested array

StructValue

Bases: Value

Attributes

fields: Mapping[str, dt.DataType] property

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

names: Sequence[str] property

Return the field names of the struct.

types: Sequence[dt.DataType] property

Return the field types of the struct.

Functions

destructure()

Destructure a StructValue into the corresponding struct fields.

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

Returns:

Type	Description
list[AnyValue]	Value expressions corresponding to the struct fields.

lift()

Project the fields of self into a table.

This method is useful when analyzing data that has deeply nested structs or arrays of structs. lift can be chained to avoid repeating column names and table references.

Returns:

Type	Description
Table	A projection with this struct expression's fields.

Examples:

>>> schema = dict(a="struct<b: float, c: string>", d="string")
>>> t = ibis.table(schema, name="t")
>>> t
UnboundTable: t
  a struct<b: float64, c: string>
  d string
>>> t.a.lift()
r0 := UnboundTable: t
  a struct<b: float64, c: string>
  d string

Selection[r0] selections: b: StructField(r0.a, field='b') c: StructField(r0.a, field='c')

See Also

Table.unpack.

MapValue

Bases: Value

Functions

contains(key)

Return whether the map contains key.

Parameters:

Name	Type	Description	Default
key	int | str | ir.IntegerValue | ir.StringValue	Mapping key for which to check	required

Returns:

Type	Description
BooleanValue	Boolean indicating the presence of key in the map expression

get(key, default=None)

Return the value for key from expr.

Return default if key is not in the map.

Parameters:

Name	Type	Description	Default
key	ir.Value	Expression to use for key	required
default	ir.Value | None	Expression to return if key is not a key in expr	None

Returns:

Type	Description
Value	The element type of self

Examples:

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

keys()

Extract the keys of a map.

Returns:

Type	Description
ArrayValue	The keys of self

Examples:

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

length()

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

Returns:

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

Extract the values of a map.

Returns:

Type	Description
ArrayValue	The values of self

Examples:

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

---

Last update: August 5, 2022