Skip to content

ClickHouse

Installation

pip install "toolfront[clickhouse]"

Connection URL

Connect to ClickHouse by passing a connection URL to the Database constructor:

1
2
3
4
5
from toolfront import Database

db = Database(url="clickhouse://{user}:{password}@{host}:{port}/{database}")

revenue = db.ask("What's our total revenue this month?")

1
2
3
4
5
from toolfront import Database

db = Database(url="clickhouse://{user}:{password}@{host}:{port}/{database}?secure=true")

revenue = db.ask("What's our total revenue this month?")

1
2
3
4
5
from toolfront import Database

db = Database(url="clickhouse://{user}:{password}@{host}:{port}/{database}?compression=lz4")

revenue = db.ask("What's our total revenue this month?")

Connection Parameters

Alternatively, connect using the Database.from_clickhouse() method with parameters:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from toolfront import Database

db = Database.from_clickhouse(
    host="localhost",
    port=9000,
    database="sales",
    user="user",
    password="pass",
    secure=False
)

revenue = db.ask("What's our total revenue this month?")
PARAMETER DESCRIPTION
host

Host name of the ClickHouse server. Default is 'localhost'.

TYPE: str DEFAULT: 'localhost'

port

ClickHouse HTTP server's port. If not passed, the value depends on whether secure is True or False.

TYPE: int DEFAULT: None

database

Default database when executing queries. Default is 'default'.

TYPE: str DEFAULT: 'default'

user

User to authenticate with. Default is 'default'.

TYPE: str DEFAULT: 'default'

password

Password to authenticate with. Default is ''.

TYPE: str DEFAULT: ''

client_name

Name of client that will appear in ClickHouse server logs. Default is 'ibis'.

TYPE: str DEFAULT: 'ibis'

secure

Whether or not to use an authenticated endpoint.

TYPE: bool DEFAULT: None

compression

The kind of compression to use for requests. See ClickHouse Python Compression Docs for more information. Default is True.

TYPE: str or bool DEFAULT: True

match_schema

Regex pattern to filter schemas. Mutually exclusive with match_tables.

TYPE: str DEFAULT: None

match_tables

Regex pattern to filter tables. Mutually exclusive with match_schema.

TYPE: str DEFAULT: None

**kwargs

Client specific keyword arguments.

TYPE: Any DEFAULT: {}