thinkphp中gsi不会自动生效，必须显式指定索引名或使用hint；常见原因包括orm不生成索引提示、优化器无法自动选择gsi、表组与分区键不一致等。
全局二级索引（GSI）在 ThinkPHP 中不会自动生效，必须显式指定索引名或使用 HINT，否则即使建了 GLOBAL INDEX，查询仍走全分区扫描。
ThinkPHP 查询不走 GSI 的常见原因
ThinkPHP 默认生成的 SQL 不含任何索引提示，而 PolarDB-X 的优化器在多数 JOIN 或非主键 WHERE 场景下，无法自动选择 GSI 表——尤其当主表和索引表不在同一表组、分区键不一致时，优化器倾向于放弃 GSI 路由。
典型现象包括：
-
EXPLAIN显示LogicalView(tables="product[p1,p2,p3]")全分区扫描，而非LogicalView(tables="g_i_emp_id[p1,p2]") - 关联查询如
emp JOIN product ON emp.id = product.producer没有命中g_i_emp_id，执行计划里出现BKAJoin且右表shardCount=3 - 单表查询
WHERE producer = ?仍扫描全部 product 分区（3 个），而非仅查 GSI 的 2 个分区
在 ThinkPHP 中强制使用 GSI 的两种方式
必须绕过 ORM 默认行为，手动注入 HINT。PolarDB-X 支持两种语法，ThinkPHP 均可适配：
- 用原生 SQL +
FORCE INDEX：适用于简单查询，例如Db::query("SELECT * FROM product FORCE INDEX(g_i_emp_id) WHERE producer = ?", [$id]) - 用注释 HINT +
/+TDDL:INDEX(...)/：更稳定，兼容复杂 JOIN，例如Db::table('product a')->whereRaw('/+TDDL:INDEX(a, g_i_emp_id_name)/')->where('a.producer', $id)->find() - 注意：HINT 中的表别名（如
a）必须与查询中定义的一致；索引名（如g_i_emp_id_name）须与SHOW CREATE TABLE输出完全匹配，大小写敏感
GSI 覆盖列不足时的回表开销要提前预估
如果查询字段超出 GSI 的 COVERING 列范围，PolarDB-X 会先查 GSI 表取主键和分库分表键，再发起第二次请求回查主表——相当于两次网络往返 + 两次分片路由。
例如建表时定义了 GLOBAL INDEX g_i_seller(seller_id) COVERING (order_id)，但代码中执行：
Db::table('t_order a')->whereRaw('/+TDDL:INDEX(a, g_i_seller)/')->field('id, order_id, buyer_id, order_snapshot')->where('seller_id', 'S123')->find()
由于 buyer_id 和 order_snapshot 不在覆盖列中，将触发回表。实测延迟可能从 8ms 升至 25ms+，QPS 下降约 40%。
建议做法：
- 建 GSI 时尽可能把高频查询字段加入
COVERING，但避免过度冗余（每多一列，GSI 表体积和写放大同步增加） - ThinkPHP 中对关键接口做
EXPLAIN验证，确认是否真正“免回表” - 慎用
field('*')，尤其在 GSI 查询中——它大概率导致隐式回表
JOIN 场景下 GSI 生效的前提很苛刻
ThinkPHP 的 join() 方法生成的 SQL，几乎不可能让 GSI 在 JOIN 中自动生效，除非满足全部条件：
- 被 JOIN 的两张表必须在同一表组（
TABLE_GROUP_NAME相同），否则无法做分片对齐 - GSI 的分区键必须与 JOIN 条件列完全一致，且类型兼容（如
product.producer和emp.id都是bigint） - 必须显式用 HINT 绑定 GSI 表，且 JOIN 写法需保证 GSI 表为驱动表（如 LEFT JOIN 时把它放在左边）
现实中，emp 和 product 分区方式不同、不在同一表组，此时强行用 GSI JOIN 反而引入跨组路由和额外 Gather 节点，性能可能比全扫还差。
更务实的做法是：对这类异构 JOIN，改用应用层两阶段查询——先查 emp 得到一批 id，再用 IN 查 product 并带上 /+TDDL:INDEX(...)/ HINT，控制 IN 长度 ≤ 500。
GSI 不是“建了就快”的银弹，它在 ThinkPHP 中的落地强依赖 SQL 精确控制；最容易被忽略的是：HINT 必须出现在最终发送给 PolarDB-X 的 SQL 字符串里，而不是 ThinkPHP 构建过程中的某个中间对象上。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
