Unit conversion functions - Simple Log Service - Alibaba Cloud Documentation Center

Simple Log Service provides unit conversion functions for converting data sizes and time intervals between units.

Log Service provides the following unit conversion functions.

Important If you want to use strings in analytic statements, you must enclose strings in single quotation marks (''). Strings that are not enclosed or enclosed in double quotation marks ("") indicate field names or column names. For example, 'status' indicates the status string, and status or "status" indicates the status log field.

Category	Function	Syntax	Description	SQL	SPL
Data size conversion functions	convert_data_size function	convert_data_size(x)	Automatically converts a data size to the most appropriate human-readable unit. For example, it converts 1024 KB to 1 MB and 1024 MB to 1 GB. Returns a string.	√	×
	convert_data_size function	convert_data_size(x, unit)	Converts a data size to the specified unit. Returns a string.	√	×
	format_data_size function	format_data_size(x, unit)	Formats a data size in bytes into a string in the specified unit. Returns a string.	√	×
	parse_data_size function	parse_data_size(x)	Parses a string representing a data size and returns the value in bytes. Returns a decimal.	√	×
	to_data_size_B function	to_data_size_B(x)	Converts a data size to its value in bytes. Returns a double.	√	×
	to_data_size_KB function	to_data_size_KB(x)	Converts a data size to its value in kilobytes (KB). Returns a double.	√	×
	to_data_size_MB function	to_data_size_MB(x)	Converts a data size to its value in megabytes (MB). Returns a double.	√	×
	to_data_size_GB function	to_data_size_GB(x)	Converts a data size to its value in gigabytes (GB). Returns a double.	√	×
	to_data_size_TB function	to_data_size_TB(x)	Converts a data size to its value in terabytes (TB). Returns a double.	√	×
	to_data_size_PB function	to_data_size_PB(x)	Converts a data size to its value in petabytes (PB). Returns a double.	√	×
Time interval conversion functions	format_duration function	format_duration(x)	Formats a time interval, provided in seconds, into a human-readable string.	√	×
	parse_duration function	parse_duration(x)	Parses a duration string, such as one in `0 00:00:00.000` format, and returns the value in seconds.	√	×
	to_days function	to_days(x)	Converts a time interval to its value in days. Returns a double.	√	×
	to_hours function	to_hours(x)	Converts a time interval to its value in hours. Returns a double.	√	×
	to_microseconds function	to_microseconds(x)	Converts a time interval to its value in microseconds. Returns a double.	√	×
	to_milliseconds function	to_milliseconds(x)	Converts a time interval to its value in milliseconds. Returns a double.	√	×
	to_minutes function	to_minutes(x)	Converts a time interval to its value in minutes. Returns a double.	√	×
	to_most_succinct_time_unit function	to_most_succinct_time_unit(x)	Automatically converts a time interval to the most succinct human-readable unit. Returns a string.	√	×
	to_nanoseconds function	to_nanoseconds(x)	Converts a time interval to its value in nanoseconds. Returns a double.	√	×
	to_seconds function	to_seconds(x)	Converts a time interval to its value in seconds. Returns a double.	√	×

convert_data_size function

Converts a data size to a different unit, either automatically or to a specified target unit.

Syntax

Converts a data size to the optimal unit, which the system determines automatically.
```
convert_data_size(x)
```
Converts a data size to a specified unit.
```
convert_data_size(x, unit)
```

Parameters

Parameter	Description
x	The data size, which must be a string.
unit	The target unit. Valid values: KB, MB, GB, TB, PB, EB, ZB, and YB.

Return value type

Returns a string.

Examples

Example 1: Convert 1200 KB to a different unit.
- Query and analysis statement
```
* | SELECT convert_data_size('1200KB')
```
- The result is 1.17MB.
Example 2: The body_bytes_sent field represents the number of bytes sent to the client. This example converts the field value to KB.
- Query and analysis statement
```
* | select convert_data_size(format_data_size(body_bytes_sent, 'KB'))
```
- The _col0 column displays the converted data sizes, such as 1.74KB, 11.38KB, 4.12KB, and 1.19KB. The query first uses format_data_size to convert the body_bytes_sent value to a string in KB, then processes it with convert_data_size.

Format_data_size function

Formats a byte value as a string in a specified unit.

