Function Syntax

Humio's query functions take a set of events, parameters, or configurations. From this, they produce, reduce, or modify values within that set, or in the events themselves within a query pipeline. Humio has many built-in query functions. They're listed and described in the Query Functions section.

Composite Function Calls

Whenever a function accepts a function as an argument, there are some special rules. For all variations of groupBy(), bucket() and timeChart(), that take a function= argument, you can also use a composite function. Composite functions take the form { f1(..) | f2(..) } which works like the composition of f1 and f2. For example, you can do

humio
groupBy(type, function={ avgFoo := avg(foo) | outFoo := round(avgFoo) })

You can also use filters inside such composite function calls, but not saved queries.

Incidentally, queries can contains comments. This is useful for long multi-line queries and especially with saved queries since later you may not remember the purpose of each step. Below is an example of a comment embedded in a query:

humio
#type=accesslog // choose the type
| top(url)  // count urls and choose the most frequently used

User Functions

In addition to built-in functions, you can create your own functions by saving a query you use often. Then it can be used as a top-level element of another query, similar to a function call.

To use a saved query this way you invoke it using the syntax $"SAVED_QUERY_NAME"() or, if the name does not contain whitespace or special characters you can use $nameOfSavedQuery() without quotes. A typical use for this is to define a filter or extraction ruleset that you can use as a prefix of another query.

Below is an example of how you might name and use a custom function:

humio
$"My Saved Query"() | $filterOutFalsePositive() | ...
Using Arguments with User Functions

You can add arguments to your user functions by using the ?argname in your saved query; you then call the saved query and supply the argument name and matching value. For example, given the following query:

humio
host = ?host

Now save the query as findhost, you can execute the query using:

humio
$findhost(host="gendarme")

Multiple arguments can be during the process. For example, when processing syslog data you can parse the content, create new fields, and then query that in the output:

humio
regex(regex="Service exited due to (?<signal>\S+)")| signal = ?signal
| regex(regex="sent by (?<process>\S+)[\d+]")| process = ?process

Now we have two arguments which we can save to as a query killedprocess and then query for killed processes:

humio
$killedprocess(signal="SIGKILL", process="mds")

To call with only one argument, you can set a default value for the argument using ?{argument=default}, for example:

humio
?{signal="*" }
| ?{process="*"}
| regex(regex="Service exited due to (?<signal>\S+)")
| signal = ?signal
| regex(regex="sent by (?<process>\S+)\[\d+\]")
| process = ?process

Now you call the query with either argument:

humio
$killedprocess(process="mds")

Repeating Queries

Some functions have limitations around their use in live queries, such as join() — see beta:repeating() and selfJoin().

Beginning with version 1.17, Humio provides an alternative way of doing live queries to overcome these limitations: repeating queries. A repeating query is a static query that is executed at regular intervals and can be used in the same places as live queries, such as in dashboards or alerts.

When this feature is enabled,you can turn a live query into a repeating by adding the beta:repeating() function to the query. For example, this query will be repeated every 10 minutes and can be used in dashboards and alerts:

humio
selfJoin(field=email_id, where=[{from=peter},{to=anders}]) | beta:repeating(10m)

Using beta:repeating() in a static query is allowed, but has no effect.

If query snapshot cache is enabled, the static queries made by a repeating query will reuse previous results and will consequently not be as much work for Humio to execute as a regular static query. When this happens, the update interval will be adjusted to the nearest time-bucket.

Enabling Repeating Queries

Repeating queries are in beta. In order to use repeating queries, you must enable them by making the following GraphQL mutation as root from the API explorer found at $$YOUR_HUMIO_URL/docs/api-explorer:

graphql
mutation {
    enableFeature(feature: RepeatingQueries)
}

Note that if this feature is disabled later then any alert, dashboard, or saved query using beta:repeating() in the query will not function.