csvql-query
Query CSV files with SQL from Python — powered by a Zig/SIMD engine.
Zero-copy mmap reads + SIMD parsing happen before Python ever sees the data. Faster than DuckDB on typical workloads, no dependencies required.
Installation
pip install csvql-query
Quick Start
import csvql
# Returns a list of dicts (like csv.DictReader, but with SQL)
rows = csvql.query("SELECT name, salary FROM 'employees.csv' WHERE salary > 100000 ORDER BY salary DESC")
# [{'name': 'Alice', 'salary': '185000'}, ...]
# Raw CSV string
csv_str = csvql.query_csv("SELECT * FROM 'data.csv' LIMIT 10")
# pandas DataFrame (pandas must be installed)
df = csvql.query_df("SELECT category, COUNT(*) as n FROM 'sales.csv' GROUP BY category")
# (headers, rows) tuples — no dependencies
headers, rows = csvql.query_tuples("SELECT name, age FROM 'users.csv' WHERE age > 25")
API
| Function | Returns | Description |
|---|---|---|
query(sql) |
list[dict] |
Execute SQL, get list of dicts |
query_csv(sql) |
str |
Execute SQL, get raw CSV string |
query_df(sql) |
DataFrame |
Execute SQL, get pandas DataFrame |
query_tuples(sql) |
(list[str], list[tuple]) |
Execute SQL, get (headers, rows) |
SQL Support
The SQL path is embedded in the query string (same as the CLI):
# Filtering, ordering, limiting
csvql.query("SELECT name, city FROM 'data.csv' WHERE age > 30 ORDER BY name LIMIT 5")
# Aggregation
csvql.query("SELECT department, AVG(salary) FROM 'emp.csv' GROUP BY department")
# Unix pipes — use '-' as the filename
import subprocess, sys
# or just pass stdin data via the engine directly
Full SQL reference: SIMPLE_QUERY_LANGUAGE.md
Performance
- mmap + SIMD parsing — data is never copied into Python memory
- Parallel chunk processing on multi-core machines
- Typically 5–9x faster than DuckDB on 1M-row CSVs
Requirements
- Python ≥ 3.10
- macOS (x86_64 / arm64) or Linux (x86_64)
pandasoptional — only needed forquery_df()
Links
1 maintainer
Metadata
1 maintainer
Release files for csvql-query 2.6.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| csvql_query-2.6.3-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details |
| csvql_query-2.6.3-py3-none-manylinux_2_17_x86_64.whl | Python 3 | none | Linux glibc 2.17+ x86-64 | Details |
| csvql_query-2.6.3-py3-none-manylinux_2_17_aarch64.whl | Python 3 | none | Linux glibc 2.17+ ARM64 | Details |
| csvql_query-2.6.3-py3-none-macosx_12_0_x86_64.whl | Python 3 | none | macOS 12.0+ x86-64 | Details |
| csvql_query-2.6.3-py3-none-macosx_12_0_arm64.whl | Python 3 | none | macOS 12.0+ ARM64 | Details |
Total release size: 4.3 MB
Release files / csvql_query-2.6.3-py3-none-win_amd64.whl
| Download URL | csvql_query-2.6.3-py3-none-win_amd64.whl |
|---|---|
| Size | 520.5 kB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
f9cb635b23dcc2f7dbb70b8b16867397ebe69f3e8d600df202e5210e7d929880
|
|
BLAKE2b-256 checksum How to use checksums |
06f196a853e19fca0e7df31a3ae3c1d00aefe54ab54130d3e8d2bd4d70dec2a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / csvql_query-2.6.3-py3-none-manylinux_2_17_x86_64.whl
| Download URL | csvql_query-2.6.3-py3-none-manylinux_2_17_x86_64.whl |
|---|---|
| Size | 1.6 MB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
3fa06a5433c6a77df5aa2089002da3a419830a52bb5b2e0c2225a3afab9e3655
|
|
BLAKE2b-256 checksum How to use checksums |
964833e805f9002153b336906eedb1e8134c70e15770dd198fc674b381b2588a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / csvql_query-2.6.3-py3-none-manylinux_2_17_aarch64.whl
| Download URL | csvql_query-2.6.3-py3-none-manylinux_2_17_aarch64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
cdb1ef52f57cee21674abb79aa46e6d0b8b83d6175fa18d40487611abf07373e
|
|
BLAKE2b-256 checksum How to use checksums |
3055c298e03c3ba61724b9c0b2dd1fdc95ce83b434fd3d6f4b8d8f2147241a8c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / csvql_query-2.6.3-py3-none-macosx_12_0_x86_64.whl
| Download URL | csvql_query-2.6.3-py3-none-macosx_12_0_x86_64.whl |
|---|---|
| Size | 359.3 kB |
| Tags | Python 3 macOS 12.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
c1db6192a4820cf1e60a9717fa3cd693913acaa21bc9161d5a6a8a314fb22c45
|
|
BLAKE2b-256 checksum How to use checksums |
e25d522fecf57607e589e0cb92dac8b54a311612e29c8b3f1a12ed5baf0514b7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / csvql_query-2.6.3-py3-none-macosx_12_0_arm64.whl
| Download URL | csvql_query-2.6.3-py3-none-macosx_12_0_arm64.whl |
|---|---|
| Size | 359.3 kB |
| Tags | Python 3 macOS 12.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
b3ea983f456b757ade502c7dd3a8b35bd2d805c9bcb3fca3d72d5f0ee797b387
|
|
BLAKE2b-256 checksum How to use checksums |
26794ce6cfc44f26cadefabc777292511b29bd43456d7d8a9024a0f8170f3cea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