Syntax

format_data_size(x, unit)

Parameters

Parameter	Description
x	The data size in bytes. Must be a bigint.
unit	The target unit for the conversion. Valid values: KB, MB, GB, PB, TB, EB, ZB, and YB.

Return value type

Returns a string.

Examples

Example 1: The body_bytes_sent field represents the number of bytes sent to a client. This example converts the field's value to kilobytes (KB).
- Sample field
```
body_bytes_sent:4619
```
- Query and analysis statement
```
* | select format_data_size(body_bytes_sent, 'KB')
```
- The _col0 column in the query and analysis results contains values such as 7.33 KB, 2.19 KB, 4.16 KB, and 4.84 KB.
Example 2: This example calculates the sum of the body_bytes_sent field and then converts the total to gigabytes (GB).
- Sample field
```
body_bytes_sent:4619
```
- Query and analysis statement
```
* | select format_data_size(sum(body_bytes_sent), 'GB')
```
- The _col0 column returns 0.73 GB, the formatted sum of the body_bytes_sent field values.

parse_data_size

Parses a data size string and returns the equivalent value in bytes.

Syntax

parse_data_size(x)

Parameters

Parameter	Description
x	The data size to parse. Must be a string.

Return value type

Returns a value of type decimal.

Examples

Convert 1024 KB to its equivalent value in bytes.

Query statement
```
*| SELECT parse_data_size('1024KB')
```
The query returns 1048576, the equivalent of 1024 KB in bytes.

to_data_size_B function

Converts a data size to bytes.

Syntax

to_data_size_B(x)

Parameters

Parameter	Description
x	The data size. This parameter must be a string.

Return value type

Returns a double value.

Examples

Convert 1024 KB to its equivalent value in bytes.

Query and analysis statement
```
* | select to_data_size_B('1024KB')
```
The query and analysis result is 1048576.0, the equivalent of 1024 KB in bytes.

to_data_size_KB

Converts a data size to kilobytes (KB).

Syntax

to_data_size_KB(x)

Parameters

Parameter	Description
x	The data size. This value must be a `string`.

Return value type

The return value is a double.

Examples

The body_bytes_sent field represents the number of bytes sent to the client. This example converts the field value to KB.

Query and analysis statement

* | select to_data_size_KB(format_data_size(body_bytes_sent, 'KB'))

The _col0 column in the query and analysis results contains the values 3.52, 4.25, 3.2, and 1.69.

to_data_size_MB function

Converts a data size to megabytes (MB).

Syntax

to_data_size_MB(x)

Parameters

Parameter	Description
x	The data size, which must be a string.

Return value type

This function returns a double value.

Examples

The body_bytes_sent field represents the number of bytes sent to the client. This example converts the total to megabytes (MB).

Query and analysis statement

* | select to_data_size_MB(format_data_size(sum(body_bytes_sent), 'KB'))

The query returns 814.49, which is the sum of body_bytes_sent converted to megabytes (MB).

to_data_size_GB function

Converts a data size to gigabytes (GB).

Syntax

to_data_size_GB(x)

Parameters

Parameter	Description
x	The data size to convert. The value must be a string.

Return value type

A double value.

Examples

The body_bytes_sent field represents the number of bytes sent to the client. This example converts the total to gigabytes (GB).

Query and analysis statement

* | select to_data_size_GB(format_data_size(sum(body_bytes_sent), 'KB'))

The query returns 0.79. This value is the total number of bytes sent, in gigabytes (GB).

to_data_size_TB function

Converts a data size to terabytes (TB).

Syntax

to_data_size_TB(x)

Parameters

Parameter	Description
x	The data size, specified as a string.

Return value type

Returns a double value.

Examples

The body_bytes_sent field represents the number of bytes sent to a client. This example converts the total to terabytes (TB).

Query statement

* | select to_data_size_TB(format_data_size(sum(body_bytes_sent), 'KB'))

The query returns a single column, _col0, with the value 0.01, which represents the sum of body_bytes_sent in terabytes (TB).

to_data_size_PB function

Converts a data size to petabytes (PB).

Syntax

to_data_size_PB(x)

Parameters

Parameter	Description
x	The data size. The value must be a string.

Return value type

Returns a double.

Examples

