Skip to content
krasninjaPublic

About

Use SQL to query different data sources like logs, JSON, CSV, XML, etc.

Resources

Contributing

Stars

25 stars

Watchers

1 watching

Forks

Repository files navigation

QueryCat logo

QueryCat

Query CSV, JSON, XML and log files with plain SQL - right from your terminal!

Run Tests Latest Release NuGet Version Downloads License

Installation | Examples | Tutorial | Documentation | Playground

$ ps -ef | qcat "SELECT UID, COUNT(*) cnt FROM - GROUP BY UID ORDER BY cnt DESC LIMIT 3"
| UID        | cnt   |
| ---------- | ----- |
| root       | 256   |
| ivan       | 93    |
| systemd+   | 1     |

QueryCat is a command line tool that lets you use SQL to query CSV, JSON, XML and log files - or the output of any other command. No need to import your data into Excel or a database first: point QueryCat at a file or pipe and query it as is.

  • Single binary, zero dependencies. Natively compiled - download it and run it.
  • Streaming pipeline. Rows are processed as they are read, so large files don't have to fit in memory.
  • Read and write. INTO converts the result into another format: CSV in, JSON out.
  • Embeddable. Use it as a .NET library to query files or your own objects.

Features

  • Inputs: CSV, TSV, JSON, XML, LTSV, IIS W3C, CLEF logs, plain text, stdin and more via plugins.
  • SQL: filtering, aggregates and GROUP BY, joins, ORDER BY, LIMIT/OFFSET, UNION, subqueries, CTEs (including recursive), window functions.
  • Parsing helpers: JSONPath, XPath, regex and Grok patterns.
  • Outputs: text table, CSV, TSV, JSON, XML.
  • Scripting: variables, IF, INSERT, UPDATE, DELETE.
  • Web UI, REST API and a simple file server with partial request support - see web server.
  • .NET library: query .NET objects in your app; AOT friendly.

Installation

Install Script

Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/krasninja/querycat/main/scripts/install.sh | bash

Windows:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/krasninja/querycat/main/scripts/install.ps1 | iex"

Installs qcat and qcat-plugins-proxy from the latest release: on Linux/macOS to /usr/local/bin when run as root, otherwise to ~/.local/bin; on Windows to %ProgramFiles%\QueryCat when elevated, otherwise to %LOCALAPPDATA%\Programs\QueryCat. Set QCAT_INSTALL_DIR to choose another directory; re-running upgrades in place.

Prebuilt Binary

Grab the single binary for your platform from the latest release, unpack it and run - no runtime or dependencies required. Builds are published for Linux (x64/arm64), macOS (x64/arm64) and Windows (x64).

# Example for Linux x64. Use the current version from the releases page
# and the archive for your platform (linux-arm64, osx-x64, osx-arm64, win-x64).
VERSION=X.Y.Z
curl -LO https://github.com/krasninja/querycat/releases/download/v$VERSION/qcat-$VERSION-linux-x64.tar.gz
tar -xzf qcat-$VERSION-linux-x64.tar.gz
./qcat --version

Arch Linux

QueryCat is available in the AUR. Install it with your AUR helper, for example:

yay -S querycat-bin

.NET

Prefer .NET? Install it as a NuGet package instead.

In Action

Find the most failing endpoints in a JSON log.

$ qcat "SELECT url, COUNT(*) AS cnt, MAX(\"time\") AS last_seen FROM 'app-log.json' WHERE level = 'error' GROUP BY url ORDER BY cnt DESC"
| url         | cnt   | last_seen           |
| ----------- | ----- | ------------------- |
| /api/orders | 2     | 03/30/2026 13:35:02 |
| /api/login  | 1     | 03/30/2026 13:36:40 |

Convert CSV to JSON while aggregating it.

$ qcat "SELECT dept, AVG(salary) AS avg_salary INTO 'by-dept.json' FROM 'employees.csv' GROUP BY dept"
$ cat by-dept.json
[{"dept":"IT","avg_salary":5000},{"dept":"Sales","avg_salary":4000}]

Rank rows within groups using window functions.

$ qcat "SELECT name, dept, salary, row_number() OVER (PARTITION BY dept ORDER BY salary DESC) AS pos FROM 'employees.csv'"
| name       | dept       | salary | pos   |
| ---------- | ---------- | ------ | ----- |
| Anna       | IT         | 5200   | 1     |
| Boris      | IT         | 4800   | 2     |
| Clara      | Sales      | 3900   | 2     |
| Dmitry     | Sales      | 4100   | 1     |

Calculate the total files size per user in a directory.

$ find /tmp -ls 2>/dev/null | qcat "SELECT column4 as user, size_pretty(SUM(column6)) size FROM - GROUP BY column4"
| user       | size       |
| ---------- | ---------- |
| root       | 56.1 K     |
| ivan       | 252.6 M    |

Show the full user name for each process by joining ps output with /etc/passwd.

$ ps aux | qcat "SELECT psw.column4 AS full_name, ps.PID, ps.COMMAND FROM - AS ps JOIN '/etc/passwd' FORMAT csv(delimiter=>':', has_header=>false) AS psw ON ps.USER = psw.column0 LIMIT 3"
| full_name  | ps.PID | ps.COMMAND               |
| ---------- | ------ | ------------------------ |
| Super User | 1      | /usr/lib/systemd/systemd |
| Super User | 2      | [kthreadd]               |
| Super User | 3      | [pool_workqueue_release] |

Pass a file as a variable.

$ qcat --var csv=./numbers.csv "SELECT a + b FROM csv"
3
7

More examples are in the tutorial, or try queries online in the playground.

Use as a .NET Library

QueryCat is also available as a NuGet package, so you can run SQL over files and your own .NET objects from your application. See the SDK section in the docs.

dotnet add package QueryCat

Limitations

  • Not the whole SQL standard is implemented.
  • Only a limited number of row sources support INSERT and UPDATE commands.

Links

Contributing

Issues and pull requests are welcome! See CONTRIBUTING.md for how to build the project and run tests. Please target the develop branch.

License

QueryCat is licensed under the MIT License - see the LICENSE file for details.

About

Use SQL to query different data sources like logs, JSON, CSV, XML, etc.

Resources

Contributing

Stars

25 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages