ES中字段为null、空数组或[null]的文档不会被索引到倒排索引，因此term/match等查询无法匹配；whereNull()在Scout中不生效，因ES无IS NULL语义且不存储null字段；正确方案是用must_not.exists查询，或建索引时配置null_value。
ES 中字段值为 null、空数组 [] 或 [null] 的文档，**根本不会被索引到倒排索引里**——这意味着你用 term、match 等常规查询去“查 null”，注定失败或报错。
为什么 whereNull('field') 在 Scout + ES 里不生效
Laravel 的 whereNull() 是针对数据库的 Eloquent 方法，底层生成 WHERE field IS NULL。但 Elasticsearch 没有 IS NULL 语义，它压根不存 null 字段。Scout 扩展（如 Laravel Scout + TNTSearch 或 Meilisearch）也基本不支持该语法透传；若用官方 Elastic Scout Driver，whereNull() 会被忽略或抛异常。
- 直接调用
Article::whereNull('tags')->get()→ 返回空集合，不是因为没匹配，而是 Scout 没把这条件转成 ES 的bool.must_not.exists - 错误日志常见：
"field name is null or empty"（因误传term: { "field": null }） - ES 7.0+ 已移除
missing过滤器，只保留exists作为唯一标准方案
ES 层正确过滤 null 字段：用 exists + must_not
想查“tags 字段不存在（即为 null/空/未设置）”的文档，必须在 ES Query DSL 中显式构造布尔查询。Scout 默认不封装这个逻辑，需手动干预：
- 查“有值”的文档：
{"query":{"constant_score":{"filter":{"exists":{"field":"tags"}}}}} - 查“无值（即 null 类）”的文档：
{"query":{"bool":{"must_not":{"exists":{"field":"tags"}}}}} - 在 Laravel 中，可通过自定义 Scout 引擎或使用
raw()方法注入：
$results = Article::search('', function (Client $client, string $query, array $params) {
$params['body']['query'] = [
'bool' => [
'must_not' => [['exists' => ['field' => 'tags']]]
]
];
return $client->search($params);
})->get();
注意：这不是通用 whereNull() 替代，而是针对单次搜索的精准控制。
Laravel 模型层补救：避免序列化时暴露 null 字段
即使 ES 查出了含 null 字段的文档（比如通过 null_value mapping 显式索引），Laravel 默认 toJson() 仍会输出 "tags": null。前端通常不要这个。此时不能依赖 Scout 或 ES 配置，得在模型或 Resource 层过滤：
- 在模型中重写
toArray()，仅移除=== null的键（保留0、false、''）：
public function toArray()
{
$array = parent::toArray();
foreach ($array as $key => $value) {
if ($value === null) {
unset($array[$key]);
}
}
return $array;
}
- 更推荐在 API Resource 中处理（如
ArticleResource），解耦更干净：
public function toArray($request)
{
$arr = parent::toArray($request);
return array_filter($arr, fn($v) => $v !== null);
}
⚠️ 注意：array_filter() 默认会重置键，若需保持原始键名，加第二个参数 ARRAY_FILTER_USE_BOTH 并手动判断。
长期建议：建索引时用 null_value 显式归一化
如果业务真需要区分“字段为空”和“字段未设置”，别让 ES 自动丢弃 null。在创建 mapping 时指定 null_value：
PUT /articles
{
"mappings": {
"properties": {
"tags": {
"type": "keyword",
"null_value": "MISSING"
}
}
}
}
这样 tags: null 会被索引为 "MISSING"，后续就能用 term: { "tags": "MISSING" } 精确查询。但代价是：所有 null 和真实值 "MISSING" 无法区分 —— 这就是设计取舍。
最易被忽略的一点：ES 的 null 处理是索引时决定的，不是查询时能绕过的。你无法在不重建索引的前提下，让已有的 null 字段突然变得可查。要么接受“不存在即不可查”，要么提前规划 null_value。
