Record.RenameFields - Record Function

Record.RenameFields is a Power Query M function that renames fields in a record to the new field names specified in a list. The function returns a new record with the fields renamed according to the provided renames list.

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

Syntax

Record.RenameFields(
   record as record,
   renames as list,
   optional missingField as nullable number,
) as record

Argument	Attribute	Description
record		A record value to rename fields in.
renames		A list of values to rename values in.
missingField	optional	The MissingField.Type determines the function’s reaction to operations on missing columns. When omitted, it uses MissingField.Error and generates an error for missing columns. Alternatives include MissingField.UseNull, substituting null for missing columns, and MissingField.Ignore, which ignores missing columns.

Description

Record.RenameFields applies new names to existing fields in a record based on a list of rename pairs provided in renames. For multiple renames, a list of such pairs is used to update the record’s field names accordingly. In case the specified field does not exist, the function returns an error by default. You can change this behavior by providing an optional MissingField.Type.

Examples

Renaming a Single Field

Let’s start with a simple example. Suppose we have a record containing different fruits. The fruit Peach is categorized as StoneFruit. However, you want to rename this category to “Rose”. You can use the Record.RenameFields function to do this.

//Output: // [Citrus = "Orange", Berry = "Strawberry", Rose = "Peach" ]
let
  myRecord = [Citrus = "Orange", Berry = "Strawberry", StoneFruit = "Peach"],
  Rename = 
    Record.RenameFields( 
      myRecord, 
      {"StoneFruit", "Rose" } 
    )
in
  Rename

In this example, the Record.RenameFields function takes two arguments:

The original record (myRecord).
A list containing a pair of the old field name (“StoneFruit”) and the new field name (“Rose”).

The function then returns a new record with the field name changed from StoneFruit to Rose. Notice that the second argument of Record.RenameFields contains a list of pairs with the old and new field names. We can use a simplified notation here using a single pair of curly brackets.

Renaming Multiple Fields

There are times when you might want to rename more than one field at a time. The Record.RenameFields function can handle this by accepting a list of lists, where each inner list contains a pair of old and new field names.

For instance, let’s say you also want to rename the field Berry to “Rose”, as strawberries are part of the rose family. Here’s how you can do it:

//Output: // [Citrus = "Orange", Berry = "Strawberry", Rose = "Peach" ]
let
  myRecord = [Citrus = "Orange", Berry = "Strawberry", StoneFruit = "Peach"],
  Rename = 
    Record.RenameFields( 
      myRecord, 
      {{"Berry", "Rose"}, {"StoneFruit", "Rose" }}
    )
in
  Rename

In this example:

The outer list contains two inner lists: {"Berry", "Rose"} and {"StoneFruit", "Rose"}.
The function renames both the Berry and StoneFruit fields to Rose.

This syntax is useful when you need to update multiple fields.

Handling Missing Fields

It’s important to be aware of what happens if you try to rename a field that doesn’t exist in your record. By default, if the field name you want to rename is not found, the Record.RenameFields function will return an error.

Here’s an example:

//Output: // [Expression.Error] The field 'Stone' of the record wasn't found.
let
  myRecord = [Citrus = "Orange", Berry = "Strawberry", StoneFruit = "Peach"],
  Rename = Record.RenameFields( myRecord, {"Stone", "Rose" } )
in
  Rename

In this case, there is no field named Stone in the original record, so the function throws an error.

To handle situations where the field might not exist, the M language offers the MissingField.Type enumeration. This allows you to specify different behaviors when a field is missing.

Default Behavior: MissingField.Error

The MissingField.Error, enumeration returns an error if a field is not found. This is the default behavior used by Record.RenameFields, even when not explicitly mentioning a MissingField.Type in the third argument.

//Output: // [Expression.Error] The field 'Stone' of the record wasn't found.
let
  myRecord = [Citrus = "Orange", Berry = "Strawberry", StoneFruit = "Peach"],
  Rename = Record.RenameFields( myRecord, {"Stone", "Rose" }, MissingField.Error )
in
  Rename

Ignore Missing Fields: MissingField.Ignore

If you prefer the function to ignore missing fields and proceed with renaming the existing ones, you can use MissingField.Ignore. This option skips the renaming operation for fields that do not exist.

//Output: // [Citrus = "Orange", Berry = "Strawberry", StoneFruit = "Peach"]
let
  myRecord = [Citrus = "Orange", Berry = "Strawberry", StoneFruit = "Peach"],
  Rename = Record.RenameFields( myRecord, {"Stone", "Rose" }, MissingField.Ignore)
in
  Rename

In this example, the function skips the attempt to rename Stone to Rose and leaves the original record unchanged.

Add Missing Fields as Null: MissingField.UseNull

Another option is MissingField.UseNull. When this setting is used, the function will add a new field with a null value if the specified field to rename does not exist.

//Output: // [Citrus = "Orange", Berry = "Strawberry", StoneFruit = "Peach", Rose = null ]
let
  myRecord = [Citrus = "Orange", Berry = "Strawberry", StoneFruit = "Peach"],
  Rename = Record.RenameFields( myRecord, {"Stone", "Rose" }, MissingField.UseNull )
in
  Rename

In this scenario, a new field named Rose is added to the record with a value of null because the original field Stone was not found.

Other functions related to Record.RenameFields are:

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