一、问题背景：为什么集成时会踩坑？

很多做数据可视化的朋友，大概率都用过ClickHouse和Superset这对组合——ClickHouse存海量数据快，Superset做报表灵活，俩搭一起本来是“强强联合”，但实际用的时候经常碰到俩糟心问题：要么查个稍微大点的表直接超时，要么明明ClickHouse里存的是日期、小数，Superset里识别成字符串或者乱码，报表根本做不出来。

之前很多人解决这俩问题，要么改ClickHouse的超时配置，要么在Superset里手动转数据类型，不仅麻烦还容易出问题。其实有个更省心的办法：用ClickHouse的原生协议来连Superset，从根上解决这俩坑。

二、核心原理：原生协议为啥能解决问题？

先得搞懂“原生协议”到底是什么。简单说，ClickHouse有两种对外提供服务的方式：一种是HTTP协议（就是普通网页用的那种），另一种是自己专属的原生TCP协议。

之前大家用的基本都是HTTP协议连，HTTP是通用协议，为了兼容各种场景，加了很多额外的处理步骤，比如数据要转成JSON格式传，中间还要经过多层编码解码，不仅慢，还容易因为格式转换出数据类型不匹配的问题。

而原生TCP协议是ClickHouse专门给自己用的，就像自家的钥匙开自家的锁，完全适配ClickHouse的内部逻辑：传数据的时候不用转成通用格式，直接用ClickHouse内部的二进制格式传，速度快很多，而且能完整保留ClickHouse里的所有数据类型，不会出现识别错的情况。

三、前置准备：需要做哪些准备工作？

在开始配置之前，得先确保几个基础条件满足，不然配置到一半会卡壳。

3.1 确认ClickHouse的原生协议端口

ClickHouse的原生协议默认端口是9000，HTTP是8123，别搞混了。先检查ClickHouse有没有开这个端口，用下面的命令测试能不能通：

# 测试ClickHouse原生端口连通性
telnet 你的ClickHouse服务器IP 9000

如果能连上，就说明端口没问题；如果连不上，要去ClickHouse的配置文件里改，配置文件一般在/etc/clickhouse-server/config.xml，找到<listen_host>标签，改成0.0.0.0（允许所有IP连），然后重启ClickHouse服务。

3.2 确认Superset的版本

原生协议的支持需要Superset 2.0及以上版本，太低的版本没有对应的驱动。可以在Superset的控制台里看版本，或者用命令行查：

# 进入Superset的Python环境（假设用的是虚拟环境）
source superset-venv/bin/activate
# 查看Superset版本
pip show apache-superset

如果版本不够，先升级到最新的稳定版。

四、具体配置：一步步来怎么弄？

接下来是核心的配置步骤，分两部分：先装驱动，再在Superset里新建数据库连接。

4.1 安装ClickHouse原生协议驱动

Superset要识别原生协议，得装专门的驱动，这个驱动叫clickhouse-connect，是官方维护的，比旧的驱动更稳定。安装命令很简单：

# 进入Superset的Python环境（如果是虚拟环境的话）
source superset-venv/bin/activate
# 安装原生协议驱动
pip install clickhouse-connect

安装完之后，要确认驱动有没有装成功，在Python里导入测试一下：

# 测试驱动安装成功
from clickhouse_connect import get_client
# 测试连接（把下面的参数换成自己的）
client = get_client(
    host='你的ClickHouse服务器IP',
    port=9000,  # 原生协议端口，不是8123
    username='ClickHouse用户名',
    password='ClickHouse密码',
    database='默认数据库名'
)
# 执行一个简单的查询测试
result = client.query('SELECT 1 AS test').result_rows
print(result)  # 如果输出[[1]]，说明连接成功

这个测试很重要，如果这里连不上，后面在Superset里肯定也连不上。

4.2 在Superset里新建原生协议的数据库连接

打开Superset的控制台，进入“数据”→“数据库”→“添加数据库”，然后按下面的步骤配置：

  1. 数据库类型选“ClickHouse”（注意不是其他带HTTP的类型）
  2. 数据库名称随便填，比如“ClickHouse-原生”
  3. 连接字符串（SQLAlchemy URI）的格式是：
clickhouse+native://用户名:密码@服务器IP:9000/数据库名

举个具体的例子：

clickhouse+native://admin:123456@192.168.1.100:9000/bi_db

这里的“native”就是指定用原生协议，端口是9000，别写错成8123。 4. 然后点击“测试连接”，如果显示“连接成功”，就可以保存了。

五、效果验证：怎么确认问题解决了？

配置完之后，要验证之前的两个问题是不是真的解决了。

5.1 验证查询超时问题

找一个之前会超时的大表，比如有1亿条数据的订单表，在Superset里做一个查询，比如统计每个月的订单金额，看会不会超时。

原生协议的速度比HTTP快很多，比如之前HTTP协议查这个表要30秒以上甚至超时，现在原生协议可能10秒以内就能出结果。原因是原生协议传数据的时候不用转JSON，直接传二进制，减少了很多不必要的开销。

5.2 验证数据类型不匹配问题

找一个有特殊数据类型的表，比如ClickHouse里存的是Date（日期类型）、Float64（小数类型）、Decimal（精确小数类型）的字段，在Superset里做报表的时候，看这些字段会不会被识别成字符串。

