elasticsearch-reindex

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Elasticsearch Reindex

Copy documents from source indices or data streams to a destination using

POST /_reindex

. An expert reindex workflow prepares the destination explicitly, chooses local versus remote execution, filters at the source when only a subset is needed, runs long copies asynchronously, tracks the task to completion, and verifies the destination document count before reporting results.

使用

POST /_reindex

将文档从源索引或数据流复制到目标索引。专业的重新索引工作流会明确准备目标索引，选择本地或远程执行方式，仅在需要子集时在源端过滤，异步运行长时复制任务，跟踪任务直至完成，并在报告结果前验证目标文档数量。

Environment Configuration

环境配置

This skill executes Elasticsearch operations through the

elastic

CLI. If the

elastic

CLI is not installed, tell the user what it is needed for. Do not guess credentials, call the HTTP API directly, or attempt other workarounds.

This skill references operations in HTTP-shorthand form (e.g.,

GET /

GET /_cat/indices

GET /{index}/_mapping

GET /{index}/_settings/index.mode

POST /_query

). The Operations table at the end of this document maps each shorthand to the equivalent

elastic

CLI command — always use the CLI rather than calling the HTTP API directly.

本技能通过

elastic

CLI执行Elasticsearch操作。如果未安装

elastic

CLI，请告知用户其用途。请勿猜测凭证、直接调用HTTP API或尝试其他变通方法。

本技能使用HTTP简写形式引用操作（例如

GET /

、

GET /_cat/indices

、

GET /{index}/_mapping

、

GET /{index}/_settings/index.mode

、

POST /_query

）。本文档末尾的操作表格将每个简写映射为对应的

elastic

CLI命令——请始终使用CLI而非直接调用HTTP API。

Process

操作流程

Confirm connectivity and deployment type. Call
```
GET /
```
. Read
```
build_flavor
```
and
```
version.number
```
to know whether shard, replica, and cluster-settings APIs are available (Serverless manages shards/replicas internally and blocks most
```
_cluster/*
```
APIs). The decision: continue only when the cluster is reachable. If the call fails, stop — do not guess endpoints or credentials.
Decide local versus remote reindex. Compare where the source and destination live.
- Same cluster — use local reindex:
```
source.index
```
  and
```
dest.index
```
  only. Do not add
```
source.remote
```
  when both indices are on the cluster you are connected to.
- Different cluster — use reindex from remote: add
```
source.remote
```
  with the remote cluster URL and credentials. Remote reindex does not support slicing; compensate with query-based partitioning (date ranges, term filters) across parallel requests. Confirm the remote host is allowlisted on Self-Managed / ECH (
```
reindex.remote.whitelist
```
  in cluster config); Serverless manages allowlisting internally (ECH remotes only, Tech Preview).
Data needed: source index name(s), destination index name, and whether they share a cluster.
Inspect the source — never guess field names or counts. Call
```
GET /{source}/_mapping
```
to ground field names and types. Call
```
GET /{source}/_count
```
(or
```
GET /_cat/count/{source}?h=count
```
on Self-Managed / ECH) to learn how many documents exist.
The decision: full copy versus filtered subset.
- Full copy — omit
```
source.query
```
  (match-all behavior).
- Filtered subset — add
```
source.query
```
  with Query DSL. For time ranges, use a
```
range
```
  filter on the timestamp field (commonly
```
@timestamp
```
  ), e.g.
```
"gte": "2025-01-01", "lt": "2025-02-01"
```
  for January 2025. Do not run a full-index copy when the user asked for a date range or other filter.
Data needed: the user's filter criteria and the mapping-confirmed field names.
Prepare the destination index before copying.
```
_reindex
```
does not copy mappings, shard counts, or analyzers. Create the destination with explicit settings and mappings derived from the source mapping via
```
PUT /{dest}
```
.
- On Self-Managed / ECH: set
```
number_of_replicas: 0
```
  and
```
refresh_interval: "-1"
```
  on the destination during the copy for write throughput; restore production values afterward with
```
PUT /{dest}/_settings
```
  .
- On Serverless: omit
```
number_of_shards
```
  and
```
number_of_replicas
```
  (managed by Elastic); you may set
```
refresh_interval: "-1"
```
  during the copy.
