---
title: Metadata functions
description: PromQL metadata functions in Elasticsearch that derive new labels from existing label values.
url: https://www.elastic.co/elastic/docs-builder/docs/4561/reference/query-languages/promql/functions/metadata
products:
  - Elasticsearch
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Planned
---

# Metadata functions
These functions derive a new label, or overwrite an existing one, from the values of other labels.

## `label_join`

<applies-to>Elastic Stack: Planned</applies-to>
Joins the values of the source labels `src_label_1` .. `src_label_N` using `separator` and stores the result in the label `dst_label`. A missing source label contributes an empty string.
The destination can be a new label or an existing stored label (a dimension or `__name__`).
<applies-to>Elastic Stack: Planned</applies-to> <applies-to>Elastic Cloud Serverless: Generally available</applies-to> A call over a `by(...)` aggregation, directly or under `topk`, `bottomk`, `limitk`, or `limit_ratio`, is supported when the destination is a new label, such as `label_replace(sum by (job) (x), "dst", "$1", "job", "(.*)")`.
**Return type**
`instant_vector`
**Parameters**
<definitions>
  <definition term="v (instant_vector)">
    Instant vector input.
  </definition>
  <definition term="dst_label (scalar)">
    Name of the label to set.
  </definition>
  <definition term="separator (scalar)">
    String inserted between the source values.
  </definition>
  <definition term="src_label (scalar)">
    Name of a label to join (repeatable).
  </definition>
</definitions>

**Example**
```
sum by (endpoint) (label_join(http_requests_total, "endpoint", "/", "job", "instance"))
```

<note>
  **Differences from Prometheus**A call that isn't aggregated or is under `without(...)`, and a destination label named `step`, which is an output column of the `PROMQL` command, aren't supported yet.<applies-to>Elastic Stack: Planned</applies-to> A call over an aggregation, such as `label_replace(sum by (job) (x), ...)`, isn't supported yet.<applies-to>Elastic Stack: Planned</applies-to> <applies-to>Elastic Cloud Serverless: Generally available</applies-to> A call over anything other than a `by(...)` aggregation, such as `sum(x)`, a `without(...)` aggregation, `topk`, or a binary operator, and a call that overwrites a grouping label, such as `label_replace(sum by (job) (x), "job", "$1", "job", "(.*)")`, aren't supported yet. Write a new label instead.Reading or overwriting `__name__` behaves like Prometheus only for Prometheus-style data that stores `__name__` as a label; for OpenTelemetry-style metrics the metric name is not exposed as a readable or writable label here.
</note>


## `label_replace`

<applies-to>Elastic Stack: Planned</applies-to>
Matches the regular expression `regex` against the value of the label `src_label`. On a match, sets the label `dst_label` to the expansion of `replacement`, substituting `$1`, `$name`, and `${name}` with the matched capture groups; on no match the input series is returned unchanged.
The destination can be a new label or an existing stored label (a dimension or `__name__`). Regular expressions use the RE2 engine (RE2 syntax including `(?P<name>)`, `$1`/`$name`/`${name}` replacement expansion, no backreferences, fully anchored as `^(?s:regex)$`), matching Prometheus.
<applies-to>Elastic Stack: Planned</applies-to> <applies-to>Elastic Cloud Serverless: Generally available</applies-to> A call over a `by(...)` aggregation, directly or under `topk`, `bottomk`, `limitk`, or `limit_ratio`, is supported when the destination is a new label, such as `label_replace(sum by (job) (x), "dst", "$1", "job", "(.*)")`.
**Return type**
`instant_vector`
**Parameters**
<definitions>
  <definition term="v (instant_vector)">
    Instant vector input.
  </definition>
  <definition term="dst_label (scalar)">
    Name of the label to set.
  </definition>
  <definition term="replacement (scalar)">
    Replacement value, with `$1`/`$name`/`${name}` capture-group expansion.
  </definition>
  <definition term="src_label (scalar)">
    Name of the label to read.
  </definition>
  <definition term="regex (scalar)">
    Regular expression matched against `src_label`.
  </definition>
</definitions>

**Example**
```
sum by (job2) (label_replace(http_requests_total, "job2", "$1", "job", "(.*)-server"))
```

<note>
  **Differences from Prometheus**A call that isn't aggregated or is under `without(...)`, and a destination label named `step`, which is an output column of the `PROMQL` command, aren't supported yet.<applies-to>Elastic Stack: Planned</applies-to> A call over an aggregation, such as `label_replace(sum by (job) (x), ...)`, isn't supported yet.<applies-to>Elastic Stack: Planned</applies-to> <applies-to>Elastic Cloud Serverless: Generally available</applies-to> A call over anything other than a `by(...)` aggregation, such as `sum(x)`, a `without(...)` aggregation, `topk`, or a binary operator, and a call that overwrites a grouping label, such as `label_replace(sum by (job) (x), "job", "$1", "job", "(.*)")`, aren't supported yet. Write a new label instead.Reading or overwriting `__name__` behaves like Prometheus only for Prometheus-style data that stores `__name__` as a label; for OpenTelemetry-style metrics the metric name is not exposed as a readable or writable label here.
</note>