es单条件精准查询不能用match而必须用term，因match会分词、小写化等，term要求字段为keyword类型且值原样传入（如user_id.keyword），中文字段需确保keyword子字段确为keyword类型而非text。
ES 单条件精准查询为什么不能直接用 match？
因为 match 是全文检索，默认会分词、小写化、做同义词扩展，查 "user_123" 可能匹配到 "user" 或 "123"。真要“完全一致”，必须用 term 查询——但它要求字段在 ES 中是 keyword 类型，不是默认的 text。
常见错误现象："No search results even though data exists"，本质是 mapping 没配对，或用了 match 去查未分词字段。
- 检查索引 mapping：运行
GET /your_index/_mapping，确认目标字段（如user_id）下有"type": "keyword"子字段（例如user_id.keyword） - 若没有，需重建索引或用
PUT /your_index/_mapping添加fields: { keyword: { type: "keyword" } } - Laravel 中不推荐动态修改 mapping，建议建索引时就定义好：
"user_id": { "type": "text", "fields": { "keyword": { "type": "keyword" } } }
Laravel 使用 elasticsearch-php 发起 term 查询
假设你已通过 composer require elasticsearch/elasticsearch 安装客户端，并配置好 Elasticsearch\Client 实例（如绑定为 es 服务）。
关键点：字段名必须带 .keyword 后缀，且值不经过任何处理（不能 trim、不能 strtolower）。
$params = [
'index' => 'users',
'body' => [
'query' => [
'term' => [
'user_id.keyword' => 'U2024001' // 值必须原样传入
]
]
]
];
$response = app('es')->search($params);
$hits = $response['hits']['hits'] ?? [];
- 不要写
'user_id' => 'U2024001'—— 这是text字段，term查不到 - 如果字段本身就是
keyword类型（无text主字段），可直接用'user_id'，但这种情况少见 - 注意响应结构：
$hits是数组，每个元素含_source，不是直接返回模型对象，需自行映射
封装成 Eloquent 风格的查询方法（可选但实用）
很多人想在 Model 里加个 findByUserId($id)，但 Laravel 不原生支持 ES，得手动桥接。不建议继承 Eloquent，而是建一个 Repository 或 Service。
示例（放在 app/Services/ElasticsearchUserService.php）：
class ElasticsearchUserService
{
public function findByUserId(string $userId): ?array
{
$params = [
'index' => 'users',
'body' => ['query' => ['term' => ['user_id.keyword' => $userId]]]
];
$response = app('es')->search($params);
if (empty($response['hits']['hits'])) {
return null;
}
return $response['hits']['hits'][0]['_source'];
}
}
- 返回
array而非模型实例，避免混淆 ORM 行为 - 不抛异常，用
null表示未找到，符合 Laravel 的惯用法（如User::find()） - 若需关联其他 ES 索引，别在这里 join —— ES 不支持传统 join，应分两次查 + PHP 关联
中文字段精准查询要额外注意什么？
如果你查的是中文字段（比如 name），即使加了 .keyword，也要确保该字段在 mapping 中确实是 keyword 类型，而不是用了中文分词器后又强行开了 keyword 子字段但没生效。
典型翻车点："name": { "type": "text", "analyzer": "ik_smart", "fields": { "keyword": { "type": "keyword" } } } 是 OK 的；但若误写成 "fields": { "keyword": { "type": "text" } }，那 name.keyword 依然会分词。
- 验证方式：用 Kibana 或 curl 对该字段执行
term查询，看是否返回预期结果 - 中文 ID 类字段（如
订单号、手机号）强烈建议直接设为keyword类型，禁用text - ES 7.x+ 不再有 type 概念，但字段类型规则不变，别被旧教程误导
字段类型一旦写错，重索引成本高，上线前务必用真实数据跑一遍 term 查询验证。
