Record.RenameFields Function in Power Query M (4 Examples)

If you want to rename one or more fields in a record, and keep everything else exactly as it is, the Record.RenameFields function is what you reach for. It returns a new record with the old field names swapped for the new ones, while the values and their positions stay put. Available in Excel (Power Query), Power BI Desktop, and Power BI Service.

Table of Contents

Syntax of Record.RenameFields Function

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

where

record (required, record). The source record whose fields you want to rename.
renames (required, list). The old-to-new name pairs. A single rename is a flat two-item list like {"OldName","NewName"}. For more than one rename, you nest those pairs into a list like {{"o1","n1"},{"o2","n2"}}.
missingField (optional, nullable number). Controls what happens when you try to rename a field the record does not have. Leave it out and a missing name raises an error. Pass MissingField.Ignore to silently skip it.

Returns: a new record with the named fields renamed. Values and field order stay the same. The original record is left unchanged.

In plain terms, you hand it a record and a set of old-name-to-new-name pairs, and it gives you back the same record with those fields renamed.

Example 1: Rename a single field

A single rename uses a flat two-item list: the old name first, the new name second.

Say you have a record with fname, city, and age, and you want to rename fname to FirstName.

let
    Source = Record.RenameFields([fname="Ava",city="Pune",age=29],{"fname","FirstName"})
in
    Source

Result: [FirstName = "Ava", city = "Pune", age = 29]

Only the name changed. The value "Ava" and the field’s first position both stayed the same.

Example 2: Rename multiple fields at once

This is where people slip up. For more than one rename, you cannot just list the names flat. You nest each old-to-new pair inside an outer list.

Here you have three messy field names to clean up in one go.

let
    Source = Record.RenameFields([cust_id=1001,sales_amt=250.5,region="East"],{{"cust_id","CustomerID"},{"sales_amt","Amount"},{"region","Region"}})
in
    Source

Result: [CustomerID = 1001, Amount = 250.5, Region = "East"]

Each {old,new} pair sits inside the outer {...}. Passing {"cust_id","CustomerID","sales_amt","Amount"} as one flat list would be wrong.

Example 3: Skip a rename for a field that is not there

Naming a field the record does not have throws an error by default. You get Expression.Error: The field 'lname' of the record wasn't found.

To skip a missing rename instead of erroring, pass MissingField.Ignore as the third argument.

This record has fname and city. You ask to rename both fname and lname, but lname is not there.

let
    Source = Record.RenameFields([fname="Ava",city="Pune"],{{"fname","FirstName"},{"lname","LastName"}},MissingField.Ignore)
in
    Source

Result: [FirstName = "Ava", city = "Pune"]

fname was renamed to FirstName, and the missing lname rename was quietly skipped instead of throwing.

Example 4: Rename a field across every row of a table

Record.RenameFields works on a single record, so to use it across a table you run it per row with Table.TransformRows, then turn the records back into a table with Table.FromRecords.

Here is the starting data:

fname	city
Ava	Pune
Ben	Delhi
Cara	Mumbai

Rename the fname field to FirstName on each row:

let
    Source = Excel.CurrentWorkbook(){[Name="People"]}[Content],
    Renamed = Table.TransformRows(Source,each Record.RenameFields(_,{"fname","FirstName"})),
    Back = Table.FromRecords(Renamed)
in
    Back

Each row was a record, so Record.RenameFields renamed its fname field the same way it did the single records above.

The result keeps the same values, with the column now named FirstName:

FirstName	city
Ava	Pune
Ben	Delhi
Cara	Mumbai

For a whole table like this, Table.RenameColumns is the simpler one-liner. The per-row trick is mainly for when you are already working inside records.

Things to keep in mind with Record.RenameFields

Single rename is flat, multiple is nested. One rename is {"old","new"}. Two or more must be {{"o1","n1"},{"o2","n2"}}. Passing several names in one flat list is the most common mistake.
Old name comes first, new name second. Each pair reads {old,new}. Reversing them renames the wrong way or errors if the “new” name is not actually in the record.
Field names are case-sensitive. "Fname" will not match a field called fname, so it counts as missing and throws unless you pass MissingField.Ignore.
A missing field throws by default. Renaming a field the record does not have raises Expression.Error: The field 'X' of the record wasn't found. Pass MissingField.Ignore to skip it.
For a whole table, use Table.RenameColumns. It renames columns across every row directly, no per-row record handling needed.
It renames, it does not subset. Every field stays in the result. To read a single renamed value back out, reach for Record.Field with the new name.

Common questions about Record.RenameFields

What is the difference between Record.RenameFields and Table.RenameColumns?

Record.RenameFields renames fields in one record at a time, while Table.RenameColumns renames columns across an entire table. Use the record version when you are inside a single row, and the table version for the whole dataset.

Does renaming a field move it to the end of the record?

No. The renamed field keeps its original position. Only its name changes, so the field order you see in the result matches the input.

List of All Power Query Functions

Related Power Query Functions / Articles: