---
schema_version: "1"
id: 8d38b35c7c026e920b84fac67068bc41baa0b506f5f77942269b30ca5902c774
title: DataWeave Language Guide
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/dataweave/2.9/dataweave-language-guide.md
canonical_url: https://docs.mulesoft.com/dataweave/2.9/dataweave-language-guide
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 059a86b7e98958edef89298073ba10140ff5929819343746625bbbdbf1b5c3fb
description: MuleSoft Documentation Site
release: "2.9"
latest: false
---
---
product: DataWeave
version: 2.9
keywords: studio, anypoint, transform, transformer, format, aggregate, rename, split, filter convert, xml, json, csv, pojo, java object, metadata, dataweave, data weave, datawave, datamapper, dwl, dfl, dw, output structure, input structure, map, mapping
---

# DataWeave Language Guide

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

DataWeave is a functional language used in Mule applications to perform data transformations. Before
you begin to use DataWeave to code your own powerful and complex data transformations, you must
understand the basic concepts of programming and the core features of functional programming
languages.

DataWeave enables you to take advantage of the benefits of functional programming, including:

- Pure functions that always produce the same output given the same input, making them easier for
  you to debug.

- Immutable variables that do not change their value during the execution, adding stability to your
  code.

- Function signatures that provide additional transparency about what affects a function’s
  execution, because pure functions depend on only their input parameters to produce a result.

- Functional languages produce code that’s easier to maintain because the code is concise and clear.

- A call-by-need strategy (also known as _lazy evaluation_) that improves performance, because
  expressions are evaluated only when they are needed and their result is stored to avoid evaluating
  an expression multiple times if the input parameters are the same.

## DataWeave Language Basic Concepts

DataWeave incorporates concepts that are common to most programming languages. All DataWeave scripts
consist of a _header_ that contains important directives, including the output format of the
transformation, and a _body_ that contains the expression to generate a result.

DataWeave supports different _data structures_, including _simple_, _complex_, and _composite_
types. In most of your DataWeave transformations, you use _data selectors_, _data operators_, and
_functions_ alongside _arrays_ and _objects_ to perform data mappings or transformations.

You can also import prebuilt DataWeave _modules_ to extend the set of functions available to use in
your scripts.

### Architecture of a DataWeave Script

A DataWeave script consists of a _header_ and a _body_, separated by three dashes (`---`). The
header contains language directives (`import`, for example), defines the output format of the
transformation, and can also contain variable and function declarations. The body contains the
expression that produces the resulting output, usually a data mapping or a transformation.

Here is an example of a basic DataWeave transformation:

```dataweave
%dw 2.0
output application/json
---
payload
```

### Data Types

DataWeave represents data using values, each of which has a data type associated with it. The type
system enables you to apply constraints to variables and function parameters. The supported data
types include simple types such as `String`, `Boolean`, `Number`, and `Date`, as well as composite
and complex types such as `Array`, `Object`, and `Any`.

