Record.RenameFields
RecordRenames one or more fields in a record by specifying a list of {oldName, newName} pairs.
Syntax
Record.RenameFields(record as record, renames as list, optional missingField as nullable number) as recordParameters
| Name | Type | Required | Description |
|---|---|---|---|
record | record | Yes | The source record. |
renames | list | Yes | A list of {oldFieldName, newFieldName} pairs. Each element is a two-item list. |
missingField | number | No | Controls behavior when a specified old field name does not exist: MissingField.Error (default), MissingField.Ignore, or MissingField.UseNull. |
Return Value
record — A new record with the specified fields renamed.
Remarks
Record.RenameFields returns a new record with specified fields renamed. The renames parameter is a list of two-element lists, each containing {oldName, newName}. Multiple renames can be specified in a single call and are applied simultaneously (not sequentially), so renaming A to B and B to A in the same call correctly swaps the field names.
Field values and field order are preserved — only the names change. The function returns a new record; the original is unchanged.
The optional missingField parameter controls behavior when an old field name is not found in the record:
- MissingField.Error (default, 0) — raises an error; use this when renames must always succeed
- MissingField.Ignore (1) — silently skips missing renames; use this for defensive or optional renaming
- MissingField.UseNull (2) — adds a new field with a null value even though the old field was absent
For table-level column renaming, use Table.RenameColumns, which has an equivalent missingField parameter.
Examples
Example 1: Rename a single field
Record.RenameFields([Name = "Alice", Age = 30], {{"Name", "FullName"}})FullName | Age | |
|---|---|---|
| 1 | Alice | 30 |
Example 2: Rename multiple fields in a single call
Record.RenameFields(
[Nm = "Bob", Ag = 25, Ct = "Seattle"],
{{"Nm", "Name"}, {"Ag", "Age"}, {"Ct", "City"}}
)Name | Age | City | |
|---|---|---|---|
| 1 | Bob | 25 | Seattle |
Example 3: Skip missing fields gracefully with MissingField.Ignore
Record.RenameFields(
[Name = "Alice", Age = 30],
{{"Name", "FullName"}, {"Email", "EmailAddress"}},
MissingField.Ignore
)FullName | Age | |
|---|---|---|
| 1 | Alice | 30 |