Supported functions

On this page

🔍 Core Functions 🧮 Math & Aggregation 🧰 String Utilities 📊 Array Operations 🧩 Object Operations 🔄 Functional / Recursive 🧱 Type Filters ⚙️ Utility Helpers 🧾 Notes

このページの目次

基本関数数値計算と集計文字列操作配列操作オブジェクト操作関数型操作と再帰型による絞り込み補助関数対話モード注意事項

JQ::Liteが対応するjq形式の関数と拡張関数を、目的別に掲載しています。jqと同名でも動作が異なる場合があります。互換性の差分も確認してください。

基本関数

関数	説明
`length`	要素数・キー数・文字数
`keys`, `keys_unsorted`	オブジェクトのキー（整列済み・未整列）
`values`	オブジェクトの値
`type()`	`"string"`、`"number"`、`"array"`などの型名
`is_empty`	配列・オブジェクトが空なら真
`default(value)`	null・未定義値を代替値に置換
`expr // fallback`	代替値演算子。2.xではfalseを置き換えない点に注意
`try expr [catch handler]`	実行時エラーを捕捉して回復

数値計算と集計

関数	説明
`add`, `sum`, `product`	配列の集計
`sum_by(path)`, `avg_by(path)`, `median_by(path)`	フィールドごとの集計
`avg`, `median`, `mode`, `percentile(p)`	平均・中央値・最頻値・パーセンタイル
`variance`, `stddev`	分散・標準偏差
`abs`, `ceil`, `floor`, `round`	絶対値・切り上げ・切り捨て・丸め
`clamp(min, max)`	数値を指定範囲に制限
`tonumber()`, `to_number()`	厳密な数値変換・値を保持する数値変換

文字列操作

関数	説明
`upper()`, `lower()`, `titlecase()`	大文字・小文字・単語頭の大文字への変換
`ascii_upcase()`, `ascii_downcase()`	ASCII文字だけの大文字・小文字変換
`trim()`, `ltrimstr()`, `rtrimstr()`	空白・接頭辞・接尾辞の除去
`startswith()`, `endswith()`	接頭辞・接尾辞の判定
`contains(value)`	部分文字列・配列内の包含判定（配列は従来の意味論）
`contains_subset(value)`	配列の再帰的な順序非依存の多重集合包含
`inside(container)`	入力が指定コンテナー内に含まれるかを判定
`split(sep)`, `join(sep)`	分割・結合
`substr(start, len)`	部分文字列の抽出
`replace(old, new)`	リテラルとして部分文字列を置換
`@json`, `@csv`, `@tsv`, `@base64`, `@base64d`, `@uri`	JSON・CSV/TSV行・Base64・Base64復号・URIのパーセント符号化
`explode()`, `implode()`	文字列とUnicodeコードポイント列の相互変換
`tostring`, `tojson`, `fromjson`	文字列化・JSON化・JSONの解析

配列の包含判定

contains(value)は2.xの従来の動作を維持します。引数全体に等しい1つの要素を配列内で探し、入れ子の配列は順序と長さも一致する必要があります。オブジェクトは部分集合、文字列は部分文字列として判定します。

contains_subset(value)は、右側の配列のすべての要素に左側の配列のどこかで対応する要素があれば成立します。順序は問いませんが重複回数を数え、入れ子の配列とオブジェクトも再帰的に比較します。

jqのcontainsとそのまま置き換えられるものではありません。重複した要求には同数の一致が必要で、スカラーは文字列へ変換して比較します。

[1] | contains_subset([1,1])     → false
["1"] | contains_subset([1])    → true

配列操作

