> ## Documentation Index
> Fetch the complete documentation index at: https://axiom.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://axiom.co/docs/feedback

```json
{
  "path": "/apl/scalar-functions/string-functions/format-bytes",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# 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.

<AccordionGroup>
  <Accordion title="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.

    <CodeGroup>
      ```sql Splunk example theme={null}
      | eval size_str=if(resp_header_size_bytes<1024, resp_header_size_bytes." B", if(resp_header_size_bytes<1048576, round(resp_header_size_bytes/1024,2)." KB", round(resp_header_size_bytes/1048576,2)." MB"))
      ```

      ```kusto APL equivalent theme={null}
      ['sample-http-logs']
      | extend size_str = format_bytes(resp_header_size_bytes)
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="ANSI SQL users">
    In ANSI SQL, formatting bytes requires complex CASE statements. APL's `format_bytes` simplifies this operation.

    <CodeGroup>
      ```sql SQL example theme={null}
      SELECT CASE 
        WHEN resp_header_size_bytes < 1024 THEN CONCAT(resp_header_size_bytes, ' B')
        WHEN resp_header_size_bytes < 1048576 THEN CONCAT(ROUND(resp_header_size_bytes/1024, 2), ' KB')
        ELSE CONCAT(ROUND(resp_header_size_bytes/1048576, 2), ' MB')
      END AS size_str FROM logs;
      ```

      ```kusto APL equivalent theme={null}
      ['sample-http-logs']
      | extend size_str = format_bytes(resp_header_size_bytes)
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Usage

### Syntax

```kusto theme={null}
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. If omitted, units are auto-selected. Base 2 suffixes: `Bytes`, `KiB`, `KB`, `MiB`, `MB`, `GiB`, `GB`, `TiB`, `TB`, `PiB`, `EiB`, `ZiB`, `YiB`. Base 10 suffixes: `kB`, `MB`, `GB`, `TB`, `PB`, `EB`, `ZB`, `YB`. |
| 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

<Tabs>
  <Tab title="Log analysis">
    Format response header sizes as human-readable values for better analysis of payload patterns.

    **Query**

    ```kusto theme={null}
    ['sample-http-logs']
    | extend formatted_size = format_bytes(resp_header_size_bytes, 2)
    | summarize avg_size = avg(resp_header_size_bytes), formatted_avg = format_bytes(toint(avg(resp_header_size_bytes)), 2) by status
    | sort by avg_size desc
    | limit 10
    ```

    [Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%20%7C%20extend%20formatted_size%20%3D%20format_bytes\(resp_header_size_bytes%2C%202\)%20%7C%20summarize%20avg_size%20%3D%20avg\(resp_header_size_bytes\)%2C%20formatted_avg%20%3D%20format_bytes\(toint\(avg\(resp_header_size_bytes\)\)%2C%202\)%20by%20status%20%7C%20sort%20by%20avg_size%20desc%20%7C%20limit%2010%22%7D)

    **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 response header sizes by HTTP status code, making it easier to identify which status codes are associated with larger data transfers.
  </Tab>

  <Tab title="Security logs">
    Format response header sizes for failed authentication attempts to identify potential data exfiltration or unusual payload patterns.

    **Query**

    ```kusto theme={null}
    ['sample-http-logs']
    | where status == '403' or status == '401'
    | extend formatted_size = format_bytes(resp_header_size_bytes, 1)
    | summarize failed_attempts = count(), avg_size = format_bytes(toint(avg(resp_header_size_bytes)), 1) by status
    | sort by failed_attempts desc
    ```

    [Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27sample-http-logs%27%5D%20%7C%20where%20status%20%3D%3D%20%27403%27%20or%20status%20%3D%3D%20%27401%27%20%7C%20extend%20formatted_size%20%3D%20format_bytes\(resp_header_size_bytes%2C%201\)%20%7C%20summarize%20failed_attempts%20%3D%20count\(\)%2C%20avg_size%20%3D%20format_bytes\(toint\(avg\(resp_header_size_bytes\)\)%2C%201\)%20by%20status%20%7C%20sort%20by%20failed_attempts%20desc%22%7D)

    **Output**

    | status | failed\_attempts | avg\_size |
    | ------ | ---------------- | --------- |
    | 401    | 1234             | 850.0 KB  |
    | 403    | 987              | 720.0 KB  |

    This query formats average response header sizes, helping identify unusual payload patterns that might indicate security issues.
  </Tab>
</Tabs>

## List of related functions

* [parse\_bytes](/apl/scalar-functions/string-functions/parse-bytes): Parses a formatted byte string back to a numeric value. Use this to reverse the formatting operation.
* [strlen](/apl/scalar-functions/string-functions/strlen): Returns the length of a string in characters. Use this when you need character count rather than byte formatting.