--- title: ClickHouse Connect slug: connectors/clickhouse-connect docTags: createdAt: 2026-06-09T16:30:00.730Z --- ClickHouse Connect provides seamless integration with ClickHouse, enabling efficient data retrieval and analysis for enhanced security operations. ClickHouse is a fast and powerful open-source columnar database management system designed for real-time analytics. The ClickHouse Connect integration allows Swimlane Turbine users to execute and analyze SQL queries within their security workflows seamlessly. By leveraging this connector, users can retrieve and manipulate large datasets efficiently, enhancing their ability to make data-driven decisions in real-time. This integration empowers security teams to automate data retrieval and analysis, streamlining their operations and improving response times to potential threats. ### Limitations None to date. ### Supported Versions This ClickHouse Connect connector uses the Latest Version SDK. ## Configuration ### Prerequisites Before you can use the ClickHouse Connect connector for Turbine, you'll need access to the ClickHouse server. This requires the following: - Custom authentication using the following parameters: - Username: The username required to authenticate with the ClickHouse server. - Password: The password associated with the username for secure access. - Host: The host address of the ClickHouse server to connect to. ## Authentication Methods ### Custom Authentication: - **URL**: The address of the ClickHouse server. - **Username**: The user account for database access. - **Password**: The password associated with the user account. ## Capabilities This ClickHouse Connect connector provides the following capabilities: - **Client Query** ### Client Query The `Client.query` method is the primary way to retrieve a single "batch" dataset from the ClickHouse Server. ClickHouse Connect's documentation for this action can be found [here](https://clickhouse.com/docs/integrations/python#client-query-method). ### QueryContexts ClickHouse Connect executes standard queries within a **QueryContext**. The QueryContext contains the key structures that are used to build queries against the ClickHouse database and the configuration used to process the result into a `QueryResult` or other response data structure. This includes: - The query itself - Parameters - Settings - Read formats - Time zone handling A QueryContext can be acquired using the `client.create_query_context` method. This method takes the same parameters as the core `query` method. This query context can then be passed to the `query`, `query_df`, or `query_np` methods as the `context` keyword argument instead of specifying individual arguments each time. **Any additional arguments specified for the method call will override existing QueryContext properties.** ### Example Usage ```python client.create_query_context(query='SELECT value1, value2 FROM data_table WHERE key = {k:Int32}', parameters={'k': 2}, column_oriented=True) result = client.query(context=qc) assert result.result_set[1][0] == 'second_value2' qc.set_parameter('k', 1) result = client.query(context=qc) assert result.result_set[1][0] == 'first_value2' ``` ### QueryContext Supported Fields When `context=True`, the following fields are available: | Field Name | Type | Description | | ------------------------- | ---------- | ----------------------------------------------------------- | | **query** | `str` | The SQL query to execute (required). | | **parameters** | `dict` | Query parameters to bind. | | **settings** | `dict` | Additional ClickHouse settings for query execution. | | **query\_formats** | `dict` | Datatype formatting specification for result values. | | **column\_formats** | `dict` | Datatype formatting per column. | | **encoding** | `str` | Encoding used for ClickHouse string columns. | | **server\_tz** | `pytz.UTC` | Server timezone configuration. | | **use\_none** | `bool` | Use Python `None` for ClickHouse NULL values. | | **column\_oriented** | `bool` | Return results as a sequence of columns instead of rows. | | **use\_numpy** | `bool` | Return results as NumPy arrays. | | **max\_str\_len** | `int` | Maximum string length allowed. Defaults to `0` (unlimited). | | **query\_tz** | `str` | Timezone name for query execution. | | **column\_tzs** | `dict` | Dictionary mapping column names to specific time zones. | | **use\_extended\_dtypes** | `bool` | Use extended Pandas dtypes for NULL values. | | **as\_pandas** | `bool` | Return results as a Pandas DataFrame. | | **streaming** | `bool` | Enable streaming queries for large datasets. | | **apply\_server\_tz** | `bool` | Apply server timezone settings to datetime values. | | **external\_data** | `dict` | External data configuration for file-based queries. | By utilizing QueryContexts, users can enhance query efficiency by dynamically modifying query parameters without reconstructing the full query, ensuring optimized and structured data retrieval. ## Additional Documentation - [ClickHouse Connect Connector Documentation](https://docs.swimlane.com/connectors/clickhouse-connect) - [ClickHouse Connect API Documentation](https://clickhouse.com/docs/integrations/python#gather-your-connection-details) # Configurations ## ClickHouse Connect Asset ### Configuration Parameters | **Parameter** | **Description** | **Type** | **Required** | | ------------- | ---------------------------------- | -------- | ------------ | | url | A target host. | string | Required | | port | A target port. | integer | Optional | | username | Username | string | Required | | password | Password | string | Required | | verify\_ssl | Verify SSL certificate | boolean | Optional | | http\_proxy | A proxy to route requests through. | string | Optional | # Actions ## Client Query Retrieve a single 'batch' dataset from the ClickHouse Server using the provided query. ### Endpoint - **Method:** `GET` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | Required | The ClickHouse SQL SELECT or DESCRIBE query. | | `parameters` | object | Optional | See parameters description. | | `settings` | object | Optional | See settings description. | | `query_formats` | object | Optional | Datatype formatting specification for result values. | | `column_formats` | object | Optional | Datatype formatting per column. | | `encoding` | string | Optional | Encoding used to encode ClickHouse String columns into Python strings. Python defaults to UTF-8 if not set. | | `use_none` | boolean | Optional | Use Python None type for ClickHouse nulls. If False, use a datatype default (such as 0) for ClickHouse nulls. Note - defaults to False for NumPy/Pandas for performance reasons. | | `column_oriented` | boolean | Optional | Return the results as a sequence of columns rather than a sequence of rows. Helpful for transforming Python data to other column oriented data formats. | | `query_tz` | string | Optional | A timezone name from the zoneinfo database. This timezone will be applied to all datetime or Pandas Timestamp objects returned by the query. | | `column_tzs` | object | Optional | A dictionary of column name to timezone name. Like query\_tz, but allows specifying different timezones for different columns. | | `use_extended_dtypes` | boolean | Optional | Use Pandas extended dtypes (like StringArray), and pandas.NA and pandas.NaT for ClickHouse NULL values. Applies only to query\_df and query\_df\_stream methods. | | `external_data` | object | Optional | An ExternalData object containing file or binary data to use with the query. | | `external_data.file_path` | string | Optional | Path to a file on the local system path to read the external data from. Either file\_path or data is required. | | `external_data.file_name` | string | Optional | The name of the external data "file". If not provided, will be determined from the file\_path (without extensions). | | `external_data.data` | string | Optional | The external data in binary form (instead of being read from a file). Either data or file\_path is required. | | `external_data.fmt` | string | Optional | The ClickHouse Input Format of the data. Defaults to TSV. | | `external_data.types` | array | Optional | A list of column data types in the external data. If a string, types should be separated by commas. Either types or structure is required. | | `external_data.structure` | array | Optional | A list of column name + data type in the data (see examples). Either structure or types is required. | | `external_data.mime_type` | string | Optional | Optional MIME type of the file data. Currently ClickHouse ignores this HTTP subheader. | | `context` | boolean | Optional | A reusable QueryContext object can be used to encapsulate the above method arguments. | ### Input Example `{"query":"None","parameters":{},"settings":{},"query_formats":{},"column_formats":{},"encoding":"None","use_none":true,"column_oriented":true,"query_tz":"None","column_tzs":{},"use_extended_dtypes":true,"external_data":{"file_path":"string","file_name":"Example Name","data":"string","fmt":"string","types":["string"],"structure":["string"],"mime_type":"string"},"context":true}` ### Output | **Parameter** | **Type** | **Description** | | ---------------------------- | -------- | ------------------------------------------- | | `query_id` | string | Unique identifier | | `json_result` | array | Result of the operation | | `json_result.a` | string | Result of the operation | | `column_names` | array | Name of the resource | | `summary` | object | Output field: summary | | `summary.read_rows` | string | Output field: summary.read\_rows | | `summary.read_bytes` | string | Output field: summary.read\_bytes | | `summary.written_rows` | string | Output field: summary.written\_rows | | `summary.written_bytes` | string | Output field: summary.written\_bytes | | `summary.total_rows_to_read` | string | Output field: summary.total\_rows\_to\_read | | `summary.result_rows` | string | Result of the operation | | `summary.result_bytes` | string | Result of the operation | | `summary.elapsed_ns` | string | Output field: summary.elapsed\_ns | | `summary.query_id` | string | Unique identifier | | `first_item` | object | Output field: first\_item | | `first_item.a` | string | Output field: first\_item.a | | `first_row` | array | Output field: first\_row | ### Output Example `{"query_id":"02d6023d-526e-4fc8-8acd-ede4c3ab5d81","json_result":[{"a":"12345"}],"column_names":["a"],"summary":{"read_rows":"1","read_bytes":"14","written_rows":"0","written_bytes":"0","total_rows_to_read":"1","result_rows":"1","result_bytes":"269","elapsed_ns":"2071501","query_id":"02d6023d-526e-4fc8-8acd-ede4c3ab5d81"},"first_item":{"a":"12345"},"first_row":["12345"]}` # Response Headers | **Header** | **Description** | **Example** | | ------------ | ----------------------------------------------------- | ----------------------------- | | Content-Type | The media type of the resource | application/json | | Date | The date and time at which the message was originated | Thu, 01 Jan 2024 00:00:00 GMT |