- For data stream destinations: ensure an index template with
```
data_stream: {}
```
  exists, create the data stream, and set
```
dest.op_type
```
  to
```
"create"
```
  (append-only).
The decision: create/prepare the target rather than relying on auto-creation with dynamic mapping. Wrong or missing mappings cause partial failures or silent type coercion.

Data needed: destination name, corrected or compatible mappings, and deployment-specific settings constraints.
Build and submit the reindex request. Call
```
POST /_reindex?wait_for_completion=false
```
for any copy that may take more than a few seconds or when the user says the index is large — the response returns a task id immediately instead of blocking.
Request body essentials:
- ```
source.index
```
  — source index or data stream (correct name, not reversed with
```
dest.index
```
  ).
- ```
dest.index
```
  — prepared destination from step 4.
- ```
source.query
```
  — include only when step 3 chose a filtered subset.
- ```
conflicts: "proceed"
```
  — when retrying a partially complete reindex.
- Optional tuning:
```
source.size
```
  (batch size),
```
requests_per_second
```
  (throttle),
```
slices=auto
```
  on local reindex only (parallelize per primary shard — never for remote),
```
scroll
```
  (increase keep-alive on slow clusters),
```
max_docs
```
  (test runs),
```
script
```
  (transform),
```
dest.pipeline
```
  (ingest enrichment).
Example filtered subset (January 2025 only):
json
```
{
  "source": {
    "index": "eval-reindex-src",
    "query": {
      "range": {
        "@timestamp": { "gte": "2025-01-01", "lt": "2025-02-01" }
      }
    }
  },
  "dest": { "index": "eval-reindex-jan" }
}
```
Do not reach for
```
_split
```
,
```
_shrink
```
, or snapshot/restore when the task is a filtered subset copy or a straight document migration — those APIs solve different problems.
Track the task to completion. Store the task id from the reindex response. Poll
```
GET /_tasks/{task_id}
```
until
```
completed
```
is
```
true
```
. Read
```
status.total
```
,
```
status.created
```
, and
```
response.failures
```
. On Self-Managed / ECH you may also list active reindex tasks with
```
GET /_tasks?actions=*reindex&detailed
```
; on Serverless, query by task id only (list/cancel are not available). Adjust throttling mid-flight with
```
POST /_reindex/{task_id}/_rethrottle?requests_per_second=N
```
without canceling.
Verify and report the destination count. Call
```
GET /{dest}/_count
```
(works on all deployment types). On Self-Managed / ECH you may also use
```
GET /_cat/count/{dest}?h=count
```
. Compare source filter expectations to the destination count. Report the exact count from the destination — do not estimate or guess.
After a successful full copy, restore production settings on the destination with
```
PUT /{dest}/_settings
```
(replicas and refresh interval on Self-Managed / ECH; refresh interval only on Serverless).

确认连通性与部署类型。调用
```
GET /
```
，读取
```
build_flavor
```
和
```
version.number
```
，以了解分片、副本和集群设置API是否可用（Serverless会在内部管理分片/副本，并阻止大多数
```
_cluster/*
```
API）。决策：仅当集群可访问时继续操作。如果调用失败，请停止——请勿猜测端点或凭证。
选择本地或远程重新索引。比较源索引和目标索引的所在位置。
- 同一集群 — 使用本地重新索引：仅需指定
```
source.index
```
  和
```
dest.index
```
  。当两个索引都在当前连接的集群上时，请勿添加
```
source.remote
```
  参数。
- 不同集群 — 使用远程重新索引：添加
```
source.remote
```
  参数，包含远程集群的URL和凭证。远程重新索引不支持分片处理；可通过基于查询的分区（日期范围、术语过滤器）并行发送请求来弥补。确认远程主机已在自托管/ECH的集群配置中加入白名单（
```
reindex.remote.whitelist
```
  ）；Serverless会在内部管理白名单（仅支持ECH远程，技术预览阶段）。
所需信息：源索引名称、目标索引名称，以及两者是否处于同一集群。
检查源索引——切勿猜测字段名或文档数量。调用
```
GET /{source}/_mapping
```
确认字段名和类型。调用
```
GET /{source}/_count
```
（在自托管/ECH上可使用
```
GET /_cat/count/{source}?h=count
```
）了解文档总数。
决策：完整复制还是过滤子集。
- 完整复制 — 省略
```
source.query
```
  （默认匹配所有文档）。
