Skip to main content
ClickHouse is a high-performance, column-oriented SQL database management system designed for online analytical processing (OLAP). It’s known for its blazing-fast query performance on large datasets, making it ideal for real-time analytics, log processing, and business intelligence applications.

​
Configuring ClickHouse as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the ClickHouse option from the list of connectors. Click Next and you’ll be prompted to add your database access.

​
1. Add database access

You’ll need the following connection details to connect to your ClickHouse database:
  • Host: The host address of your ClickHouse database. Do not include the protocol (http:// or https://).
    • For ClickHouse Cloud: your-instance.region.provider.clickhouse.cloud
    • For self-hosted: Your server hostname or IP address
  • Port: The port used for connecting to your ClickHouse database.
    • Default for HTTPS: 8443
    • Default for HTTP: 8123
    • Default for Native protocol: 9440 (secure) or 9000 (insecure)
  • Database: The name of the database you want to extract data from. Default is default.
  • Username: The username for accessing your ClickHouse database. Default is default.
  • Password: The password for the specified user.
  • Batch Size: The number of rows to fetch per batch during extraction. Default is 50000. Adjust based on your table row sizes and memory constraints.
If you’re using ClickHouse Cloud:
  1. Log in to your ClickHouse Cloud Console
  2. Select your service from the dashboard
  3. Click on Connect in the left sidebar
  4. Choose HTTPS as the connection method
  5. Copy the following details:
    • Host: The hostname shown (e.g., abc123.us-east1.gcp.clickhouse.cloud)
    • Port: Usually 8443 for HTTPS
    • Username: Your configured username (default is default)
    • Password: The password you set when creating the service
Make sure your ClickHouse Cloud service allows connections from Nekt’s IP addresses. You may need to configure the IP Access List in your service settings.
Once you’re done, click Next.

​
2. Select streams

Choose which data streams (tables/views) you want to sync. You can select entire databases or pick specific tables. The connector will automatically discover all available tables and views in the specified database. System tables are excluded by default.
Tip: The stream can be found more easily by typing its name.
Select the streams and click Next.

​
3. Configure data streams

Customize how you want your data to appear in your catalog. Select a name for each table (which will contain the fetched data) and the type of sync.
  • Table name: We suggest a name, but feel free to customize it. You have the option to add a prefix and make this process faster!
  • Sync Type: You can choose between INCREMENTAL and FULL_TABLE.
    • Incremental: Every time the extraction happens, we’ll get only the new data since the last sync. This is efficient for large tables with a reliable timestamp or incrementing ID column.
    • Full table: Every time the extraction happens, we’ll get the current state of the data. This is useful for dimension tables or when you need complete accuracy.
For incremental syncs, you’ll need to select a Replication Key - a column that indicates when a row was created or modified (e.g., created_at, updated_at, or an auto-incrementing id).
Once you are done configuring, click Next.

​
4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently your ClickHouse data is updated and how current you need your analytics to be. Optionally, you can determine when to execute a full sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while. Once you are ready, click Next to finalize the setup.

​
5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your Catalog, you need at least one successful source run.

​
Implementation Notes

By default, the connector uses secure HTTPS connections to your ClickHouse database. This ensures your data is encrypted in transit.ClickHouse Cloud: Always uses HTTPS on port 8443.Self-hosted: Make sure your ClickHouse server is configured with SSL/TLS certificates for secure connections.
During large extractions, the ClickHouse server may close the connection before the full result set has been sent — typically because of a server-side constraint such as a socket write timeout (SOCKET_TIMEOUT, code 209, “Timeout exceeded while writing to socket”) or a memory limit. When a proxy sits in front of the database, the aborted query can reach the connector as a seemingly complete but truncated response body.To protect data integrity, the connector checks that every row carries the number of columns the result set declared, so a cut-off response is detected instead of being silently accepted. When that happens:
  • The extraction for that stream fails immediately and the run is stopped. The connector cannot guarantee what the destination did with the rows it already received, so it makes no claims about the destination table’s state.
  • The replication bookmark does not advance, so the next run resumes from the same point.
  • If ClickHouse’s own error text (Code: NNN. DB::Exception ...) is present in the broken payload, it is captured and shown in the run logs to help you diagnose the server-side cause. Otherwise, check the server’s system.query_log for the aborted query.
Tip: If you frequently run into timeouts or memory limit errors, reduce the Batch Size in the source configuration to lower the memory footprint of each request, or raise the relevant timeout on the ClickHouse server.
To prevent connection timeouts during large extractions, the connector reads each stream in windows of key values rather than in a single long-lived query. It slices the data by the stream’s Replication Key (incremental syncs) or by its first Primary Key column (full table syncs), which on ClickHouse is usually the head of the sorting key, so the range filters hit the index.
  • Connection Stability: Each window is fetched completely and its connection released before any record is handed downstream. Even if the destination is slow, ClickHouse never has an open response waiting on a client that is not reading it, so it cannot cut the connection due to a send timeout.
  • Value Ranges, Not Row Counts: Windows are ranges of key values, never LIMIT/OFFSET slices. ClickHouse primary keys are not unique, so a row-count cursor could silently skip rows that share a key value; a value range cannot.
  • Saturated Windows: If more rows share the exact same key value than fit in one window, they cannot be split into smaller ranges and are read in a single step. A warning is written to the run logs, and that part of the extraction temporarily uses more memory than the rest.
  • Incremental streams are only ever windowed by their replication key. If the replication key is not among the selected columns, the stream is read in a single query.
For full-table streams without a usable primary key (such as views, materialized views, or tables with ORDER BY tuple()), the connector still slices the extraction into windows to prevent source timeouts. It chooses a fallback window column from the selected schema based on the following preference:
  1. Timestamps (DateTime, Date)
  2. Numbers (Integer, Decimal)
  3. Strings (including UUID and Enum)
  4. Booleans
Float types and complex containers (like Arrays or Maps) are never used for windowing. If a stream contains no comparable columns at all, it falls back to a single continuous query but fetches data in smaller chunks (capped at 2,000 rows per round trip) to ensure the network socket remains actively read and avoids triggering server timeouts.
ClickHouse is optimized for reading large amounts of data quickly. To get the best performance:
  • HTTP Streaming: With the default HTTP driver, the connector streams query responses lazily instead of loading the whole result set into memory first. Memory usage is bounded to a single batch, which prevents out-of-memory failures when extracting very large tables.
  • Batch Size: The default batch size of 50,000 rows works well for most use cases and also sets the target size of each extraction window. If you have very wide tables (many columns), consider reducing this value.
  • Incremental Syncs: Use incremental syncs whenever possible. ClickHouse excels at filtering data by sorted columns (typically date-based).
  • Replication Key Selection: Choose a column that ClickHouse can efficiently filter on like updated_at or a column that identifies a record has been modified.
ClickHouse DateTime columns don’t accept ISO format strings with timezone suffixes in comparisons. The connector automatically handles this by converting bookmark values to ClickHouse-compatible format (YYYY-MM-DD HH:MM:SS).This means you don’t need to worry about timezone handling - the connector takes care of it automatically.
The following system databases are automatically excluded from discovery:
  • system
  • INFORMATION_SCHEMA
  • information_schema
Only user-created databases and tables will be available for extraction.
ClickHouse data types are mapped to standard types for compatibility:

​
Skills for agents

Download ClickHouse skills file

ClickHouse connector documentation as plain markdown, for use in AI agent contexts.