---
schema_version: "1"
id: d9256cafd82d092c2340776abdc068c1f854abf8379ad3edc973d936fd229cb6
title: DataWeave Selectors
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/dataweave/2.6/dataweave-selectors.md
canonical_url: https://docs.mulesoft.com/dataweave/2.6/dataweave-selectors
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 21b7b6429ccee3719100605f5f69dee75546670b04d72e3b2e73c23864caeb84
description: MuleSoft Documentation Site
release: "2.6"
latest: false
---
---
product: DataWeave
version: 2.6
keywords: studio, anypoint, esb, transform, transformer, format, aggregate, rename, split, filter convert, xml, json, csv, pojo, java object, metadata, dataweave, data weave, datamapper, dwl, dfl, dw, output structure, input structure, map, mapping
---

# DataWeave Selectors

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

DataWeave selectors traverse the structures of objects and arrays and return matching values.

A selector always operates within a context, which can be a reference to a variable, an object
literal, an array literal, or the invocation of a DataWeave function.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Selector Type</th><th>Syntax</th><th>Return Type</th></tr></thead><tbody><tr><td><p>Single-value</p></td><td><p><code>.keyName</code></p></td><td><p>Any type of value that belongs to a matching key</p></td></tr><tr><td><p>Multi-value</p></td><td><p><code>.*keyName</code></p></td><td><p>Array of values of any matching keys</p></td></tr><tr><td><p>Descendants</p></td><td><p><code>..keyName</code></p></td><td><p>Array of values of any matching descendant keys</p></td></tr><tr><td><p>Dynamic</p></td><td><p>See <a href="#dynamic_selector">Dynamic Selector</a>.</p></td><td><p>&nbsp;</p></td></tr><tr><td><p>Key-value pair</p></td><td><p><code>.&amp;keyName</code></p></td><td><p>Object with the matching key</p></td></tr><tr><td><p>Index</p></td><td><p><code>[&lt;index&gt;]</code></p></td><td><p>Value of any type at selected array index. Use negative numbers to index from the end of an array, for example, <code>-1</code> for the last element in the array. Use of numbers beyond the array size returns <code>null</code>.</p></td></tr><tr><td><p>Range</p></td><td><p><code>[&lt;index&gt; to &lt;index&gt;]</code></p></td><td><p>Array with values from selected indexes</p></td></tr><tr><td><p>XML attribute</p></td><td><p><code>@</code>, <code>.@keyName</code></p></td><td><p>String value of the selected attribute</p></td></tr><tr><td><p>Namespace</p></td><td><p><code>keyName.#</code></p></td><td><p>String value of the namespace for the selected key</p></td></tr><tr><td><p>Key present</p></td><td><p><code>keyName?</code>, <code>keyName.@type?</code></p></td><td><p>Boolean (<code>true</code> if the selected key of an object or XML attribute is present, <code>false</code> if not)</p></td></tr><tr><td><p>Assert present</p></td><td><p><code>keyName!</code></p></td><td><p>String: Exception message if the key is not present</p></td></tr><tr><td><p>Filter</p></td><td><p><code>[?(boolean_expression)]</code></p></td><td><p>Array or object containing key-value pairs <em>if</em> the DataWeave expression returns <code>true</code>. Otherwise, returns the value <code>null</code>.</p></td></tr><tr><td><p>Metadata</p></td><td><p><code>.^someMetadata</code></p></td><td><div><div><p>Returns the value of specified metadata for a Mule payload, variable, or attribute. The selector can return the value of class (<code>.^class</code>), content length (<code>.^contentLength</code>), encoding (<code>.^encoding</code>), mime type (<code>.^mimeType</code>), media type (<code>.^mediaType</code>), raw (<code>.^raw</code>), and custom (<code>.^myCustomMetadata</code>) metadata. For details, see <a href="https://docs.mulesoft.com/dataweave/2.6/dataweave-cookbook-extract-data#selector_metadata">Extract Data</a>.</p></div></div></td></tr></tbody></table>