比如之前用HTTP协议的时候，ClickHouse里的Date字段可能被识别成字符串，要手动转成日期才能做时间维度的报表；现在用原生协议，Superset会直接识别成日期类型，不用手动转换。再比如ClickHouse里的Decimal字段（比如金额存成Decimal(10,2)），之前HTTP协议可能会识别成Float，导致计算金额的时候有精度误差，现在原生协议会保留精确的小数类型，计算结果准确。

六、实际案例：一个完整的场景演示

下面用一个实际的业务场景来演示，比如电商的订单分析报表。

6.1 业务场景说明

电商公司要做一个每日订单统计报表，需要统计每天的订单数、订单总金额、平均订单金额，数据存在ClickHouse的order表中，表结构如下：

  • order_date：Date类型（订单日期）
  • order_id：String类型（订单ID）
  • amount：Decimal(10,2)类型（订单金额）
  • user_id：String类型（用户ID）

之前用HTTP协议连的时候，经常出现两个问题：

  1. 统计最近30天的订单数据，因为数据量有1000万条，经常超时；
  2. order_date字段被识别成字符串，做时间筛选的时候要手动转成日期，amount字段被识别成Float，统计总金额的时候有误差。

6.2 用原生协议解决后的效果

配置完原生协议的连接之后，再做同样的报表：

  1. 统计最近30天的订单数据，查询时间从之前的40秒超时，变成现在的8秒出结果；
  2. order_date字段直接被识别成日期类型，不用手动转换，amount字段被识别成Decimal类型，统计总金额的时候没有误差。

6.3 具体的配置代码示例

这里再补充一个更复杂的连接配置，比如如果ClickHouse有SSL加密的话，原生协议也支持，配置示例如下：

clickhouse+native://admin:123456@192.168.1.100:9000/bi_db?secure=true&verify=false

如果需要指定额外的参数，比如连接超时时间，可以加在连接字符串后面：

clickhouse+native://admin:123456@192.168.1.100:9000/bi_db?connect_timeout=30000

七、相关技术补充：clickhouse-connect驱动的其他特性

除了解决超时和数据类型问题，clickhouse-connect驱动还有一些其他有用的特性，比如支持批量插入、支持异步查询、支持自定义压缩算法等。

比如批量插入的示例，适合往ClickHouse里导大量数据：

# 批量插入示例
from clickhouse_connect import get_client

client = get_client(
    host='192.168.1.100',
    port=9000,
    username='admin',
    password='123456',
    database='bi_db'
)

# 准备批量插入的数据，每行是一个订单
data = [
    ['2024-01-01', 'ORD001', 100.50, 'U001'],
    ['2024-01-01', 'ORD002', 200.75, 'U002'],
    ['2024-01-02', 'ORD003', 150.25, 'U001']
]

# 批量插入到order表，指定列名
client.insert(
    table='order',
    data=data,
    column_names=['order_date', 'order_id', 'amount', 'user_id']
)

print('批量插入成功')

这个批量插入的速度比用HTTP协议快很多，适合大数据量的导入。

八、应用场景、优缺点和注意事项

8.1 应用场景

原生协议的方案适合所有需要用Superset对接ClickHouse做数据可视化的场景，尤其是以下几种：

  1. 数据量很大的场景，比如每天有几百万甚至几千万条数据，查询经常超时；
  2. 对数据精度要求高的场景，比如金融、电商的金额统计，不能有精度误差；
  3. 数据类型复杂的场景，比如有日期、时间、Decimal、数组等特殊类型，经常出现识别错误；
  4. 报表需要实时更新的场景，原生协议的查询速度快，能支持更频繁的更新。

8.2 技术优缺点

优点：

  1. 解决查询超时：原生协议的速度比HTTP协议快2-5倍，数据量越大差距越明显；
  2. 解决数据类型不匹配：完整保留ClickHouse的所有数据类型，不用手动转换；
  3. 配置简单：只要改一下连接字符串，不用改其他配置；
  4. 性能稳定：官方维护的驱动，兼容性好，不容易出问题；
  5. 额外特性多：支持批量插入、异步查询等，适合复杂场景。

缺点：

  1. 版本要求高：需要Superset 2.0及以上版本，旧版本不支持；
  2. 端口限制：需要开放9000端口，对网络安全有一定要求；
  3. 调试麻烦：原生协议的错误信息比HTTP协议少，出问题的时候不好排查。

8.3 注意事项

  1. 端口安全：9000端口是ClickHouse的原生端口，不要随便开放给公网，最好用防火墙限制只有Superset的服务器能访问；
  2. 驱动版本：要安装最新的clickhouse-connect驱动，旧版本可能有bug；
  3. 连接字符串：一定要注意端口是9000，协议是native，别写错；
  4. 测试连接：每次改配置之后都要测试连接，确保没问题；
  5. 性能监控：虽然原生协议速度快，但如果查询逻辑太复杂，还是可能超时，要注意优化查询逻辑。

九、总结

用ClickHouse的原生协议来连接Superset，是解决查询超时和数据类型不匹配问题的最优方案，不仅配置简单，效果也很明显。只要按照上面的步骤来，就能轻松解决这两个让很多人头疼的问题。

其实很多技术问题，不是没有解决方案，而是我们对技术本身的了解不够，没有找到最适合的方法。原生协议就是ClickHouse和Superset这对组合的“最佳搭档”，用对了就能发挥出两者的最大优势。