DataWeave Functions: Tutorial, Best Practices & Examples
DataWeave is a powerful data transformation language used in MuleSoft to process, manipulate, and convert data among formats like JSON, XML, CSV, and Java objects. DataWeave functions are built-in methods that help perform everyday tasks such as modifying strings, numbers, collections, objects, dates, or any other customization.
Whether you need to change the text to uppercase, split a sentence into words, or filter from a collection, DataWeave functions make it simple. These functions save time by handling everyday data tasks automatically, so you don’t have to write complex code by making data transformation easier and more efficient within MuleSoft applications.
This article explains commonly used DataWeave functions in MuleSoft and best practices based on real business experience.
Summary of DataWeave function categories and related concepts
The table below describes function types and associated concepts.
What is DataWeave?
DataWeave is MuleSoft's scripting language, designed to manipulate and enrich data and transform it from one format to another, such as EDI, JSON, CSV, and XML. It is the heart of MuleSoft's Anypoint Platform. Understanding and using its functions effectively helps you build seamless API integrations, ETL processes, and real-time data transformations. With its comprehensive library of functions and operators, DataWeave empowers users to tackle even the most intricate data transformation tasks easily.
DataWeave functions allow developers to handle data transformation smoothly without writing complex code, making integrations faster and more efficient. It is designed to work smoothly within MuleSoft integrations, helping you quickly process and format data to match your needs.
Introduction to DataWeave functions
DataWeave functions are built-in tools that allow developers to work with different data types, such as strings, numbers, collections, objects, dates, conditional expressions, or any other custom code. They make complex data transformations simple and fast. In addition to built-in functions, you can define customized functions in DataWeave, providing additional flexibility in data processing.
For example, the trim() function removes spaces from both ends and removes extra spaces from the beginning and end of the string.
%dw 2.0
output application/json
---
{
result: trim(" MuleSoft ") // Output: "MuleSoft"
}
Use of DataWeave Playground
DataWeave Playground is a web-based tool that enables developers to write, test, and refine DataWeave scripts in a sandbox environment. By providing sample input and script, you can instantly see the output of your DataWeave code, eliminating the need to create a complete Mule application.
The screenshot below shows the use of the Map operator to create a mapping with the help of Dataweave Playground.
{{banner-large-graph="/banners"}}
String functions
String functions help modify and clean text data by changing letter cases, splitting, or extracting text. They ensure data is correctly formatted before being sent to APIs or databases, making integrations smooth and error-free. These functions also reduce manual coding and keep data standardized for easy processing.
Here are some important string functions used in DataWeave, with examples.
upper(text)
The upper function changes all lowercase letters in a string to uppercase.
%dw 2.0
output application/json
---
{
name: upper("muleSoft") // Output: "MULESOFT"
}
lower(text)
The opposite of the previous function, this one changes all uppercase letters to lowercase.
%dw 2.0
output application/json
---
{
result: lower("HELLO MULESOFT") // Output: "hello mulesoft"
}
(text) replace (old) with (new)
The replace function replaces part of a string with another.
%dw 2.0
output application/json
---
{
result: "Hello MuleSoft" replace "MuleSoft" with "DataWeave"
// Output: "Hello DataWeave"
}
splitBy(text, delimiter)
The splitBy function splits a string into an array based on a delimiter.
%dw 2.0
output application/json
---
{
result: splitBy("apple,banana,grape", ",")
// Output: ["apple", "banana", "grape"]
}
contains(text, substring)
The contains function checks if a string contains a word and returns true if it does or false if it does not.
%dw 2.0
output application/json
---
{
result: contains("Hello MuleSoft", "MuleSoft")
// Output: true
}
startsWith(text, prefix)
The startsWith function checks if a string starts with a specific word and returns true if it does.
%dw 2.0
output application/json
---
{
result: startsWith("MuleSoft", "Mule")
// Output: true
}
endsWith(text, suffix)
The endsWith function returns true or false depending on whether or not a string ends with a specific word.
%dw 2.0
output application/json
---
{
result: endsWith("MuleSoft", "Soft")
// Output: true
}
substring(text, startIndex, endIndex)
The substring function extracts a part of a string ranging from the specified start index to the end index (excluding the end index).
%dw 2.0
import * from dw::core::Strings
output application/json
---
{
result: substring("MuleSoft", 0, 4) // Output: "Mule"
}
Numeric functions
Numeric functions make calculations easier and faster, reducing the need for manual coding. They also ensure accurate data transformations when working with numbers in APIs and databases. These functions are handy in financial and analytical operations, helping process data quickly and efficiently.
abs(number)
The abs function returns the absolute value of a number (removes negative signs).
%dw 2.0
output application/json
---
{
absoluteValue: abs(-10), // Output: 10
}
ceil(number)
The ceil (ceiling) function rounds a number up to the nearest whole number.
%dw 2.0
output application/json
---
{
ceilingValue: ceil(3.2), // Output: 4
}
floor(number)
The floor function rounds a number down to the nearest whole number.
%dw 2.0
output application/json
---
{
floorValue: floor(7.8), // Output: 7
}
round(number)
The round function rounds a number up or down to the nearest whole number.
%dw 2.0
output application/json
---
{
roundedValue: round(2.456), // Output: 2
}
max([number1, number2])
The max function returns the maximum value in an array.
%dw 2.0
output application/json
---
{
maxValue: max([5, 10]), // Output: 10
}
min([number1, number2])
The min function returns the minimum value in an array.
%dw 2.0
output application/json
---
{
minValue: min([5, 10]), // Output: 5
}
sum(array)
The sum function adds all the numbers in a list and returns the total.
%dw 2.0
output application/json
var numbers = [-5, 3.6, 7.8, 2.4, 10]
---
{
totalSum: sum(numbers), // Output: 18.8
}
avg(array)
The avg function calculates the average of a list of numbers.
%dw 2.0
output application/json
var numbers = [-5, 3.6, 7.8, 2.4, 10]
---
{
averageValue: avg(numbers) // Output: 3.76
}
Collection functions
Collection functions make working with large data sets easy by filtering, sorting, merging, and transforming information. They are especially useful in MuleSoft applications, where data is often processed in bulk, such as handling API responses, database records, or large data sets.
map(list, (value) -> expression)
The map function transforms each element in a list based on the specified expression.
%dw 2.0
output application/json
var numbers = [5, 2, 8, 10, 3]
---
{
mappedValues: numbers map ((n) -> n * 2), // Output: [10, 4, 16, 20, 6]
}
filter(list, (value) -> condition)
The filter function returns only the elements that meet a condition.
%dw 2.0
output application/json
var numbers = [5, 2, 8, 10, 3]
---
{
filteredValues: numbers filter ((n) -> n > 5), // Output: [8, 10]
}
flatten(list)
The flatten function merges nested lists into a single list.
%dw 2.0
output application/json
---
{
flattenedList: flatten([[1, 2], [3, 4]]), // Output: [1, 2, 3, 4]
}
(list) distinctBy ((value) -> expression)
The distinctBy function inputs an array that contains duplicate numbers and returns an array with unique numbers from that input.
%dw 2.0
output application/json
---
{
uniqueValues: [1, 2, 2, 3, 4, 4] distinctBy ($) // Output: [1, 2, 3, 4]
}
(list) orderBy ((value) -> expression)
The orderBy function sorts a list in ascending or descending order.
%dw 2.0
output application/json
var numbers = [5, 2, 8, 10, 3]
---
{
sortedValues: numbers orderBy $, // Output: [2, 3, 5, 8, 10]
}
reduce(list, (accumulator, value) -> expression, initialValue)
The reduce function returns the sum of the numeric values in the first input array.
%dw 2.0
output application/json
---
[2, 3] reduce ($ + $$) // Output: 5
sizeOf(list)
The sizeOf function returns the number of elements in an array.
%dw 2.0
output application/json
---
sizeOf([ 1, 2, 3]) // Output: 3
Object functions
Object functions help manage key-value data by allowing you to modify and extract values easily. These functions are helpful in MuleSoft when handling API responses, database records, or structured payloads, making data processing more efficient.
namesOf(object)
The namesOf function returns a list of all keys in an object.
%dw 2.0
output application/json
var user = {
name: "Alice",
age: 25,
city: "New York"
}
---
{
objectKeys: namesOf(user), // Output:["name", "age", "city"]
}
valuesOf(object)
The valuesOf function returns a list of all values in an object.
%dw 2.0
output application/json
var user = {
name: "Alice",
age: 25,
city: "New York"
}
---
{
objectValues: valuesOf(user), // Output: ["Alice", 25, "New York"]
}
pluck(object, (value, key) -> expression)
The given input is a simple key-value object where "a" and "c" are the keys with values "b" and "d" respectively. The pluck function processes this data by creating a new object where the index (starting from 0) becomes the key. Inside each object, the original value is used as a new key, and the original key is converted to uppercase as its corresponding value. This transformation results in an array of objects, where each key-value pair from the input is restructured in a modified format.
%dw 2.0
output application/json
---
{"a":"b","c":"d"} pluck (value,key,index) -> {(index) : {(value):upper(key)}}
// Output: [{"0":{"b": "A"}}, {"1":{"d": "C"}}]
Date and time functions
These functions help manage timestamps, schedules, and logs by automating date calculations. They make adding, subtracting, comparing, and formatting dates easy without complex coding. These functions ensure accurate date formatting for APIs and handle time zones and conversions to improve data accuracy in global integrations.
now()
The now function returns the current date and time.
%dw 2.0
output application/json
---
{
currentDateTime: now(), // Current timestamp
}
Date(value)
The date function converts a string into the date format specified.
%dw 2.0
output application/json
var startDate = "2023-12-01T10:00:00Z" as DateTime
---
{
formattedDate: startDate as Date {format: "yyyy/MM/dd"},
// Output: "2023/12/01"
}
plus(value, period)
The plus function adds a specific time period to a date.
%dw 2.0
output application/json
var startDate = "2023-12-01T10:00:00Z" as DateTime
---
{
addDays: startDate + |P5D|, // Output: Adds 5 days -> "2023-12-06T10:00:00Z"
}
minus(value, period)
The minus function subtracts a specific time period from a date.
%dw 2.0
output application/json
var startDate = "2023-12-01T10:00:00Z" as DateTime
---
{
subtractMonths: startDate - |P2M|,
// Output: Subtracts 2 months -> "2023-10-01T10:00:00Z"
}
daysBetween(date1, date2)
This function calculates the number of days between two dates.
%dw 2.0
output application/json
var startDate = "2023-12-01T10:00:00Z" as DateTime
var endDate = "2024-01-01T10:00:00Z" as DateTime
---
{
differenceInDays: daysBetween(startDate, endDate) // Output: 31 days
}
Conditional and control flow functions
Conditional and control flow functions help automate decision-making in data transformations. They allow developers to filter, modify, and apply certain logic as per the project requirement. These functions also handle errors smoothly and ensure accurate data transformations, making integrations more efficient and reliable.
if-else
The if-else function executes different code based on a specified condition.
%dw 2.0
output application/json
var age = 18
---
{ isAdult: if (age >= 18) "Yes" else "No" }
// "Yes"
else-if
The else-if function can chain several other expressions together within an if-else construct.
%dw 2.0
output application/json
var myVar = { country : "UK" }
---
if (myVar.country =="USA")
{ currency: "USD" }
else if (myVar.country =="UK")
{ currency: "GBP" }
else { currency: "EUR" }
// {"currency": "GBP"}
unless
This function executes an expression only if a condition is false.
%dw 2.0
output application/json
var age = 18
var status = "gold"
---
{
eligibleForOffer: unless (status == "basic") "Eligible" else "Not Eligible", // “Eligible”
}
match
The match function is used for pattern matching, similar to switch-case logic.
%dw 2.0
output application/json
var temp = {
"action": "buy"
}
---
temp.action match {
case "buy" -> "Buy at market price"
case "sell" -> "Sell at market price"
case "hold" -> "Hold asset"
else -> "ERROR"
} // "Buy at market price"
update
The update function updates a field in an object with the specified string value.
%dw 2.0
import * from dw::util::Values
output application/json
---
{name: "Mariano"} update "name" with "DataWeave"
//{"name": "DataWeave"}
{{banner-large="/banners"}}
Custom functions
Custom functions help developers reuse logic, reducing the need to write the same code repeatedly. They break down complex transformations into smaller, easy-to-manage functions, making data processing more efficient. Allowing developers to apply custom business logic seamlessly helps create cleaner and more efficient MuleSoft integrations.
To create a custom function in DataWeave, you define it using the fun keyword and then call it where needed. Custom functions can take parameters and return processed data. In this example, the formatName function capitalizes the first letter and makes the rest lowercase.
%dw 2.0
output application/json
// Define a custom function to format names
fun formatName(name: String) =
upper(name[0]) ++ lower(name[1 to -1])
---
{
formattedName: formatName("john") // Output: "John"
}
Examples of using CurieTech AI for DataWeave functions
Third-party AI tools like CurieTech AI's Dataweave Generator Agent help simplify writing complex data transformations in MuleSoft. CurieTech AI simplifies MuleSoft's complex transformations by assisting developers with DataWeave scripts across projects. It allows developers to maintain code consistency and makes MuleSoft projects more efficient and scalable.
Here are some examples of how you can use CurieTech AI's Dataweave Generator Agent to generate DataWeave scripts using various functions automatically.
String functions
Suppose you need to format input strings, such as names, by removing spaces and converting them to uppercase. The tool generates DataWeave scripts automatically using string functions.
You prompt the tool with a sample input format, sample input data, and sample output data, and click Generate.
The result is the following generated DataWeave snippet.
Numeric functions
The tool can generate DWL expressions using numeric functions. For example, you can use the sum and average functions if you need to calculate the total and average sales from a list of values.
Prompt the tool with a sample input format, sample input data, and output data as shown below, and click Generate.
The result is the following generated DataWeave snippet.
Collection functions
Consider a scenario where you need to iterate through an array of books and perform a series of tasks on each to get a response in a certain formatted way using one of the collection functions.
Here’s what the input and output would look like:
And here’s the generated DataWeave snippet.
Object functions
In this example, we swap key-value pairs in an object using one of the object functions. As before, provide the tool with a sample input format and sample input and output data, then click Generate.
And here’s the output:
Date and time functions
Let’s assume a use case where the user wants to correctly calculate and format a subscription expiry date. This can be achieved by adding days to the input using the date function, as shown in the output snippet below.
First, we provide the input:
And CurieTech produces the necessary DataWeave snippet:
Conditional and control flow functions
Suppose you want to determine eligibility for a premium service based on a user’s age and membership type. You prompt the tool with a sample input format and data, as shown below, along with output data:
The output is a generated DataWeave snippet:
Best practices for using DataWeave functions
When using DataWeave, it is essential to follow best practices to make the code faster, easier to read, and simpler to manage. Writing clean and well-structured transformations helps in processing data efficiently. Developers should use clear and descriptive variable names, format the code correctly, and handle null values to prevent unexpected errors. Additionally, breaking down complex logic into small, reusable functions keeps the code organized and easy to maintain.
CurieTech AI DW generator can refer to custom functions from different DWL files in the same repository and use them to generate data weave as per the given input/output and notes.
Optimize performance by avoiding unnecessary iterations
Not recommended
This approach loops through the data multiple times, which is inefficient:
%dw 2.0
output application/json
var data = [1, 2, 3, 4, 5]
var Numbers = data filter ($ > 3)
var squaredNumbers = Numbers map (x) -> x * x
---
{ result: squaredNumbers }
// {"result": [16,25]}
Recommended
Use a single iteration by applying transformations within the same function. This reduces unnecessary loops, making the transformation more efficient:
%dw 2.0
output application/json
var data = [1, 2, 3, 4, 5]
---
{ result: data filter ($ > 3) map (x) -> x * x }
// {"result": [16,25]}
Improve readability with descriptive variable and function names
Not recommended
Using short or unclear variable names makes the code hard to understand:
%dw 2.0
output application/json
var d = ["John", "Jane", "Jack"]
---
{ r: d map (n) -> upper(n) }
//{"r": ["JOHN","JANE","JACK"]}
Recommended
Use meaningful names for better readability, which makes the transformation easier to read and maintain:
%dw 2.0
output application/json
var names = ["John", "Jane", "Jack"]
---
{ capitalizedNames: names map (name) -> upper(name) }
//Output : {"capitalizedNames": ["JOHN","JANE","JACK"]}
Handle null values safely to avoid errors
Not recommended
This code does not check for null values, which can cause runtime errors:
%dw 2.0
output application/json
var fname = { first: null }
var lname = { last: "MuleSOft"}
---
{ upperName: upper(fname.first) ++ " " ++ upper(lname.last) } // This will cause an error
Recommended
Always use default or if conditions to handle null values:
%dw 2.0
output application/json
var fname = { first: null }
var lname = { last: "MuleSOft"}
---
{ upperName: if (fname.first != null and lname.last != null) upper(fname.first) ++ " " ++ upper(lname.last) else "Unknown" }
Use custom functions for reusability
Not recommended
Repeating the same logic multiple times increases redundancy:
%dw 2.0
output application/json
var names = ["john," "jane," "jack"]
---
{
formatted1: upper(names[0][0]) ++ lower(names[0][1 to -1]),
formatted2: upper(names[1][0]) ++ lower(names[1][1 to -1]),
formatted3: upper(names[2][0]) ++ lower(names[2][1 to -1])
}
Recommended
Use a custom function to apply the same logic efficiently, which makes the code cleaner and more reusable.
%dw 2.0
output application/json
fun capitalize(name: String) = upper(name[0]) ++ lower(name[1 to -1])
var names = ["john," "jane," "jack"]
---
{ formattedNames: names map (name) -> capitalize(name) }
Example of an AI agent recommending best practices
Using CurieTech AI's Single Repo Code Lens, you can get in-depth analysis and answers, including DataWeave scripts, ensuring that best practices are followed in the project.
For instance, the user can ask any question related to the project, as shown below, like “Please review the code and suggest best practices, if any.”
The tool reviews the code and provides suggestions and steps for best practices.
CurieTech AI’s Code Enhancer can enhance the existing code and recommend best practices or changes that need to be made according to standard coding.
Here is an example of using the Code Enhancer. We upload the project folder and a description explaining the required changes. Multiple options are provided, such as “Upgrade Connector Version” or “Update Logging.”
After uploading the project folder, we pass the description as “Change the datatype of employeeID from string to a number,” choose the description “Change DataWeave Logic,” and click Submit.
Once the script is completed, we see all the changes made by the tool to the project, showing that the field type has been changed to “Number” as requested.
{{banner-large-table="/banners"}}
Conclusion
In this article, we discussed DataWeave functions and how they make data transformation in MuleSoft simple, efficient, and flexible by providing built-in methods for handling strings, numbers, collections, objects, etc. Some best practices, like avoiding unnecessary iterations and handling null values, can be followed when using the dataweave functions. AI tools like CurieTech further enhance development by automating complex transformations and improving decision-making. This boosts MuleSoft’s integration power, creating innovative and seamless business operations.