{"id":32483647,"url":"https://github.com/zmaril/zquery","last_synced_at":"2026-06-17T16:07:08.831Z","repository":{"id":256093613,"uuid":"854304258","full_name":"zmaril/zquery","owner":"zmaril","description":null,"archived":false,"fork":false,"pushed_at":"2024-09-23T17:15:50.000Z","size":76,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-27T03:36:30.873Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zmaril.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-09-08T22:59:01.000Z","updated_at":"2025-04-05T07:44:47.000Z","dependencies_parsed_at":"2024-09-09T00:29:33.947Z","dependency_job_id":"868bbf88-e0af-40ca-930c-2dcaf0588994","html_url":"https://github.com/zmaril/zquery","commit_stats":null,"previous_names":["zmaril/zquery"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zmaril/zquery","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmaril%2Fzquery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmaril%2Fzquery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmaril%2Fzquery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmaril%2Fzquery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zmaril","download_url":"https://codeload.github.com/zmaril/zquery/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmaril%2Fzquery/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34453523,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-10-27T03:36:21.939Z","updated_at":"2026-06-17T16:07:08.793Z","avatar_url":"https://github.com/zmaril.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zquery\n\n`zquery` is a tool for running SQL queries on the output of various Unix tools. It lets you query the output of various Unix tools in a way that's easy to work with. It's powered by [Apache DataFusion](https://datafusion.apache.org/) and [jc](https://github.com/kellyjonbrazil/jc) which means it works way better than it has any right to.\n\n```\n$ zquery \n\u003e\u003e select * from ps() order by pid limit 1;\n+---------------+-------------+-------------+-----+-------+---------+------+----------+-----+\n| command       | cpu_percent | mem_percent | pid | rss   | started | stat | time     | tty |\n+---------------+-------------+-------------+-----+-------+---------+------+----------+-----+\n| /sbin/launchd | 0.0         | 0.0         | 1   | 15664 | 24Aug24 | Ss   | 34:45.79 |     |\n+---------------+-------------+-------------+-----+-------+---------+------+----------+-----+\n\n\u003e\u003e SELECT left(command,70) as cmd, cpu_percent FROM ps() WHERE cpu_percent \u003e 0.5 order by cpu_percent desc, cmd;\n+------------------------------------------------------------------------+-------------+\n| cmd                                                                    | cpu_percent |\n+------------------------------------------------------------------------+-------------+\n| /Applications/Firefox.app/Contents/MacOS/plugin-container.app/Contents | 99.0        |\n| /Applications/iTerm.app/Contents/MacOS/iTerm2                          | 17.0        |\n| /System/Library/CoreServices/ReportCrash agent                         | 9.9         |\n| /System/Library/PrivateFrameworks/SkyLight.framework/Resources/WindowS | 7.9         |\n| /System/Library/PrivateFrameworks/CoreSymbolication.framework/coresymb | 6.6         |\n| /Applications/Firefox.app/Contents/MacOS/plugin-container.app/Contents | 3.2         |\n| /Applications/Firefox.app/Contents/MacOS/firefox -foreground           | 2.0         |\n| /Applications/Cursor.app/Contents/Frameworks/Cursor Helper (Plugin).ap | 1.8         |\n| /Applications/Firefox.app/Contents/MacOS/plugin-container.app/Contents | 1.3         |\n| /Applications/Firefox.app/Contents/MacOS/plugin-container.app/Contents | 0.9         |\n| /System/Library/CoreServices/Siri.app/Contents/MacOS/Siri launchd      | 0.9         |\n| /Library/Application Support/iStat Menus 5/iStat Menus Status.app/Cont | 0.8         |\n| /usr/sbin/cfprefsd daemon                                              | 0.6         |\n+------------------------------------------------------------------------+-------------+\n\n//We can go remote too.\n\u003e\u003eselect * from who(host('some_ssh_host'));\n+------+-------+-------+------------------+------------+\n| user | event | tty   | time             | epoch      |\n+------+-------+-------+------------------+------------+\n| root |       | pts/0 | 2024-09-22 19:51 | 1727049060 |\n+------+-------+-------+------------------+------------+\n\n\n// We can join across commands too and do all the normal SQL stuff.\n\u003e\u003e SELECT\n    ps.user,\n    ps.pid,\n    LEFT(ps.command, 50) AS command,\n    ps.cpu_percent,\n    ps.mem_percent,\n    up.uptime_days,\n    up.load_1m,\n    up.load_5m,\n    up.load_15m\nFROM\n    ps() as ps\nCROSS JOIN\n    uptime() AS up\nWHERE\n    ps.cpu_percent \u003e 1.0\nORDER BY\n    ps.cpu_percent DESC\nLIMIT 5;\n+---------------+-------+----------------------------------------------------+-------------+-------------+-------------+---------+---------+----------+\n| user          | pid   | command                                            | cpu_percent | mem_percent | uptime_days | load_1m | load_5m | load_15m |\n+---------------+-------+----------------------------------------------------+-------------+-------------+-------------+---------+---------+----------+\n| zackmaril     | 18477 | /Applications/Firefox.app/Contents/MacOS/firefox - | 20.3        | 3.0         | 29          | 3.21    | 3.54    | 3.79     |\n| _windowserver | 374   | /System/Library/PrivateFrameworks/SkyLight.framewo | 14.5        | 0.3         | 29          | 3.21    | 3.54    | 3.79     |\n| zackmaril     | 18979 | /Applications/Firefox.app/Contents/MacOS/plugin-co | 13.0        | 1.6         | 29          | 3.21    | 3.54    | 3.79     |\n| zackmaril     | 48158 | /Applications/Firefox.app/Contents/MacOS/plugin-co | 11.5        | 1.4         | 29          | 3.21    | 3.54    | 3.79     |\n| zackmaril     | 18692 | /Applications/Firefox.app/Contents/MacOS/plugin-co | 7.0         | 0.5         | 29          | 3.21    | 3.54    | 3.79     |\n+---------------+-------+----------------------------------------------------+-------------+-------------+-------------+---------+---------+----------+\n```\n\n\n## Installation\n\nTo install `zquery`, ensure you have Rust's package manager, Cargo, installed. You'll also need `jc` (JSON CLI output utility) installed locally.\n\n1. Install `zquery` using Cargo:\n\n   ```bash\n   cargo install zquery\n   ```\n\n2. Install `jc` (if not already installed):\n\n   ```bash\n   pip install jc\n   ```\n\n## Supported Commands\n\n`zquery` currently supports the following commands:\n\n- `ps()` - Returns a table of processes.\n- `uptime()` - Returns a row of uptime information.\n- `who()` - Returns a table of who is and was on the system.\n- `ls('.')` - Returns a table of files in the given directory.\n- `stat('.')` - Returns a table of file information for the given path.\n- `df('.')` - Returns a table of disk space information.\n- `du('.')` - Returns a table of disk usage information.\n- `env()` - Returns a table of environment variables.\n- `date()` - Returns a table of date and time information.\n- `dir('.')` - Returns a table of directory information. (Windows only)\n- `dpkg_list()` - Returns a table of dpkg packages. \n- `file('.')` - Returns a table of file information. \n- `find('.')` - Returns a table of files and directories.  (TODO: broken)\n- `free()` - Returns a table of free memory information.\n\nTo query remote servers, you can use the `host()` function as the first argument to any of the above commands.\n\nFor example: \n```\n\u003e\u003e select * from ps(host('some_ssh_host'));\n\u003e\u003e select * from ls(host('some_ssh_host'), '/home/some_user/');\n```\n## SQL Support\n\nCurrently, `zquery` supports the `SELECT` statement in general. Nested, windows, joins, aggregates are all supported. Datafusion is great! Support for `CREATE TABLE` with `INSERT`, `UPDATE`, `DELETE` and `DROP` statements is planned via a local sqlite3 database. Additionally, support for streaming sql is in the works. \n\n## Limitations \n\n* Currently it relies on short names in your `ssh` config for simplicity of using `host('server_name')`. If you want to use `zquery` with your own ssh config you can do so but you'll have to make sure your config file has all the info ssh2 needs to get into the server.\n* Additionally, `zquery` experts there to be an `id_rsa` file in your `~/.ssh` directory. It shouldn't be too hard to add support for other key types or other methods of authentication but that isn't done yet.\n* The ssh commands are implemented as user defined table functions in datafusion. This is convenient in some ways, but a limitation right now is that it's not possible to pass columns as arguments to these functions. So any arguments to the functions need to be literals. This is a work in progress, and may be possible in the future once I learn more about how datafusion works.\n\n## Contributing/License\n\n`zquery` is licensed under the MIT License. `zquery` is a work in progress so contributions are welcome with the understanding that things might be unstable and breaking and that this is a big experiment with a vision I am working towards. So if a PR languishes or is not accepted at the moment, that's because I'm one person focusing on trying to get the vision down. \n\n## Roadmap \n\n- [ ] Expand command list. \n- [ ] Add pgwire.\n- [ ] Add a TUI. \n- [ ] Make it easy to install.\n- [ ] Add tests. \n- [ ] Add CI.\n- [ ] Branch protection and pull requests and versioning.\n- [ ] Make a website for it with better documentation and with real time examples.\n- [ ] Set up a discord.\n- [ ] Figure out how to get streaming working with datafusion. \n- [ ] Get bpftrace working ala [`bpfquery`](https://bpfquery.com).\n- [ ] Figure out a better way than `jq` to handle the output of `jc` for converting from JSON to NDJSON.Or, hey, don't convert from JSON to NDJSON at all! Just have arrow parse the JSON directly somehow.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzmaril%2Fzquery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzmaril%2Fzquery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzmaril%2Fzquery/lists"}