# Query YAML with jq-style filters

Query and transform YAML with jq-style filters in your browser — yq-like selection, mapping, slurp mode, YAML/JSON output, no upload.

## Run it

- **CLI:** `gizza tool yaml-query 'services:
  web:
    image: nginx:1.27
    ports:
      - "80:80"
      - "443:443"' 'query=.services.web.ports'`
- **Web:** https://gizza.ai/tools/yaml-query/
- **Agents:** machine-readable descriptor (parameters JSON Schema) at https://gizza.ai/tools/yaml-query/tool.json

## Inputs

- `yaml` — YAML input _(field)_
- `query` — jq/yq-style filter _(field)_
- `input_format` — Input format _(field)_
- `output_format` — Output format _(field)_
- `documents` — Documents _(field)_
- `pretty` — Pretty-print JSON _(field)_
- `raw_output` — Raw string output _(field)_

## Output

- Query output (text)

## Query parameters

Open the tool pre-filled and auto-run via URL:

- `yaml` — YAML input
- `query` — jq/yq-style filter
- `input_format` — Input format
- `output_format` — Output format
- `documents` — Documents
- `pretty` — Pretty-print JSON
- `raw_output` — Raw string output

Example: `https://gizza.ai/tools/yaml-query/?yaml=services%3A%0A%20%20web%3A%0A%20%20%20%20image%3A%20nginx%3A1.27%0A%20%20%20%20ports%3A%0A%20%20%20%20%20%20-%20%2280%3A80%22%0A%20%20%20%20%20%20-%20%22443%3A443%22&query=.services.web.ports&input_format=auto&output_format=yaml&documents=each&pretty=true&raw_output=true`

---

## Query YAML with jq-style filters in your browser

Paste a YAML document, type a jq/yq-style filter, and get the selected or
reshaped result back as YAML or JSON. The tool uses the same pure-Rust jaq engine
as the JSON jq tool, but parses YAML first, so common config workflows work in
one step: read docker-compose ports, list Kubernetes container images, filter CI
jobs, or convert a YAML projection to compact JSON for another tool.

Everything runs locally in WebAssembly. No YAML is uploaded, and there is no
server-side `jq` or `yq` process.

### Worked examples

- `gizza tool yaml-query --yaml 'services:\n  web:\n    ports:\n      - "80:80"' --query '.services.web.ports'`
  returns the `ports` list as YAML.
- Use `--output-format json --pretty false` with `.services | keys` to get a
  compact JSON array of service names.
- Use `--documents slurp --query 'map(.metadata.name)'` on a `---` separated
  Kubernetes stream to query across all resources at once.
- Use `--raw-output true --query '.image'` when a scalar string should be copied
  into a shell pipeline without JSON/YAML quotes.

### Limits and edge cases

- Input is capped at 4 MiB and output streams are capped at 50,000 values to keep
  browser runs bounded.
- YAML anchors, aliases, merge keys (`<<`) and custom tags are resolved into data
  before the jq filter runs. Comments and exact formatting are not preserved
  because jq-style transforms operate on a data tree.
- YAML mapping keys that are scalars become jq object keys as strings. Complex
  sequence or mapping keys are rejected because jq objects cannot represent them.
- jaq implements jq with the standard library (`map`, `select`, `sort_by`,
  `group_by`, `to_entries`, `with_entries`, `add`, `length`, `unique`, and more),
  but it may differ from a local yq installation for yq-specific assignment or
  in-place editing extensions.

## FAQ

<details>
<summary>Is this the same as yq?</summary>

It covers the browser-safe query and transform path: YAML is parsed to a jq data
tree, a jq-style filter runs, and the result is emitted as YAML or JSON. It does
not edit files in place or preserve comments, so use it for selection,
projection, filtering, aggregation, and conversion rather than source-preserving
rewrites.

</details>

<details>
<summary>How do I query a multi-document Kubernetes YAML stream?</summary>

Leave **Documents** as `each` to run the filter independently on every `---`
document. Choose `slurp` when the filter needs to see all documents at once, for
example `map(.metadata.name)` or `map(select(.kind == "Service"))`.

</details>

<details>
<summary>Why did I get several output values?</summary>

jq filters produce a stream. A filter like `.items[] | .name` emits one value per
item. Wrap the filter in brackets, such as `[.items[] | .name]`, when you want a
single array result instead.

</details>

<details>
<summary>Does this preserve YAML comments and anchors?</summary>

Anchors, aliases, merge keys, and tags are resolved before querying, so their
data is visible to the filter. Comments and original formatting are not
preserved in transformed output; the result is newly serialized YAML or JSON.

</details>

## Related tools

- [JSON ⇄ YAML Converter](https://gizza.ai/tools/json-yaml-converter/): Convert between JSON and YAML in either direction, right in your browser. Auto-detects the input format. Nothing is uploaded, free.
- [YAML Path Query](https://gizza.ai/tools/yaml-path-query/): Query, set or delete YAML values by dotted and bracketed paths in your browser — dot keys, list indexes, quoted keys, JSON output, and comment-preserving edits.
- [Absolute value, sign, or negation for a whole column](https://gizza.ai/tools/absolute-value-transformer/): Paste a column of numbers and apply absolute value, sign extraction (-1/0/1), sign flipping, or force-negative to every value at once, with rounding and an audit table.
- [Adjacency Matrix Converter](https://gizza.ai/tools/adjacency-matrix-converter/): Convert a graph between edge list, adjacency matrix, and incidence matrix — directed or undirected, weighted or not. Free, private, runs in your browser.
- [Amazon Order Analyzer](https://gizza.ai/tools/amazon-order-analyzer/): Paste an Amazon order-history CSV export to summarize total spend by month, top items, and category breakdowns. Browser-only, private, with Markdown or JSON output.