# Time Syntax

As a part of the Humio Query Language, there is a syntax in particular related to time and dates. This reference page describes how you can convert timestamps and other time related values to different values and formats. This is covered in the next section. The section after that provides a table of relative time syntax to which you may often want to refer.

## Rate Unit Conversion

When displaying a rate (somethings per unit of time) in a timechart(), the display is sensitive to the size of the chart’s `span` or `bucket` parameter, if the thing being graphed is a sum() or count() of log data.

You can use `timechart(function=sum(bytes),span=1h)` to show an hourly rate. But sometimes you want a rate (say `Kibytes/sec`) for which it does not make sense to create a bucket for each. Previously we have suggested to use a successive eval() to reduce the chart inputs, but that’s rather cumbersome and also sensitive to the size of the buckets (the span of each bar in the chart). Unit conversions can resolve this.

### Source-Unit is a Sum or Count

You can convert using a syntax like `timechart(function=sum(bytes), unit="bytes/span to Mi bytes/day")`. This will make it so that the conversion takes the timespan into account. If you use the above with `span=1d` there will be no conversion, but if you it with `span=1h`, then the plotted values will be multiplied by 24 (because there are 24hours in a day). You can use `/span` or `/bucket` interchangeably.

### Source-Unit is Already a Rate

You can convert using a syntax like `timechart(..., unit="bytes/sec to Mibytes/day")`. In this case, the source is already a rate (measured in units per time). With this the conversion is applied independently of the length of the span (bucket size) for the graph.

### Expressing Rates & Units

Units in this system is either a base unit (like events or bytes) or a rate, like a base unit per time unit. The syntax for a base unit is this

humio
``````base_unit    ::= Number_opt SIunit_opt unitname_opt
Number_opt   ::= ([0-9]+)?
SIunit_opt   ::= ([KMGP]i?|)
unitname_opt ::= (' '? <string>)?
``````

So one example of a base unit is `2Gi bytes`. We use the standard SI-units K, M, G, and P to denote 1000-based kilo, mega, giga and peta; whereas Ki, Mi, Gi, and Pi designate 1024^n style. See the National Institute of Standards & Technology’s Reference on Prefixes for Binary Multiples for a detailed explanation.

The `unitname_opt` can optionally be separated from the SI unit with a single space to be able to differentiate names unit names starting with an `i`.

Time units follow the same pattern, as you see here:

humio
``````time_unit    ::= Number_opt Time
Number_opt   ::= ([0-9]+)?
Time         ::= prefix-of( "seconds, "milliseconds", "minutes", "hours" "days" ) | "ms" | "bucket" | "span"
``````

The non-uniq prefixes `m` and `mi` are interpreted as minutes. Whereas, `ms` designates milliseconds. A rate is like so:

humio
``````Rate ::=   base_unit "/" time_unit
``````

Since the entirety of base-unit is optional—a missing base unit is implied to be one—you can convert from events/second to events/hour with a minimal expression such as this:

humio
``````unit="/s to /h"
``````

The `to` side of such a conversion must be a rate, whereas the left side can be a basic unit, which is interpreted as `unit/bucket`.

## Relative Time Syntax

In many places in Humio you have to specify a time interval. For example when specifying the time interval for a query or when using the timechart() query function.

To make specifying a time more flexible, Humio supports a relative time syntax. This lets you express a simple time duration, rather than specifying two absolute times.

You specify a relative time modifier as a number followed by a word. The following table shows which words you can use:

Time Unit

Accepted Values

Milliseconds

`millisecond`, `milliseconds`, `millis`, `ms`

Seconds

`second`, `seconds`, `s`, `sec`, `secs`

Minutes

`minute`, `minutes`, `m`, `min`

Hours

`hour`, `hours`, `h`, `hr`, `hrs`

Days

`day`, `days`, `d`

Weeks

`week`, `weeks`, `w`

Months

`month`, `months`, `mon`

Quarters

`quarter`, `quarters`, `q`, `qtr`, `qtrs`

Years

`year`, `years`, `y`, `yr`, `yrs`

You can include a space character between the number and the unit of time.

### Examples

`2h`

`2 hours`

`3 weeks`

`10s` or `10seconds`

### Regular Expression

This regular expression describes the format:

humio
``````^(\d+) ?(years?|y|yrs?|quarters?|q|qtrs?|months?|mon|weeks?|w|days?|d|hours?|hr?|hrs|minutes?|m|min|seconds?|s|secs?|milliseconds?|millis|ms)\$
``````