whyq - low overhead yq implementation

A lightweight and portable jq wrapper for doing arbitrary queries from YAML/TOML/JSON documents by converting to JSON and passing to jq, then returning the result either as raw jq output, or back into TOML or YAML.

Installation

Via cargo:

sh cargo install whyq

or download a prebuilt from releases either manually, or via binstall:

sh cargo binstall whyq

Note: Depends on jq being installed.

Features

• arbitrary jq usage on yaml/toml/json input with the same syntax (same filter syntax, supports modules) by leveraging jq as an intermediate format
• drop-in replacement to python-yq (e.g. provides: yq)
• handles multidoc yaml input (vector of documents returned when multiple docs found)
• handles yaml merge keys and expands yaml tags (via serde_yaml)
• handles toml input (from Table)
• allows converting jq output to YAML (-y) or TOML (-t)
• <1MB in binary size (for your small cloud CI images)

YAML Input

Use as jq either via stdin:

```sh $ yq '.[3].kind' -r < test/deploy.yaml Service

$ yq -y '.[3].metadata' < test/deploy.yaml labels: app: controller name: controller namespace: default ```

or from a file arg (at the end):

sh $ yq '.[3].kind' -r test/deploy.yaml $ yq -y '.[3].metadata' test/deploy.yaml

Stdin is always used if it's piped to.

Note that YAML is the assumed default input format and primary usage case (and what the binary is named after).

TOML Input

Using say Cargo.toml from this repo as input, and aliasing tq='yq --input=toml':

```sh $ tq '.package.categories[]' -r < Cargo.toml command-line-utilities parsing

$ tq -t '.package.metadata' < Cargo.toml [binstall] bin-dir = "yq-{ target }/{ bin }{ format }" pkg-url = "{ repo }/releases/download/{ version }/yq-{ target }{ archive-suffix }"

$ tq -y '.dependencies.clap' < Cargo.toml features: - cargo - derive version: 4.4.2

$ tq '.profile' -c < Cargo.toml {"release":{"lto":true,"panic":"abort","strip":"symbols"}} ```

Add alias tq='yq --input=toml' to your .bashrc or .zshrc (etc) to make this permanent if you find it useful.

JSON Input

If you need to convert json to another format you pass --input=json:

sh $ yq --input=json '.ingredients | keys' -y < test/guacamole.json ☸ production-eu-west-1󰛢monitoring - avocado - coriander - cumin - garlic - lime - onions - pepper - salt - tomatoes

Advanced Examples

Select with nested query and raw output:

sh $ yq '.spec.template.spec.containers[].image' -r < test/grafana.yaml quay.io/kiwigrid/k8s-sidecar:1.24.6 quay.io/kiwigrid/k8s-sidecar:1.24.6 docker.io/grafana/grafana:10.1.0

Select on multidoc:

sh $ yq -y '.[] | select(.kind == "Deployment") | .spec.template.spec.containers[0].ports[0].containerPort' test/deploy.yaml 8000

Escaping keys with slashes etc in them:

sh yq -y '.updates[] | select(.["package-ecosystem"] == "cargo") | .groups' .github/dependabot.yml

Using helpers from jq modules:

sh $ yq 'include "k"; .[] | gvk' -r -L$PWD/test/modules < test/deploy.yaml v1.ServiceAccount rbac.authorization.k8s.io/v1.ClusterRole rbac.authorization.k8s.io/v1.ClusterRoleBinding v1.Service apps/v1.Deployment

Output Caveats

Output formatting such as -y for YAML or -t for TOML will require the output from jq to be parseable json. If you pass on -r for raw output, then this will not be parseable as json.

Limitations

• Shells out to jq (only supports what your jq version supports).
• Does not preserve YAML tags (input is singleton mapped recursively and then apply_merged before jq)
• Does not preserve (or allow customizing) indentation in the output (supported in serdejson, but unsupported in serdeyaml)
• Does not support duplicate keys in the input document
• No XML support