Complex Type Expressions¶
These APIs are available on arrays, maps and structs.
ArrayValue
¶
Bases: Value
Functions¶
__add__(other)
¶
Concatenate this array with another.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
other |
ArrayValue
|
Array to concat with |
required |
Returns:
Type | Description |
---|---|
ArrayValue
|
|
Examples:
>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"a": [[7], [3] , None]})
>>> t
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ a ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int8> │
├──────────────────────┤
│ [7] │
│ [3] │
│ ∅ │
└──────────────────────┘
>>> t.a + t.a
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ ArrayConcat(a, a) ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int8> │
├──────────────────────┤
│ [7, 7] │
│ [3, 3] │
│ ∅ │
└──────────────────────┘
>>> t.a + [4]
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ ArrayConcat(a, (4,)) ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int8> │
├──────────────────────┤
│ [7, 4] │
│ [3, 4] │
│ [4] │
└──────────────────────┘
__getitem__(index)
¶
Extract one or more elements of self
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
index |
int | ir.IntegerValue | slice
|
Index into |
required |
Returns:
Type | Description |
---|---|
Value
|
|
Examples:
Extract a single element
>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"a": [[7, 42], [3], None]})
>>> t.a[0]
┏━━━━━━━━━━━━━━━━━━┓
┃ ArrayIndex(a, 0) ┃
┡━━━━━━━━━━━━━━━━━━┩
│ int8 │
├──────────────────┤
│ 7 │
│ 3 │
│ ∅ │
└──────────────────┘
Extract a range of elements
>>> t = ibis.memtable({"a": [[7, 42, 72], [3] * 5, None]})
>>> t
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ a ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int8> │
├──────────────────────┤
│ [7, 42, ... +1] │
│ [3, 3, ... +3] │
│ ∅ │
└──────────────────────┘
>>> t.a[1:2]
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ ArraySlice(a, 1, 2) ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int8> │
├──────────────────────┤
│ [42] │
│ [3] │
│ ∅ │
└──────────────────────┘
__mul__(n)
¶
Repeat this array n
times.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
n |
int | ir.IntegerValue
|
Number of times to repeat |
required |
Returns:
Type | Description |
---|---|
ArrayValue
|
|
Examples:
>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"a": [[7], [3] , None]})
>>> t
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ a ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int8> │
├──────────────────────┤
│ [7] │
│ [3] │
│ ∅ │
└──────────────────────┘
>>> t.a * 2
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ ArrayRepeat(a, 2) ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int8> │
├──────────────────────┤
│ [7, 7] │
│ [3, 3] │
│ [] │
└──────────────────────┘
__radd__(other)
¶
Concatenate this array with another.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
other |
ArrayValue
|
Array to concat with |
required |
Returns:
Type | Description |
---|---|
ArrayValue
|
|
Examples:
>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"a": [[7], [3] , None]})
>>> t
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ a ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int8> │
├──────────────────────┤
│ [7] │
│ [3] │
│ ∅ │
└──────────────────────┘
>>> [4] + t.a
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ ArrayConcat((4,), a) ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int8> │
├──────────────────────┤
│ [4, 7] │
│ [4, 3] │
│ [4] │
└──────────────────────┘
__rmul__(n)
¶
Repeat this array n
times.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
n |
int | ir.IntegerValue
|
Number of times to repeat |
required |
Returns:
Type | Description |
---|---|
ArrayValue
|
|
Examples:
>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"a": [[7], [3] , None]})
>>> t
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ a ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int8> │
├──────────────────────┤
│ [7] │
│ [3] │
│ ∅ │
└──────────────────────┘
>>> 2 * t.a
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ ArrayRepeat(a, 2) ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int8> │
├──────────────────────┤
│ [7, 7] │
│ [3, 3] │
│ [] │
└──────────────────────┘
filter(predicate)
¶
Filter array elements using predicate
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
predicate |
Callable[[ir.Value], ir.BooleanValue]
|
Function to use to filter array elements |
required |
Returns:
Type | Description |
---|---|
ArrayValue
|
Array elements filtered using |
Examples:
>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"a": [[1, None, 2], [4], []]})
>>> t
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ a ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int8> │
├──────────────────────┤
│ [1, None, ... +1] │
│ [4] │
│ [] │
└──────────────────────┘
>>> t.a.filter(lambda x: x > 1)
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ ArrayFilter(a) ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int8> │
├──────────────────────┤
│ [2] │
│ [4] │
│ [] │
└──────────────────────┘
join(sep)
¶
Join the elements of this array expression with sep
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sep |
str | ir.StringValue
|
Separator to use for joining array elements |
required |
Returns:
Type | Description |
---|---|
StringValue
|
Elements of |
Examples:
>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"arr": [["a", "b", "c"], None, [], ["b", None]]})
>>> t
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ arr ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<string> │
├──────────────────────┤
│ ['a', 'b', ... +1] │
│ ∅ │
│ [] │
│ ['b', None] │
└──────────────────────┘
>>> t.arr.join("|")
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ArrayStringJoin('|', arr) ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ string │
├───────────────────────────┤
│ a|b|c │
│ ∅ │
│ ∅ │
│ b │
└───────────────────────────┘
See Also¶
length()
¶
Compute the length of an array.
Returns:
Type | Description |
---|---|
IntegerValue
|
The integer length of each element of |
Examples:
>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"a": [[7, 42], [3], None]})
>>> t
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ a ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int8> │
├──────────────────────┤
│ [7, 42] │
│ [3] │
│ ∅ │
└──────────────────────┘
>>> t.a.length()
┏━━━━━━━━━━━━━━━━┓
┃ ArrayLength(a) ┃
┡━━━━━━━━━━━━━━━━┩
│ int64 │
├────────────────┤
│ 2 │
│ 1 │
│ ∅ │
└────────────────┘
map(func)
¶
Apply a callable func
to each element of this array expression.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
func |
Callable[[ir.Value], ir.Value]
|
Function to apply to each element of this array |
required |
Returns:
Type | Description |
---|---|
ArrayValue
|
|
Examples:
>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"a": [[1, None, 2], [4], []]})
>>> t
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ a ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int8> │
├──────────────────────┤
│ [1, None, ... +1] │
│ [4] │
│ [] │
└──────────────────────┘
>>> t.a.map(lambda x: (x + 100).cast("float"))
┏━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ArrayMap(a) ┃
┡━━━━━━━━━━━━━━━━━━━━━━━┩
│ array<float64> │
├───────────────────────┤
│ [101.0, None, ... +1] │
│ [104.0] │
│ [] │
└───────────────────────┘
unnest()
¶
Flatten an array into a column.
This operation changes the cardinality of the result
Examples:
>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"a": [[7, 42], [3, 3] , None]})
>>> t
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃ a ┃
┡━━━━━━━━━━━━━━━━━━━━━━┩
│ array<int8> │
├──────────────────────┤
│ [7, 42] │
│ [3, 3] │
│ ∅ │
└──────────────────────┘
>>> t.a.unnest()
┏━━━━━━┓
┃ a ┃
┡━━━━━━┩
│ int8 │
├──────┤
│ 7 │
│ 42 │
│ 3 │
│ 3 │
└──────┘
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¶
__getattr__(name)
¶
Extract the name
field from this struct.
__getitem__(name)
¶
Extract the name
field from this struct.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
name |
str
|
The name of the field to access. |
required |
Returns:
Type | Description |
---|---|
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(...)
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:
>>> import ibis
>>> ibis.options.interactive = True
>>> lines = '''
... {"pos": {"lat": 10.1, "lon": 30.3}}
... {"pos": {"lat": 10.2, "lon": 30.2}}
... {"pos": {"lat": 10.3, "lon": 30.1}}
... '''
>>> with open("/tmp/lines.json", "w") as f:
... _ = f.write(lines)
>>> t = ibis.read_json("/tmp/lines.json")
>>> t
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ pos ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ struct<lat: float64, lon: float64> │
├────────────────────────────────────┤
│ {'lat': 10.1, 'lon': 30.3} │
│ {'lat': 10.2, 'lon': 30.2} │
│ {'lat': 10.3, 'lon': 30.1} │
└────────────────────────────────────┘
>>> t.pos.lift()
┏━━━━━━━━━┳━━━━━━━━━┓
┃ lat ┃ lon ┃
┡━━━━━━━━━╇━━━━━━━━━┩
│ float64 │ float64 │
├─────────┼─────────┤
│ 10.1 │ 30.3 │
│ 10.2 │ 30.2 │
│ 10.3 │ 30.1 │
└─────────┴─────────┘
See Also¶
MapValue
¶
Bases: Value
Functions¶
__add__(other)
¶
Concatenate this map with another.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
other |
MapValue
|
Map to concatenate with |
required |
Returns:
Type | Description |
---|---|
MapValue
|
|
Examples:
>>> import ibis
>>> m1 = ibis.map({"a": 1, "b": 2})
>>> m2 = ibis.map({"c": 3, "d": 4})
>>> m1 + m2
MapMerge(...)
__getitem__(key)
¶
Get the value for a given map key
.
This operation may have different semantics depending on the backend.
Some backends return NULL
when a key is missing, others may fail
the query.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
key |
ir.Value
|
A map key |
required |
Returns:
Type | Description |
---|---|
Value
|
An element with the value type of the map |
Examples:
>>> import ibis
>>> m = ibis.map({"a": 1, "b": 2})
>>> m["a"]
MapGet(...)
>>> m["c"] # note that this does not fail on construction
MapGet(...)
__radd__(other)
¶
Concatenate this map with another.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
other |
MapValue
|
Map to concatenate with |
required |
Returns:
Type | Description |
---|---|
MapValue
|
|
Examples:
>>> import ibis
>>> m1 = ibis.map({"a": 1, "b": 2})
>>> m2 = ibis.map({"c": 3, "d": 4})
>>> m1 + m2
MapMerge(...)
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 |
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 |
None
|
Returns:
Type | Description |
---|---|
Value
|
The element type of |
Examples:
>>> import ibis
>>> m = ibis.map({"a": 1, "b": 2})
>>> m.get("a")
MapGet(...)
>>> m.get("c", 3)
MapGet(...)
>>> m.get("d")
MapGet(...)
keys()
¶
Extract the keys of a map.
Returns:
Type | Description |
---|---|
ArrayValue
|
The keys of |
Examples:
>>> import ibis
>>> m = ibis.map({"a": 1, "b": 2})
>>> m.keys()
MapKeys(...)
length()
¶
Return the number of key-value pairs in the map.
Returns:
Type | Description |
---|---|
IntegerValue
|
The number of elements in |
Examples:
>>> import ibis
>>> m = ibis.map({"a": 1, "b": 2})
>>> m.length()
MapLength(...)
values()
¶
Extract the values of a map.
Returns:
Type | Description |
---|---|
ArrayValue
|
The values of |
Examples:
>>> import ibis
>>> m = ibis.map({"a": 1, "b": 2})
>>> m.values()
MapValues(...)