DataWeave Selectors | MuleSoft Documentation
# DataWeave Selectors
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.
Selector Type | Syntax | Return Type  
---|---|---  
Single-value | Any type of value that belongs to a matching key  
Multi-value | `.*keyName` | Array of values of any matching keys  
Descendants | `..keyName` | Array of values of any matching descendant keys  
See Dynamic Selector.  
Key-value pair | Object with the matching key  
Value of any type at selected array index. Use negative numbers to index from the end of an array, for example, `-1` for the last element in the array. Use of numbers beyond the array size returns `null`.  
`[<index> to <index>]` | Array with values from selected indexes  
XML attribute | `@`, `.@keyName` | String value of the selected attribute  
Namespace | `keyName.#` | String value of the namespace for the selected key  
Key present | `keyName?`, `keyName.@type?` | Boolean (`true` if the selected key of an object or XML attribute is present, `false` if not)  
Assert present | String: Exception message if the key is not present  
`[?(boolean_expression)]` | Array or object containing key-value pairs _if_ the DataWeave expression returns `true`. Otherwise, returns the value `null`.  
Metadata | `.^someMetadata` |  Returns the value of specified metadata for a Mule payload, variable, or attribute. The selector can return the value of class (`.^class`), content length (`.^contentLength`), encoding (`.^encoding`), mime type (`.^mimeType`), media type (`.^mediaType`), raw (`.^raw`), and custom (`.^myCustomMetadata`) metadata. For details, see Extract Data.  
The following examples use these selectors. For additional examples of selectors, see 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
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.
For information about the dot selector (`.`) and how to use it on DataWeave types, refer to 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"`:
```
{ "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.
```
%dw 2.0
output application/json
---
payload.name
```

#### Output
The script outputs the String value of the input object, "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":
```
[
 {
  "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":
```
%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"`:
```
["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 . 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`):
```
<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`):
```
%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 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/"`:
```
<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:
```
%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 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"`:
```
<user name="Weave"/>
```
#### 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:
```
%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 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"`:
```
<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.
```
%dw 2.0
output application/json
---
payload.user.@name
```

### Output
The DataWeave script outputs the value of `name` attribute.
## 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.
```
<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.
```
%dw 2.0
output application/json
---
payload.users.*user
```

### Output
The script outputs an array of `user` values.
```
[
 "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.
```
<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.
```
%dw 2.0
output application/json
---
payload..
```

#### Output
```
[
 {
  "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.
```
<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.
```
%dw 2.0
output application/json
---
payload..name
```

#### Output
The script outputs a JSON array with all `name` values.
```
[
 "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.
```
<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.
```
%dw 2.0
output application/json
---
payload..*name
```

#### Output
The script outputs a JSON array with all `name` values.
```
[
 "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.
```
<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.
```
%dw 2.0
output application/xml
---
{
  Supermarket: {
    Item: {
      Value: payload..*Item.Name
    }
  }
}
```

#### Output
The script outputs a XML array with all `name` values.
```
<?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"`:
```
{ "ref": "name", "name": "Data Weave" }
```

#### DataWeave Source
The DataWeave script dynamically selects the value of the `"name"` key:
```
%dw 2.0
output application/json
---
payload[(payload.ref)]
```
## 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"`:
```
{ "ref": "name", "name": "Data Weave" }
```

#### DataWeave Source
The DataWeave script dynamically selects the value of the `"name"` key:
```
%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:
### 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`:
```
<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/`:
```
%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/`:
## Use of Selectors on Content Stored in Variables
All selectors work with the predefined Mule Runtime variables and with DataWeave variables.
To select 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.
Data to extract | Syntax  
---|---  
`payload`, for example: `payload.name` If the `payload` is `{"name" : "somebody"}`, `payload.name` returns `"somebody"`. For more on the Mule payload, see Message Payload.  
`attributes.<myAttributeName>` For examples, see Attributes.  
`<myVariableName>` To avoid name collisions, you must prepend `vars` to the variable name: `vars.<myVariableName>` For more on Mule variables, see Variables in Mule Apps.  
**Error object** |  For information on errors in the flow, you can use `#[error.cause]`.  
For the flow name in the Logger: `#[flow.name]` Note that `flow.name` does not work in some Core components, such as Set Payload and Transform Message. For more on flows, see Flows and Subflows.