# unit:convert() Query Function

Convert values between different units. Such as, `514 ms` to `0.514` or `sizeInKiB=4` to `size=4096`.

Troubleshooting note: If the unit begins with a reserved prefix character, try manually setting the unit parameter.

Any unit is supported and the following unit prefixes are converted:

Prefix

Decimal Factor

Binary Factor

Prefix

Typical Value

Y

10^24

1024^8

Yotta-

Bytes

Z

10^21

1024^7

Zetta-

Bytes

E

10^18

1024^6

Exa-

Bytes

P

10^15

1024^5

Peta-

Bytes

T

10^12

1024^4

Tera-

Bytes

G

10^9

1024^3

Giga-

Bytes

M

10^6

1024^2

Mega-

Bytes

k

10^3

1024

Kilo-

Metric, Bytes

h

10^2

Hect-

Metric

da

10^1

Deca-

Metric

d

10-1

Deci-

Metric

c

10-2

Centi-

Metric

m

10-3

Milli-

Metric, Seconds

u

10-6

Micro-

Metric, Seconds

µ

10-6

Micro-

Metric, Seconds

n

10-9

Nano

Metric, Seconds

p

10-12

Pico

Metric, Seconds

f

10-15

Femto

Metric, Seconds

a

10-18

Atto

Metric, Seconds

z

10-21

Zepto

Metric, Seconds

y

10-24

Yocto

Metric, Seconds

Ki

2^10

1024

Kibi

Bytes

Mi

2^20

1024^2

Mebi

Bytes

Gi

2^30

1024^3

Gibi

Bytes

Ti

2^40

1024^4

Tebi

Bytes

Pi

2^50

1024^5

Pebi

Bytes

Ei

2^60

1024^6

Exbi

Bytes

Zi

2^70

1024^7

Zebi

Bytes

Yi

2^80

1024^8

Yobi

Bytes

If a field contains a value such as 5 kB that should be treated as 5 KiB, set the binary flag.

When the unit is a rate, such as MB/min the rate will be normalized to per second, e.g. B/s.

The following rate conversions are supported: `s`, `sec`, `m`, `min`, `h`, `hour`, `d`, `day`, `w`, `week`.

## Parameters

Name

Type

Required

Default

Description

field

string

Yes

The name of the input field.

as

string

No

The output name of the field to set (defaults to the same as the input field).

from

string

No

If the field contains unitless values, specify this parameter to tell which unit the value should be normalized from.

to

string

No

The output field should have the value converted to this unit.

unit

string

No

If specified, the field must end with this unit.

binary

boolean

No

If specified, unit prefixes `kMGTPEZY` will be treated as powers of 1024 instead of 1000.

keepUnit

boolean

No

If specified, the output field will have the normalized unit appended.

The implied parameter is `field`.

## Examples

Parses a value into a number by removing the unit. An input event with the field size with the value 5 MB results in the field size having the value `5000000`.

humio
``````unit:convert(size)
``````

Parses a value into a number by removing the unit. An input event with the field size with the value 5 MiB results in the field size having the value `5242880`.

humio
``````unit:convert(size)
``````

Parses a value into a number by removing the unit. An input event with the field size with the value 5 MB results in the field size having the value `5242880`.

humio
``````unit:convert(size, binary=true)
``````

Parses a value into a number by removing the unit. An input event with the field duration with the value `514` us results in the field duration having the value `0.000514`.

humio
``````unit:convert(duration)
``````

Parses a unit less value into a number by manually specifying the input unit. An input event with the field size with the value `234.567` results in the field size having the value `234567`.

Internally the value is parsed as `{size} {from}`, just as if the field had contained the value `234.567 k`.

humio
``````unit:convert(size, from="k")
``````

Parses a value into a number by removing the unit. An input event with the field rate with the value 120 hits/min results in the field rate having the value `2`.

Note: since the unit in this case starts with a letter h from the supported prefixes, it will be interpreted as the prefix `h` (102) and unit its. To enforce that the unit is actually hits, specify the unit parameter.

humio
``````unit:convert(rate, as="rate", unit="hits")
``````

Converts a number into a value with a unit. An input event with the field size with the value 19886168 results in the field rate having the value 19.886168.

humio
``````unit:convert(rate, as="rate", to="M")
``````