Table.CombineColumnsToRecord

Table

Combines selected columns into a single record column.

Syntax

Table.CombineColumnsToRecord(table as table, newColumnName as text, sourceColumns as list, optional options as nullable record) as table

Parameters

Name	Type	Required	Description
`table`	`table`	Yes	The table to process.
`newColumnName`	`text`	Yes	The name of the new record column.
`sourceColumns`	`list`	Yes	A list of column names to combine into a record.
`options`	`record`	No	Optional record. Supports DisplayNameColumn (text) to specify which field name to use as the display name for the record column.

Return Value

table — The original table with the specified columns replaced by a single record column.

Remarks

Table.CombineColumnsToRecord packages multiple columns into a single column where each cell is a record. The source columns are removed and replaced by the new record column. This is useful for passing structured sub-objects downstream or for reshaping data before expanding with Table.ExpandRecordColumn.

The field names in the resulting records match the original column names.

Examples

Example 1: Combine address columns into a record

Table.CombineColumnsToRecord(
    #table({"Name", "City", "Country"}, {{"Alice", "Paris", "France"}, {"Bob", "Tokyo", "Japan"}}),
    "Address",
    {"City", "Country"}
)

Result

	Name	Address
1	Alice	[City = "Paris", Country = "France"]
2	Bob	[City = "Tokyo", Country = "Japan"]

Example 2: Round-trip with ExpandRecordColumn

let
    Source   = #table({"ID", "X", "Y"}, {{1, 10, 20}, {2, 30, 40}}),
    Combined = Table.CombineColumnsToRecord(Source, "Coords", {"X", "Y"}),
    Expanded = Table.ExpandRecordColumn(Combined, "Coords", {"X", "Y"})
in
    Expanded

Applied Steps

The final output — expands the Coords record column back into separate X and Y columns, restoring the original flat structure.

	ID	X	Y
1	1	10	20
2	2	30	40

Compatibility

✓ Power BI Desktop✓ Power BI Service✓ Excel Desktop✓ Excel Online✓ Dataflows✓ Fabric Notebooks