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.

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 ClickHouse port documentation).
     • Username — The ClickHouse username configured for Hex (we recommend creating a dedicated read-only user).
     • 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 ClickHouse data connection setup guide.

NOTE: If you use a firewall to restrict database access, make sure to allow Hex's IP addresses. See the Hex IP allowlist documentation 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:

  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:

  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 chDB integration guide.

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

Get Started

Ready to try ClickHouse in Hex? Follow the getting started tutorial to set up your first connection. Want more time to explore? Sign up for an extended 30-day Hex trial with full access to ClickHouse integrations.