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: The format differs by series. In the 4.0 series starting with 4.0.2609.0, this is returned in JSON array format (for example, ["value1","value2",...]); elements are serialized recursively, so nested arrays or maps are also converted to JSON. This applies to object arrays and lists such as those returned by array(), but not to primitive arrays such as the byte[] returned by binary() (for which the toString() result is returned as-is). In the 5.0 series (through 5.0.2605.2), elements are instead recursively converted and returned in [value1,value2,...] format (not JSON).
• Map: The format differs by series. In the 4.0 series starting with 4.0.2609.0, this is returned in JSON object format (for example, {"key1":"value1","key2":"value2"}). In the 5.0 series (through 5.0.2605.2), there is no dedicated Map handling, so the default toString() representation (for example, {key1=value1, key2=value2}) is returned instead.
• Timestamp values inside an array, list, or map: In the 4.0 series starting with 4.0.2609.0, these are serialized as strings in yyyy-MM-dd HH:mm:ssZ format; this does not affect applying DATE_FMT/TIMEZONE to a scalar timestamp value. The 5.0 series (through 5.0.2605.2) does not perform this format-specific serialization for nested timestamps.
• 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
   

5. Converting an array — format differs by series

   json "{}" | eval arr = array("a", "b") | eval result = string(arr)
   | # 5.0 series (through 5.0.2605.2) result: [a,b] / 4.0 series (4.0.2609.0 and later) result: ["a","b"]
   

   In the 5.0 series (through 5.0.2605.2), the result is in [a,b] format. In the 4.0 series starting with 4.0.2609.0, it is output in JSON array format (["a","b"]) instead.

6. Converting a map — format differs by series

   json "{'m': {'k': 'v', 'n': 1}}" | eval result = string(m)
   | # 5.0 series (through 5.0.2605.2) result: {k=v, n=1} / 4.0 series (4.0.2609.0 and later) result: {"k":"v","n":1}
   

   In the 5.0 series (through 5.0.2605.2), the result uses the default toString() representation ({k=v, n=1}). In the 4.0 series starting with 4.0.2609.0, it is output in JSON object format ({"k":"v","n":1}) instead.

Change history