Laravel 无法用 Eloquent 直接查询 Elasticsearch 多层嵌套字段，必须通过 HTTP 客户端调用 ES API 获取原始响应，再用 Laravel Collection 结合 data_get()、filter()、groupBy() 等方法安全处理嵌套结构，并注意 ES mapping 配置与聚合优先原则。
ES 多层数组嵌套字段在 Laravel 中不能直接用 Eloquent 查
你写的 whereJsonContains('data.tags', 'php') 或 whereRaw 去匹配 Elasticsearch 返回的嵌套数组，这条路走不通——Laravel 的数据库查询构建器（Query Builder）和 Eloquent **不解析 ES 的嵌套结构**，它只对 MySQL/PostgreSQL 等关系型数据库生效。ES 是独立服务，返回的是 PHP 数组或 StdClass 对象，不是 Eloquent 模型实例，更没有 with()、whereHas() 这类能力。
常见错误现象：Call to undefined method Illuminate\Database\Query\Builder::whereNested() 或查出空结果但 ES Dev Tools 里明明有数据。
正确做法是：先用 HTTP 客户端（如 GuzzleHttp\Client）调用 ES API 获取原始响应，再用 Laravel Collection 处理嵌套数组。
用 Collection::filter() 遍历多层嵌套数组（如 hits.hits._source.tags）
ES 的标准响应结构是：['hits' => ['hits' => [['_source' => [...]]]]。你不能靠循环硬解，得用 Collection 的链式方法穿透层级。
- 先用
collect($esResponse['hits']['hits'])->pluck('_source')提取所有文档源数据 - 再用
filter()+ 闭包安全访问嵌套字段：->filter(fn($doc) => data_get($doc, 'tags.0.name') === 'php') - 避免
$doc['tags'][0]['name']这种写法——一旦某条文档tags为空或不是数组，直接报Undefined index -
data_get()是 Laravel 内置函数，支持点号路径和默认值：data_get($doc, 'company.profile.status', 'inactive')
深层嵌套字段分组（如按 user.profile.department 分组）
ES 返回的扁平化文档里可能含多层嵌套对象，比如 user 下有 profile，profile 下有 department。想按这个路径分组，不能传字符串 'user.profile.department' 给原生 PHP array_column() ——它不支持点号。
必须用 Collection 的 groupBy()，它原生支持：
-
collect($sources)->groupBy('user.profile.department')✅ 自动递归取值 - 若字段可能缺失，加空值保护：
->groupBy(fn($item) => data_get($item, 'user.profile.department', 'unknown')) - 分组后想转成纯数组？链式调用
->map->values()->all()
性能关键：别在循环里反复调 ES，也别用 foreach 做深度遍历
ES 查询本身已带聚合（aggs）能力，如果只是要“每个 department 有多少条记录”，根本不用拉全量数据回 PHP 再 groupBy——直接在 DSL 里写 "aggs": {"by_dept": {"terms": {"field": "user.profile.department.keyword"}}，让 ES 在服务端算好再返回。
只有当业务逻辑必须在 PHP 层判断时（比如结合用户权限、动态计算字段），才拉数据回来处理。此时注意：
- 用
collect()->flatMap()替代多层foreach，避免手动维护层级索引 - 嵌套过深（如
logs.0.events.1.payload.user.id）建议先用map()提前规整结构：->map(fn($hit) => ['id' => data_get($hit, 'logs.0.events.1.payload.user.id'), ...]) - 内存敏感场景下，别用
collect($bigArray)一次性加载，改用生成器 +LazyCollection
真正容易被忽略的是：ES 字段默认不索引嵌套对象的内部结构，user.profile.department 要能被 terms 聚合，mapping 必须声明为 nested 类型并配 include_in_parent，否则 groupBy('user.profile.department') 能跑通，但结果永远为空。
