harelba/q

q - Run SQL directly on delimited files and multi-file sqlite databases

Python

10,365

396 commits

updated Feb 6, 2026

See the code

README

Build and Package

q - Text as Data

q's purpose is to bring SQL expressive power to the Linux command line and to provide easy access to text as actual data.

q allows the following:

  • Performing SQL-like statements directly on tabular text data, auto-caching the data in order to accelerate additional querying on the same file.
  • Performing SQL statements directly on multi-file sqlite3 databases, without having to merge them or load them into memory

The following table shows the impact of using caching:

RowsColumnsFile SizeQuery time without cachingQuery time with cachingSpeed Improvement
5,000,0001004.8GB4 minutes, 47 seconds1.92 secondsx149
1,000,000100983MB50.9 seconds0.461 secondsx110
1,000,00050477MB27.1 seconds0.272 secondsx99
100,00010099MB5.2 seconds0.141 secondsx36
100,0005048MB2.7 seconds0.105 secondsx25

Notice that for the current version, caching is not enabled by default, since the caches take disk space. Use -C readwrite or -C read to enable it for a query, or add caching_mode to .qrc to set a new default.

q's web site is https://harelba.github.io/q/ or https://q.textasdata.wiki It contains everything you need to download and use q immediately.

Usage Examples

q treats ordinary files as database tables, and supports all SQL constructs, such as WHERE, GROUP BY, JOINs, etc. It supports automatic column name and type detection, and provides full support for multiple character encodings.

Here are some example commands to get the idea:

$ q "SELECT COUNT(*) FROM ./clicks_file.csv WHERE c3 > 32.3"

$ ps -ef | q -H "SELECT UID, COUNT(*) cnt FROM - GROUP BY UID ORDER BY cnt DESC LIMIT 3"

$ q "select count(*) from some_db.sqlite3:::albums a left join another_db.sqlite3:::tracks t on (a.album_id = t.album_id)"

Detailed examples are in here

Installation.

New Major Version 3.1.6 is out with a lot of significant additions.

Instructions for all OSs are here.

The previous version 2.0.19 Can still be downloaded from here

Contact

Any feedback/suggestions/complaints regarding this tool would be much appreciated. Contributions are most welcome as well, of course.

Linkedin: Harel Ben Attia

Twitter @harelba

Email harelba@gmail.com

q on twitter: #qtextasdata

Patreon: harelba - All the money received is donated to the Center for the Prevention and Treatment of Domestic Violence in my hometown - Ramla, Israel.

cli
command-line
command-line-tool
csv
database
python
q
qtextasdata
sql
sqlite
sqlite3
textasdata
tsv

harelba/q

q - Run SQL directly on delimited files and multi-file sqlite databases

Python

10,365

396 commits

updated Feb 6, 2026

See the code

README

Build and Package

q - Text as Data

q's purpose is to bring SQL expressive power to the Linux command line and to provide easy access to text as actual data.

q allows the following:

  • Performing SQL-like statements directly on tabular text data, auto-caching the data in order to accelerate additional querying on the same file.
  • Performing SQL statements directly on multi-file sqlite3 databases, without having to merge them or load them into memory

The following table shows the impact of using caching:

RowsColumnsFile SizeQuery time without cachingQuery time with cachingSpeed Improvement
5,000,0001004.8GB4 minutes, 47 seconds1.92 secondsx149
1,000,000100983MB50.9 seconds0.461 secondsx110
1,000,00050477MB27.1 seconds0.272 secondsx99
100,00010099MB5.2 seconds0.141 secondsx36
100,0005048MB2.7 seconds0.105 secondsx25

Notice that for the current version, caching is not enabled by default, since the caches take disk space. Use -C readwrite or -C read to enable it for a query, or add caching_mode to .qrc to set a new default.

q's web site is https://harelba.github.io/q/ or https://q.textasdata.wiki It contains everything you need to download and use q immediately.

Usage Examples

q treats ordinary files as database tables, and supports all SQL constructs, such as WHERE, GROUP BY, JOINs, etc. It supports automatic column name and type detection, and provides full support for multiple character encodings.

Here are some example commands to get the idea:

$ q "SELECT COUNT(*) FROM ./clicks_file.csv WHERE c3 > 32.3"

$ ps -ef | q -H "SELECT UID, COUNT(*) cnt FROM - GROUP BY UID ORDER BY cnt DESC LIMIT 3"

$ q "select count(*) from some_db.sqlite3:::albums a left join another_db.sqlite3:::tracks t on (a.album_id = t.album_id)"

Detailed examples are in here

Installation.

New Major Version 3.1.6 is out with a lot of significant additions.

Instructions for all OSs are here.

The previous version 2.0.19 Can still be downloaded from here

Contact

Any feedback/suggestions/complaints regarding this tool would be much appreciated. Contributions are most welcome as well, of course.

Linkedin: Harel Ben Attia

Twitter @harelba

Email harelba@gmail.com

q on twitter: #qtextasdata

Patreon: harelba - All the money received is donated to the Center for the Prevention and Treatment of Domestic Violence in my hometown - Ramla, Israel.

cli
command-line
command-line-tool
csv
database
python
q
qtextasdata
sql
sqlite
sqlite3
textasdata
tsv

Project health

Overall

2.6/10

Maintained

0/10

Code review

1/10
OpenSSF Scorecard

Significant stargazers

(top 24 of 109)

TJ

54,603 followers · starred Nov 2018

Yoann Padioleau

502 followers · starred Mar 2014

Arthur

18 followers · starred Mar 2019

Ben Balter

10,358 followers · starred Feb 2016