Atlas Search索引报错：嵌入式文档中不可存在可排序字符串字段

问题场景 #

我在Atlas Search中创建了如下结构的索引：

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "_id": {
        "type": "objectId"
      },
      ...
      "properties": {
        "type": "embeddedDocuments",
        "dynamic": false,
        "fields": {
          ...
          "stringValueAsToken": {
            "type": "token"
          },
          ...
        }
      },
      ...
    }
  }
}

但mongot服务器抛出如下异常：

java.lang.IllegalStateException: should be impossible for sortable string fields to be present in embedded documents
        at com.xgen.mongot.util.Check.stateAssertion(Check.java:168)
        at com.xgen.mongot.index.lucene.document.single.LuceneSearchIndexFieldValueHandler.handleSortableString(LuceneSearchIndexFieldValueHandler.java:493)
        at com.xgen.mongot.index.lucene.document.single.LuceneSearchIndexFieldValueHandler.handleString(LuceneSearchIndexFieldValueHandler.java:425)
        at com.xgen.mongot.index.lucene.document.block.EmbeddedFieldValueHandler.handleString(EmbeddedFieldValueHandler.java:138)
        at com.xgen.mongot.index.ingestion.BsonDocumentProcessor.handleField(BsonDocumentProcessor.java:152)
        at com.xgen.mongot.index.ingestion.BsonDocumentProcessor.handleDocumentField(BsonDocumentProcessor.java:52)
        at com.xgen.mongot.index.ingestion.BsonDocumentProcessor.handleField(BsonDocumentProcessor.java:93)
        at com.xgen.mongot.index.ingestion.BsonDocumentProcessor.handleField(BsonDocumentProcessor.java:76)
        at com.xgen.mongot.index.ingestion.BsonDocumentProcessor.handleDocumentField(BsonDocumentProcessor.java:52)
        at com.xgen.mongot.index.ingestion.BsonDocumentProcessor.process(BsonDocumentProcessor.java:38)
        at com.xgen.mongot.index.lucene.SingleLuceneIndexWriter.handleInsertOrUpdate(SingleLuceneIndexWriter.java:407)
        at com.xgen.mongot.index.lucene.SingleLuceneIndexWriter.updateIndex(SingleLuceneIndexWriter.java:242)
        at com.xgen.mongot.index.lucene.SingleLuceneIndexWriter.updateIndex(SingleLuceneIndexWriter.java:227)
        at com.xgen.mongot.index.MeteredIndexWriter.updateIndex(MeteredIndexWriter.java:20)
        at com.xgen.mongot.replication.mongodb.common.DefaultDocumentIndexer.indexDocumentEvent(DefaultDocumentIndexer.java:49)
        at com.xgen.mongot.replication.mongodb.common.IndexingWorkScheduler$IndexingTask.run(IndexingWorkScheduler.java:239)
        at com.xgen.mongot.util.FutureUtils.lambda$checkedRunAsync$2(FutureUtils.java:108)
        at java.base/java.util.concurrent.CompletableFuture$AsyncRun.run(CompletableFuture.java:1736)
        at io.micrometer.core.instrument.internal.TimedRunnable.run(TimedRunnable.java:49)
        at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
        at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
        at java.base/java.lang.Thread.run(Thread.java:829)

此前创建MongoDB文档中不存在该字段时索引成功，但为该字段存入数据后索引构建失败。问题出在token类型字段，需要明确异常原因和正确的字段创建方式。

异常原因 #

• 核心限制：Atlas Search的token类型本质是可排序的字符串字段，而mongot（Atlas Search后端服务）不允许在**嵌入式文档（embeddedDocuments）**中使用可排序字符串类型。从异常栈可见，代码在处理嵌入式文档内的可排序字符串时触发了断言检查，直接抛出异常。
• 无数据时成功的逻辑：当文档中不存在该字段时，索引构建无需处理实际字段值，不会触发断言检查，因此索引创建成功；一旦存入包含该字段的数据，mongot处理字段值时就会触发限制检查，导致索引构建失败。

正确创建方式 #

根据Atlas Search的规则，token类型字段不能放在嵌入式文档内，可按以下两种方案调整：

方案1：将token字段移至顶层（适用于需要精确匹配/排序/聚合的场景） #

把stringValueAsToken字段从嵌入式文档中移出，放在索引的顶层字段中：

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "_id": {
        "type": "objectId"
      },
      "stringValueAsToken": {
        "type": "token"
      },
      "properties": {
        "type": "embeddedDocuments",
        "dynamic": false,
        "fields": {
          // 其他嵌入式字段，不包含token类型
          ...
        }
      },
      ...
    }
  }
}

方案2：改用带分词器的string类型（适用于必须保留嵌入式结构且需文本搜索的场景） #

如果字段必须放在嵌入式文档中，放弃token类型，改用string类型并配置合适的分词器，实现文本搜索同时避开可排序字段的限制：

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "_id": {
        "type": "objectId"
      },
      "properties": {
        "type": "embeddedDocuments",
        "dynamic": false,
        "fields": {
          ...
          "stringValueAsToken": {
            "type": "string",
            "analyzer": "lucene.standard" // 根据业务需求选择分词器
          },
          ...
        }
      },
      ...
    }
  }
}

注意事项 #

• token类型适合精确匹配、排序、聚合场景；string类型带分词器适合全文搜索场景，需根据实际业务需求选择。

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