> [!NOTE] The following examples use these selectors. For additional examples of selectors, see
> [Extract Data](https://docs.mulesoft.com/dataweave/2.6/dataweave-cookbook-extract-data).

## Rules for Matching

In DataWeave, a name that matches the key of an object (such as the key `"someName"` in the JSON
object `{ "someName" : "Data Weave" }`) can select data from that object. For a simple example, see
[Single-Value Selector](#single_value_selector).

## Single-Value Selector

This selector matches the value of the first key-value pair in which the key matches the given
selector name. The selector can be applied to an Object or to an array. On an array, the selector
applies to all Object values inside the array and ignores all values that are not Object values. If
no key matches, the value `null` is returned.

> [!NOTE] For information about the dot selector (`.`) and how to use it on DataWeave types, refer
> to [Selecting Types](https://docs.mulesoft.com/dataweave/2.6/dataweave-selecting-types).

### Example: Using a Single-Value Selector on an Object

This example shows how the selector works on a simple JSON object.

#### Input Payload

The input payload is an object with the key `"name"` and the value `"DataWeave"`:

```JSON
{ "name": "Data Weave" }
```

#### DataWeave Source

The DataWeave script uses `payload.name` to select the value of the object that has the key
`"name"`. Note that `payload.name` and `payload."name"` are both valid ways to perform the
selection.

```DataWeave
%dw 2.0
output application/json
---
payload.name
```

#### Output

The script outputs the String value of the input object, "Data Weave":

```JSON
"Data Weave"
```

### Example: Using a Single-Value Selector on an Array

On an array, the selector applies to every element.

#### Input Payload

The input payload is an array that contains two objects with the same key, "name":

```JSON
[
  {
    "name": "Arg"
  },
  {
    "name": "Japan"
  }
]
```

#### DataWeave Source

The DataWeave script uses `payload.name` to select the value of any objects in input payload that
have the key "name":

```DataWeave
%dw 2.0
output application/json
---
payload.name
```

#### Output

The script outputs an array that contains the values of the input objects with the key `"name"`:
`"Arg"` and `"Japan"`:

```json
["Arg", "Japan"]
```

## Namespace Selector

The DataWeave namespace selector supports the use of a name that matches a namespace or a local
part. To match a namespace, the name must match the namespace and the local part. If the name only
matches the local part, the selector matches all namespaces with that local part, regardless of the
namespace.

Note that XML namespaces and their prefixes are defined in the `xmlns` attribute of an XML element.
For example, the element `<h:table xmlns:h="http://www.w3.org/TR/html4/"/>` defines a namespace that
assigns the prefix `h` to the namespace
`[http://www.w3.org/TR/html4/](http://www.w3.org/TR/html4/)`. All elements in that namespace contain
the `h` prefix. For example, in the element `<h:table/>`, `h` is the prefix for the namespace, and
`table` is the local part.

### Example: Using a Namespace Selector

This example selects values from XML elements using the namespace and local part.

#### Input Payload

The input payload contains XML elements, `h:table` and `f:table`, that have different namespaces but
the same local names (`table`):

```xml
<root>

  <h:table xmlns:h="http://www.w3.org/TR/html4/">
    <h:tr>
      <h:td>Apples</h:td>
      <h:td>Bananas</h:td>
    </h:tr>
  </h:table>

  <f:table xmlns:f="https://www.w3schools.com/furniture">
    <f:tr>
      <f:name>African Coffee Table</f:name>
      <f:width>80</f:width>
      <f:length>120</f:length>
    </f:tr>
  </f:table>

</root>
```

#### DataWeave Source

The DataWeave script selects XML content from specified namespaces. The script’s header creates
namespace (`ns`) variables `html` and `furniture` to store namespaces from the input payload. To
select the children of `h:table` into element `a` and the children of `f:table` elements into
element `b`, the script uses the `html` and `furniture` namespace variables with a namespace
selector (`#`) and local part (`table`):

```DataWeave
%dw 2.0
output application/xml
ns html http://www.w3.org/TR/html4/
ns furniture https://www.w3schools.com/furniture
---
root: {
     a: payload.root.html#table,
     b: payload.root.furniture#table
 }
```

#### Output

The script outputs children of the `h:table` element under element `a` and the children of the
`f:table` under element `b`:

```xml
<?xml version='1.0' encoding='UTF-8'?>
<root>
  <a>
    <h:tr xmlns:h="http://www.w3.org/TR/html4/">
      <h:td>Apples</h:td>
      <h:td>Bananas</h:td>
    </h:tr>
  </a>
  <b>
    <f:tr xmlns:f="https://www.w3schools.com/furniture">
      <f:name>African Coffee Table</f:name>
      <f:width>80</f:width>
      <f:length>120</f:length>
    </f:tr>
  </b>
</root>
```

### Example: Using a Local Name to Select XML Values

This example selects XML values using a local name `table` from the `h:table` element.

#### Input Payload

The input payload contains XML with a `table` element that contains the namespace
`"http://www.w3.org/TR/html4/"`:

```xml
<root>
  <h:table xmlns:h="http://www.w3.org/TR/html4/">
    <h:tr>
      <h:td>Apples</h:td>
      <h:td>Bananas</h:td>
    </h:tr>
  </h:table>
</root>
```

#### DataWeave Source

The DataWeave script selects values of children in the `table` element by using a local name of the
XML element `table` instead of its namespace:

```DataWeave
%dw 2.0
output application/xml
---
root: { a: payload.root.table }
```

#### Output

The script outputs XML that contains the values of children in the `table` element:

```xml
<?xml version='1.0' encoding='UTF-8'?>
<root>
  <a>
    <h:tr xmlns:h="http://www.w3.org/TR/html4/">
      <h:td>Apples</h:td>
      <h:td>Bananas</h:td>
    </h:tr>
  </a>
</root>
```

## Attribute Selector

The attribute selector returns the first attribute value that matches the selected name expression.
If no key matches, the selection returns the value `null`.

The following example selects the value of an XML attribute.

### Input Payload

The input payload is an XML `user` element that contains the attribute `name="Weave"`:

```xml
<user name="Weave"/>
```

### DataWeave Source

The DataWeave script selects the value of the `name` attribute from the input payload
(`<user name="Weave"/>`). Notice that the `@` indicates an attribute selection.

```DataWeave
%dw 2.0
output application/json
---
payload.user.@name
```

### Output

The DataWeave script outputs the value of `name` attribute.

```json
"Weave"
```

## Multi-Value Selector

Instead of returning the value of the first matching key in an array of objects, the multi-value
selector (`*`) returns an array containing values to the matching key (for example, `*user` where
`user` is the key). The selector does not return the values of descendants, only those at the
specified level. If no key matches, the selection returns the value `null`.

### Input Payload

The input payload contains an XML array of `user` elements.

```xml
<users>
  <user>Weave</user>
  <user>BAT</user>
  <user>TF</user>
</users>
```

### DataWeave Source

The DataWeave script uses `*user` to select the values of all `user` elements from the input
payload.

```DataWeave
%dw 2.0
output application/json
---
payload.users.*user
```

### Output

The script outputs an array of `user` values.

```json
["Weave", "BAT", "TF"]
```

## Descendant Selector

The descendant selector returns a list of all children and their descendants. You can directly chain
this selector to any other selector without using a single `.`. For example, `payload..` recursively
returns an array of all the child values, the values of _their_ children, and so on. You can also
chain the selector to another element (for example, with `payload..user`) to select the values of
each `user` key and its descendants, or you can use `payload..*name` to select the values of all
`name` descendants.

### Example: Selecting Each Descendant

This example selects each descendant of the input payload.

#### Input Payload

The input payload contains a set of elements that are nested at different levels.

```xml
<users>
  <user>
    <name>Weave</name>
    <user>
      <name>BAT</name>
      <user>
        <name>BDD</name>
      </user>
    </user>
  </user>
</users>
```

#### DataWeave Source

The DataWeave script uses `..` to recursively select all elements in the input payload and return
them in a JSON array.

```DataWeave
%dw 2.0
output application/json
---
payload..
```

#### Output

```json
[
  {
    "user": {
      "name": "Weave",
      "user": {
        "name": "BAT",
        "user": {
          "name": "BDD"
        }
      }
    }
  },
  {
    "name": "Weave",
    "user": {
      "name": "BAT",
      "user": {
        "name": "BDD"
      }
    }
  },
  "Weave",
  {
    "name": "BAT",
    "user": {
      "name": "BDD"
    }
  },
  "BAT",
  {
    "name": "BDD"
  },
  "BDD"
]
```

### Example: Selecting Descending Values

This example selects the descending `name` values.

#### Input Payload

The input payload contains a set of `name` elements that are nested at different levels.

```xml
<users>
  <user>
    <name>Weave</name>
    <user>
      <name>BAT</name>
      <name>Munit</name>
      <user>
        <name>BDD</name>
      </user>
    </user>
  </user>
</users>
```

#### DataWeave Source

The DataWeave script uses `..` to select the values of all first `name` elements from the input
payload and output those values into a JSON array.

```DataWeave
%dw 2.0
output application/json
---
payload..name
```

#### Output

The script outputs a JSON array with all `name` values.

```json
["Weave", "BAT", "BDD"]
```

### Example

This example selects the descending `name` values.

#### Input Payload

The input payload contains a set of `name` elements that are nested at different levels.

```xml
<users>
  <user>
    <name>Weave</name>
    <user>
      <name>BAT</name>
      <name>Munit</name>
      <user>
        <name>BDD</name>
      </user>
    </user>
  </user>
</users>
```

#### DataWeave Source

The DataWeave script uses `..*` to select the values of all `name` elements from the input payload
and output those values into a JSON array, including the `BAT` and `Munit` values of the repeated
`name` keys that are at the same level in the XML hierarchy.

```DataWeave
%dw 2.0
output application/json
---
payload..*name
```

#### Output

The script outputs a JSON array with all `name` values.

```json
["Weave", "BAT", "Munit", "BDD"]
```

### Example: Selecting Descending Values

This example selects the descending `Name` values of the `Item` elements.

#### Input Payload

The input payload contains a set of `Name` elements that are nested at different levels.

```xml
<Example>
    <Brand>
        <Id>32345</Id>
        <logo>circle</logo>
        <Item>
            <Name>Perfume</Name>
            <Item>
                <Name>Bosque</Name>
            </Item>
        </Item>
        <Item>
            <Name>t-Shirt</Name>
        </Item>
    </Brand>
    <Brand>
        <Id>435678C</Id>
        <logo>circle</logo>
        <Item>
            <Name>t-Shirt2</Name>
            <Item>
                <Name>t-Shirt red</Name>
                <Item>
                    <Name>t-Shirt red with logo</Name>
                </Item>
            </Item>
        </Item>
    </Brand>
</Example>
```

#### DataWeave Source

The DataWeave script uses `..*` to select the values of all `Name` elements nested in the `Item`
elements from the input payload and output those values into a XML array.

```DataWeave
%dw 2.0
output application/xml
---
{
    Supermarket: {
        Item: {
            Value: payload..*Item.Name
        }
    }
}
```

#### Output

The script outputs a XML array with all `name` values.

```xml
<?xml version='1.0' encoding='UTF-8'?>
<Supermarket>
  <Item>
    <Value>Perfume</Value>
    <Value>t-Shirt</Value>
    <Value>Bosque</Value>
    <Value>t-Shirt2</Value>
    <Value>t-Shirt red</Value>
    <Value>t-Shirt red with logo</Value>
  </Item>
</Supermarket>
```

## Dynamic Selector

The syntax for dynamic selection depends on what you are selecting:

- Single Value: `payload[(nameExpression)]`

- Multi Value: `payload[*(nameExpression)]`

- Attribute: `payload[@(nameExpression)]`

- Key Value: `payload[&(nameExpression)]`

- Single Value with a Namespace: `payload.ns0#"$(nameExpression)"`

### Example: Dynamically Selecting a Single Value

This example shows how to dynamically select a single value.

#### Input Payload

The input payload is an array of objects. The first object has the key `"ref"` and the value
`"name"`. The second has the key `"name"` and the value `"Data Weave"`:

```JSON
{ "ref": "name", "name": "Data Weave" }
```

#### DataWeave Source

The DataWeave script dynamically selects the value of the `"name"` key:

```DataWeave
%dw 2.0
output application/json
---
payload[(payload.ref)]
```

Notice that it passes `payload.ref` within the parentheses of dynamic selector `[()]`. The script
works because the value of `"ref"` is `"name"`, which matches the key `"name"`.

#### Output

The script outputs the value of the object that has the `"name"` key:

```JSON
"Data Weave"
```

### Example: Dynamically Selecting a Single Value with a Namespace

This example shows how to dynamically select a single value that contains a namespace.

#### Input Payload

The input payload contains a `<root/>` element with two child elements, one of which has the
namespace `http://www.w3.org/TR/html4/`. Both child elements (`<f:table/>` and `<h:table>`) have the
local name `table`:

```xml
<root ref="table">
    <f:table xmlns:f="https://www.w3schools.com/furniture">Manzana</f:table>
    <h:table xmlns:h="http://www.w3.org/TR/html4/">Banana</h:table>
</root>
```

#### DataWeave Source

The DataWeave script dynamically selects the value of the element that has the namespace
`http://www.w3.org/TR/html4/`:

```DataWeave
%dw 2.0
output application/json
ns h http://www.w3.org/TR/html4/
---
payload.root.h#"$(payload.root.@ref)"
```

Notice that the expression `payload.root.@ref` uses the attribute selector (`@`) on the `ref`
attribute of the `root` element to select the value `table`, which matches local name `table` in the
element `<h:table xmlns:h="http://www.w3.org/TR/html4/">Banana</h:table>`.

#### Output

The script outputs the value of the element that has the namespace `http://www.w3.org/TR/html4/`:

```JSON
"Banana"
```

## Use of Selectors on Content Stored in Variables

All selectors work with the [predefined Mule Runtime variables](https://docs.mulesoft.com/dataweave/2.6/dataweave-variables-context) and
with [DataWeave variables](https://docs.mulesoft.com/dataweave/2.6/dataweave-variables).

To select [Mule event](https://docs.mulesoft.com/mule-runtime/latest/about-mule-event) data, such as the payload, an
attribute, or variable data within the Mule event, use predefined Mule Runtime variables, such as
`payload`, `attributes`, and `vars`.

Extracted values are handled as literal values of one of the supported DataWeave value types.

<table><colgroup><col> <col></colgroup><thead><tr><th>Data to extract</th><th>Syntax</th></tr></thead><tbody><tr><td><p><strong>Payload</strong></p></td><td><div><div><p><code>payload</code>, for example: <code>payload.name</code></p></div><div><p>If the <code>payload</code> is <code>{"name" : "somebody"}</code>, <code>payload.name</code> returns <code>"somebody"</code>.</p></div><div><p>For more on the Mule payload, see <a href="https://docs.mulesoft.com/mule-runtime/latest/about-mule-message#_message_payload">Message Payload</a>.</p></div></div></td></tr><tr><td><p><strong>Attribute</strong></p></td><td><div><div><p><code>attributes.&lt;myAttributeName&gt;</code></p></div><div><p>For examples, see <a href="https://docs.mulesoft.com/mule-runtime/latest/about-mule-message#_attributes">Attributes</a>.</p></div></div></td></tr><tr><td><p><strong>Variable</strong></p></td><td><div><div><p><code>&lt;myVariableName&gt;</code></p></div><div><p>To avoid name collisions, you must prepend <code>vars</code> to the variable name:</p></div><div><p><code>vars.&lt;myVariableName&gt;</code></p></div><div><p>For more on Mule variables, see <a href="https://docs.mulesoft.com/mule-runtime/latest/about-mule-variables">Variables in Mule Apps</a>.</p></div></div></td></tr><tr><td><p><strong>Error object</strong></p></td><td><div><div><p><code>error</code></p></div><div><p>For information on errors in the flow, you can use <code>#[error.cause]</code>.</p></div></div></td></tr><tr><td><p><strong>Flow</strong></p></td><td><div><div><p><code>flow</code></p></div><div><p>For the flow name in the Logger: <code>#[flow.name]</code></p></div><div><p>Note that <code>flow.name</code> does not work in some Core components, such as Set Payload and Transform Message.</p></div><div><p>For more on flows, see <a href="https://docs.mulesoft.com/mule-runtime/latest/about-flows">Flows and Subflows</a>.</p></div></div></td></tr></tbody></table>