Formatting functions ​

Formatting functions turn values into the strings a person or a destination system reads. They also parse strings back into values.

The distinction that matters here is between formatting and converting. format_date produces text for display or for a system that demands a particular layout. It doesn't produce a date. The result is a String, which doesn't support arithmetic. Keep values in their original types until the final formatting step.

Format dates and times ​

format_date, format_datetime, and format_time each take a strftime pattern or a named preset. The following table lists the common directives:

format_date ​

Formats a PlainDate.

format_date(date, pattern)

format_date(PlainDate('2026-03-15'), '%d/%m/%Y')

15/03/2026

format_datetime ​

Formats a DateTime or a PlainDateTime.

format_datetime(datetime, pattern)

format_datetime(DateTime('2026-03-15T09:30:00Z'), '%Y-%m-%d %H:%M')

2026-03-15 09:30

format_time ​

Formats a PlainTime.

format_time(time, pattern)

format_time(PlainTime('09:30:00'), '%H:%M')

09:30

Standard timestamp formats ​

Prefer to_rfc3339 and to_rfc2822 over a hand-written pattern when a protocol calls for a standard layout. These functions preserve the required format without relying on a manually maintained pattern.

to_rfc3339 ​

Formats a DateTime as RFC 3339, the format most JSON APIs expect.

Rejects offsets with nonzero seconds.

to_rfc3339(datetime)

to_rfc3339(DateTime('2026-03-15T09:30:00Z'))

2026-03-15T09:30:00Z

to_rfc2822 ​

Formats a DateTime as RFC 2822, the format used in email headers.

Rejects offsets with nonzero seconds.

to_rfc2822(datetime)

to_rfc2822(DateTime('2026-03-15T09:30:00Z'))

Sun, 15 Mar 2026 09:30:00 +0000

Parse a datetime ​

The following functions parse a string into a temporal type, the inverse of formatting one:

parse_datetime ​

Parses a string into a DateTime.

parse_datetime(text, options)

An unrecognized option key raises E222 rather than being ignored.

parse_datetime('2026-03-15T09:30:00Z')

2026-03-15T09:30:00Z

parse_datetime('15/03/2026', {format: '%d/%m/%Y'})

2026-03-15T00:00:00Z

parse_plain_datetime ​

Parses a string into a PlainDateTime, with no zone attached.

The only option is format. An unrecognized option key raises E222.

parse_plain_datetime(text, options)

parse_plain_datetime('2026-03-15 09:30', {format: '%Y-%m-%d %H:%M'})

2026-03-15T09:30:00

Format numbers ​

Both of these use the data-plane locale, which is configured on the Transform data action rather than passed as an argument. The same expression renders differently for different locales.

The following examples show the default locale, en-US.

to_local_string ​

Formats a number using the locale's grouping and decimal separators.

to_local_string(number)

to_local_string(1234567.891)

1,234,567.89

to_local_currency ​

Formats a number as a currency amount, using the locale's currency symbol and conventions.

to_local_currency(number)

to_local_currency(1234.5)

$1,234.50

Join a list into a string ​

The following functions join a list's elements into a single delimited string:

join_to_string ​

Joins the elements of a list into one string, with an optional separator. Omitting the separator concatenates the elements directly.

join_to_string(list, separator)

join_to_string(['a', 'b', 'c'], ', ')

a, b, c

join_to_string(['a', 'b'])

ab

join_to_local_string ​

Joins the elements using the list separator from the data-plane locale, rather than one you supply.

join_to_local_string(list, separator)

join_to_local_string(['a', 'b', 'c'])

a, b, c

Serialize to WEL ​

The following function serializes a value to WEL's own literal syntax, for logging and debugging:

to_wel ​

Serializes a value to a WEL literal that parses back to the same value.

to_wel is useful for logging and for debugging a transformation, because it shows exactly what a value is rather than an approximation of it. Use to_json for data leaving the recipe.

to_wel(value)

to_wel({sku: 'WID-1', qty: 3})

{sku: 'WID-1', qty: 3}

Use case: Build an order confirmation line ​

An order confirmation line needs several values combined into one finished sentence. Format the values once, at the end, in an f-string:

Input

{
  "id": "SO-1001",
  "ship_date": "2026-03-15",
  "total": 149.5
}

Formula

f"Order {_.id} ships {format_date(PlainDate(_.ship_date), '%d %b %Y')} for {to_local_currency(_.total)}"

Output

"Order SO-1001 ships 15 Mar 2026 for $149.50"

The date is converted to a PlainDate before being formatted, so the day can't shift. The currency is left to the locale rather than hard-coded, so the same expression is correct for a recipe configured for another region.

Related ​

• Temporal functions: Handle arithmetic and time zones before you format a value.
• Conversion functions: How to construct each data type.
• Strings and formatting: F-strings and format specifications.
• Transform data: Set the data-plane locale these functions use.