vitess中sharded表必须显式配置vindex,否则查询失败;unsharded表需声明类型但不可配vindex;join时sharded表须等值关联其vindex列;表类型变更需停服重刷,不支持在线切换。

sharded 表必须显式指定 vindex,否则查询会失败
Vitess 要求所有 sharded 表在 VSchema 中绑定一个有效的 vindex(如 unicode_loose_md5 或自定义函数),否则路由层无法决定数据该发往哪个分片。SELECT * FROM user WHERE id = 123 这类语句在未配置 vindex 时会直接报错:no vindex found for column 'id'。
- 常见错误:只写了
"type": "sharded",但漏掉"vindexes"字段或拼错字段名(比如写成vindex单数) -
vindex必须和CREATE TABLE中的列名完全一致,大小写敏感 - 如果用复合主键,
vindex只能绑定其中一列——Vitess 不支持多列联合 vindex - 自定义
vindex函数需提前注册到 VTTablet,且返回值类型要与目标列兼容(如BIGINT列不能配返回STRING的 vindex)
unsharded 表仍需声明,但可省略 vindex
unsharded 表本质是全局表(通常放在 0 分片),Vitess 仍要求你在 VSchema 中明确声明其类型,否则会被默认当成 sharded 处理,进而触发 vindex 检查并失败。
- 典型场景:配置
region、country_code这类小而稳定的维度表 - 正确写法是:
"type": "unsharded",不带vindexes字段;加了反而报错:unsharded table cannot have vindexes - 注意:即使物理上只有一份数据,
unsharded表的 DML 仍受 Vitess 事务协调器管控,跨分片事务中它会被当作“参与者”处理 - 性能影响:对
unsharded表的读请求会固定路由到0分片,高并发下可能成为瓶颈,别把它当缓存用
混合使用 sharded 和 unsharded 表时,JOIN 有硬性限制
Vitess 允许 sharded 表和 unsharded 表 JOIN,但前提是 sharded 表的 JOIN 条件必须命中其 vindex 列,且该列是等值条件(=),否则报错:cannot join sharded table without equality condition on vindexed column。
- 允许:
SELECT u.name, c.name FROM user u JOIN country c ON u.country_id = c.id(假设user.country_id是 vindexed 列) - 不允许:
ON u.country_id > c.id、ON u.email LIKE CONCAT('%', c.code, '%')、或ON u.created_at = c.updated_at(非 vindex 列) - 如果 JOIN 条件没走 vindex 列,Vitess 会拒绝执行,不会退化为广播查询
- 多个 unsharded 表之间 JOIN 没限制,但一旦引入 sharded 表,规则立刻生效
修改表类型需停服重刷,没有在线切换路径
Vitess 不支持运行时把 sharded 表改成 unsharded,或反过来。变更必须先停写、导出数据、更新 VSchema、重建分片映射、再导入——整个过程涉及 vtctlclient ApplySchema 和 ApplyVSchema 两步,且中间任何一步失败都会导致元数据不一致。
- 最容易被忽略的坑:改完
VSchema后忘了调用ApplyVSchema,VTGate 仍按旧规则路由 - 如果原表有外键指向它,
unsharded → sharded会失败,因为 Vitess 不支持跨分片外键约束 - 从
sharded改为unsharded时,所有分片上的数据必须先合并去重,否则0分片会写入冲突 - 测试阶段务必用真实流量压测路由逻辑,光看 DDL 成功不代表查询不出错
VSchema 里表类型的划分不是语法装饰,它直接决定查询能否发出、怎么路由、是否允许 JOIN——稍有偏差,VTGate 就会拦截,而不是静默降级。










