Builtin Functions

jq-compatible builtin functions for data transformation. All builtins have shorthand aliases.

Array Operations

Functions for working with arrays.

.head / hd()

Get the first element of an array.

bash

echo '[1, 2, 3, 4, 5]' | 1ls 'head()'
# Output: 1

.last / lst()

Get the last element of an array.

bash

echo '[1, 2, 3, 4, 5]' | 1ls 'last()'
# Output: 5

.tail / tl()

Get all elements except the first.

bash

echo '[1, 2, 3, 4, 5]' | 1ls 'tail()'
# Output: [2, 3, 4, 5]

.take / tk()

Take the first n elements.

bash

echo '[1, 2, 3, 4, 5]' | 1ls 'take(3)'
# Output: [1, 2, 3]

.drop / drp()

Drop the first n elements.

bash

echo '[1, 2, 3, 4, 5]' | 1ls 'drop(2)'
# Output: [3, 4, 5]

.uniq / unq()

Remove duplicate values.

bash

echo '[1, 2, 2, 3, 3, 3]' | 1ls 'uniq()'
# Output: [1, 2, 3]

.flatten / fltn()

Flatten nested arrays recursively.

bash

echo '[[1, 2], [3, [4, 5]]]' | 1ls 'flatten()'
# Output: [1, 2, 3, 4, 5]

.rev()

Reverse an array.

bash

echo '[1, 2, 3]' | 1ls 'rev()'
# Output: [3, 2, 1]

.chunk / chnk()

Split array into chunks of size n.

bash

echo '[1, 2, 3, 4, 5]' | 1ls 'chunk(2)'
# Output: [[1, 2], [3, 4], [5]]

.compact / cmpct()

Remove falsy values (null, undefined, false, 0, "").

bash

echo '[0, 1, false, 2, "", 3, null]' | 1ls 'compact()'
# Output: [1, 2, 3]

.nth()

Get element at index n (supports negative indexes).

bash

echo '[10, 20, 30, 40]' | 1ls 'nth(-1)'
# Output: 40

.add()

Sum numbers, concatenate arrays, or join strings.

bash

echo '[1, 2, 3, 4]' | 1ls 'add()'
# Output: 10

Object Operations

Functions for working with objects.

.keys / ks()

Get object keys.

bash

echo '{"a": 1, "b": 2}' | 1ls 'keys()'
# Output: ["a", "b"]

.vals()

Get object values.

bash

echo '{"a": 1, "b": 2}' | 1ls 'vals()'
# Output: [1, 2]

.pick / pk()

Pick specific keys from an object.

bash

echo '{"a": 1, "b": 2, "c": 3}' | 1ls 'pick("a", "c")'
# Output: {"a": 1, "c": 3}

.omit / omt()

Omit specific keys from an object.

bash

echo '{"a": 1, "b": 2, "c": 3}' | 1ls 'omit("b")'
# Output: {"a": 1, "c": 3}

.merge / mrg()

Shallow merge objects.

bash

echo '{"a": 1}' | 1ls 'merge({"b": 2})'
# Output: {"a": 1, "b": 2}

.deepMerge / dMrg()

Deep merge objects recursively.

bash

echo '{"a": {"x": 1}}' | 1ls 'deepMerge({"a": {"y": 2}})'
# Output: {"a": {"x": 1, "y": 2}}

.fromPairs / frPrs()

Convert array of pairs to object.

bash

echo '[["a", 1], ["b", 2]]' | 1ls 'fromPairs()'
# Output: {"a": 1, "b": 2}

.toPairs / toPrs()

Convert object to array of pairs.

bash

echo '{"a": 1, "b": 2}' | 1ls 'toPairs()'
# Output: [["a", 1], ["b", 2]]

.has / hs()

Check if object has a key.

bash

echo '{"name": "test"}' | 1ls 'has("name")'
# Output: true

.pluck / plk()

Extract a property from each object in an array.

bash

echo '[{"name": "a"}, {"name": "b"}]' | 1ls 'pluck("name")'
# Output: ["a", "b"]

Grouping & Sorting

Functions for grouping and sorting data.

.groupBy / grpBy()

Group array elements by a key function.

bash

echo '[{"type": "a", "v": 1}, {"type": "b", "v": 2}, {"type": "a", "v": 3}]' | 1ls 'groupBy(x => x.type)'
# Output: {"a": [...], "b": [...]}

.sortBy / srtBy()

Sort array by a key function.

bash

echo '[{"age": 30}, {"age": 20}, {"age": 25}]' | 1ls 'sortBy(x => x.age)'
# Output: [{"age": 20}, {"age": 25}, {"age": 30}]

Math & Aggregation

Mathematical and aggregation functions.

.sum()

Sum of numbers in an array.

bash

echo '[1, 2, 3, 4, 5]' | 1ls 'sum()'
# Output: 15

.mean / avg()

Average of numbers in an array.

bash

