常见问题

云数据库ClickHouse主要对社区版本进行稳定性Bug修复，同时提供资源队列进行用户角色级别的资源使用优先级配置。

您可以采取如下解决方案。

• 检查网络是否畅通。通过ping命令检查网络是否通畅，通过telnet命令探测数据库3306和8123端口是否开放。

• 检查是否配置了ClickHouse白名单，配置方法请参见 设置白名单。

• 检查客户端机器IP是否正确。通常公司办公网内的机器IP经常变动，用户看到的不是正确的IP地址。通过访问专业IP探查服务确定真实IP，示例请参见whatsmyip。

目前20.3和20.8版本在创建相关外表时程序内会自动进行验证，如果创建表成功，那说明网络是通的。如果无法创建成功，常见原因如下。

• 目标端和ClickHouse不在同一个VPC内，网络无法连通。

• MySQL端存在白名单相关设置，需要在MySQL端添加ClickHouse的白名单。

常见原因及解决方案如下。

• 常见原因1：VPC网络、公网网络环境不对。同一VPC内可用内网连接，不在同一VPC内需开设公网后连接。

  解决方案：开通公网详情请参见申请和释放外网地址。

• 常见原因2：白名单未配置。

  解决方案：设置白名单详情请参见设置白名单。

• 常见原因3：ECS安全组未放开。

  解决方案：开放安全组详情请参见安全组操作指引。

• 常见原因4：公司设置了网络防火墙。

  解决方案：修改防火墙规则。

• 常见原因5：连接串中的账号密码包含特殊字符!@#$%^&*()_+=，这些特殊字符在连接时无法被识别，导致实例连接失败。

  解决办法：您需要在连接串中对特殊字符进行转义处理，转义规则如下。

  ! : %21
  @ : %40
  # : %23
  $ : %24
  % : %25
  ^ : %5e
  & : %26
  * : %2a
  ( : %28
  ) : %29
  _ : %5f
  + : %2b
  = : %3d

  示例：密码为ab@#c时，在连接串中对特殊字符进行转义处理，密码对应为ab%40%23c。

• 常见原因6：云数据库ClickHouse会默认为您挂载CLB。CLB为按量付费，如果您的账号欠费可能会导致您的云数据库ClickHouse无法访问。

  解决办法：查询阿里云账号是否欠费。如果欠费请及时进行缴费，阿里云账户查询详情请参见资金账户查询入口。

您可以采取如下解决方案。

• 把OSS上的文件拆分为一个一个的小文件，然后再进行导入。

• 进行内存的升配。如何升配，请参见社区兼容版集群垂直变配和水平扩缩容。

常见原因及解决方案如下。

• 常见原因1：参数设置不合理。ClickHouse适合使用大batch、少数几个并发进行写入。多数情况下batch可以高达几万甚至几十万（取决于您的单行RowSize大小，一般按照每行100Byte进行评估，您需要根据实际数据特征进行估算）。

  解决方案：并发数建议不超过10个。您可以调整不同参数进行尝试。

• 常见原因2：DataWorks独享资源组的ECS规格太小。比如独享资源的CPU、Memory太小，导致并发数、网络出口带宽受限；或者是batch设置太大而Memory太小，引起DataWorks进程Java GC等。

  解决方案：您可以通过DataWorks的输出日志对ECS规格大小进行确认。

• 常见原因3：从数据源中读取慢。

  解决方案：您可以在DataWorks输出日志中搜索totalWaitReaderTime、totalWaitWriterTime，如果发现totalWaitReaderTime明显大于totalWaitWriterTime，则表明主要耗时在读取端，而不是写入端。

• 常见原因4：使用了公网Endpoint。公网Endpoint的带宽非常有限，无法承载高性能的数据导入导出。

  解决方案：您需要替换为VPC网络的Endpoint。

