DateTimeZone.ToText
DateTimeZoneConverts a datetimezone value to a text string.
Syntax
DateTimeZone.ToText(dateTimeZone as nullable datetimezone, optional options as any) as nullable textParameters
| Name | Type | Required | Description |
|---|---|---|---|
dateTimeZone | datetimezone | Yes | The datetimezone value to convert to text. |
options | any | No | A record or culture text string. Supported record fields: Format (custom format string, e.g., "yyyy-MM-ddTHH:mm:sszzz") and Culture (e.g., "en-US"). |
Return Value
text — A text representation of the datetimezone, or null if the input is null.
Remarks
DateTimeZone.ToText formats a datetimezone value as a text string. Without options, it produces an ISO 8601 string including the UTC offset such as "2024-03-15T14:30:00+05:30". Use the Format field in the options record to apply a custom pattern; the format specifier zzz produces the offset in ±HH:mm notation. Format strings follow .NET custom datetime format conventions.
Always specify Culture when using locale-sensitive specifiers such as MMMM (full month name) or dddd (full day name). Without an explicit Culture, output depends on the host machine's locale setting, which can differ between Power BI Desktop and Power BI Service cloud refresh. Use "en-US" as a consistent default for English output.
If the input is null, the function returns null. To format a datetime without timezone information, use DateTime.ToText. To format a date-only value, use Date.ToText.
Examples
Example 1: Format datetimezone values as ISO 8601 strings
#table(
type table [DTZ = datetimezone, AsText = text],
{
{#datetimezone(2024, 1, 15, 9, 30, 0, -5, 0),
DateTimeZone.ToText(#datetimezone(2024, 1, 15, 9, 30, 0, -5, 0), [Format="yyyy-MM-ddTHH:mm:sszzz", Culture="en-US"])},
{#datetimezone(2024, 3, 15, 14, 0, 0, 1, 0),
DateTimeZone.ToText(#datetimezone(2024, 3, 15, 14, 0, 0, 1, 0), [Format="yyyy-MM-ddTHH:mm:sszzz", Culture="en-US"])}
}
)DTZ | AsText | |
|---|---|---|
| 1 | 1/15/2024 2:30:00 PM | 2024-01-15T09:30:00-05:00 |
| 2 | 3/15/2024 1:00:00 PM | 2024-03-15T14:00:00+01:00 |
Example 2: Format with a human-readable pattern including offset
#table(
type table [DTZ = datetimezone, Formatted = text],
{{#datetimezone(2024, 3, 15, 14, 30, 0, 5, 30),
DateTimeZone.ToText(#datetimezone(2024, 3, 15, 14, 30, 0, 5, 30),
[Format="MMMM d, yyyy h:mm tt (zzz)", Culture="en-US"])}}
)DTZ | Formatted | |
|---|---|---|
| 1 | 3/15/2024 9:00:00 AM | March 15, 2024 2:30 PM (+05:30) |
Example 3: Format log timestamps with short date and 24-hour time
Table.AddColumn(
Table.SelectColumns(Table.FirstN(OrderLog, 4), {"LogID", "Timestamp"}),
"TimestampLabel",
each DateTime.ToText([Timestamp], [Format="dd-MMM HH:mm", Culture="en-US"]),
type text
)LogID | Timestamp | TimestampLabel | |
|---|---|---|---|
| 1 | L001 | 1/15/2024 9:30:00 AM | 15-Jan 09:30 |
| 2 | L002 | 1/16/2024 2:15:00 PM | 16-Jan 14:15 |
| 3 | L003 | 1/18/2024 11:00:00 AM | 18-Jan 11:00 |
| 4 | L004 | 1/20/2024 8:45:00 AM | 20-Jan 08:45 |