使用 gocql 执行 `select *` 查询时列数不全，本质是客户端预编译语句未同步表结构变更，叠加 cassandra 2.1.2 及更早版本的元数据缓存 bug（cassandra-7910）所致；需禁用自动预编译、显式重建查询或动态构建列名列表。
在基于 Cassandra 的计数器应用中，通过 ALTER TABLE ... ADD COLUMN 动态扩展列是一种常见实践（尤其适用于按消息类型分维度统计的场景）。但当配合 gocql 驱动执行 SELECT * 时，常出现「返回列数少于实际列数」的问题——例如表有 34 列，却只返回约 30 列。而同一 CQL 在 cqlsh 中执行结果完整，说明问题不在数据层，而在驱动与服务端的元数据协同机制。
根本原因：双重缓存失效
该问题由两个关键因素共同导致：
gocql 自动预编译（Automatic Query Preparation）
默认情况下，gocql 对形如 SELECT * FROM t WHERE date IN ? 的查询会自动预编译。预编译时，Cassandra 返回一份静态列元数据快照（含列名、类型、顺序），后续同结构查询均复用此元数据解析响应。一旦表结构通过 ALTER TABLE 新增列，客户端不会主动刷新该快照。Cassandra 服务端元数据缓存 Bug（CASSANDRA-7910）
在 Cassandra ≤2.1.2 版本中，服务端对已预编译语句的元数据也存在缓存，且未在 ALTER TABLE 后自动失效。即使客户端强制重连或新建 session，服务端仍返回旧元数据，导致新列被忽略。该 Bug 已在 Cassandra 2.1.3+ 修复。
✅ 验证方式：重启 Cassandra 节点后首次执行 SELECT * 可临时恢复完整列——这印证了服务端缓存是关键瓶颈。
推荐解决方案（按优先级排序）
✅ 方案一：禁用自动预编译（最简有效）
在 ClusterConfig 中关闭自动预编译，强制每次查询走非预编译路径，确保元数据实时拉取：
cluster := gocql.NewCluster("127.0.0.1")
cluster.Consistency = gocql.Quorum
cluster.ProtoVersion = 4
cluster.DisableInitialHostLookup = true
cluster.DisableAutoPrepare = true // ? 关键配置：禁用自动预编译
session, err := cluster.CreateSession()
if err != nil {
log.Fatal(err)
}
defer session.Close()
// 此时 SELECT * 将每次获取最新元数据
query := session.Query(`SELECT * FROM ` + _apiCountersTable + ` WHERE date IN ?`, dates)
res, err := query.Iter().SliceMap() // 现在可返回全部 34 列✅ 方案二：显式重建 Prepared Statement
若需保留预编译性能优势，可在检测到 schema 变更（如部署新版本）后，手动清除预编译缓存并重建：
// 注意：gocql v0.0.0-2023xxx 后版本支持 StmtCache 清理
session := cluster.CreateSession()
// 强制清空所有预编译语句（影响全局，建议在维护窗口执行）
session.Control().ClearPreparedStatements()
// 或针对特定查询重建（需自行管理 stmt 生命周期）
stmt := session.Query(`SELECT * FROM ` + _apiCountersTable + ` WHERE date = ?`)
prepared, err := stmt.Prepare()
if err != nil {
log.Fatal(err)
}
iter := prepared.Bind("total").Iter()⚠️ 方案三：动态构建列名（兼容性最强，但有开销）
如无法升级 Cassandra 或修改驱动配置，可退化为动态拼接列名（需注意注入风险）：
// 从 system_schema.columns 获取当前列（生产环境建议缓存并定时刷新）
var cols []string
iter := session.Query(`SELECT column_name FROM system_schema.columns
WHERE keyspace_name = ? AND table_name = ?
ORDER BY position`, "stats_dev", _apiCountersTable).Iter()
for iter.Scan(&col) {
cols = append(cols, col)
}
colList := strings.Join(cols, ", ")
query := session.Query(fmt.Sprintf(`SELECT %s FROM %s WHERE date IN ?`, colList, _apiCountersTable), dates)
res, err := query.Iter().SliceMap()架构建议：避免过度依赖动态列
尽管 ALTER TABLE ADD COLUMN 在开发期便捷，但在生产环境中频繁变更宽表结构存在隐患：
- 触发 SSTable 重建，增加 compaction 压力；
- 多列计数器易导致热点（如 date='total' 单行写入激增）；
- 宽表不利于水平扩展（单行超 100KB 易触发警告）。
✅ 更健壮的设计模式：
-- 改用复合主键，按时间+类型分片
CREATE TABLE stats_dev.log_counters_by_type (
date text,
msg_type text,
count counter,
PRIMARY KEY (date, msg_type)
);
-- 查询某日全部类型：SELECT * FROM log_counters_by_type WHERE date = '2024-01-01'
-- 查询某类型历史：SELECT * FROM log_counters_by_type WHERE date IN ('2024-01-01','2024-01-02') AND msg_type = 'ERROR'总结
| 方案 | 适用场景 | 风险提示 |
|---|---|---|
| DisableAutoPrepare = true | 大多数场景首选 | 少量性能损耗（毫秒级），但彻底规避元数据陈旧问题 |
| 手动清理 Prepared Statements | 高并发且需预编译性能 | 需精确控制刷新时机，避免运行时抖动 |
| 动态列名拼接 | 无法修改驱动/服务端的遗留系统 | SQL 注入风险（务必参数化过滤列名）、额外 round-trip 开销 |
最终建议：立即启用 DisableAutoPrepare，同时规划向基于 msg_type 的复合主键模型迁移，兼顾可维护性与 Cassandra 的分布式设计哲学。
