daft.functions.explode#

def explode(list_expr: Expression, ignore_empty_and_null: bool = False) -> Expression:
    """Explode a list expression.

    A row is created for each item in the lists, and the other non-exploded output columns are broadcasted to match.

    If exploding multiple columns at once, all list lengths must match.

    Note:
        Since this changes the cardinality of the dataframe, We only allow a single explode per projection (`select`, `with_columns`)
        If you need to do multiple explodes, each one must be done separately.

    Args:
        list_expr (List Expression): expression to explode.
        ignore_empty_and_null: If True, drops rows where the list is empty or null.
            If False (default), empty lists and null values each produce a single row with a null value.

    Returns:
        Expression: Expression representing the exploded list.

    Tip: See also
        [`DataFrame.explode`](https://docs.daft.ai/en/stable/api/dataframe/#daft.DataFrame.explode)

    Examples:
        Explode one column, broadcast the rest:

        >>> import daft
        >>> from daft.functions import explode
        >>>
        >>> df = daft.from_pydict({"id": [1, 2, 3], "sentence": ["lorem ipsum", "foo bar baz", "hi"]})
        >>>
        >>> df.with_column("word", explode(df["sentence"].split(" "))).show()
        ╭───────┬─────────────┬────────╮
        │ id    ┆ sentence    ┆ word   │
        │ ---   ┆ ---         ┆ ---    │
        │ Int64 ┆ String      ┆ String │
        ╞═══════╪═════════════╪════════╡
        │ 1     ┆ lorem ipsum ┆ lorem  │
        ├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
        │ 1     ┆ lorem ipsum ┆ ipsum  │
        ├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
        │ 2     ┆ foo bar baz ┆ foo    │
        ├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
        │ 2     ┆ foo bar baz ┆ bar    │
        ├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
        │ 2     ┆ foo bar baz ┆ baz    │
        ├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌┤
        │ 3     ┆ hi          ┆ hi     │
        ╰───────┴─────────────┴────────╯
        <BLANKLINE>
        (Showing first 6 of 6 rows)

        Explode multiple columns with the same lengths:

        >>> df.select(
        ...     explode(df["sentence"].split(" ")).alias("word"),
        ...     explode(df["sentence"].capitalize().split(" ")).alias("capitalized_word"),
        ... ).show()
        ╭────────┬──────────────────╮
        │ word   ┆ capitalized_word │
        │ ---    ┆ ---              │
        │ String ┆ String           │
        ╞════════╪══════════════════╡
        │ lorem  ┆ Lorem            │
        ├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
        │ ipsum  ┆ ipsum            │
        ├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
        │ foo    ┆ Foo              │
        ├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
        │ bar    ┆ bar              │
        ├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
        │ baz    ┆ baz              │
        ├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
        │ hi     ┆ Hi               │
        ╰────────┴──────────────────╯
        <BLANKLINE>
        (Showing first 6 of 6 rows)
        >>>

        This will error because exploded lengths are different:

        >>> # df.select(
        >>> #     df["sentence"]
        >>> #             .split(" ")
        >>> #             .explode()
        >>> #             .alias("word"),
        >>> #     df["sentence"]
        >>> #             .split("a")
        >>> #             .explode()
        >>> #             .alias("split_on_a")
        >>> # ).show()
    """
    from daft.expressions import lit

    return Expression._call_builtin_scalar_fn("explode", list_expr, lit(ignore_empty_and_null))