関数	説明
`sort`, `sort_desc`, `sort_by(key)`	配列の並べ替え
`reverse`, `first`, `last`	逆順・先頭・末尾
`unique`, `unique_by(path)`	重複の除去
`limit(n)`, `drop(n)`, `rest`, `tail(n)`	配列の切り出し
`range(start; end[, step])`	数列の生成
`chunks(n)`	部分配列への分割
`flatten()`, `flatten_all()`, `flatten_depth(n)`	入れ子の配列の平坦化
`enumerate()`	要素とインデックスの組を生成
`transpose()`	行と列の入れ替え
`nth(n)`	n番目の要素
`compact()`	null・未定義値の除去
`index(v)`, `rindex(v)`, `indices(v)`	位置の検索

オブジェクト操作

関数	説明
`has(key)`	キーの存在確認
`pick(keys...)`	指定キーだけを保持
`pluck(key)`	オブジェクトから値を抽出
`merge_objects()`	オブジェクトの配列を結合
`del(key)`, `delpaths(paths)`	キーの削除
`to_entries()`, `from_entries()`	オブジェクトと`{key,value}`の配列を相互変換
`with_entries(filter)`	各エントリーを変換
`group_by(key)`, `group_count(key)`	グループ化・件数の集計
`paths()`, `leaf_paths()`	全パス・末端のパスを列挙
`getpath(path)`, `setpath(path; value)`	パスによる読み書き

関数型操作と再帰

関数	説明
`map(expr)`, `map_values(expr)`	配列・オブジェクトの変換と絞り込み
`walk(filter)`	再帰的に適用
`recurse([filter])`	深さ優先の探索
`reduce expr as $x (init; update)`	累積値への畳み込み
`foreach expr as $x (init; update [; extract])`	逐次結果を出す畳み込み
`any([filter])`, `all([filter])`	真偽値の集約
`not`	論理否定

型による絞り込み

関数	説明
`arrays`	配列だけを通す
`objects`	オブジェクトだけを通す
`scalars`	スカラー（文字列・数値・真偽値・null）だけを通す

補助関数

関数	説明
`empty()`	結果を捨てる
`count`	要素を数える
`path()`	キーやインデックスを返す
`range(start; end[, step])`	数値範囲の生成
`expr // value`	代替値の指定

対話モード

クエリを省略すると、固定のJSON入力に対して1行ずつクエリを入力する対話モードに入ります。

jq-lite users.json

注意事項

jq形式のパイプ構文と式を使えます。

.[] | select(.age > 20) | .name

数式は通常の優先順位と括弧に従います。ゼロ除算などのエラーには診断があります。使用例と環境についてはプロジェクト概要、組み込みについてはPerlガイドを参照してください。

This document lists all jq-compatible and extended functions supported by JQ::Lite. Functions are grouped by purpose for easier lookup.

🔍 Core Functions

Function	Description
`length`	Number of elements / keys / characters
`keys`, `keys_unsorted`	Object keys (sorted / unsorted)
`values`	Object values
`type()`	Type string: `"string"`, `"number"`, `"array"`, etc.
`is_empty`	True if array/object has no elements
`default(value)`	Replace null/undef with fallback
`expr // fallback`	Alternative operator (like jq)
`try expr [catch handler]`	Catch and recover from runtime errors

🧮 Math & Aggregation

Function	Description
`add`, `sum`, `product`	Aggregation over arrays
`sum_by(path)`, `avg_by(path)`, `median_by(path)`	Aggregate by field
`avg`, `median`, `mode`, `percentile(p)`	Statistical metrics
`variance`, `stddev`	Statistical dispersion
`abs`, `ceil`, `floor`, `round`	Rounding helpers
`clamp(min, max)`	Restrict number to range
`tonumber()`, `to_number()`	Strict / safe numeric conversion

🧰 String Utilities