echo '[1, 2, 3, 4, 5]' | 1ls 'mean()'
# Output: 3

.min()

Minimum value in an array.

bash

echo '[5, 2, 8, 1, 9]' | 1ls 'min()'
# Output: 1

.max()

Maximum value in an array.

bash

echo '[5, 2, 8, 1, 9]' | 1ls 'max()'
# Output: 9

.floor / flr()

Floor a number.

bash

echo '3.7' | 1ls 'floor()'
# Output: 3

.ceil / cl()

Ceiling of a number.

bash

echo '3.2' | 1ls 'ceil()'
# Output: 4

.round / rnd()

Round a number.

bash

echo '3.5' | 1ls 'round()'
# Output: 4

.abs()

Absolute value.

bash

echo '-5' | 1ls 'abs()'
# Output: 5

String Operations

Functions for working with strings.

.split / spl()

Split a string by separator.

bash

echo '"a,b,c"' | 1ls 'split(",")'
# Output: ["a", "b", "c"]

.join / jn()

Join array elements with separator.

bash

echo '["a", "b", "c"]' | 1ls 'join("-")'
# Output: "a-b-c"

.startswith / stw()

Check if string starts with prefix.

bash

echo '"hello world"' | 1ls 'startswith("hello")'
# Output: true

.endswith / edw()

Check if string ends with suffix.

bash

echo '"hello world"' | 1ls 'endswith("world")'
# Output: true

.ltrimstr / ltrm()

Remove prefix from string.

bash

echo '"hello world"' | 1ls 'ltrimstr("hello ")'
# Output: "world"

.rtrimstr / rtrm()

Remove suffix from string.

bash

echo '"hello world"' | 1ls 'rtrimstr(" world")'
# Output: "hello"

.tostring / tstr()

Convert value to string.

bash

echo '42' | 1ls 'tostring()'
# Output: "42"

.tonumber / tnum()

Convert string to number.

bash

echo '"42"' | 1ls 'tonumber()'
# Output: 42

Type & Inspection

Functions for inspecting values.

.type / typ()

Get the type of a value.

bash

echo '{"a": 1}' | 1ls 'type()'
# Output: "object"

.len()

Get length of array, string, or object.

bash

echo '"hello"' | 1ls 'len()'
# Output: 5

.count / cnt()

Count items (alias for len).

bash

echo '[1, 2, 3]' | 1ls 'count()'
# Output: 3

.isEmpty / emp()

Check if value is empty.

bash

echo '[]' | 1ls 'isEmpty()'
# Output: true

.isNil / nil()

Check if value is null or undefined.

bash

echo 'null' | 1ls 'isNil()'
# Output: true

.contains / ctns()

Check if value contains another (deep comparison).

bash

echo '[1, 2, 3]' | 1ls 'contains([2])'
# Output: true

Path Operations

Functions for navigating nested structures.

.path / pth()

Get all paths in a structure.

bash

echo '{"a": {"b": 1}}' | 1ls 'path()'
# Output: [[], ["a"], ["a", "b"]]

.getpath / gpth()

Get value at a path.

bash

echo '{"a": {"b": 1}}' | 1ls 'getpath(["a", "b"])'
# Output: 1

.setpath / spth()

Set value at a path.

bash

echo '{"a": {"b": 1}}' | 1ls 'setpath(["a", "b"], 99)'
# Output: {"a": {"b": 99}}

.recurse / rec()

Recursively collect all values.

bash

echo '{"a": [1, {"b": 2}]}' | 1ls 'recurse()'
# Output: [..all nested values..]

Control Flow

Functions for control flow and composition.

.select / sel()

Filter by predicate (jq-style).

bash

echo '[1, 2, 3, 4]' | 1ls '.map(x => select(x > 2))'
# Output: [3, 4]

.empty()

Return nothing (useful in select).

bash

echo '1' | 1ls 'empty()'
# Output: (no output)

.error()

Throw an error with message.

bash

echo '1' | 1ls 'error("bad value")'
# Output: Error: bad value

.debug / dbg()

Output debug information.

bash

echo '{"x": 1}' | 1ls 'debug()'
# Output: (logs value, returns input)

.not()

Boolean negation.

bash

echo 'true' | 1ls 'not()'
# Output: false

.range / rng()

Generate a range of numbers.

bash

echo 'null' | 1ls 'range(5)'
# Output: [0, 1, 2, 3, 4]

Composition

Functions for composing operations.

.pipe()

Apply expressions left-to-right.

bash

echo '[1, 2, 3]' | 1ls 'pipe(.map(x => x * 2), .filter(x => x > 2))'
# Output: [4, 6]

.compose()

Apply expressions right-to-left.

bash

echo '[1, 2, 3]' | 1ls 'compose(.filter(x => x > 1), .map(x => x * 2))'
# Output: [4, 6]

.id()

Identity function (returns input unchanged).

bash

echo '{"a": 1}' | 1ls 'id()'
# Output: {"a": 1}