Skip to content



Install ibis and dependencies for the ClickHouse backend:

pip install 'ibis-framework[clickhouse]'
conda install -c conda-forge ibis-clickhouse
mamba install -c conda-forge ibis-clickhouse



Create a client by passing in connection parameters to ibis.clickhouse.connect.

See ibis.backends.clickhouse.Backend.do_connect for connection parameter information.

ibis.clickhouse.connect is a thin wrapper around ibis.backends.clickhouse.Backend.do_connect.

Connection Parameters

do_connect(self, host='localhost', port=9000, database='default', user='default', password='', client_name='ibis', compression='lz4', **kwargs)

Create a ClickHouse client for use with Ibis.


host Host name of the clickhouse server port Clickhouse server's port database Default database when executing queries user User to authenticate with password Password to authenticate with client_name Name of client that wil appear in clickhouse server logs compression Whether or not to use compression. Default is 'lz4' if installed else False. True is equivalent to 'lz4'.


import ibis import os clickhouse_host = os.environ.get('IBIS_TEST_CLICKHOUSE_HOST', 'localhost') clickhouse_port = int(os.environ.get('IBIS_TEST_CLICKHOUSE_PORT', 9000)) client = ibis.clickhouse.connect(host=clickhouse_host, port=clickhouse_port) client # doctest: +ELLIPSIS

Backend API

Backend (BaseSQLBackend)


current_database property readonly

Return the name of the current database.

Backends that don't support different databases will return None.


str | None Name of the current database.

version: str property readonly

Return the version of the backend engine.

For database servers, return the server version.

For others such as SQLite and pandas return the version of the underlying library or application.


str The backend version


Options (BaseModel) pydantic-model
temp_db: str pydantic-field

Database to use for temporary objects.



Close Clickhouse connection and drop any temporary objects

list_databases(self, like=None)

List existing databases in the current connection.


like A pattern in Python's regex format to filter returned database names.


list[str] The database names that exist in the current connection, that match the like pattern if provided.

list_tables(self, like=None, database=None)

Return the list of table names in the current database.

For some backends, the tables may be files in a directory, or other equivalent entities in a SQL database.


like : str, optional A pattern in Python's regex format. database : str, optional The database to list tables of, if not the current one.


list[str] The list of the table names that match the pattern like.

raw_sql(self, query, external_tables=None)

Execute a SQL string query against the database.


query Raw SQL string external_tables Mapping of table name to pandas DataFrames providing external datasources for the query


Any The resutls of executing the query

Last update: March 1, 2022