Record.AddField

Record

Returns a new record with an additional field added. Raises an error if the field already exists.

Syntax

Record.AddField(record as record, fieldName as text, value as any, optional delayed as nullable logical) as record

Parameters

Name	Type	Required	Description
`record`	`record`	Yes	The source record.
`fieldName`	`text`	Yes	The name of the field to add.
`value`	`any`	Yes	The value to assign to the new field.
`delayed`	`logical`	No	When true, the value expression is evaluated lazily. Defaults to false.

Return Value

record — A new record with the specified field added.

Remarks

Record.AddField returns a new record with one additional field appended. Records in M are immutable — the original record is never modified; a new record is always returned. If the field name already exists in the record, an error is raised. To replace an existing field, use Record.RemoveFields to drop it first, then Record.AddField.

For simple cases where you want to merge two records, the record merge operator & is often more concise: [A = 1] & [B = 2] produces [A = 1, B = 2]. Use Record.AddField when the field name or value is computed dynamically.

The optional delayed parameter (true/false) controls whether the value expression is evaluated eagerly (default, false) or lazily (only when the field is first accessed, true). Lazy evaluation is useful for expensive computations that may not always be needed.

Examples

Example 1: Add a new text field to a record

Record.AddField([Name = "Alice", Age = 30], "City", "New York")

Result

	Name	Age	City
1	Alice	30	New York

Example 2: Add a computed field from existing field values

let
    R = [UnitPrice = 25, Quantity = 4]
in
    Record.AddField(R, "Total", R[UnitPrice] * R[Quantity])

Result

	UnitPrice	Quantity	Total
1	25	4	100

Example 3: Add a "Status" field to the first row of the Sales table

let
    Row = Sales{0},
    WithStatus = Record.AddField(Row, "Status", "Processed")
in
    Record.SelectFields(WithStatus, {"OrderID", "CustomerName", "Product", "Status"})

Applied Steps

The final output — selects only OrderID, CustomerName, Product, and Status from the enriched record.

	OrderID	CustomerName	Product	Status
1	1	Alice	Widget A	Processed

Compatibility

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