使用PHP操作ElasticSearch时如何追加嵌套对象而非替换现有对象

你当前使用的doc模式更新，本质是全量替换addresses字段的原有内容，并非对数组元素做追加操作，因此原有地址会被直接覆盖。同时你采用了双层nested的结构，这类嵌套数组的局部精准更新，无法通过普通的doc传参方式完成，必须通过Elasticsearch自带的painless脚本做数组级别的原子操作。

场景1：新建地址并挂载新房间（追加新地址到用户地址数组） #

该场景不需要匹配已有地址，直接把完整的新地址对象（结构上包含对应新房间的数组）追加到用户的addresses数组尾部即可。
实现代码如下：

// 构造要新增的完整地址对象
$newAddress = [
    "id" => $address->id,
    "address" => $address->address,
    "zipcode" => $address->zipcode,
    "city" => $address->locality,
    "country" => $address->country,
    // 注意：rooms是nested类型，必须为数组结构，哪怕只有一个房间也要套数组
    "rooms" => [
        [
            "id" => $room->id,
            "name" => $room->room_name,
        ]
    ]
];

$params = [
    'index' => 'users',
    'id'    => $user_id,
    'body' => [
        'script' => [
            // 脚本逻辑：将新地址原子追加到addresses数组
            'source' => '
                // 兜底：如果addresses字段不存在，初始化为空数组
                if (ctx._source.addresses == null) {
                    ctx._source.addresses = [];
                }
                ctx._source.addresses.add(params.new_address)
            ',
            'params' => [
                'new_address' => $newAddress
            ]
        ],
        // 兜底：如果用户文档不存在，初始化对应结构
        'upsert' => [
            'addresses' => [$newAddress]
        ]
    ]
];
$client->update($params);

场景2：向已有指定地址追加新房间 #

该场景需要先通过目标地址的ID，定位到addresses数组里匹配的地址元素，再把新房间原子追加到该地址的rooms数组中。
实现代码如下：

// 构造要新增的房间对象
$newRoom = [
    "id" => $room->id,
    "name" => $room->room_name,
];

$params = [
    'index' => 'users',
    'id'    => $user_id,
    'body' => [
        'script' => [
            'source' => '
                // 遍历用户所有地址，找到和传入ID匹配的目标地址
                for (address in ctx._source.addresses) {
                    if (address.id == params.target_address_id) {
                        // 定位到目标后，将新房间追加到该地址的rooms数组
                        address.rooms.add(params.new_room);
                        return;
                    }
                }
                // 未找到目标地址时，抛出明确错误提示
                throw new IllegalArgumentException("未找到ID为" + params.target_address_id + "的地址");
            ',
            'params' => [
                'target_address_id' => $address->id, // 前端传入的要追加房间的目标地址ID
                'new_room' => $newRoom
            ]
        ]
    ]
];
$client->update($params);

关键注意点 #

• 结构规范：只要定义为nested类型的字段，实际存储必须是对象数组结构，哪怕数组里只有一个元素，也不能直接写成单个对象。你之前代码里把rooms写成单对象的写法，本身和nested的字段设计不匹配，容易导致后续查询、更新出现逻辑偏差。
• 更新方式选择：如果需要对数组做追加、删除、局部修改操作，绝对不能用doc全量传值的方式——这种方式会把整个字段的原有内容全部替换，也就是你当前遇到的覆盖问题。这类场景必须搭配painless脚本做数组级别的精准操作。
• 并发安全：如果采用“先查全量地址列表，在业务代码里拼好新数组再全量传回更新”的方式，在多请求并发操作同一个用户的地址/房间时，很容易出现后提交的请求覆盖先提交请求的问题；而使用painless脚本的方式，是在ES服务端原子执行数组操作，不会出现这类并发冲突。
• 索引兼容：脚本直接修改_source的方式完全兼容nested字段的索引逻辑，ES在写入时会自动根据最新的_source内容重新构建对应的nested隐藏文档，不影响后续的嵌套查询能力。

内容的提问来源于stack exchange，提问作者Thbwun