ClickShack
|
A collection of ClickHouse query parsing and analysis tools built on a rickety, hollowed-out version of ClickHouse.
One of the challenges of building tooling around SQL is that some dialects provide a large set of features beyond standard ANSI SQL. ClickHouse is one of these, providing a rich SQL dialect that is difficult for generic tooling to keep up with.
This project builds more reliable tooling for ClickHouse queries by providing abstractions over the actual ClickHouse parser.
Note: Parsing is currently limited to
SELECTqueries, other query types are on the roadmap.
Usage
The primary entrypoint is a Python package, clickshack. Features include:
- A near like-for-like port of the actual ClickHouse SQL parser (currently supports version
26.2) - Converters for integrating with SQLGlot — parse with
clickshack, then reach for SQLGlot's growing library of SQL utilities. - (Experimental) - A minimal Python library for writing custom SQL linting rules.
- Note: I am not entirely sure where this one is headed, but it might make a useful counterpart to something like sqlcheck for ClickHouse.
Install from PyPI with:
pip install clickshack
Then parse a query with:
from clickshack import parse_sql
envelope = parse_sql("SELECT id, name FROM users WHERE active = 1")
print(envelope.ir_version) # "1"
print(envelope.query) # SelectNode(...)
Integrate with SQLGlot:
from sqlglot.lineage import lineage
from clickshack import parse_sql
from clickshack.ir.adapter import to_sqlglot
envelope = parse_sql("SELECT id, name FROM users WHERE active = 1")
sqlglot_expr = to_sqlglot(envelope.query)
# Trace which source column feeds 'name' in the output
node = lineage("name", sqlglot_expr)
for n in node.walk():
print(n.name)
# name
# users.name
Or run one of the experimental linters with:
from clickshack import parse_sql
from clickshack.ir.models import StarNode
from clickshack.linter.base import LintRunner, LintViolation
class NoSelectStar:
"""Prohibit SELECT *."""
def check(self, node) -> list[LintViolation]:
if isinstance(node, StarNode):
return [LintViolation(rule="no-star", message="SELECT * is not allowed", span=node.span)]
return []
envelope = parse_sql("SELECT * FROM events")
runner = LintRunner(rules=[NoSelectStar()])
violations = runner.run(envelope.query)
for v in violations:
print(f"{v.rule} at offset {v.span.start}: {v.message}")
# no-star at offset 7: SELECT * is not allowed
See the modules under ./clickshack/ for more details (docs are still in the works).
Development
Prerequisites
bazel,just,uv- Python 3.11+ (managed automatically by uv)
Setup
# Install Python dependencies (creates .venv automatically)
just sync
Project Structure
ported_clickhouse/ C++ parser (ported ClickHouse SELECT dialect)
ir/ C++ IR serializer (AST → JSON, uses nlohmann/json)
examples/bootstrap/ Smoke binaries incl. ir_dump (SQL stdin → JSON IR stdout)
clickshack/
ir/ Pydantic v2 models + SQLGlot adapter for the JSON IR
linter/ LintRule protocol + LintRunner for IR-based linting
tests/ Python tests (pytest)
testdata/ Parser workload fixtures and manifest
Common Commands
| Command | What it does |
|---|---|
just build |
Build primary binary (hello_clickshack) |
just build-all |
Build all example binaries |
just build-ir |
Build IR serializer and ir_dump binary |
just run-ported-smokes |
Run C++ parser smoke tests |
just sync |
Install / sync Python dependencies |
just test-python |
Run Python tests |
just clean |
Remove Bazel build outputs |
just clean-expunge |
Fully reset Bazel output state |
IR Dump
Parse SQL and emit the JSON IR:
echo "SELECT id FROM users WHERE active = 1" | \
bazel-bin/examples/bootstrap/ir_dump
(Build with just build-ir first.)
License
The clickshack Python package and original C++ code are licensed under the
MIT License.
The C++ parser in ported_clickhouse/ is derived from
ClickHouse and is licensed under
the Apache License 2.0. See NOTICE for
attribution details and a description of modifications.
Metadata
Release files for clickshack 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 9.7 MB
Release files / clickshack-0.1.1-cp313-cp313-musllinux_1_2_x86_64.whl
| Download URL | clickshack-0.1.1-cp313-cp313-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.13 Linux musl 1.2+ x86-64 |
|
SHA-256 checksum How to use checksums |
76f16e8763f6bb3c7e85dcc48eddc907b161f9a400a192df4469dce51293f308
|
|
BLAKE2b-256 checksum How to use checksums |
a144c85d4ae08d8f8831eb542851aeb592e7c4237032c50f53bb705484bf461d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.
Transparency logRelease files / clickshack-0.1.1-cp313-cp313-musllinux_1_2_aarch64.whl
| Download URL | clickshack-0.1.1-cp313-cp313-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.13 Linux musl 1.2+ ARM64 |
|
SHA-256 checksum How to use checksums |
33bfa9918d4fc79533fcc792753d1022e7bdeb96752b3e88657d3fff7998b8e9
|
|
BLAKE2b-256 checksum How to use checksums |
c1b22d3810ceac4a3a970f698e6e6d9cc30ff1ecda512a7ad37ff4371f26f8de
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.
Transparency logRelease files / clickshack-0.1.1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | clickshack-0.1.1-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 258.8 kB |
| Tags | CPython 3.13 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
16c052b81774864aff9030adfaf0ab97fcc645204a9a0146703e016d860008cf
|
|
BLAKE2b-256 checksum How to use checksums |
1c99d5dbe9168c3de1129cc4dfcc7922d78be80e240aa71c3d6fc766bbcf14b7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.
Transparency logRelease files / clickshack-0.1.1-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
| Download URL | clickshack-0.1.1-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 260.3 kB |
| Tags | CPython 3.13 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
5808be2a2fa0d8d1440994e105d1023ee5e0d4d8b131cb53d8a4cd7664d288ad
|
|
BLAKE2b-256 checksum How to use checksums |
dc2175ecf5547ff6c3b74912be20108cb4dccfd4598ac0658433e3fdfe24d0cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.
Transparency logRelease files / clickshack-0.1.1-cp313-cp313-macosx_14_0_arm64.whl
| Download URL | clickshack-0.1.1-cp313-cp313-macosx_14_0_arm64.whl |
|---|---|
| Size | 267.8 kB |
| Tags | CPython 3.13 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
c19133a8a09e8b21999eb6ee74a63f8f9b7931b835fe4f27affb10d79e0e3d5c
|
|
BLAKE2b-256 checksum How to use checksums |
8c7a35225e02f0dba5a72e329fcff1361036a1cfcd5590dab1cca781b479c0c3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.
Transparency logRelease files / clickshack-0.1.1-cp312-cp312-musllinux_1_2_x86_64.whl
| Download URL | clickshack-0.1.1-cp312-cp312-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.12 Linux musl 1.2+ x86-64 |
|
SHA-256 checksum How to use checksums |
3319c17bb9ab2342df99362bd3aa83095cdda081476fb38516228daaae261fd8
|
|
BLAKE2b-256 checksum How to use checksums |
1bfb8deab554ce06ffef74c5d2de251555e00f2e21abfd1ba03cf82b65a83919
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.
Transparency logRelease files / clickshack-0.1.1-cp312-cp312-musllinux_1_2_aarch64.whl
| Download URL | clickshack-0.1.1-cp312-cp312-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.12 Linux musl 1.2+ ARM64 |
|
SHA-256 checksum How to use checksums |
42a864d224c389a1bfcf76cabdf8d38be97214b1b2d581a2aa68fa42d6abd0f5
|
|
BLAKE2b-256 checksum How to use checksums |
8a75cd0d542fc7c2dde02139cc3f696f55ed3a262c1874353fdc7714814370d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.
Transparency logRelease files / clickshack-0.1.1-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | clickshack-0.1.1-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 258.8 kB |
| Tags | CPython 3.12 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
1b84bc22b1a1ad25103c253456c82ffc5de7ce9095f0ebc9c3b02de1d63c2143
|
|
BLAKE2b-256 checksum How to use checksums |
03dc33b34b0167003e81e1a5ffb363f5d43ac482af7ec201b318f292a8bde26f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.
Transparency logRelease files / clickshack-0.1.1-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
| Download URL | clickshack-0.1.1-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 260.3 kB |
| Tags | CPython 3.12 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
15f52e2928d37833690e342cb03ed48d0e2772a222e0be85dd13e1749787e3ee
|
|
BLAKE2b-256 checksum How to use checksums |
26b42e331666a409587669d559ce5a30a4ce7c6175606a36ac4bf44719d816e5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.
Transparency logRelease files / clickshack-0.1.1-cp312-cp312-macosx_14_0_arm64.whl
| Download URL | clickshack-0.1.1-cp312-cp312-macosx_14_0_arm64.whl |
|---|---|
| Size | 267.8 kB |
| Tags | CPython 3.12 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
baf7ccd0aad62d5f8cfe475641561bf13d93975f6f7d9d458c936705ede41b2d
|
|
BLAKE2b-256 checksum How to use checksums |
c6f65acedb8754f3869ade50c6f0610ae7bc5e23c2cb8b83c0adf9d4cded9883
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.
Transparency logRelease files / clickshack-0.1.1-cp311-cp311-musllinux_1_2_x86_64.whl
| Download URL | clickshack-0.1.1-cp311-cp311-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.11 Linux musl 1.2+ x86-64 |
|
SHA-256 checksum How to use checksums |
1db7e6441a82ecd65b15318517ba83e120c84fa29fedceda253d7f88fc79e414
|
|
BLAKE2b-256 checksum How to use checksums |
bb4d86b69279f7f1088f68b66475432b0761f3ef385dc4fccc0d43bd3c7e0a60
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.
Transparency logRelease files / clickshack-0.1.1-cp311-cp311-musllinux_1_2_aarch64.whl
| Download URL | clickshack-0.1.1-cp311-cp311-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.11 Linux musl 1.2+ ARM64 |
|
SHA-256 checksum How to use checksums |
45f2d5b051bc0597f1bb76b4c41f598bf8a840bc18bf5c68d3e2a10c2f7fe7d3
|
|
BLAKE2b-256 checksum How to use checksums |
170b0b1f0dcd81575c09edd563c32e6002bad6991764f001f468d9f5b0dde59f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.
Transparency logRelease files / clickshack-0.1.1-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
| Download URL | clickshack-0.1.1-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 258.8 kB |
| Tags | CPython 3.11 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
6fb68bb13c3157da86a229439babbb4b301d1e13d1e9ebbe4a511f71e025f134
|
|
BLAKE2b-256 checksum How to use checksums |
2d9838085cff6c90b9e3a9bdc2e70d7c065d3e500ab01889f8e630b4987450a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.
Transparency logRelease files / clickshack-0.1.1-cp311-cp311-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
| Download URL | clickshack-0.1.1-cp311-cp311-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 260.3 kB |
| Tags | CPython 3.11 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
2c9a12678fb8fbdd63b1cc1bc2342862d9e5fd4a23e05ba74912948f24a48f07
|
|
BLAKE2b-256 checksum How to use checksums |
2df27e50cedc8d5bb8fa378cd9742cdf3c37732c4aea60dd58e42d2c39ad2349
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.
Transparency logRelease files / clickshack-0.1.1-cp311-cp311-macosx_14_0_arm64.whl
| Download URL | clickshack-0.1.1-cp311-cp311-macosx_14_0_arm64.whl |
|---|---|
| Size | 267.8 kB |
| Tags | CPython 3.11 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
c744c686ff4fb175338b459b7fa637db09ab0b019779af824008aae26855fb0d
|
|
BLAKE2b-256 checksum How to use checksums |
bb76b513cec4f6c975b38f2c73a73f5e914c49b77d08305635d53b13225eb00e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.
Transparency logSecurity for clickshack 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 15 files in this release have been uploaded with provenance metadata.
Attestation for clickshack-0.1.1-cp313-cp313-musllinux_1_2_x86_64.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.