• English

      • ClickHouse

      Data source: External ClickHouseEnterprise Edition+

      Introduction

      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.

      SettingDescription
      Supported versionClickHouse >= 20.2.
      Commercial editionsAvailable in the Enterprise edition.
      Plugin@nocobase/plugin-data-source-external-clickhouse.
      Connection methodConnect through the ClickHouse MySQL-compatible port.
      Recommended usePrimarily for viewing, filtering, aggregation, and reporting.

      External ClickHouse is suitable when you need to:

      • Connect analytical data such as logs, event tracking data, metrics, or risk-control data
      • Build operational dashboards, reports, or query pages in NocoBase
      • Provide business users with a read-only query entry point instead of direct database-client access
      • Apply permissions and visual presentation to existing ClickHouse data
      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.

      Plugin installation

      This is a commercial plugin. For activation instructions, see the Commercial plugin activation guide.

      Add a data source

      In Data source management, click Add new, select ClickHouse, and then enter the connection details.

      Add an external ClickHouse data source

      Common connection settings are as follows:

      SettingDescription
      Data source nameThe internal identifier used by blocks, permissions, workflows, and APIs. It cannot be changed after the data source is created.
      Data source display nameThe name displayed in the interface. Use a name that business users can recognize, such as ClickHouse log database or Metrics database.
      Host / PortThe ClickHouse host address and MySQL-compatible port. Do not enter the HTTP port or native TCP port.
      DatabaseThe name of the ClickHouse database to connect to.
      Username / PasswordThe 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 prefixA table-name prefix. When configured, NocoBase reads only tables that match the prefix, and removes the prefix from the generated NocoBase collection names.
      Use SSLWhether to enable SSL. This is usually required when connecting to ClickHouse Cloud or a secure connection environment.
      Enabled the data sourceWhether to enable the data source. When disabled, its configuration is retained, but blocks, permissions, workflows, and APIs can no longer read its data.
      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.

      Connection scope

      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.

      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.

      Synchronize and configure fields

      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.

      Field type mapping

      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 typeNocoBase Field typeAvailable Field interfaces
      Int8, Int16, Int32, UInt8, UInt16, UInt32integer, unixTimestamp, sortInteger, Sort, Unix timestamp, Select, Radio group.
      Int64, UInt64bigInt, unixTimestamp, sortInteger, Sort, Unix timestamp, Created at, Updated at.
      Float32, Float64floatNumber, Percent.
      Decimaldecimal, doubleNumber, Percent, Currency.
      String, FixedStringtext, stringInput, Textarea, Markdown, URL.
      Date, Date32dateOnlyDate.
      DateTime, DateTime64datetimeNoTz, datetimeTz, dateDate, Time, Created at, Updated at.
      UUIDstring, uuidInput, UUID.
      Bool, Booleaninteger, boolean, sortCheckbox, Switch, Integer.
      Arrayjson, arrayJSON.
      Nullable(...)Mapped according to the inner field typeDepends on the inner field type.
      LowCardinality(...)Mapped according to the inner field typeDepends on the inner field type.
      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.

      Primary key and Record unique key

      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.

      Primary key and Record unique key Configure Record unique key