- 过滤子集 — 添加
```
source.query
```
  参数并使用Query DSL。对于时间范围，可对时间戳字段（通常为
```
@timestamp
```
  ）使用
```
range
```
  过滤器，例如
```
"gte": "2025-01-01", "lt": "2025-02-01"
```
  表示2025年1月的数据。当用户要求按日期范围或其他条件过滤时，请勿执行全索引复制。
所需信息：用户的过滤条件，以及经映射确认的字段名。
复制前准备目标索引。
```
_reindex
```
不会复制映射、分片数量或分析器。需通过
```
PUT /{dest}
```
创建目标索引，并基于源索引映射设置明确的配置和映射。
- 在自托管/ECH上：复制期间将目标索引的
```
number_of_replicas
```
  设为
```
0
```
  ，
```
refresh_interval
```
  设为
```
"-1"
```
  以提升写入吞吐量；复制完成后，通过
```
PUT /{dest}/_settings
```
  恢复生产环境配置。
- 在Serverless上：无需设置
```
number_of_shards
```
  和
```
number_of_replicas
```
  （由Elastic管理）；复制期间可设置
```
refresh_interval: "-1"
```
  。
- 对于数据流目标：确保存在包含
```
data_stream: {}
```
  的索引模板，创建数据流，并将
```
dest.op_type
```
  设为
```
"create"
```
  （仅追加模式）。
决策：手动创建/准备目标索引，而非依赖自动创建的动态映射。错误或缺失的映射会导致部分失败或静默类型转换。

所需信息：目标索引名称、校正后的兼容映射，以及部署特定的配置限制。
构建并提交重新索引请求。对于可能耗时超过几秒的复制操作，或用户表明索引较大时，调用
```
POST /_reindex?wait_for_completion=false
```
——响应会立即返回任务ID，而非阻塞等待。
请求主体要点：
- ```
source.index
```
  — 源索引或数据流（名称正确，请勿与
```
dest.index
```
  混淆）。
- ```
dest.index
```
  — 步骤4中准备好的目标索引。
- ```
source.query
```
  — 仅在步骤3选择过滤子集时包含。
- ```
conflicts: "proceed"
```
  — 当重试部分完成的重新索引时使用。
- 可选调优参数：
```
source.size
```
  （批量大小）、
```
requests_per_second
```
  （限速）、
```
slices=auto
```
  （仅适用于本地重新索引，按主分片并行处理——远程索引切勿使用）、
```
scroll
```
  （在慢集群上延长存活时间）、
```
max_docs
```
  （测试运行）、
```
script
```
  （数据转换）、
```
dest.pipeline
```
  （摄入增强）。
过滤子集示例（仅2025年1月数据）：
json
```
{
  "source": {
    "index": "eval-reindex-src",
    "query": {
      "range": {
        "@timestamp": { "gte": "2025-01-01", "lt": "2025-02-01" }
      }
    }
  },
  "dest": { "index": "eval-reindex-jan" }
}
```
当任务为过滤子集复制或直接文档迁移时，请勿使用
```
_split
```
、
```
_shrink
```
或快照/恢复——这些API用于解决其他问题。
跟踪任务直至完成。保存重新索引响应中的任务ID，轮询
```
GET /_tasks/{task_id}
```
直到
```
completed
```
变为
```
true
```
。读取
```
status.total
```
、
```
status.created
```
和
```
response.failures
```
。在自托管/ECH上，还可使用
```
GET /_tasks?actions=*reindex&detailed
```
列出活跃的重新索引任务；在Serverless上，仅支持通过任务ID查询（不支持列出/取消任务）。无需取消任务即可通过
```
POST /_reindex/{task_id}/_rethrottle?requests_per_second=N
```
调整限速。
验证并报告目标索引文档数量。调用
```
GET /{dest}/_count
```
（适用于所有部署类型）。在自托管/ECH上，还可使用
```
GET /_cat/count/{dest}?h=count
```
。将源索引过滤后的预期数量与目标索引数量进行比较。报告目标索引的精确数量——请勿估算或猜测。
成功完成完整复制后，通过
```
PUT /{dest}/_settings
```
恢复目标索引的生产环境配置（自托管/ECH上恢复副本数和刷新间隔；Serverless上仅恢复刷新间隔）。

