ClickHouse is an open-source column-oriented database for real-time analytics using SQL. It's known for extremely fast query performance on large datasets.
Installation
Required packages: clickhouse-sqlalchemyclickhouse-connect>=1.8.0,<2.0
# For a Python environment
pip install "clickhouse-connect>=1.8.0,<2.0"
# For the repository Docker Compose setup
echo "clickhouse-connect>=1.8.0,<2.0" >> ./docker/requirements-local.txt
# Restart the containers after adding the driver.Drivers
clickhouse-connectRecommended
clickhouse-sqlalchemy (Legacy)
PyPI Package:
clickhouse-connect>=1.8.0,<2.0clickhousedb://{username}:{password}@{host}:{port}/{database}Official ClickHouse Python driver using HTTP(S). Use the HTTP port (8123 by default), or the HTTPS port with secure=true (8443 for ClickHouse Cloud). Native TCP ports are not supported.
Connection Examples
ClickHouse Cloud SQL playground (demo user, no password)
clickhousedb://demo:@sql-clickhouse.clickhouse.com:8443/uk?secure=trueClickHouse Cloud (HTTPS)
clickhousedb://{username}:{password}@{host}:8443/{database}?secure=trueAltinity Cloud
clickhousedb://demo:demo@github.demo.trial.altinity.cloud/default?secure=trueLocal (default user, no password, no TLS)
clickhousedb://default@localhost:8123/defaultSupported Features
JOINsSubqueriesDynamic SchemaCatalog SupportDynamic CatalogSSH TunnelingQuery CancellationFile UploadUser ImpersonationCost EstimationSQL Validation
Feature Score: 61/201
Time Grains
Common Time Grains:
SECONDMINUTEHOURDAYWEEKMONTHQUARTERYEAR
Extended Time Grains:
FIVE_SECONDSTHIRTY_SECONDSFIVE_MINUTESTEN_MINUTESFIFTEEN_MINUTESTHIRTY_MINUTESHALF_HOURSIX_HOURSWEEK_STARTING_SUNDAYWEEK_STARTING_MONDAYWEEK_ENDING_SATURDAYWEEK_ENDING_SUNDAYQUARTER_YEAR
Extended Aggregate Functions
The base aggregates (SUM, COUNT, AVG, MIN, MAX, COUNT DISTINCT) are supported everywhere; these are opt-in per engine.
MEDIANSTDDEV_SAMPVAR_SAMP
Compatible Databases
The following databases are compatible with the ClickHouse driver:
ClickHouse CloudClickHouse Cloud is the official fully-managed cloud service for ClickHouse. It provides automatic scaling, built-in backups, and enterprise security features.
clickhousedb://{username}:{password}@{host}:8443/{database}?secure=trueParameters:
| Parameter | Description |
|---|---|
| username | Database username from the service Connect dialog (default: default) |
| password | URL-encoded database password from the service Connect dialog |
| host | HTTPS hostname from the service Connect dialog |
| database | Database name (default) |
Open your service in the ClickHouse Cloud console and select Connect to find the HTTPS endpoint and database credentials. For public connections, allow the Superset server IP address in the service IP access list.
Altinity.CloudAltinity.Cloud is a managed ClickHouse service providing Kubernetes-native deployments with enterprise support.
clickhousedb://{username}:{password}@{host}/{database}?secure=trueNotes
The SQL playground at sql.clickhouse.com uses the database endpoint sql-clickhouse.clickhouse.com; the example connects to its uk sample database. URL-encode special characters in usernames and passwords when building a SQLAlchemy URI. Use database credentials, not your ClickHouse Cloud console sign-in. For Docker deployments, localhost refers to the Superset container; use a hostname reachable from that container.
Resources