• 常见原因5：有脏数据。在没有脏数据的情况下，数据以batch方式写入。但是遇到了脏数据，正在写入的batch就会失败，并回退到逐行写入，生成大量的data part，大幅度降低了写入速度。

  您可以参考如下两种方式判断是否有脏数据。

  • 查看报错信息，如果返回信息包含Cannot parse，则存在脏数据。

    代码如下。

    SELECT written_rows, written_bytes, query_duration_ms, event_time, exception
    FROM system.query_log
    WHERE event_time BETWEEN '2021-11-22 22:00:00' AND '2021-11-22 23:00:00' AND lowerUTF8(query) LIKE '%insert into <table_name>%' and type != 'QueryStart' and exception_code != 0
    ORDER BY event_time DESC LIMIT 30;

  • 查看batch行数，如果batch行数变为1，则存在脏数据。

    代码如下。

    SELECT written_rows, written_bytes, query_duration_ms, event_time
    FROM system.query_log
    WHERE event_time BETWEEN '2021-11-22 22:00:00' AND '2021-11-22 23:00:00' AND lowerUTF8(query) LIKE '%insert into <table_name>%' and type != 'QueryStart'
    ORDER BY event_time DESC LIMIT 30;

  解决方案：您需要在数据源删除或修改脏数据。

您可以通过以下手段进行排查。

1. 首先通过系统表query_log来查看导入的过程中是否有报错，如果有报错，那很有可能出现数据丢失的情况。

2. 确定使用的表引擎是否可以去重，比如使用ReplacingMergeTree，那很可能出现ClickHouse中的Count小于Hive中的情况。

3. 重新确认Hive中数据行数的正确性，很有可能出现源头的行数确定错误的情况。

您可以通过以下手段进行排查。

1. 首先通过系统表query_log来查看导入的过程中是否有报错，如果有报错，那很有可能出现数据丢失的情况。

2. 确定使用的表引擎是否可以去重，比如使用ReplacingMergeTree，那很可能出现ClickHouse中的Count小于Kafka中的情况。

3. 查看Kafka外表的配置是否有kafka_skip_broken_messages参数的配置，如果有该参数，那可能会跳过解析失败的Kafka消息，导致ClickHouse总的行数是小于Kafka中的。

您可以采取如下方案。

• 通过ClickHouse Client以导出文件的形式进行数据迁移，详情请参见将自建ClickHouse数据迁移到云ClickHouse中。

• 通过Remote函数进行数据的迁移。

  INSERT INTO <目的表> SELECT * FROM remote('<连接串>', '<库>', '<表>', '<username>', '<password>');

解决方案：重新同步MySQL数据，具体步骤如下。

1. 删除停止同步的表。

   DROP TABLE <table_name> ON cluster default;

   说明

   table_name为停止同步的表名。如果停止同步的表有分布式表，那么本地表和分布式表都需要删除。

2. 重启同步进程。

   ALTER database <database_name> ON cluster default MODIFY SETTING skip_unsupported_tables = 1;

   说明

   <database_name>为云数据库ClickHouse中同步的数据库。

常见原因及解决方案如下。

• 常见原因1：内存使用率比较高。

  解决方案：调整参数max_insert_threads，减少可能的内存使用量。

• 常见原因2：当前是通过insert into select把数据从一个ClickHouse集群导入到另外一个集群。

  解决方案：通过导入文件的方式来迁移数据，更多信息请参见将自建ClickHouse数据迁移到云ClickHouse中。

ClickHouse服务端对所有查询线程都配有memory tracker，同一个查询下的所有线程tracker会汇报给一个memory tracker for query，再上层还是memory tracker for total。您可以根据情况采取如下解决方案。

• 遇到Memory limit (for query)超限报错说明是查询内存占用过多（实例总内存的70%）导致失败，这种情况下您需要垂直升配提高实例内存规模。

• 遇到Memory limit (for total)超限报错说明是实例总内存使用超限（实例总内存的90%），这种情况下您可以尝试降低查询并发，如果仍然不行则可能是后台异步任务占用了比较大的内存（常常是写入后主键合并任务），您需要垂直升配提高实例内存规模。