Deployment constraints

部署限制

Capability	Self-Managed / ECH	Serverless
Local reindex	Full support	Full support
Reindex from remote	Full support	Tech Preview — ECH remotes only
`number_of_shards/replicas`	User-configurable	Managed — omit on index creation
`slices=auto` (local only)	Supported	Supported for local reindex
`GET /_cat/count/{index}`	Supported	Not available — use `GET /{index}/_count`
`GET /_tasks` (list/cancel)	Full	Get by task id only
`PUT /_cluster/settings`	Supported	Blocked
`_split` / `_shrink`	Supported	Not available

功能	自托管 / ECH	Serverless
本地重新索引	完全支持	完全支持
远程重新索引	完全支持	技术预览——仅支持ECH远程
`number_of_shards/replicas`	用户可配置	由Elastic管理——创建索引时无需设置
`slices=auto` （仅本地）	支持	支持本地重新索引
`GET /_cat/count/{index}`	支持	不可用——使用 `GET /{index}/_count`
`GET /_tasks` （列出/取消）	完全支持	仅支持通过任务ID查询
`PUT /_cluster/settings`	支持	已禁用
`_split` / `_shrink`	支持	不可用

Consider alternatives first

优先考虑替代方案

Runtime fields — fix field-type mismatches or add computed fields without reindexing when stored values need not change.
Aliases — redirect queries transparently; combine with reindex for zero-downtime mapping changes.
Snapshot and restore (Self-Managed / ECH) — faster whole-index transfer when no transformation is needed.

See the decision tree in references/patterns.md.

运行时字段 — 当存储值无需更改时，可修复字段类型不匹配问题或添加计算字段，无需重新索引。
别名 — 透明重定向查询；结合重新索引可实现零停机映射变更。
快照与恢复（自托管/ECH） — 无需数据转换时，全索引传输速度更快。

请参阅references/patterns.md中的决策树。

Reference material

参考资料

API parameter reference — full
```
POST /_reindex
```
body and query parameters
Multi-step patterns — mapping changes, remote migration, merge, ingest pipeline, performance
Tuning — batch size (
```
source.size
```
), timestamps, versioning
Troubleshooting — mapping conflicts, scroll timeouts, count mismatches

API参数参考 —
```
POST /_reindex
```
完整的请求主体和查询参数
多步骤模式 — 映射变更、远程迁移、合并、摄入管道、性能优化
调优指南 — 批量大小（
```
source.size
```
）、时间戳、版本控制
故障排除 — 映射冲突、滚动超时、数量不匹配

Examples

示例

"Copy
logs-2024
into a new index with a corrected mapping" — create the destination first, then reindex:

json

POST /_reindex
{ "source": { "index": "logs-2024" }, "dest": { "index": "logs-2024-v2" } }

"Reindex a large index in parallel and throttle it" — slice automatically and cap the request rate:

json

POST /_reindex?slices=auto&requests_per_second=2000
{ "source": { "index": "events" }, "dest": { "index": "events-v2" } }

"Migrate only recent documents" — filter the source with a query:

json

POST /_reindex
{
  "source": { "index": "metrics", "query": { "range": { "@timestamp": { "gte": "now-30d" } } } },
  "dest": { "index": "metrics-recent" }
}

"将
logs-2024
复制到具有修正映射的新索引中" — 先创建目标索引，再执行重新索引：

json

POST /_reindex
{ "source": { "index": "logs-2024" }, "dest": { "index": "logs-2024-v2" } }

"并行重新索引大型索引并限速" — 自动分片并限制请求速率：

json

POST /_reindex?slices=auto&requests_per_second=2000
{ "source": { "index": "events" }, "dest": { "index": "events-v2" } }

"仅迁移近期文档" — 使用查询过滤源索引：

json

POST /_reindex
{
  "source": { "index": "metrics", "query": { "range": { "@timestamp": { "gte": "now-30d" } } } },
  "dest": { "index": "metrics-recent" }
}

Guidelines

指南

