{"id":13502849,"url":"https://github.com/yamafaktory/jql","last_synced_at":"2025-05-13T18:07:58.413Z","repository":{"id":39862274,"uuid":"147120314","full_name":"yamafaktory/jql","owner":"yamafaktory","description":"A JSON Query Language CLI tool","archived":false,"fork":false,"pushed_at":"2025-04-07T20:16:05.000Z","size":4224,"stargazers_count":1577,"open_issues_count":2,"forks_count":32,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-04-25T17:55:35.849Z","etag":null,"topics":["cargo","cli","devops-tools","json","rust","rustlang","tool","tools","utility"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/jql","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yamafaktory.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-09-02T20:42:42.000Z","updated_at":"2025-04-23T08:09:31.000Z","dependencies_parsed_at":"2023-02-15T09:46:27.721Z","dependency_job_id":"e9ba724c-039a-48fb-9440-ad9db8426586","html_url":"https://github.com/yamafaktory/jql","commit_stats":{"total_commits":422,"total_committers":18,"mean_commits":"23.444444444444443","dds":"0.18957345971563977","last_synced_commit":"6f1948da8c31b3f8785de593cd9e5f5250703683"},"previous_names":[],"tags_count":172,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yamafaktory%2Fjql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yamafaktory%2Fjql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yamafaktory%2Fjql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yamafaktory%2Fjql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yamafaktory","download_url":"https://codeload.github.com/yamafaktory/jql/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254000849,"owners_count":21997441,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cargo","cli","devops-tools","json","rust","rustlang","tool","tools","utility"],"created_at":"2024-07-31T22:02:27.025Z","updated_at":"2025-05-13T18:07:58.392Z","avatar_url":"https://github.com/yamafaktory.png","language":"Rust","funding_links":[],"categories":["Rust","JSON","cli","Projects","Other","Applications","Data Processing"],"sub_categories":["Open USP Tsukubai","Utilities"],"readme":"![jql](jql.svg)\n\n---\n\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/yamafaktory/jql/ci.yml?branch=main\u0026logo=github\u0026style=flat-square)](https://github.com/yamafaktory/jql/actions/workflows/ci.yml)\n[![Crates.io](https://img.shields.io/crates/v/jql?style=flat-square)](https://crates.io/crates/jql)\n[![Docs.rs](https://img.shields.io/docsrs/jql-parser?label=jql-parser%20docs\u0026style=flat-square)](https://docs.rs/jql-parser/latest/jql_parser/)\n[![Docs.rs](https://img.shields.io/docsrs/jql-runner?label=jql-runner%20docs\u0026style=flat-square)](https://docs.rs/jql-runner/latest/jql_runner/)\n\n`jql` is a JSON Query Language tool built with Rust 🦀.\n\nPronounce it as **jackal** 🐺.\n\n## 📜 Philosophy\n\n- ⚡Be fast\n- 🪶 Stay lightweight\n- 🎮 Keep its features as simple as possible\n- 🧠 Avoid redundancy\n- 💡 Provide meaningful error messages\n- 🍰 Eat JSON as input, process, output JSON back\n\n## 🚀 Installation\n\n### Alpine Linux\n\nThe package is maintained by @jirutka.\n\n```sh\napk add jql\n```\n\n### Archlinux\n\nThe AUR package is maintained by @barklan.\n\n```sh\nyay -S jql\n```\n\n### Cargo\n\n```sh\ncargo install jql\n```\n\n### Cargo Binstall\n\n```sh\ncargo binstall jql\n```\n\n### Fedora\n\n```sh\ndnf install jql\n```\n\n### FreeBSD\n\n```sh\npkg install jql\n```\n\n### Homebrew\n\n```sh\nbrew install jql\n```\n\n### Nix\n\n```sh\nnix-env -i jql\n```\n\n### openSUSE\n\n```sh\nzypper install jql\n```\n\n### Manual installation from GitHub\n\nCompiled binary versions are automatically uploaded to GitHub when a new release is made. You can install `jql` manually by [downloading a release](https://github.com/yamafaktory/jql/releases).\n\n## 🛠️ Usage\n\nTo make a selection from a JSON input, `jql` expects a **query** as a sequence of **tokens**.\n\nTo be fully compliant with the JSON format, `jql` always expect key selectors to be **double-quoted**, see [The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259#section-13).\n\n```json\n{\n  \".valid\": 1337,\n  \"\": \"yeah!\",\n  \"\\\"\": \"yup, valid too!\"\n}\n```\n\nConsequently, to be shell compliant, a query must be either enclosed by single quotation marks or every inner double quotation mark must be escaped.\n\n### Separators\n\n#### Group separator\n\nGroup separators build up an array from sub-queries.\n\n**JSON input**\n\n```json\n{ \"a\": 1, \"b\": 2, \"c\": 3 }\n```\n\n**Query**\n\n```sh\n'\"a\",\"b\",\"c\"'\n```\n\n**JSON output**\n\n```json\n[1, 2, 3]\n```\n\n### Selectors\n\n#### Arrays\n\n##### Array index selector\n\nIndexes can be used in arbitrary order.\n\n**JSON input**\n\n```json\n[1, 2, 3]\n```\n\n**Query**\n\n```sh\n'[2,1]'\n```\n\n**JSON output**\n\n```json\n[3, 2]\n```\n\n##### Array range selector\n\nRange can be in natural order `[0:2]`, reversed `[2:0]`, without lower `[:2]` or upper bound `[0:]`.\n\n**JSON input**\n\n```json\n[1, 2, 3]\n```\n\n**Query**\n\n```sh\n'[2:1]'\n```\n\n**JSON output**\n\n```json\n[3, 2]\n```\n\n##### Lens selector\n\nLens can be a combination of one or more selectors with or an optional value, a value being any of **boolean** | **null** | **number** | **string**.\n\n**JSON input**\n\n```json\n[\n  { \"a\": 1, \"b\": { \"d\": 2 } },\n  { \"a\": 2, \"b\": \"some\" },\n  { \"a\": 2, \"b\": { \"d\": null } },\n  { \"a\": 2, \"b\": true },\n  { \"c\": 3, \"b\": 4 }\n]\n```\n\n**Query**\n\n```sh\n'|={\"b\"\"d\"=2, \"c\"}'\n```\n\n**JSON output**\n\n```json\n[\n  { \"a\": 1, \"b\": { \"d\": 2 } },\n  { \"c\": 3, \"b\": 4 }\n]\n```\n\n#### Objects\n\n##### Key selector\n\nAny valid JSON key can be used.\n\n**JSON input**\n\n```json\n{ \"a\": 1, \"b\": 2, \"c\": 3 }\n```\n\n**Query**\n\n```sh\n'\"c\"'\n```\n\n**JSON output**\n\n```json\n3\n```\n\n##### Multi key selector\n\nKeys can be used in arbitrary order.\n\n**JSON input**\n\n```json\n{ \"a\": 1, \"b\": 2, \"c\": 3 }\n```\n\n**Query**\n\n```sh\n'{\"c\",\"a\"}'\n```\n\n**JSON output**\n\n```json\n{ \"c\": 3, \"a\": 1 }\n```\n\n##### Object index selector\n\nIndexes can be used in arbitrary order.\n\n**JSON input**\n\n```json\n{ \"a\": 1, \"b\": 2, \"c\": 3 }\n```\n\n**Query**\n\n```sh\n'{2,0}'\n```\n\n**JSON output**\n\n```json\n{ \"c\": 3, \"a\": 1 }\n```\n\n##### Object range selector\n\nRange can be in natural order `{0:2}`, reversed `{2:0}`, without lower `{:2}` or upper bound `{0:}`.\n\n**JSON input**\n\n```json\n{ \"a\": 1, \"b\": 2, \"c\": 3 }\n```\n\n**Query**\n\n```sh\n'{2:1}'\n```\n\n**JSON output**\n\n```json\n{ \"c\": 3, \"b\": 2 }\n```\n\n#### Operators\n\n##### Flatten operator\n\nFlattens arrays and objects.\n\n**JSON input**\n\n```json\n[[[[[[[[[[[[[[{ \"a\": 1 }]]]]]]]]]]]]], [[[[[{ \"b\": 2 }]]]], { \"c\": 3 }], null]\n```\n\n**Query**\n\n```sh\n'..'\n```\n\n**JSON output**\n\n```json\n[{ \"a\": 1 }, { \"b\": 2 }, { \"c\": 3 }, null]\n```\n\n**JSON input**\n\n```json\n{ \"a\": { \"c\": false }, \"b\": { \"d\": { \"e\": { \"f\": 1, \"g\": { \"h\": 2 } } } } }\n```\n\n**Query**\n\n```sh\n'..'\n```\n\n**JSON output**\n\n```json\n{\n  \"a.c\": false,\n  \"b.d.e.f\": 1,\n  \"b.d.e.g.h\": 2\n}\n```\n\n##### Keys operator\n\nReturns the keys of an object or the indices of an array. Other primitives are returned as is.\n\n**JSON input**\n\n```json\n{ \"a\": 1, \"b\": 2, \"c\": 3 }\n```\n\n**Query**\n\n```sh\n'@'\n```\n\n**JSON output**\n\n```json\n[\"a\", \"b\", \"c\"]\n```\n\n##### Pipe in operator\n\nApplies the next tokens in parallel on each element of an array.\n\n**JSON input**\n\n```json\n{ \"a\": [{ \"b\": { \"c\": 1 } }, { \"b\": { \"c\": 2 } }] }\n```\n\n**Query**\n\n```sh\n'\"a\"|\u003e\"b\"\"c\"'\n```\n\n**JSON output**\n\n```json\n[1, 2]\n```\n\n##### Pipe out operator\n\nStops the parallelization initiated by the pipe in operator.\n\n**JSON input**\n\n```json\n{ \"a\": [{ \"b\": { \"c\": 1 } }, { \"b\": { \"c\": 2 } }] }\n```\n\n**Query**\n\n```sh\n'\"a\"|\u003e\"b\"\"c\"\u003c|[1]'\n```\n\n**JSON output**\n\n```json\n2\n```\n\n##### Truncate operator\n\nMaps the output into simple JSON primitives **boolean** | **null** | **number** | **string** | **[]** | **{}**.\n\n**JSON input**\n\n```json\n{ \"a\": [1, 2, 3] }\n```\n\n**Query**\n\n```sh\n'\"a\"!'\n```\n\n**JSON output**\n\n```json\n[]\n```\n\n## 💻 Shell integration\n\n### How to save the output\n\n```sh\njql '\"a\"' input.json \u003e output.json\n```\n\n### How to read from stdin\n\n```sh\ncat test.json | jql '\"a\"'\n```\n\n### Available flags\n\n#### Inline the JSON output\n\nBy default, the output is pretty printed in a more human-readable way, this can be disabled.\n\n```sh\n-i, --inline\n```\n\n#### Read the query from file\n\nThe command will read the provided query from a file instead of the stdin.\n\n```sh\n-q, --query \u003cFILE\u003e\n```\n\n#### Write to stdout without JSON double-quotes\n\nThis can be useful to drop the double-quotes surrounding a string primitive.\n\n```sh\n-r, --raw-string\n```\n\n#### Read a stream of JSON data line by line\n\nThis flag is only about reading processing any JSON output streamed line by line (e.g. Docker logs with the `--follow` flag). This is not an option to read an incomplete streamed content (e.g. a very large input).\n\n```sh\n-s, --stream\n```\n\n#### Validate the JSON data\n\nThe command will return a matching exit code based on the validity of the JSON content or file provided.\n\n```sh\n-v, --validate\n```\n\n#### Print help\n\n```sh\n-h, --help\n```\n\n#### Print version\n\n```sh\n-V, --version\n```\n\n#### Help\n\n```sh\njql -h\njql --help\n```\n\n## 🦀 Workspace\n\nThis project is composed of following crates:\n\n- jql (_binary_)\n- [jql-parser](https://docs.rs/jql-parser/latest/jql_parser/) (_library_)\n- [jql-runner](https://docs.rs/jql-runner/latest/jql_runner/) (_library_)\n\n## Development\n\nSome commands are available as a `justfile` at the root of the workspace (testing / fuzzing).\n\n### Prerequisites\n\n- [cargo-nextest](https://nexte.st/)\n- [just](https://just.systems/man/en/)\n\n### Commands\n\n```sh\njust --list\n```\n\n## ⚠️ Non-goal\n\nThere's no plan to align `jql` with `jq` or any other similar tool.\n\n## ⚡ Performance\n\nSome benchmarks comparing a set of similar functionalities provided by this tool and [jq](https://stedolan.github.io/jq/) are available [here](PERFORMANCE.md).\n\n## 📔 Licenses\n\n- [Apache License, Version 2.0](https://github.com/yamafaktory/jql/blob/main/LICENSE-APACHE)\n- [MIT license](https://github.com/yamafaktory/jql/blob/main/LICENSE-MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyamafaktory%2Fjql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyamafaktory%2Fjql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyamafaktory%2Fjql/lists"}