Value.ReplaceMetadata

Value

Returns a copy of a value with its metadata replaced by the given metadata record.

Syntax

Value.ReplaceMetadata(value as any, metadataRecord as record) as any

Parameters

Name	Type	Required	Description
`value`	`any`	Yes	The value whose metadata is replaced.
`metadataRecord`	`record`	Yes	The new metadata record to attach to the value.

Return Value

any — The same value with its metadata replaced by metadataRecord.

Remarks

Value.ReplaceMetadata attaches a new metadata record to a value, replacing any existing metadata entirely. It is the function form of the value meta record M expression — Value.ReplaceMetadata(v, r) is equivalent to v meta r.

Metadata is supplementary information carried alongside a value without changing the value itself. The underlying data, type kind, and equality semantics are all unaffected — Value.ReplaceMetadata(42, [Tag = "x"]) is still equal to 42.

Important behaviors:

- Full replacement: Value.ReplaceMetadata discards all previous metadata and replaces it with the provided record. It does not merge. To add fields to existing metadata without losing others, use the pattern: Value.ReplaceMetadata(v, Record.Combine({Value.Metadata(v), [NewField = "value"]})). - Lost on operations: most M operations (arithmetic, string operations, table transforms) strip metadata from their outputs. Metadata must be explicitly re-attached if needed after a transformation. - Engine use: Power Query uses metadata internally to carry display format hints, column descriptions (Documentation.FieldCaption), and data source provenance information.

Examples

Example 1: Attach a metadata record to a number

let
    Annotated = Value.ReplaceMetadata(42, [Source = "Calculated", Verified = true]),
    Meta = Value.Metadata(Annotated)
in
    Meta[Source]

Applied Steps

The final output — accesses the Source field from the metadata record, returning "Calculated".

	Result
1	Calculated

Example 2: Replace existing metadata — old fields are discarded

let
    Original = "hello" meta [Tag = "old"],
    Updated = Value.ReplaceMetadata(Original, [Tag = "new"]),
    Meta = Value.Metadata(Updated)
in
    Meta[Tag]

Applied Steps

The final output — accesses the Tag field from the new metadata record, returning "new" to confirm the replacement.

	Result
1	new

Example 3: The underlying value is unchanged by metadata replacement

let
    Annotated = Value.ReplaceMetadata(100, [Note = "special"])
in
    Annotated + 5

Result

	Result
1	105

Compatibility

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