jackson-jq

While jackson-jq aims for compatibility with jq, it is not a 1:1 implementation. Some jq features are omitted because they are not relevant to a Java library, while others may be incomplete or contain bugs.

When writing filters, be aware that not every feature from the jq 1.5 manual is guaranteed to be available in jackson-jq. Always verify feature availability if your logic relies on advanced jq functionality.

By default, jackson-jq does not include regex support. To use regex functions such as test, match, capture, scan, sub, gsub, splits, and split/2, you must add the jackson-jq-regex-impl-joni module to your project. This module is backed by the Joni regex engine.

In a Java project using Maven, add the following dependency:

Functions are discovered automatically via ServiceLoader, so no manual registration is required in your code. If you are using the jackson-jq command-line application, this module is included by default.

<dependency>
	<groupId>net.thisptr.jackson.jq.v2</groupId>
	<artifactId>jackson-jq-regex-impl-joni</artifactId>
	<version>2.0.0-alpha2</version>
</dependency>

Benchmarks are performed using JMH and measure query compilation and application separately. By default, the benchmark uses the jackson3 provider and jq 1.8.2 compatibility semantics.

Usage Pattern: bazelisk run //jackson-jq-benchmark -- [options] <jq_expression> <json_input> [jmh_options]

Supported JSON Providers:

• jackson2
• jackson3
• fastjson2
• gson
• jakarta

Supported jq Versions:

• Specified via --jq-version (e.g., 1.7).

# Default benchmark run
bazelisk run //jackson-jq-benchmark -- '.items | map(.price) | add' '{"items":[{"price":10},{"price":20}]}'

# Benchmark with custom provider and jq version
bazelisk run //jackson-jq-benchmark -- \
	--json-provider gson \
	--jq-version 1.7 \
	'.foo' \
	'{"foo":42}' \
	-f 3

For security reasons, jackson-jq does not provide a built-in implementation of env/0. If your jq scripts require access to environment variables, you must implement the function yourself and register it with the EnvironmentBuilder.

builder.defineFunction(FunctionSignature.of("env", 0), new Function() {
	@Override
	public <Context extends RuntimeContext, T> Expression<Context, T> bind(BindContext<T> bindCtx, List<Expression<Context, T>> args) {
		JsonProvider<T> jsonProvider = bindCtx.getJsonProvider();
		return (context, in, ipath, output) -> {
			Map<String, T> result = new HashMap<>();
			for (Map.Entry<String, String> entry : System.getenv().entrySet()) {
				result.put(entry.getKey(), jsonProvider.createString(entry.getValue()));
			}
			output.emit(jsonProvider.createObject(result), UntrackedPath.getInstance());
		};
	}
});

The Maven projects located in smoke-tests/ are consumers of the library. To test them, you must first publish the Bazel-built artifacts to your local Maven repository using the //:maven_install target.

bazel run //:maven_install
for project in java8 jpms osgi quarkus graalvm; do
	mvn -f "smoke-tests/$project/pom.xml" clean verify
done

The project uses Bazel 9. It is recommended to use bazelisk to ensure the correct version is used as pinned in .bazelversion.

Before submitting changes, you should format the code, check Bazel file linting, and run the full test suite:

1. Check code formatting: bazelisk run //:idea-format -- --check
2. Check Bazel file linting: bazel run //:buildifier_test
3. Run all tests: bazel test //...

The expression .foo |= empty is considered undefined in jq and results in an error in jackson-jq. If you need to replicate the specific (and often incorrect) behaviors found in jq 1.5 or jq 1.6, use the _modify/2 function directly.

# To replicate jq 1.6 behavior:
$ java -jar jackson-jq-cli-2.0.0-alpha2.jar --jq 1.6 -n '[1,2,3] | _modify((.[] | select(. > 1)); empty)'
# Output: [ 1, 3 ]

# To replicate jq 1.5 behavior:
$ java -jar jackson-jq-cli-2.0.0-alpha2.jar --jq 1.5 -n '[1,2,3] | _modify((.[] | select(. > 1)); empty)'
# Output: null

In jackson-jq, input options like -n, -R, and -s do not change the execution logic of a query itself. Instead, they change the nature of the InputSource—the sequence of values that the query is applied to.

Depending on the flags used, the query receives different types of input:

• A stream of parsed JSON values.
• One string per input line (raw input).
• A single array containing all input data (slurp mode).

Each of these modes is implemented as an InputSource, which manages how data is read and passed to the query engine.

The jackson-jq command-line interface allows you to run jq filters on JSON data. The basic usage pattern is:

jackson-jq [OPTIONS...] QUERY [FILE...]

If you use the --from-file option, the first positional argument is treated as the filter file, and all subsequent arguments are treated as input files. Otherwise, the first positional argument is the query string, and the rest are input files. If no input files are provided, it reads from standard input.