For a complete list of all supported data types, see [Type System](https://docs.mulesoft.com/dataweave/2.9/dataweave-type-system).

### Data Selectors

Data selectors enable you to access fields within a data structure so that you can retrieve data
from the payload or any other variable created during the DataWeave script execution. Different
types of selectors provide you with a variety of options that you can use to extract data from
structures.

For example, you can use the _single-value selector_ `payload.userName` to retrieve the single value
`userName`, where `userName` represents an actual key in the input message.

See [Selectors](https://docs.mulesoft.com/dataweave/2.9/dataweave-selectors) for a complete list of data selectors and their usage.

### Functions

A function is a code block that contains a group of operations that are executed when the function
is called in your application. Functions can accept different parameters as input that can then be
used by the operations defined in the function. Additionally, every function returns a value after
it finishes processing, and this value can then be used as input for a different function.

Each DataWeave script that you write in any component (like a Transform Message component or Set
Payload component) works as an independent program, meaning that all function definitions and calls
are unique to the script defined in the component.

See [Define DataWeave Functions](https://docs.mulesoft.com/dataweave/2.9/dataweave-functions) for additional function definition details.

#### Function Definition vs. Function Call

DataWeave enables you to [define your own functions](https://docs.mulesoft.com/dataweave/2.9/dataweave-functions) in the header of the
script, creating a blueprint for the process that defines the operations that are executed upon the
function call. You can also define them in
[DataWeave mapping and module files](https://docs.mulesoft.com/dataweave/2.9/dataweave-create-module).

When you _call_ a function from a DataWeave expression, you are instructing DataWeave to run all the
operations defined in that function at that exact point of the script’s execution.

For example, `upper` is a built-in function defined in the String module. You can call this function
to convert a text value to uppercase. Also, you can use a selector to retrieve a value from the
payload, and then execute the `upper()` function call with this value as the input parameter
`upper(payload.someKey)`.

DataWeave supports both _prefix_ notation (`function (param1, param2)`) and _infix_ notation
(`param1 function param2`) for function calls. Note that you can use infix notation only with
functions that accept only two parameters.

See also, [Function Signatures](https://docs.mulesoft.com/dataweave/2.9/dw-functions#function_signatures).

### Data Operators

Data operators are symbols that enable you to perform operations on data to produce a result.
DataWeave supports operators that are common in most programming languages like mathematical
(`` `, `-`, `/`, `*`), relational (`<`, `>`, `⇐+ ``, `>=`, `==`, `~=`), and logical (`not`, `!`,
`and`, `or`) operators.

DataWeave also supports the following operators:

- Append (`<<`, `+`), Prepend (`>>`), and Remove (`-`), which enable you to manage data in an array.

- Scope and Flow control operators (`do`, `using`, `if`, `else`) that enable you to create a scope
  where new variables and functions can be declared, or to execute an expression based on a
  condition.

- Update (`update`), which enables you to update specific fields of a data structure.

See [DataWeave Operators](https://docs.mulesoft.com/dataweave/2.9/dw-operators) for a complete list of supported operators, their usage, and
examples.

#### Import Function Modules

By default, DataWeave scripts import the `dw::Core` function module. To use functions from different
modules, import the modules to your script by adding the `import` directive.

See [DataWeave Reference](https://docs.mulesoft.com/dataweave/2.9/dw-functions) for instructions on using the `import` directive.

### Arrays

An array is a data structure that can contain any number of elements of the supported DataWeave
types. To declare an array, use brackets (`[` and `]`) to enclose a comma-separated list of
elements, for example: `[1,2,3]`.

Arrays also support the application of conditional logic to define conditional elements
(`[(value1) if condition]`). For example, the expression
`[(1) if true, (2) if false, (3) if payload != null]` defines the array `[1,3]` (assuming that
`payload` is not `null`).

### Objects

An object is a collection of zero or more `Key` and `value` pairs:

- `Key`, which is formed by:

  - `Name`, composed of a `String` value as the local name and an optional `Namespace`.

  - `Attributes`, a collection of zero or more `Name:value` pairs, where `value` can be any possible
    value.

- `Value`, comprising any supported type, including another object, a function call, or an array.

To declare an object, use braces (`{` and `}`) to enclose a comma-separated list of `Key:value`
pairs:

```dataweave
{
  keyName @(keyAttributeName :"keyAttributeValue"): "value",
  User @(role:"admin"): upper("max the mule"),
  myArray: [1,2,3]
}
```

Objects also support the definition of conditional elements:

```dataweave
{
 (userName: name) if !isBlank(name),
 (userRole: role) if !isBlank(role)
}
```

## Functional Programming Principles

The functional programming paradigm enables developers to build applications by using pure function
composition and immutable data. Because functional programming is declarative, functions in
DataWeave are just expressions that return a value, instead of imperative statements that change
program states.

DataWeave follows the core principles of functional programming, including pure functions,
first-class functions, high-order functions, function composition, lambda expressions, and immutable
data.

### Pure Functions

Pure functions in programming are similar to pure functions in mathematics in that, given a certain
input, they always return the same output. Also, executing a function has no impact on other parts
of a program, other than producing a result. All functions in DataWeave are pure; they are not
affected by external values that could change the result of the execution.

### First-Class Functions

The pure functions in DataWeave are also “first-class citizens” in that they support operations that
are available to any other data type, including being stored in variables, passed as parameters, and
returned as results.

### High-Order Functions

High-order functions in programming also have the same concept as in mathematics. These functions
take one or more functions as parameters and return a function as a result. The result of a
high-order function can then be used as an input parameter in another function, enabling the concept
of _function composition_.

### Function Composition

Function composition is the process by which functions are combined to build complex operations. In
this case, the result of executing one function serves as an input parameter for the next function.
In DataWeave, all data transformations are a chain of expressions, functions composed to obtain a
final result that outputs the data as needed.

#### Example of Function Composition

The following example uses the function `pluck` to map an object into an array. Then the resulting
array serves as input for the function `filter`, which selects the elements in the array that have a
`Role` equal to `ADMIN`. During the mapping process, the function `upper` transforms the `role`
value:

```dataweave
%dw 2.0
output application/json
var collaborators =
{
    Max: {role: "admin", id: "01"},
    Einstein: {role: "dev", id: "02"},
    Astro: {role: "admin", id: "03"},
    Blaze: {role: "user", id: "04"}
}
---
collaborators pluck ((value,key,index)->  {
        "Name": key,
        "Role": upper(value.role),
        "ID": value.id
    })
    filter ((item, index) -> item.Role == "ADMIN")
```

The following example shows the same expression, but it uses prefix notation. This syntax helps
visualize how `filter` takes as the first parameter the result of `pluck`.

```dataweave
%dw 2.0
output application/json
var collaborators =
{
    Max: {role: "admin", id: "01"},
    Einstein: {role: "dev", id: "02"},
    Astro: {role: "admin", id: "03"},
    Blaze: {role: "user", id: "04"}
}
---
filter(
   pluck(
       collaborators, (value,key,index)->
       {
           "Name": key,
           "Role": upper(value.role),
           "ID": value.id
       }),
   (item, index) -> item.Role == "ADMIN")
```

The output of both expressions is:

```dataweave
[
  {
    "Name": "Max",
    "Role": "ADMIN",
    "ID": "01"
  },
  {
    "Name": "Astro",
    "Role": "ADMIN",
    "ID": "03"
  }
]
```

### Lambda Expressions

Lambda expressions, also known as _anonymous functions_ or _function literals_, are function
definitions that do not have an identifier name and can be passed as parameters to high-order
functions. Lambda syntax is expressed in the form `(a,b) → c`, which can be read as “Given a certain
input (`a` and `b`), execute the following (`c`).”

For example, the `map` function in DataWeave accepts a lambda expression as one of its parameters:
`map(Array<T>, (item: T, index: Number) → R): Array<R>`. `map` iterates over the items in an array
and executes the lambda expression that is passed as a parameter. This lambda expression consists of
two parameters that represent the value (`item`) and index (`index`) of each array element during
the execution, and a function definition to execute during the iteration `R`.

The following code example shows a `map` function that receives a lambda expression to concatenate
the index and the value of each element in the array it iterates on, and then returns these values
as a new array:

Source

```dataweave
%dw 2.0
output application/json
---
["Max", "the", "Mule"] map (item, index) -> index ++ " - " ++ item
```

Output

```dataweave
[
    "0 - Max",
    "1 - the",
    "2 - Mule"
]
```

See [Work with Functions and Lambdas in DataWeave](https://docs.mulesoft.com/dataweave/2.9/dataweave-functions-lambdas) for additional
information about Lambda expressions.

### Immutable Data

In DataWeave, variables cannot change their assigned value after they are defined. This ensures that
there are no unexpected results from executing functions. If you want to store a new value that is
the result of an operation, you must declare a new data structure.

## Differences with Imperative Programming

If you have a development background in working with object-oriented programming languages, it is
important to understand that functional programming separates data from functions and does not use
loop control statements.

### Separation of Data and Functions

DataWeave does not use assignment statements, which ensures that data remains immutable. Because
there are no getter and setter methods, nor classes containing data structures and behavior, each
function works only with the data you provide as input. If you need to modify any existing data
structure, you create a new copy and apply functions to modify its values.

### Control Flow Statements

There are no loop control statements like `for` or `while` in DataWeave. In DataWeave, instead of
defining how to execute a procedure using iteration, you focus on your current requirements when you
write the expressions.

For example, to make changes to a list, you use the `map` function to apply changes to the elements
in the collection. Additionally, you can use the `filter` function to remove specific elements from
a list, or the `reduce` function to collapse all values from an array into one single value.

However, you can use `if-else` statements to apply a condition when executing an expression:

```dataweave
%dw 2.0
var myVar = { country : "FRANCE" }
output application/json
---
if (myVar.country == "USA")
  { currency: "USD" }
else { currency: "EUR" }
```

#### DataWeave Examples

For usage examples of `map`, `reduce`, and `filter`, see:

- [Map Data with DataWeave](https://docs.mulesoft.com/dataweave/2.9/dataweave-cookbook-map)

- [Conditionally Reduce a List through a Function](https://docs.mulesoft.com/dataweave/2.9/dataweave-cookbook-conditional-list-reduction-via-function)

- [Merge Fields from Separate Objects](https://docs.mulesoft.com/dataweave/2.9/dataweave-cookbook-merge-multiple-payloads)

## See Also

- [Mule Message Structure](https://docs.mulesoft.com/mule-runtime/latest/about-mule-message)

- [Mule Events](https://docs.mulesoft.com/mule-runtime/latest/about-mule-event)

- [Core Components](https://docs.mulesoft.com/mule-runtime/latest/about-components)

- [Connectors and Modules](https://docs.mulesoft.com/connectors/)

- [Transform Message Component](https://docs.mulesoft.com/mule-runtime/latest/transform-component-about)