默认Server查询最大并发数为100，您可以在控制台上进行修改。修改运行参数值具体操作步骤如下。

1. 登录云数据库ClickHouse控制台。

2. 在集群列表页面，选择社区版实例列表，单击目标集群ID。

3. 单击左侧导航栏的参数配置。

4. 在参数配置页面，单击max_concurrent_queries参数的运行参数值后面的编辑按钮。

5. 在悬浮框中填写目标值，单击确定。

6. 单击提交参数。

7. 单击确定。

您可以采取如下解决方案。

• 检查是否是多节点集群。多节点集群需要创建分布式表，往分布式表里写入数据并查询，每次查询结果一致。否则每次查询到不同分片的数据，结果不一致。如何创建分布式表请参见创建分布式表。

• 检查是否是多副本集群。多副本集群需要建Replicated系列表引擎的表，才能实现副本间数据同步。否则每次查到不同副本，结果不一致。如何创建Replicated系列表引擎的表请参见表引擎。

常见原因及解决方案如下。

• 常见原因1：建表流程存在问题。ClickHouse的分布式集群搭建并没有原生的分布式DDL语义。如果您在自建ClickHouse集群时使用create table创建表，查询虽然返回了成功，但实际这个表只在当前连接的Server上创建了。下次连接重置换一个Server，您就看不到这个表了。

  解决方案：

  1. 建表时，请使用create table <table_name> on cluster default语句，on cluster default声明会把这条语句广播给default集群的所有节点进行执行。示例代码如下。

     CREATE TABLE test ON cluster default (a UInt64) Engine = MergeTree() ORDER BY tuple();

  2. 在test表上再创建一个分布式表引擎，建表语句如下。

     CREATE TABLE test_dis ON cluster default AS test Engine = Distributed(default, default, test, cityHash64(a));

• 常见原因2：ReplicatedMergeTree存储表配置有问题。ReplicatedMergeTree表引擎是对应MergeTree表引擎的主备同步增强版，在单副本实例上限定只能创建MergeTree表引擎，在双副本实例上只能创建ReplicatedMergeTree表引擎。

  解决方案：在双副本实例上建表时，请使用ReplicatedMergeTree('/clickhouse/tables/{database}/{table}/{shard}', '{replica}')或ReplicatedMergeTree()配置ReplicatedMergeTree表引擎。其中，ReplicatedMergeTree('/clickhouse/tables/{database}/{table}/{shard}', '{replica}')为固定配置，无需修改。

首先为了让数据有正确的主键合并逻辑，需要保证以下两个前提条件。

• 存储表里的partition by定义字段必须是包含在order by里的，不同分区的数据不会主键合并。

• 分布式表里定义的Hash算法字段必须是包含在order by里的，不同节点的数据不会主键合并。

optimize常用命令及相关说明如下。

常见原因及解决方案如下。

• 常见原因1：数据的TTL淘汰是在主键合并阶段执行的，如果data part迟迟没有进行主键合并，那过期的数据就无法淘汰。

  解决方案：

  • 您可以通过手动optimize final或者optimize 指定分区的方式触发合并任务。

  • 您可以在建表时设置merge_with_ttl_timeout、ttl_only_drop_parts等参数，提高含有过期数据data parts的合并频率。

• 常见原因2：表的TTL经过修改或者添加，存量的data part里缺少TTL信息或者不正确，这样也可能导致过期数据淘汰不掉。

  解决方案：

  • 您可以通过alter table materialize ttl命令重新生成TTL信息。

  • 您可以通过optimize 分区更新TTL信息。

本地表的修改直接执行即可。如果要对分布式表进行修改，需分如下情况进行。

• 如果没有数据写入，您可以先修改本地表，然后修改分布式表。