Function	Description
`upper()`, `lower()`, `titlecase()`	Case conversion
`ascii_upcase()`, `ascii_downcase()`	ASCII-only case conversion
`trim()`, `ltrimstr()`, `rtrimstr()`	Trim whitespace or prefixes/suffixes
`startswith()`, `endswith()`	Prefix/suffix test
`contains(value)`	Substring or array inclusion (legacy array semantics)
`contains_subset(value)`	Recursive, order-insensitive multiset inclusion for arrays
`inside(container)`	Whether input is inside container
`split(sep)`, `join(sep)`	Split and join
`substr(start, len)`	Substring extraction
`replace(old, new)`	Replace substring (literal)
`@json`, `@csv`, `@tsv`, `@base64`, `@base64d`, `@uri`	Format value as JSON, CSV/TSV row, Base64 string, decode Base64 text, or percent-encoded URI
`explode()`, `implode()`	String ↔ Unicode code points
`tostring`, `tojson`, `fromjson`	Serialization utilities

Array containment semantics

contains(value): keeps the legacy behavior for arrays—it searches for an element equal to the provided value. Nested arrays must match exactly (order and length) to satisfy equality. Objects still use subset semantics and strings still use substring matching.
contains_subset(value): recursive subset matching for arrays. The right-hand array is satisfied when every element can be matched anywhere in the left-hand array (order-insensitive) with multiset counting. Nested arrays and objects are compared recursively using the same subset rules. This is not a drop-in replacement for jq's contains: duplicate needles require duplicate matching elements ([1] | contains_subset([1,1]) is false), and scalar values are compared after string coercion (["1"] | contains_subset([1]) is true).

📊 Array Operations

Function	Description
`sort`, `sort_desc`, `sort_by(key)`	Sort array
`reverse`, `first`, `last`	Basic reordering
`unique`, `unique_by(path)`	Deduplicate
`limit(n)`, `drop(n)`, `rest`, `tail(n)`	Array slicing
`range(start; end[, step])`	Numeric sequence
`chunks(n)`	Split into subarrays
`flatten()`, `flatten_all()`, `flatten_depth(n)`	Flatten nested arrays
`enumerate()`	Pair elements with index
`transpose()`	Convert rows ↔ columns
`nth(n)`	Nth element
`compact()`	Remove null/undef
`index(v)`, `rindex(v)`, `indices(v)`	Locate positions

🧩 Object Operations

Function	Description
`has(key)`	Key existence
`pick(keys...)`	Keep specified keys
`pluck(key)`	Extract values from objects
`merge_objects()`	Merge array of objects
`del(key)`, `delpaths(paths)`	Remove keys
`to_entries()`, `from_entries()`	Convert between object ↔ array of `{key,value}`
`with_entries(filter)`	Transform entries
`group_by(key)`, `group_count(key)`	Group and count
`paths()`, `leaf_paths()`	Enumerate all or leaf paths
`getpath(path)`, `setpath(path; value)`	Read/write by path

🔄 Functional / Recursive

Function	Description
`map(expr)`, `map_values(expr)`	Map/filter array or object
`walk(filter)`	Recursive apply
`recurse([filter])`	Depth-first traversal
`reduce expr as $x (init; update)`	Fold accumulator
`foreach expr as $x (init; update [; extract])`	Streaming reduce
`any([filter])`, `all([filter])`	Boolean aggregation
`not`	Logical negation

🧱 Type Filters

Function	Description
`arrays`	Pass only arrays
`objects`	Pass only objects
`scalars`	Pass only scalars (string/number/bool/null)

⚙️ Utility Helpers

Function	Description
`empty()`	Discard results
`count`	Count elements
`path()`	Return keys or indices
`range(start; end[, step])`	Numeric range
`expr // value`	Default operator

🔄 Interactive Mode

If you omit the query, jq-lite enters interactive mode, allowing you to type queries line-by-line against a fixed JSON input.

jq-lite users.json

🧾 Notes

jq-style pipe syntax and expressions are fully supported: .[] | select(.age > 20) | .name
Mathematical expressions follow normal precedence and parentheses.
Errors are descriptive (e.g. divide-by-zero).

📚 For usage examples and environment compatibility, see README.md. 👉 Also available on MetaCPAN — JQ::Lite

All documentation Home