Contact Us 1-800-596-4880
  1. Homepage
  2. DataWeave (2.8)
  3. Language Guide

  4. Selectors

DataWeave Selectors

DataWeave selectors traverse the structures of objects and arrays and return matching values. Before you begin, note that 2.x versions of DataWeave are used by Mule 4 apps. For DataWeave in Mule 3 apps, refer to the DataWeave version 1.2 documentation. For other Mule versions, you can use the version selector in the DataWeave table of contents.

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

.keyName

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

Dynamic

See Dynamic Selector.

 

Key-value pair

.&keyName

Object with the matching key

Index

[<index>]

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.

Range

[<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

keyName!

String: Exception message if the key is not present

Filter

[?(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":

"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 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):

<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 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.

"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.

<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)]

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:

"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:

<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/:

"Banana"

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

payload, for example: payload.name

If the payload is {"name" : "somebody"}, payload.name returns "somebody".

For more on the Mule payload, see Message Payload.

Attribute

attributes.<myAttributeName>

For examples, see Attributes.

Variable

<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

error

For information on errors in the flow, you can use #[error.cause].

Flow

flow

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.