format_bytes

This page explains how to use the format_bytes function in APL.

The format_bytes function formats a numeric value as a human-readable string representing data size in bytes with appropriate units (KB, MB, GB, etc.). Use this function to make byte values more readable in reports, dashboards, and log analysis.

For users of other query languages

If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.

Splunk SPL users

In Splunk SPL, you typically need custom eval expressions or lookup tables to format bytes. APL’s format_bytes provides this functionality natively.

Splunk example

| eval size_str=if(bytes<1024, bytes." B", if(bytes<1048576, round(bytes/1024,2)." KB", round(bytes/1048576,2)." MB"))

ANSI SQL users

In ANSI SQL, formatting bytes requires complex CASE statements. APL’s format_bytes simplifies this operation.

SQL example

SELECT CASE 
  WHEN bytes < 1024 THEN CONCAT(bytes, ' B')
  WHEN bytes < 1048576 THEN CONCAT(ROUND(bytes/1024, 2), ' KB')
  ELSE CONCAT(ROUND(bytes/1048576, 2), ' MB')
END AS size_str FROM logs;

Usage

Syntax

format_bytes(value, precision, units, base)

Parameters

Name	Type	Required	Description
value	number	Yes	The numeric value representing bytes to format.
precision	number	No	Number of decimal places (default: 0).
units	string	No	Target units (e.g., ‘KB’, ‘MB’, ‘GB’). If omitted, units are auto-selected.
base	number	No	Either 2 (default, 1024-based) or 10 (1000-based) for unit calculations.

Returns

Returns a formatted string representing the byte value with appropriate units.

Use case examples

Log analysis

Format request duration values as human-readable sizes for better analysis of payload patterns.

Query

['sample-http-logs']
| extend formatted_duration = format_bytes(req_duration_ms, 2)
| summarize avg_size = avg(req_duration_ms), formatted_avg = format_bytes(toint(avg(req_duration_ms)), 2) by status
| sort by avg_size desc
| limit 10

Run in Playground

Output

status	avg_size	formatted_avg
500	8765432	8.36 MB
200	3456789	3.30 MB
404	1234567	1.18 MB
301	456789	446.08 KB

This query formats average request duration values by HTTP status code, making it easier to identify which status codes are associated with larger data transfers.

List of related functions

• parse_bytes: Parses a formatted byte string back to a numeric value. Use this to reverse the formatting operation.
• strlen: Returns the length of a string in characters. Use this when you need character count rather than byte formatting.