---
title: "Integrating ClickHouse with Hex"
description: "Hex is an AI analytics platform that unifies deep analysis, conversation self-serve and ad hoc exploration in a single experience – enhanced by agents."
category: "DATA_VISUALIZATION"
support: "PARTNER"
docs: "https://learn.hex.tech/docs/connect-to-data/data-connections/clickhouse-chdb"
---

# Hex

Hex offers two ways to work with ClickHouse data:

1. **Data Connection** — Connect Hex to a remote ClickHouse Cloud service or self-managed instance. This is the standard approach for querying production databases from Hex notebooks and apps.
2. **chDB Integration** — Use chDB, ClickHouse's embedded in-process analytical engine, to run ClickHouse SQL directly inside Hex. chDB uses lazy evaluation and only materializes data when needed, making it ideal for working with large datasets without overloading notebook memory.

<iframe width="560" height="315" src="https://www.youtube.com/embed/JS_MKfeNOP0?si=ZDfemDJAyO0BAi7p" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

### **Option 1: Data Connection**



To connect Hex to a remote ClickHouse instance:

1. In Hex, go to **Settings → Data sources**.
2. Click **+ Connection**, select the **ClickHouse** tile.
3. Fill in your connection details:
   - **Host** — The address of your ClickHouse database.
   - **Port** — The port for secure native connections (typically `9440`, see <a href="https://clickhouse.com/docs/guides/sre/network-ports" target="_blank">ClickHouse port documentation</a>).
   - **Username** — The ClickHouse username configured for Hex (we recommend creating a dedicated <a href="https://clickhouse.com/docs/en/guides/sre/users-and-roles" target="_blank">read-only user</a>).
   - **Password** — The corresponding password.





You can also configure optional settings such as custom SQL formatting, SSH tunneling, access controls, and schema browsing schedules. For full instructions, see the <a href="https://learn.hex.tech/docs/connect-to-data/data-connections/setup-guides/connect-to-clickhouse" target="_blank">ClickHouse data connection setup guide</a>.




>**NOTE:** If you use a firewall to restrict database access, make sure to allow Hex's IP addresses. See the <a href="https://learn.hex.tech/docs/connect-to-data/data-connections/allow-connections-from-hex-ip-addresses" target="_blank">Hex IP allowlist documentation</a> for the current list.


### **Option 2: chDB Integration**




To enable chDB on an existing ClickHouse data connection:

1. Open the ClickHouse data connection settings in Hex.
2. Scroll to the **Advanced** section.
3. Toggle on **chDB**.






Once enabled, import the connection into your project and create a chDB session:

```python
import hextoolkit
hex_clickhouse_conn = hextoolkit.get_data_connection('My ClickHouse Connection')
session = hex_clickhouse_conn.get_chdb_session()
```





You can then write SQL and chain Pythonic operations, all executed directly in ClickHouse:

```python
ds = session.sql("SELECT * FROM transactions_table")
filtered = ds[ds["event_type"] == "purchase"]
df = filtered.to_pandas()  # Materialize only when needed
```




For full details, see the <a href="https://learn.hex.tech/docs/connect-to-data/data-connections/clickhouse-chdb" target="_blank">chDB integration guide</a>.


>**NOTE:** The `get_chdb_session` function requires Python 3.12+ kernels in Hex.



## **Get Started**

Ready to try ClickHouse in Hex? Follow the <a href="https://app.hex.tech/partnerships/app/chDB-Tutorial-032XsQ4qoKtlXxcw49joav/latest" target="_blank">getting started tutorial</a> to set up your first connection. Want more time to explore? Sign up for an <a href="https://app.hex.tech/signup/clickhouse-30" target="_blank">extended 30-day Hex trial</a> with full access to ClickHouse integrations.