Record.AddField - Record Function

Record.AddField is a Power Query M function that adds a field to a record, given the name of the field and its value. The function returns a new record with the specified field added to it.

Compatible with: Power BI Service Power BI Desktop Excel Microsoft 365

Syntax

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

Description

Record.AddField integrates a new field into an existing record with a designated fieldName and assigns it a value. This function expands the record by adding an additional piece of data without altering the existing content.

Examples

Here’s some examples on how to use the Record.AddField function.

Basic Usage of Record.AddField

The Record.AddField function allows you to manually add a field to a record. You can specify the field name in the second argument and the field value in the third argument. Hereâ€™s a basic example:

// Output: [ Name = "Rick", Nationality = "Dutch", Height = 1.91 ]
let
  myRecord = [ Name = "Rick", Nationality = "Dutch" ],
  addField = Record.AddField( myRecord, "Height", 1.91 )
in
  addField

In this example:

myRecord is the original record.
Record.AddField adds a new field “Height” with a value of 1.91.

Handling Existing Fields

The Record.AddField function is meant to add new fields. It will throw an error if you try to add a field that already exists in the record.

// Output: [Expression.Error] The field 'Name' already exists in the record.
let
  myRecord = [ Name = "Rick", Nationality = "Dutch" ],
  addField = Record.AddField( myRecord, "Name", "de Groot" )
in
  addField

If instead you want the operation to overwrite your existing values, you can also combine records. To overwrite existing values, you can use the Record.Combine function or the combination operator (&):

//Output: [ Name = "de Groot", Nationality = "Dutch" ]

// Using Record.Combine
Record.Combine( { [ Name = "Rick", Nationality = "Dutch" ],  [ Name = "de Groot" ] } )

// Using the combination operator &
[ Name = "Rick", Nationality = "Dutch" ] & [ Name = "de Groot" ]

Both methods will update the “Name” field to “de Groot”.

Using the delayed Argument

The Record.AddField function also has an optional fourth argument called delayed. This argument controls whether the value of the new field is evaluated immediately or only when needed (lazily evaluated). This can be particularly useful when the value is expensive to compute or if you want the field to contain the result of a function rather than a function reference.

Example: Using delayed with a Function

Let’s start with a simple example. Imagine you have a function fxMyDate that returns a date.

() as date => #date( 2024, 1, 1 )

If you add this function to a record using Record.AddField without the delayed argument, the record will contain a reference to the function itself, not its result.

// Output: [MyFunction = fxMyDate ]
let
  fxMyDate = () as date => #date( 2024, 1, 1 ),
  addField = Record.AddField( [], "MyFunction", fxMyDate )
in
  addField

To have the record contain the result of the function, you can set the delayed argument to true.

// Output: [MyFunction = #date( 2024, 1, 1 ) ]
let
  fxMyDate = () as date => #date( 2024, 1, 1 ),
  addField = Record.AddField( [], "MyFunction", fxMyDate, true )
in
  addField

By setting delayed to true, Power Query evaluates the function and stores its result (the date #date(2024, 1, 1)) in the record.

Learn more about Record.AddField in the following articles:

Record.AddField(), Functions And The Delayed Option In M
This article explains the purpose of the ‘delayed’ parameter of Record.AddField. » Read more
Dynamic, Lazy Records
In this article you learn how to make evaluation lazy in the Record.Addfield function by using its fourth argument. » Read more

Other functions related to Record.AddField are:

Contribute » | Contributors: Rick de Groot
Microsoft documentation: https://learn.microsoft.com/en-us/powerquery-m/record-addfield