Base Expression Types¶
These APIs are shared by both table and column expressions.
Expr
¶
Bases: Immutable
Base expression class.
Functions¶
as_table()
¶
Convert an expression to a table.
compile(limit=None, timecontext=None, params=None)
¶
Compile to an execution target.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
limit |
int | None
|
An integer to effect a specific row limit. A value of |
None
|
timecontext |
TimeContext | None
|
Defines a time range of |
None
|
params |
Mapping[ir.Value, Any] | None
|
Mapping of scalar parameter expressions to value |
None
|
equals(other)
¶
Return whether this expression is structurally equivalent to other
.
If you want to produce an equality expression, use ==
syntax.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
other |
Another expression |
required |
Examples:
>>> import ibis
>>> t1 = ibis.table(dict(a="int"), name="t")
>>> t2 = ibis.table(dict(a="int"), name="t")
>>> t1.equals(t2)
True
>>> v = ibis.table(dict(a="string"), name="v")
>>> t1.equals(v)
False
execute(limit='default', timecontext=None, params=None, **kwargs)
¶
Execute an expression against its backend if one exists.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
limit |
int | str | None
|
An integer to effect a specific row limit. A value of |
'default'
|
timecontext |
TimeContext | None
|
Defines a time range of |
None
|
params |
Mapping[ir.Value, Any] | None
|
Mapping of scalar parameter expressions to value |
None
|
kwargs |
Any
|
Keyword arguments |
{}
|
get_name()
¶
Return the name of this expression.
has_name()
¶
Check whether this expression has an explicit name.
pipe(f, *args, **kwargs)
¶
Compose f
with self
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
f |
If the expression needs to be passed as anything other than the first argument to the function, pass a tuple with the argument name. For example, (f, 'data') if the function f expects a 'data' keyword |
required | |
args |
Any
|
Positional arguments to |
()
|
kwargs |
Any
|
Keyword arguments to |
{}
|
Examples:
>>> import ibis
>>> t = ibis.table([('a', 'int64'), ('b', 'string')], name='t')
>>> f = lambda a: (a + 1).name('a')
>>> g = lambda a: (a * 2).name('a')
>>> result1 = t.a.pipe(f).pipe(g)
>>> result1
r0 := UnboundTable: t
a int64
b string
a: r0.a + 1 * 2
>>> result2 = g(f(t.a)) # equivalent to the above
>>> result1.equals(result2)
True
Returns:
Type | Description |
---|---|
Expr
|
Result type of passed function |
to_csv(path, *, params=None, **kwargs)
¶
Write the results of executing the given expression to a CSV file
This method is eager and will execute the associated expression immediately.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
path |
str | Path
|
The data source. A string or Path to the CSV file. |
required |
params |
Mapping[ir.Scalar, Any] | None
|
Mapping of scalar parameter expressions to value. |
None
|
**kwargs |
Any
|
Additional keyword arguments passed to pyarrow.csv.CSVWriter |
{}
|
to_parquet(path, *, params=None, **kwargs)
¶
Write the results of executing the given expression to a parquet file
This method is eager and will execute the associated expression immediately.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
path |
str | Path
|
The data source. A string or Path to the parquet file. |
required |
params |
Mapping[ir.Scalar, Any] | None
|
Mapping of scalar parameter expressions to value. |
None
|
**kwargs |
Any
|
Additional keyword arguments passed to pyarrow.parquet.ParquetWriter |
{}
|
Examples:
Write out an expression to a single parquet file.
>>> import ibis
>>> penguins = ibis.examples.penguins.fetch()
>>> penguins.to_parquet("penguins.parquet")
Write out an expression to a hive-partitioned parquet file.
>>> import ibis
>>> penguins = ibis.examples.penguins.fetch()
>>> # partition on single column
>>> penguins.to_parquet("penguins_hive_dir", partition_by="year")
>>> # partition on multiple columns
>>> penguins.to_parquet("penguins_hive_dir", partition_by=("year", "island"))
Hive-partitioned output is currently only supported when using DuckDB
to_pyarrow(*, params=None, limit=None, **kwargs)
¶
Execute expression and return results in as a pyarrow table.
This method is eager and will execute the associated expression immediately.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
params |
Mapping[ir.Scalar, Any] | None
|
Mapping of scalar parameter expressions to value. |
None
|
limit |
int | str | None
|
An integer to effect a specific row limit. A value of |
None
|
kwargs |
Any
|
Keyword arguments |
{}
|
Returns:
Type | Description |
---|---|
Table
|
A pyarrow table holding the results of the executed expression. |
to_pyarrow_batches(*, limit=None, params=None, chunk_size=1000000, **kwargs)
¶
Execute expression and return a RecordBatchReader.
This method is eager and will execute the associated expression immediately.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
limit |
int | str | None
|
An integer to effect a specific row limit. A value of |
None
|
params |
Mapping[ir.Value, Any] | None
|
Mapping of scalar parameter expressions to value. |
None
|
chunk_size |
int
|
Maximum number of rows in each returned record batch. |
1000000
|
kwargs |
Any
|
Keyword arguments |
{}
|
Returns:
Type | Description |
---|---|
results
|
RecordBatchReader |
unbind()
¶
Return an expression built on UnboundTable
instead of backend-specific objects.
visualize(format='svg', *, label_edges=False, verbose=False)
¶
Visualize an expression as a GraphViz graph in the browser.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
format |
str
|
Image output format. These are specified by the |
'svg'
|
label_edges |
bool
|
Show operation input names as edge labels |
False
|
verbose |
bool
|
Print the graphviz DOT code to stderr if |
False
|
Raises:
Type | Description |
---|---|
ImportError
|
If |