ClickHouse 事件表怎么设计：埋点写入、去重与查询的工程取舍

做埋点系统时，第一版事件表往往很简单：事件名、用户标识、发生时间，再加一列属性 JSON。这个结构足以跑通演示，但一旦开始接收真实流量，问题会很快出现：客户端重试是否造成重复事件？属性类型变化后如何查询？迟到数据按哪个时间统计？为了去重而引入复杂表引擎，是否反而让结果难以解释？

本文不提供一个“适用于所有团队”的建表模板，而是记录 SensorFlow 在 Go 接收服务、ClickHouse 与 Apache Superset 这条链路里，如何拆解这些取舍。

先区分三个时间

事件分析至少会遇到三个时间概念：

1. 事件时间：业务行为真正发生的时间，通常来自 SDK 上报；
2. 接收时间：服务端收到请求的时间；
3. 入库时间：数据成功写入 ClickHouse 的时间。

正常网络下三者相差不大，但移动端离线缓存、批量上报、队列积压和重试都会拉开差距。报表按事件时间统计更接近业务事实；监控接收延迟和写入延迟，则需要另外两个时间。

因此，不建议只保留一个 timestamp。至少应明确保存事件时间与接收时间，并把时区约定写进协议和数据字典。否则“昨天的新增用户为什么今天才出现”很难排查。

一行事件需要哪些稳定字段

在属性之外，事件表应保留一组不随业务变化的基础列。例如：

CREATE TABLE events
(
    project_id       String,
    event_name       LowCardinality(String),
    distinct_id      String,
    event_time       DateTime64(3, 'UTC'),
    received_at      DateTime64(3, 'UTC'),
    event_id         String,
    source_platform  LowCardinality(String),
    properties       String
)
ENGINE = MergeTree
PARTITION BY toYYYYMM(event_time)
ORDER BY (project_id, event_name, toDate(event_time), distinct_id, event_time);

这只是便于讨论的简化示例，不是生产环境可以直接复制的最终结构。真实方案还要根据查询模式、数据量、保留周期和 ClickHouse 版本决定分区、排序键、TTL、压缩编码与副本策略。

排序键尤其需要从常见查询反推。若查询大多限定项目、事件名与日期，把这些高频过滤条件放在排序键前部通常更有意义。不要因为 distinct_id 看起来重要，就默认把它放在第一列；那可能使大量按事件名和日期的扫描无法充分利用数据跳过。

属性应该全部放 JSON 吗

把属性整体保存为 JSON 或字符串，优点是接入快、结构变化容易容纳，也便于保存原始上报内容。缺点是高频查询属性需要反复解析，类型不一致时容易出现隐式转换和空值语义问题。

另一种极端是把每个属性都变成独立列。这样查询清晰，但埋点属性会持续变化，频繁加列、类型冲突和大量稀疏列都会增加治理成本。

更实际的做法通常是分层：

• 事件名、身份、时间、平台等稳定字段使用独立强类型列；
• 高频过滤或聚合的公共属性逐步提升为显式列；
• 长尾属性保留在原始属性列中；
• 建立属性字典，记录首次出现时间、推断类型和冲突情况。

重点不是选 JSON 还是宽表，而是让“原始数据可追溯”与“常用查询可预测”同时成立。

去重之前先定义重复

网络请求重试并不等于业务事件重复。用户连续点击两次按钮，可能是两个真实事件；同一个上报批次因超时重发，才是传输层重复。如果没有稳定事件标识，仅凭事件名、用户和时间拼接哈希，可能把真实的连续操作误删。

更可靠的顺序是：

1. 优先使用客户端或接收协议提供的稳定事件 ID；
2. 若协议没有事件 ID，明确记录生成规则及其误判边界；
3. 把请求 ID、批次 ID 与事件 ID 分开，不要混为一个概念；
4. 先观测重复率，再决定是否需要写入时去重、后台合并或查询时去重。

ClickHouse 的 ReplacingMergeTree 经常被当作去重开关，但它的合并是异步的。在后台合并完成前，同一排序键可能同时存在多行；依赖 FINAL 可以得到更接近最终状态的结果，却会增加查询成本。它更适合“同一主键保留某个版本”的模型，而不是无需设计就能获得实时唯一性的魔法。

如果业务要求写入后立刻严格唯一，通常需要在接收层、缓存层或专门的幂等存储中完成约束，再把结果写入 ClickHouse。是否值得付出这部分状态和延迟，要看重复事件对指标的实际影响。

批量写入比逐条 INSERT 更重要

埋点接收服务很容易在功能测试中采用逐条写入，因为代码最直接。但在持续流量下，大量小 INSERT 会增加 ClickHouse 的 part 数量和后台合并压力。

Go 接收层更适合先做有界批量：达到条数阈值或时间阈值就刷新，同时对队列长度、批量大小、刷新耗时、失败重试和丢弃数量做监控。这里的“有界”很重要——无限缓存会把数据库波动变成接收服务的内存故障。

失败处理也要区分：格式非法的数据应进入可审计的拒绝路径；短暂网络错误可以退避重试；持续写入失败则需要触发限流或降级，不能只在日志里打印错误后继续返回成功。

用 SQL 做三层验收

一个新的事件接入后，可以按三层检查：

原始层：抽样查看事件名、身份、属性类型、事件时间和接收时间，确认原始语义没有丢失。

质量层：统计空身份、未来时间、严重迟到、类型冲突与疑似重复比例，并按 SDK、版本和平台切分。

指标层：用明确 SQL 计算事件量、用户数或转化，并与测试样本的预期结果核对。只有这一层正确，不代表前两层没有隐患。

Apache Superset 适合把这些质量查询做成只读看板，但告警仍应接入团队已有的监控体系。BI 看板能帮助解释数据，不能替代服务健康检查、备份与容量告警。

迁移时不要先追求“全部兼容”

如果团队已经使用神策官方 SDK，验证新接收后端时可以从独立测试项目开始：先发送少量测试事件，再依次检查身份、属性、时间、批量上报和异常重试。验证通过后再做小流量灰度，并为客户端 serverUrl 或网关路由保留可回滚路径。

SensorFlow 目前聚焦的是一条可检查的数据链路：

神策官方 SDK 标准上报流程 → Go 接收 → ClickHouse → Apache Superset

它不是神策、PostHog 或其他完整产品分析套件的等价替代，也不宣称已经提供成熟的无代码漏斗、留存、路径、会话回放、实验或 Feature Flag。选择自托管意味着团队还要承担 TLS、鉴权、监控、备份、容量、升级和合规责任。

结语

事件表设计没有脱离查询和运维场景的标准答案。先把时间语义、稳定字段、属性类型和重复定义说清楚，再决定表引擎与去重方式，通常比一开始追求复杂模型更可靠。

SensorFlow 是独立开源项目，与文中提及的厂商不存在关联、背书或官方认证关系。兼容性应以实际 SDK 版本和事件样本验证。

• GitHub：https://github.com/data-analyze-bi/sensorFlow
• 中文文档：https://sensorflow.site/docs
• Superset 只读演示：https://superset.sensorflow.site/