Confirm deployment type first. Call
```
GET /
```
and read
```
build_flavor
```
; shard, replica, cluster-settings, and task APIs differ between Self-Managed / ECH and Serverless (see Deployment constraints).
Prefer an alternative when it fits. Runtime fields, aliases, or snapshot-and-restore often avoid a full reindex.
Tune the destination for the copy. On Self-Managed / ECH set
```
number_of_replicas: 0
```
and
```
refresh_interval: "-1"
```
during the copy, then restore production settings afterward; on Serverless these are managed.
Parallelize large copies. Use
```
slices=auto
```
for local reindex and throttle with
```
requests_per_second
```
to protect the cluster.
Run big jobs asynchronously. Submit with
```
wait_for_completion=false
```
and poll the task instead of blocking.
Verify by count. Compare the source filter expectation to the exact destination
```
GET /{dest}/_count
```
— never estimate.

首先确认部署类型。调用
```
GET /
```
并读取
```
build_flavor
```
；自托管/ECH与Serverless的分片、副本、集群设置和任务API存在差异（请参阅部署限制）。
适合时优先选择替代方案。运行时字段、别名或快照与恢复通常可避免全量重新索引。
为复制操作调优目标索引。在自托管/ECH上，复制期间将
```
number_of_replicas
```
设为
```
0
```
、
```
refresh_interval
```
设为
```
"-1"
```
，复制完成后恢复生产环境配置；Serverless上这些配置由系统管理。
并行处理大型复制任务。对本地重新索引使用
```
slices=auto
```
，并通过
```
requests_per_second
```
限速以保护集群。
异步运行大型任务。使用
```
wait_for_completion=false
```
提交任务，轮询任务状态而非阻塞等待。
通过数量验证结果。将源索引过滤后的预期数量与目标索引的
```
GET /{dest}/_count
```
精确值进行比较——切勿估算。

Operations

操作对照表

HTTP API (shorthand)	`elastic` CLI command
`GET /`	`elastic es info`
`GET /{index}/_mapping`	`elastic es indices get-mapping --index '<index>'`
`GET /{index}/_count`	`elastic es count --index '<index>'`
`GET /_cat/count/{index}?h=count`	`elastic es cat count --index '<index>' --h count`
`PUT /{index}`	`elastic es indices create --index '<index>' --mappings '<json>' --settings '<json>'`
`PUT /{index}/_settings`	`elastic es indices put-settings --index '<index>' --settings '<json>'`
`POST /_reindex?wait_for_completion=false`	`elastic es reindex --wait-for-completion false --source '<json>' --dest '<json>'`
`GET /_tasks/{task_id}`	`elastic es tasks get --task-id '<task_id>'`
`GET /_tasks?actions=*reindex&detailed`	`elastic es tasks list --actions '*reindex' --detailed`
`POST /_tasks/{task_id}/_cancel`	`elastic es tasks cancel --task-id '<task_id>'`
`POST /_reindex/{task_id}/_rethrottle?requests_per_second=N`	`elastic es reindex-rethrottle --task-id '<task_id>' --requests-per-second <N>`

HTTP API（简写形式）	`elastic` CLI命令
`GET /`	`elastic es info`
`GET /{index}/_mapping`	`elastic es indices get-mapping --index '<index>'`
`GET /{index}/_count`	`elastic es count --index '<index>'`
`GET /_cat/count/{index}?h=count`	`elastic es cat count --index '<index>' --h count`
`PUT /{index}`	`elastic es indices create --index '<index>' --mappings '<json>' --settings '<json>'`
`PUT /{index}/_settings`	`elastic es indices put-settings --index '<index>' --settings '<json>'`
`POST /_reindex?wait_for_completion=false`	`elastic es reindex --wait-for-completion false --source '<json>' --dest '<json>'`
`GET /_tasks/{task_id}`	`elastic es tasks get --task-id '<task_id>'`
`GET /_tasks?actions=*reindex&detailed`	`elastic es tasks list --actions '*reindex' --detailed`
`POST /_tasks/{task_id}/_cancel`	`elastic es tasks cancel --task-id '<task_id>'`
`POST /_reindex/{task_id}/_rethrottle?requests_per_second=N`	`elastic es reindex-rethrottle --task-id '<task_id>' --requests-per-second <N>`