docs/docs/en/data-sources/external/clickhouse.md
ClickHouse can be connected to NocoBase as an external database. NocoBase reads tables, fields, and views from ClickHouse and makes them available as collections in the external data source.
ClickHouse is better suited to analytical queries, log analysis, metric aggregation, and reporting. Unlike transactional databases, it is not suitable as a data source for frequently creating, editing, and deleting business records in NocoBase.
| Setting | Description |
|---|---|
| Supported version | ClickHouse >= 20.2. |
| Commercial editions | Available in the Enterprise edition. |
| Plugin | @nocobase/plugin-data-source-external-clickhouse. |
| Connection method | Connect through the ClickHouse MySQL-compatible port. |
| Recommended use | Primarily for viewing, filtering, aggregation, and reporting. |
External ClickHouse is suitable when you need to:
:::warning Note
Use ClickHouse in NocoBase as a read-only analytical data source. Do not use it as the write data source for regular business collections, and do not configure create, edit, or delete actions in pages.
:::
This is a commercial plugin. For activation instructions, see the Commercial plugin activation guide.
In Data source management, click Add new, select ClickHouse, and then enter the connection details.
Common connection settings are as follows:
| Setting | Description |
|---|---|
| Data source name | The internal identifier used by blocks, permissions, workflows, and APIs. It cannot be changed after the data source is created. |
| Data source display name | The name displayed in the interface. Use a name that business users can recognize, such as ClickHouse log database or Metrics database. |
| Host / Port | The ClickHouse host address and MySQL-compatible port. Do not enter the HTTP port or native TCP port. |
| Database | The name of the ClickHouse database to connect to. |
| Username / Password | The account credentials used to connect to ClickHouse. NocoBase can read only objects that this account is allowed to access; it does not grant access to, or read, objects private to other accounts. |
| Table prefix | A table-name prefix. When configured, NocoBase reads only tables that match the prefix, and removes the prefix from the generated NocoBase collection names. |
| Use SSL | Whether to enable SSL. This is usually required when connecting to ClickHouse Cloud or a secure connection environment. |
| Enabled the data source | Whether to enable the data source. When disabled, its configuration is retained, but blocks, permissions, workflows, and APIs can no longer read its data. |
:::tip Tip
The ClickHouse plugin connects through the MySQL-compatible protocol. Before configuring the source, make sure the ClickHouse service has enabled its MySQL-compatible port and that the network, firewall, and account permissions allow NocoBase to connect.
:::
ClickHouse pages do not provide a Collections selection list. The connection scope is primarily controlled by Database, connection-account permissions, and Table prefix.
When ClickHouse contains many tables, prepare a dedicated database, account, or table-name prefix for NocoBase. Expose only the tables that the current application needs to view and aggregate.
:::warning Note
An external data source can connect up to 500 tables or views at a time. When ClickHouse contains many objects, narrow the scope through the database, account permissions, or Table prefix first.
:::
The external ClickHouse schema is maintained in the database. NocoBase does not create fields, change field types, or delete actual fields in the external database.
When the ClickHouse schema changes, run Sync from database from the data source to read collection and field metadata again. Synchronization updates the collections, fields, primary keys, unique keys, and field-type mapping metadata stored in NocoBase. It does not delete actual ClickHouse tables or data.
After fields are synchronized, you can configure their titles, Field type, and Field interface in NocoBase. NocoBase relationship fields are also stored as relationship metadata in NocoBase and do not automatically add actual foreign-key columns to ClickHouse tables.
NocoBase converts ClickHouse types into a MySQL-compatible representation before mapping them to appropriate Field types and Field interfaces. You can adjust the display interface in field settings.
| ClickHouse type | NocoBase Field type | Available Field interfaces |
|---|---|---|
Int8, Int16, Int32, UInt8, UInt16, UInt32 | integer, unixTimestamp, sort | Integer, Sort, Unix timestamp, Select, Radio group. |
Int64, UInt64 | bigInt, unixTimestamp, sort | Integer, Sort, Unix timestamp, Created at, Updated at. |
Float32, Float64 | float | Number, Percent. |
Decimal | decimal, double | Number, Percent, Currency. |
String, FixedString | text, string | Input, Textarea, Markdown, URL. |
Date, Date32 | dateOnly | Date. |
DateTime, DateTime64 | datetimeNoTz, datetimeTz, date | Date, Time, Created at, Updated at. |
UUID | string, uuid | Input, UUID. |
Bool, Boolean | integer, boolean, sort | Checkbox, Switch, Integer. |
Array | json, array | JSON. |
Nullable(...) | Mapped according to the inner field type | Depends on the inner field type. |
LowCardinality(...) | Mapped according to the inner field type | Depends on the inner field type. |
:::warning Note
Some analytical or nested ClickHouse types cannot be mapped directly to regular business fields. For unsupported types, create a view or query table suitable for display in ClickHouse first, and then connect it to NocoBase.
:::
ClickHouse sorting keys and partition keys are not necessarily business-unique identifiers. Collections used for block display should still have a field that can uniquely identify each record.
For tables or views without a unique field, configure Record unique key manually in the collection settings. Without a usable unique identifier, blocks might not display record details correctly and are not suitable for edit or delete actions.