Value.ReplaceMetadata - Value Function

Value.ReplaceMetadata is a Power Query M function that replaces the input value’s metadata information. The function returns the input value with updated metadata.

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

Syntax

Value.ReplaceMetadata(
   value as any,
   metaValue as any,
) as any

Description

The Value.ReplaceMetadata function assigns or updates the metadata associated with a value. It replaces all the existing metadata of a value with the specified record of metadata properties.

Examples

Example 1: Attaching Metadata to a Value

To attach metadata to a value, you can use the Value.ReplaceMetadata function. For example, let’s assign metadata to the number 2025:

// Returns: 2025 meta [ Year = "Year of the Horse", Quality = "Intuitive" ]
Value.ReplaceMetadata(
  2025, 
  [ Year = "Year of the Horse", Quality = "Intuitive" ]
)

This is equivalent to directly using the meta keyword but provides a more explicit and programmatic way to assign metadata.

Example 2: Replacing Existing Metadata

If a value already has metadata, the Value.ReplaceMetadata function removes all existing metadata and replaces it with the specified record. Here’s how it works:

// Returns: [ Year = "Year of the Monkey", QueryFolding = error ]
let
  MetaValue = 2025 meta [ Year = "Year of the Horse", Quality = "Intuitive" ],
  ReplaceMeta = 
    Value.ReplaceMetadata(
      MetaValue, 
      [ Year = "Year of the Monkey" ]
    ),
  Meta = Value.Metadata( ReplaceMeta )
in
  Meta

What happens here?

Input Metadata: The value 2025 initially has metadata indicating the “Year of the Horse” and “Intuitive” as a quality.
Updated Metadata: After applying Value.ReplaceMetadata, the metadata is replaced with only one property: "Year = Year of the Monkey".
System Metadata: The QueryFolding metadata field remains visible. We can’t remove this field.

This shows that Value.ReplaceMetadata completely overwrites the existing metadata, including custom annotations.

Example 3: Adding or Updating Metadata Partially

If you need to add metadata properties without overwriting the entire record, the meta keyword is a better option. For example:

// Result: 2025 meta [ Year = "Year of the Horse", Quality = "Intuitive", ID = 1 ]
2025 meta [ Year = "Year of the Horse", Quality = "Intuitive" ] meta [ ID = 1 ]

Learn more about Value.ReplaceMetadata in the following articles:

Power Query M Primer (Part 20): Metadata
The article explains how Power Query allows attaching metadata—additional information—to values. It specifies methods to inspect, set, and merge metadata, and discusses its applications, such as parameter configuration in Power BI. » Read more

Other functions related to Value.ReplaceMetadata are:

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