Any node field where an inserted variable reference is displayed as a blue jq expression
Any value, inserted in the field
In these fields, entering the first characters of a function name displays a list of matching functions with a short description. The JQ button next to $var opens a searchable list of all functions. Selecting a function inserts only its name: the parentheses and arguments must be added by hand, as shown in the Function column of each table.
An expression receives no input: . alone evaluates to null. Always start from a variable, inserted with the $var button or by entering $ and selecting a suggestion, for example $input.payload.body.host.name | ascii_downcase.
| passes the result on its left as the input of the expression on its right.
Function arguments are separated by ;, not by ,: sub("a"; "b"). A comma produces several values.
In a string, double each backslash: the regular expression \d is written "\\d", and the domain prefix ACME\ is written "ACME\\".
Examples use literal values so the result can be checked. In a workflow, a variable reference replaces the literal, for example $alert.title | ascii_downcase instead of "Phishing" | ascii_downcase.
Functions that produce several outputs, such as range or scan, are wrapped in [ ] in the examples to collect the outputs into an array.
In the function signatures, filter is a jq expression evaluated by the function, such as .severity > 2 in select(.severity > 2). path is a path expression, such as .password in del(.password). The other argument types are plain values.
Each function returns the input unchanged when it has the expected type, and produces no output otherwise. Combined with map, they filter an array by type.
Function
Description
Example
Result
arrays
Selects arrays
[1, "a", [2]] | map(arrays)
[[2]]
objects
Selects objects
[{"a": 1}, "b"] | map(objects)
[{"a": 1}]
iterables
Selects arrays and objects
[1, [2], {"a": 3}] | map(iterables)
[[2], {"a": 3}]
booleans
Selects booleans
[true, 1, false] | map(booleans)
[true, false]
numbers
Selects numbers
[1, "2", 3] | map(numbers)
[1, 3]
strings
Selects strings
["a", 1, null] | map(strings)
["a"]
nulls
Selects null values
[1, null, 2] | map(nulls)
[null]
values
Selects values that aren't null
[1, null, "a"] | map(values)
[1, "a"]
scalars
Selects values that aren't arrays or objects
[1, "a", [2], {"b": 3}] | map(scalars)
[1, "a"]
normals
Selects normal numbers: finite, non-zero, and not subnormal
Returns the element with the smallest result of the filter
[{"s": 3}, {"s": 1}] | min_by(.s)
{"s": 1}
max_by(filter)
Returns the element with the largest result of the filter
[{"s": 3}, {"s": 1}] | max_by(.s)
{"s": 3}
reverse
Reverses the elements of an array. Fails on a string: use explode | reverse | implode instead
[1, 2, 3] | reverse
[3, 2, 1]
flatten, flatten(number)
Flattens nested arrays, fully or down to the given depth
[1, [2, [3]]] | flatten(1)
[1, 2, [3]]
contains(any)
Returns true if the input completely contains the argument. For strings, tests for a substring, also inside arrays: ["tor-exit"] | contains(["tor"]) is true
"phishing" | contains("ish")
true
inside(any)
Returns true if the input is completely contained in the argument
["a"] | inside(["a", "b"])
true
to_entries
Converts an object to an array of {key, value} objects
{"a": 1} | to_entries
[{"key": "a", "value": 1}]
from_entries
Converts an array of {key, value} objects to an object
[{"key": "a", "value": 1}] | from_entries
{"a": 1}
with_entries(filter)
Applies the filter to each {key, value} entry of an object
{"a": 1} | with_entries(.value += 1)
{"a": 2}
pick(path)
Keeps only the given paths of the input
{"a": 1, "b": {"c": 2, "d": 3}} | pick(.b.c)
{"b": {"c": 2}}
bsearch(any)
Returns the index of the value in a sorted array. If the value is missing, returns -1 - i where i is the position where it would be inserted
Regular expressions use the RE2 syntax. The optional flags argument accepts g for all matches, i for case-insensitive matching, x for extended mode, n to ignore empty matches, and s for single-line mode.
Function
Description
Example
Result
test(string), test(string; string)
Returns true if the string matches the regular expression
"INC-42" | test("^INC-[0-9]+$")
true
match(string), match(string; string)
Returns a match object with offset, length, string, and captures
"INC-42" | match("[0-9]+") | .string
"42"
capture(string), capture(string; string)
Returns an object of the named capture groups
"INC-42" | capture("(?<id>[0-9]+)")
{"id": "42"}
scan(string), scan(string; string)
Returns all non-overlapping matches
"a1b22" | [scan("[0-9]+")]
["1", "22"]
splits(string), splits(string; string)
Splits the string on a regular expression, producing one output per part
"a1b22c" | [splits("[0-9]+")]
["a", "b", "c"]
sub(string; string), sub(string; string; string)
Replaces the first match with the replacement string
Converts the input to a string. Arrays and objects are encoded as JSON
42 | tostring
"42"
toboolean
Converts the strings "true" and "false" to booleans
"true" | toboolean
true
tojson
Encodes the input as a JSON string
{"a": 1} | tojson
"{\"a\":1}"
fromjson
Parses a JSON string into a value
"{\"a\":1}" | fromjson
{"a": 1}
format(string)
Formats the input with the named format: base64, base64d, csv, html, json, sh, text, tsv, uri, or urid. Same as the @base64 shorthand syntax
"hi" | format("base64")
"aGk="
A format can precede a string: only the \(...) parts are encoded. A typical use is building a pivot URL, for example $input.payload.body.source.ip | @uri "https://www.virustotal.com/gui/ip-address/\(.)".
Timestamps are Unix timestamps, in seconds. A broken-down time is an array of [year, month, day, hours, minutes, seconds, day of week, day of year], with the month, day of week, and day of year starting at 0.
Function
Description
Example
Result
now
Returns the current Unix timestamp, with decimals
now | floor
1790812800
todate
Formats a Unix timestamp as an ISO 8601 date string
1700000000 | todate
"2023-11-14T22:13:20Z"
fromdate
Parses an ISO 8601 date string into a Unix timestamp. Fails on fractions of seconds: remove them first with sub("\\.[0-9]+"; "")
"2023-11-14T22:13:20Z" | fromdate
1700000000
todateiso8601
Same as todate
1700000000 | todateiso8601
"2023-11-14T22:13:20Z"
fromdateiso8601
Same as fromdate
"2023-11-14T22:13:20Z" | fromdateiso8601
1700000000
gmtime
Converts a Unix timestamp to a broken-down time in UTC
1700000000 | gmtime
[2023, 10, 14, 22, 13, 20, 2, 317]
localtime
Converts a Unix timestamp to a broken-down time in the time zone of the server running TheHive Flow
1700000000 | localtime
[2023, 10, 14, 22, 13, 20, 2, 317] on a UTC server
mktime
Converts a broken-down time to a Unix timestamp
[2023, 10, 14, 22, 13, 20, 2, 317] | mktime
1700000000
strftime(string)
Formats a Unix timestamp or broken-down time with a format string
1700000000 | strftime("%Y-%m-%d")
"2023-11-14"
strptime(string)
Parses a string into a broken-down time with a format string
"2023-11-14" | strptime("%Y-%m-%d")
[2023, 10, 14, 0, 0, 0, 2, 317]
strflocaltime(string)
Formats a Unix timestamp or broken-down time with a format string, in the time zone of the server running TheHive Flow
Generates numbers up to a limit, from a start, with a step
[range(1; 4)]
[1, 2, 3]
while(filter; filter)
Repeats an update while the condition is true, producing each value
[1 | while(. < 10; . * 2)]
[1, 2, 4, 8]
until(filter; filter)
Repeats an update until the condition is true, producing the final value
1 | until(. > 10; . * 2)
16
repeat(filter)
Applies the filter to the input again and again, producing the same result endlessly. Wrap it in limit. To update a value at each step, use while or range
[limit(3; 1 | repeat(. * 2))]
[2, 2, 2]
recurse, recurse(filter), recurse(filter; filter)
Produces the input and all its nested values. With a filter, follows the filter instead, optionally while a condition holds
{"a": [1]} | [recurse]
[{"a": [1]}, [1], 1]
walk(filter)
Applies the filter to every nested value, bottom up
[1, [2]] | walk(if type == "number" then . + 1 else . end)
[2, [3]]
limit(number; filter)
Produces at most the given number of outputs of the filter
[limit(2; range(10))]
[0, 1]
skip(number; filter)
Skips the given number of outputs of the filter
[skip(2; range(4))]
[2, 3]
first, first(filter)
Returns the first element of an array, or the first output of the filter
[3, 1] | first
3
last, last(filter)
Returns the last element of an array, or the last output of the filter
[3, 1] | last
1
nth(number), nth(number; filter)
Returns the element at the given index of an array, or the output at that position of the filter
Fails the expression, with the input or the argument as the error message. Wrap the expression in try and catch to get a fallback value instead: try ("abc" | tonumber) catch "not a number"
{"a": 1} | .b // error("Missing b")
Error Missing b
halt
Stops the expression without an error. Values already produced are kept, and the following ones are dropped. Inside [ ], the array is never produced, so the example isn't wrapped. An If condition using it evaluates to false
1, 2, halt, 3
1 and 2
halt_error, halt_error(number)
Fails the expression with the input as the error message. Stops like halt when the input is null. The exit code argument is ignored