flatten pathexpression: col array or object, [suggesttypes: bool]?

Expands a column that holds an object, array, or variant into many rows—one per nested path—while copying the other input columns onto each exploded row.

Use this when you need the full recursive tree with a row for every object and array node; on those intermediate rows the generated value column is null, which makes the nesting shape visible. flatten_leaves drops intermediate nodes entirely, flatten_all keeps nested containers as non-null values on the same paths, and flatten_single expands only one level and leaves deeper structure inside the value column.

The referenced column is removed. New columns include a string path (_c_<column>_path), a variant value column (_c_<column>_value), and a hidden int64 flatten id (_c_<column>_flattenid). The optional second argument suggesttypes must be a constant boolean literal; when true, an extra hidden string column (_c_<column>_type) records the suggested OPAL type name for each value. The path column is appended to any existing primary key, grouping keys are cleared, and the result is no longer strongly keyed. The stage output is a Table dataset even when the input is a Resource. The first argument must be a column path whose static type is object, array, or variant; other types are rejected at compile time.

For similarly nested data, flatten is substantially more expensive than flatten_leaves or flatten_single; prefer those verbs when their narrower output is enough.

Categories

• Semistructured

Accelerable

flatten is always accelerable if the input is accelerable. A dataset that only uses accelerable verbs can be accelerated, making queries on the dataset respond faster.

Examples

make_col doc:parse_json('{"a":1,"b":{"c":2}}')
flatten doc

Turns a nested JSON object into multiple rows, including null value rows for intermediate nodes, and drops the original doc column.

make_col items:parse_json('[{"x":1},{"x":2}]')
flatten items, true

Uses flatten with suggesttypes true so each emitted row also gets a hidden-style type hint column for the flattened value.