• 如果数据正在写入，您需要区分不同的类型进行操作。

  类型	操作步骤

  类型	操作步骤
  增加Nullable的列	修改本地表。 修改分布式表。
  修改列的数据类型（类型可以相互转换）
  删除Nullable列	修改分布式表。 修改本地表。
  增加非Nullable的列	停止数据的写入。 执行SYSTEM FLUSH DISTRIBUTED分布式表。 修改本地表。 修改分布式表。 重新进行数据的写入。
  删除非Nullable的列
  修改列的名称

您可以采取如下解决方案。

• 等待运行结束。

• 在控制台尝试终止查询。

常见原因及解决方案如下。

• 常见原因1：ClickHouse客户端会进行语法解析，而set global on cluster default是服务端增加的语法。在客户端尚未更新到与服务端对齐的版本时，该语法会被客户端拦截。

  解决方案：

  • 使用JDBC Driver等不会在客户端解析语法的工具，比如DataGrip、DBeaver。

  • 编写JDBC程序来执行该语句。

• 常见原因2：set global on cluster default key = value; 中value是字符串，但是漏写了引号。

  解决方案：在字符串类型的value两侧加上引号。

您可以通过如下代码查看每张表所占的磁盘空间。

SELECT table, formatReadableSize(sum(bytes)) as size, min(min_date) as min_date, max(max_date) as max_date FROM system.parts WHERE active GROUP BY table; 

示例代码如下。

SELECT * FROM system.disks;

示例代码如下。

SELECT * FROM system.parts WHERE disk_name = 'cold_disk';

示例代码如下。

ALTER TABLE table_name MOVE PARTITION partition_expr TO DISK 'cold_disk';

常见原因如下。

• 查询触发OOM。

• 修改配置触发重启。

• 升降配后的实例重启。

常用系统表及作用如下。

用户级别的参数对应users.xml内的部分配置项，你需要执行如下示例语句。

SET global ON cluster default ${key}=${value};

您可以在执行语句的settings里增加，示例代码如下。

settings max_memory_usage = XXX;

如果您的集群是双副本，或单副本多节点的集群，在进行较多写入操作时，写入节点的CPU和内存使用率将高于其他节点。待数据同步至其他节点后，CPU和内存使用率将趋于基本平衡。

• 问题描述：

  如何查看系统的详细日志信息，以便排查错误或发现潜在问题。

• 解决方案：

  1. 查看集群text_log.level参数，进行以下操作：

     1. text_log.level为空，表示您未开启text_log，您需设置text_log.level以开启text_log。

     2. text_log.level不为空，查看text_log等级是否满足目前需求，如不满足，您需修改此参数，设置text_log等级。

     如何查看和修改text_log.level参数，请参见配置config.xml参数。

  2. 登录目标数据库。如何登录，请参见连接数据库。

  3. 执行以下语句，查看分析。

     SELECT * FROM system.text_log;

如果目标集群与数据源使用相同的VPC并位于同一地域。您需检查二者是否将IP地址添加到了对方的白名单中。如果没有，请添加白名单。

• ClickHouse中如何添加白名单，请参见设置白名单。

• 其他数据源如何添加白名单，请参见自身产品文档。

如果目标集群与数据源不属于上述情况，选择合适的网络解决方案，解决网络问题后再将彼此IP地址添加到对方的白名单中。

ClickHouse社区版集群支持迁移至企业版集群。

企业版集群与社区版集群相互迁移数据的主要方式有两种，通过remote函数和通过文件导出导入方式。具体操作，请参见将自建ClickHouse数据迁移到云ClickHouse中。

新建的企业版24.5及以后的版本实例，其查询引擎默认使用新analyzer。新analyzer具有更好的查询性能，但可能与部分旧版SQL不兼容，从而导致解析错误。如遇该错误，您可执行以下语句，将新analyzer回退至旧analyzer。更多新analyzer详情，请参见进一步了解全新analyzer。

SET allow_experimental_analyzer = 0;

ClickHouse社区版集群暂不支持暂停功能，企业版集群支持此功能。如果您需要暂停企业版集群，您可前往企业版集群列表，在集群列表页面左上角，选中目标地域，在集群列表找到目标集群，单击目标集群操作列的>暂停。