添加列至Cassandra表后出现Unknown column反序列化RuntimeException

问题本质 #

这是Cassandra schema变更的最终一致性特性导致的。ALTER TABLE添加列的操作不是集群原子生效的，变更会先发送到schema协调器节点，再异步传播到其他集群节点。在传播完成前，不同节点的表结构不一致，此时包含新列的查询请求会在未同步schema的节点上触发反序列化错误，进而导致一致性级别不满足的查询失败。

报错分析 #

• 应用端报错：Cassandra failure during read query at consistency LOCAL_QUORUM (3 responses were required but only 1 replica responded, 2 failed)
  因为集群中部分节点还未更新schema，无法处理包含新列的查询，直接抛出异常，导致协调器节点无法收集到足够的副本响应，无法满足LOCAL_QUORUM的一致性要求。
• 节点日志中的java.lang.RuntimeException: Unknown column {} during deserialization
  明确说明该节点的schema尚未同步新列，收到包含新列的查询请求后，反序列化列定义时失败。
• 另一节点的Failed; received 1 of 3 responses日志
  进一步验证了协调器节点无法获取足够的有效响应，查询最终失败。

为什么会出现这个情况 #

你误以为ALTER TABLE是即时生效的原子操作，但Cassandra的schema采用最终一致性模型：变更不会瞬间在所有节点生效，存在传播延迟。如果在schema完全同步前，应用就发送了包含新列的查询（比如SELECT *或显式指定新列），未同步的节点就会因无法识别新列而报错。

解决方案 #

• 等待schema全集群同步
  执行ALTER操作后，不要立刻让应用使用新列。可以通过以下方式确认同步完成：

  • 执行nodetool describecluster，检查所有节点的schema版本是否一致；
  • 执行CQL查询：SELECT schema_version FROM system.local;，对比所有节点的返回值；
  • 使用nodetool waitforagreement命令，该命令会阻塞直到集群所有节点的schema达成一致。

• 变更期间避免查询新列
  在schema同步完成前，应用的查询应只使用原有列，避免SELECT *或显式引用新列。等确认全集群schema同步后，再修改应用代码引入新列。

• 优化schema传播速度（可选）
  调整Cassandra配置中的schema_refresh_interval_in_seconds（默认30秒），临时调小该值可以让节点更快拉取新schema，但注意不要设置过小，避免增加集群负载。

• 启用驱动的schema感知
  Java Driver 4.x支持schema感知功能，配置后驱动会主动感知集群schema变化，避免发送节点无法处理的查询：
  在驱动配置中设置：

  advanced.metadata.schema.enabled = true
  advanced.metadata.schema.refresh_interval = 10s
  

内容的提问来源于stack exchange，提问作者niocer