Azure AI Search：新增可筛选字段运行索引器后未填充问题咨询

原有索引新字段未填充的疑问解答 #

1. 是否需要重置或删除索引器？ #

不需要删除索引器，但必须重置索引器后重新运行。索引器默认仅增量同步已处理过的文档，新增字段后存量文档不会自动回溯更新。重置索引器会清除已处理的状态标记，强制全量重新索引所有文档，新字段才能被填充。

2. 能否仅重新索引新字段？ #

不行。Azure AI Search没有针对单个新字段的增量索引机制，只有两种处理方式：

• 重置索引器全量重新索引所有文档；
• 通过Search API批量手动更新存量文档的新字段值（适合文档量较大的场景，需自行实现批量更新逻辑）。

3. 是缓存或字段映射问题吗？ #

• 缓存问题：是常见诱因。索引器会缓存已处理文档的状态，增量模式下不会重新读取旧文档的新字段，重置索引器即可清除该缓存。
• 字段映射问题：需重点排查：
  • 若为手动添加的字段，默认不会自动映射（除非开启自动字段映射），需确认数据源字段名与索引字段名完全匹配（区分大小写）；
  • 若字段名不一致，需检查索引器是否配置了自定义字段映射规则，规则表达式是否正确。

新建索引可筛选属性丢失的问题处理 #

你新建索引使用了自动字段映射，自动映射会根据数据源字段类型推断索引字段属性，但默认不会自动设置可筛选属性。解决方式：

• 在Azure门户或通过Search API修改索引定义，找到对应字段，将filterable属性设为true；
• 若依赖自动映射，可在索引器的字段映射中显式指定字段属性，或创建索引时手动定义字段（而非完全依赖自动推断）。

通用排查步骤 #

• 查看索引器运行日志：在Azure门户索引器页面查看运行历史，排查是否存在字段映射失败、数据源读取错误等日志，这是定位问题最直接的方式；
• 验证字段映射规则：对比数据源与索引的字段名，确保大小写、拼写完全一致，自定义映射规则的表达式无错误；
• 测试单文档索引：通过Search API手动提交一条包含新字段的文档，验证是否能成功填充并保留可筛选属性，排除索引本身的配置问题；
• 检查索引器权限：确认索引器的身份（系统分配或密钥）拥有读取数据源所有字段的权限，避免因权限不足无法读取新字段。

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