Skip to content

ClickHouse

Install

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

Connect

API

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.

Parameters

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'.

Examples

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)

Attributes

current_database property readonly

Return the name of the current database.

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

Returns

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.

Returns

str The backend version

Classes

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

Database to use for temporary objects.

Methods

close(self)

Close Clickhouse connection and drop any temporary objects

list_databases(self, like=None)

List existing databases in the current connection.

Parameters

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

Returns

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.

Parameters

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

Returns

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.

Parameters

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

Returns

Any The resutls of executing the query


Last update: March 1, 2022