最近在回顾一些曾经在 ES 上踩过的坑，想起了这么一个问题：Elasticsearch 索引突然无法写入新文档了，日志里报错说文档数量超过了限制。这个问题在 7.x 版本的集群中尤其常见，因为从 7.x 开始，Elasticsearch 默认索引只有 1 个分片。今天就来回顾一下这个问题的来龙去脉。

当索引的单个分片文档数达到上限时，会看到类似这样的错误：

Number of documents in the index can't exceed [2147483519]

这个数字看起来很眼熟对吧？没错，它非常接近 Java 的

（2147483647）。实际上，这个限制来自于 Lucene 的

这个限制其实是 Lucene 层面的硬性约束。我们来看看源码中的关键部分：

private Exception tryAcquireInFlightDocs(Operation operation, int addingDocs) {
    assert operation.origin() == Operation.Origin.PRIMARY : operation;
    assert operation.seqNo() == SequenceNumbers.UNASSIGNED_SEQ_NO : operation;
    assert addingDocs > 0 : addingDocs;
    final long totalDocs = indexWriter.getPendingNumDocs() + inFlightDocCount.addAndGet(addingDocs);
    if (totalDocs > maxDocs) {
        releaseInFlightDocs(addingDocs);
        return new IllegalArgumentException("Number of documents in the index can't exceed [" + maxDocs + "]");
    } else {
        return null;
    }
}


在 Elasticsearch 7.x 之前，默认索引会创建 5 个主分片。但从 7.x 开始，为了优化资源使用和提升性能，

对于日志类、时序类数据，如果没有合理规划索引策略，很容易就会触碰到这个天花板。

让我们通过一个流程图来理解文档写入时的检查机制：

1. 文档数量检查（InternalEngine.java）

private final AtomicLong inFlightDocCount = new AtomicLong();
private final int maxDocs;

public InternalEngine(EngineConfig engineConfig) {
    this(engineConfig, IndexWriter.MAX_DOCS, LocalCheckpointTracker::new);
}


。在每次写入操作前，都会检查：

final long totalDocs = indexWriter.getPendingNumDocs() + inFlightDocCount.addAndGet(addingDocs);
if (totalDocs > maxDocs) {
    // 超限，拒绝写入
}


2. Shrink 操作的检查（TransportResizeAction.java）

在执行索引收缩（shrink）操作时，也会检查合并后的分片是否会超过限制：

for (int i = 0; i < numShards; i++) {
    if (resizeRequest.getResizeType() == ResizeType.SHRINK) {
        Set<ShardId> shardIds = IndexMetadata.selectShrinkShards(i, sourceMetadata, numShards);
        long count = 0;
        for (ShardId id : shardIds) {
            DocsStats docsStats = perShardDocStats.apply(id.id());
            if (docsStats != null) {
                count += docsStats.getCount();
            }
            if (count > IndexWriter.MAX_DOCS) {
                throw new IllegalStateException("Can't merge index with more than [" + IndexWriter.MAX_DOCS
                    + "] docs - too many documents in shards " + shardIds);
            }
        }
    }
}


这确保了在 shrink 操作时，不会将多个分片合并成一个超过限制的大分片。

方案一：增加分片数（推荐用于新索引）

对于新创建的索引，可以在索引模板中设置合适的分片数：

PUT _index_template/my_template
{
  "index_patterns": ["logs-*"],
  "template": {
    "settings": {
      "number_of_shards": 3,
      "number_of_replicas": 1
    }
  }
}


：这个设置只对新创建的索引生效，已存在的索引不会受影响。

方案二：使用 Split API（用于已存在的索引）

对于已经达到限制的索引，可以使用 Split API 来增加分片数：

# 1. 先将索引设置为只读
PUT /my_index/_settings
{
  "settings": {
    "index.blocks.write": true
  }
}

# 2. 执行 split 操作
POST /my_index/_split/my_index_new
{
  "settings": {
    "index.number_of_shards": 3
  }
}

# 3. 等待 split 完成后，可以删除旧索引
DELETE /my_index


方案三：使用索引生命周期管理（ILM）

对于日志类、时序类数据，最佳实践是使用 ILM 自动管理索引：

PUT _ilm/policy/logs_policy
{
  "policy": {
    "phases": {
      "hot": {
        "actions": {
          "rollover": {
            "max_docs": 2000000000,
            "max_age": "7d",
            "max_size": "50gb"
          }
        }
      },
      "delete": {
        "min_age": "30d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}


这样可以在文档数接近限制前自动滚动到新索引，避免触碰天花板。

GET /_cat/shards?v&h=index,shard,docs&s=docs:desc


Elasticsearch 的单分片文档数限制是 Lucene 层面的硬性约束，这个限制在 7.x 版本中因为默认分片数的改变而变得更容易触碰。理解这个限制的原理和检查机制，可以帮助我们更好地规划索引策略，避免生产环境中出现意外。

希望这篇文章能帮助你更好地理解和应对这个问题。如果你的集群中有大量数据，不妨现在就检查一下各个分片的文档数吧！

踩坑记：Elasticsearch 索引写不进去了？可能是触碰了这个隐藏限制

Elasticsearch 单分片最多只能存储 21.47 亿个文档，这是 Lucene 的硬性限制。7.x 版本将默认分片数从 5 个改为 1 个，使得这个问题更容易出现。本文揭示限制的底层原理，并提供三种解决方案：增加分片数、使用 Split API 扩容、以及通过 ILM 自动管理索引生命周期。对于日志类时序数据，建议提前规划分片策略，避免触碰天花板。

大数据工程师

云计算

后端

大数据

Elasticsearch单分片文档数上限为21.47亿，7.x版本默认1个分片易触达限制。推荐使用索引模板增加分片数、Split API扩容或ILM自动管理。合理规划分片数，监控文档量，避免写入中断。时序数据建议采用ILM策略自动滚动索引。

Java

ES特惠专场，新客首购1折起！


AI驱动 智领未来

bigdata-class

文章

问答

视频

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

踩坑记：Elasticsearch 索引写不进去了？可能是触碰了这个隐藏限制

踩坑记：Elasticsearch 索引写不进去了？可能是触碰了这个隐藏限制

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