string()

Converts a value to a string, or formats a timestamp value using a specified format.

Syntax

The str() function provides the same functionality.

Parameters

EXPR

The value or expression to convert to a string.

DATE_EXPR

A value or expression of timestamp type.

DATE_FMT

A date format string as defined by Java's SimpleDateFormat class. The following date pattern letters are supported.

Date pattern letters

Letter	Description	Example
G	Era designator	AD
y	Year in calendar	2025 (yyyy); 25 (yy)
M	Month in year	July (MMMM); Jul (MMM); 07 (MM), 7 (M)
w	Week in year	27 (27th week of the year)
W	Week in month	2 (second week of the month)
D	Day in year	10
d	Day in month	189
E	Day of week	Tuesday (EEEE); Tue (E, EE, EEE)
F	Day of week in month	2 (second occurrence of the weekday in the month)
u	Day number of week (1=Monday, …, 7=Sunday)	1
a	AM/PM marker	PM
H	Hour in day (0-23)	0
k	Hour in day (1-24)	24
K	Hour in AM/PM (0-11)	0
h	Hour in AM/PM (1-12)	12
m	Minute in hour	30
s	Second in minute	55
S	Millisecond	978
z	Time zone (general form)	Pacific Standard Time; PST
Z	Time zone (RFC 822 form)	-0800
X	Time zone (ISO 8601 form)	-08;-0800;08:00

TIMEZONE

The time zone to use for output. Accepts offset formats such as "GMT+09", "GMT+0900", "GMT+09:00", abbreviations such as "KST", "UTC", "PST", or IANA time zone IDs. Refer to Time Zone Abbreviations – Worldwide List for time zone abbreviations.

Time zone abbreviation examples

Abbreviation	GMT offset	Description
UTC	GMT+0	Coordinated Universal Time
KST	GMT+9	Korea Standard Time
CEST	GMT+2	Central European Summer Time
MSK	GMT+3	Moscow Standard Time
PST	GMT-7	Pacific Standard Time
EST	GMT-5	Eastern Standard Time

Description

The string() function converts the argument to a string and returns it. If the argument is null, returns null.

Conversion behavior by type:

• Timestamp: Formatted using DATE_FMT and TIMEZONE. If DATE_FMT is not specified, the format "yyyy-MM-dd HH:mm:ss.SSS" is used.
• IP address: Converted to a string by calling getHostAddress().
• Array or list: Each element is recursively converted and returned in [value1,value2,...] format.
• All other types: toString() is called.

Specifying an invalid date format string or an invalid time zone causes an error during the parsing phase.

Error codes

Usage examples

To prepare the WEB_APACHE_SAMPLE table used in these examples, refer to Preparing sample data.

1. Converting the HTTP status code (integer) to a string

   table limit=5 WEB_APACHE_SAMPLE | eval result = string(status) | fields status, result
   | # result: "200", "404", etc.
   

2. Formatting a timestamp in a specified format

   table limit=5 WEB_APACHE_SAMPLE | eval result = string(_time, "yyyy-MM-dd HH:mm:ss") | fields _time, result
   | # result: "2024-11-18 17:40:25", etc.
   

3. Formatting a timestamp in a specific time zone

   table limit=5 WEB_APACHE_SAMPLE | eval result = string(_time, "yyyy-MM-dd HH:mm:ssZ", "UTC") | fields _time, result
   | # result: a date string in the specified time zone
   

4. NULL input

   json "{'val': null}" | eval result = string(val)
   | # result: null
   

Compatibility

The string() function has been available since before Sonar 4.0.