Convert 1,048,576 GB to petabytes (PB).

Query and analysis statement
```
*| SELECT to_data_size_PB('1048576GB')
```
The query and analysis results return 1.0, meaning 1,048,576 GB equals 1.0 PB.

format_duration function

Formats a time interval in seconds into a human-readable string.

Syntax

format_duration(x)

Parameters

Parameter	Description
x	The time interval to format. The value must be a double.

Return value type

Returns the formatted time interval as a string.

Examples

Formats 235 seconds as 3 minutes, 55 seconds.

Query statement
```
* | SELECT format_duration(235)
```
The _col0 column returns 3 minutes, 55 seconds.

parse_duration

Parses a time interval string into the 0 00:00:00.000 format.

Syntax

parse_duration(x)

Parameters

Parameter	Description
x	The time interval to parse. The value must be a string.

Return value type

Returns an interval value.

Examples

Convert 1,340 milliseconds into the 0 00:00:01.340 format.

Query statement
```
* | SELECT parse_duration('1340ms')
```
The query returns 0 00:00:01.340, which represents 1,340 milliseconds in the standard time interval format.

to_days function

Converts a time interval to days.

Syntax

to_days(x)

Parameters

Parameter	Description
x	The time interval. This parameter must be a varchar.

Return value type

A double value.

Examples

Convert 192848s to days.

Query statement
```
*| SELECT to_days('192848s')
```
The _col0 column returns 2, indicating that 192848 seconds equals 2 days.

to_hours function

Converts a time interval to hours.

Syntax

to_hours(x)

Parameters

Parameter	Description
x	The time interval to convert. Must be a varchar.

Return value type

Returns a double.

Examples

Convert a 1.2-day time interval to hours.

Query and analysis statement
```
* | SELECT to_hours('1.2d')
```
The value in the query and analysis results is 28.8.

to_microseconds function

Converts a time interval to microseconds.

Syntax

to_microseconds(x)

Parameters

Parameter	Description
x	The time interval, which must be of type varchar.

Return value type

Returns a double.

Examples

Convert 3600 nanoseconds to microseconds.

Query and analysis statement
```
* | SELECT to_microseconds('3600ns')
```
The query and analysis result is 3.6 in the _col0 column.

to_milliseconds

Converts a time interval to milliseconds.

Syntax

to_milliseconds(x)

Parameters

Parameter	Description
x	The time interval. This parameter must be of the varchar type.

Return value type

Returns a double.

Examples

Convert 1.2 seconds to milliseconds.

Query and analysis statement
```
* | SELECT to_milliseconds('1.2s')
```
Query and analysis results: The _col0 column returns the value 1200, meaning 1.2 seconds equals 1,200 milliseconds.

to_minutes function

Converts a time interval to minutes.

Syntax

to_minutes(x)

Parameters

Parameter	Description
x	The time interval. This parameter must be of type varchar.

Return value type

The return value is a double.

Examples

Convert 1.2 hours to minutes.

Query and analysis statement
```
* | SELECT to_minutes('1.2h')
```
The statement returns 72.

to_most_succinct_time_unit

Converts a time interval to its most succinct unit automatically.

Syntax

to_most_succinct_time_unit(x)

Parameters

Parameter	Description
x	The time interval. This parameter must be of the varchar type.

Return value type

The return value is of the varchar type.

Examples

Convert 1,340 ms to a time interval in seconds.

Query and analysis statement:

* | SELECT to_most_succinct_time_unit('1340ms')

Query and analysis results: 1.34s

to_nanoseconds function

Converts a time interval to nanoseconds.

Syntax

to_nanoseconds(x)

Parameters

Parameter	Description
x	The time interval to convert. The value must be of the varchar type.

Return value type

Returns a value of the double type.

Examples

Convert 125 milliseconds to its equivalent value in nanoseconds.

Query statement
```
* | SELECT to_nanoseconds('125ms')
```
The query returns 125000000.

to_seconds function

Converts a time interval to seconds.

Syntax

to_seconds(x)

Parameters

Parameter	Description
x	The time interval to convert. This parameter is a varchar.

Return value type

The return value is a double.

Examples

Convert 1340 milliseconds to seconds.

Query statement
```
* | SELECT to_seconds('1340ms')
```
The query and analysis result is 1.34.