New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« 更新索引设置 API 索引生命周期管理 API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST API ›索引 API

更新映射 API

编辑

更新映射 API

编辑

向现有数据流或索引添加新字段。您还可以使用此 API 更改现有字段的搜索设置。

对于数据流，这些更改默认应用于所有后备索引。

resp = client.indices.put_mapping(
    index="my-index-000001",
    properties={
        "email": {
            "type": "keyword"
        }
    },
)
print(resp)
response = client.indices.put_mapping(
  index: 'my-index-000001',
  body: {
    properties: {
      email: {
        type: 'keyword'
      }
    }
  }
)
puts response
const response = await client.indices.putMapping({
  index: "my-index-000001",
  properties: {
    email: {
      type: "keyword",
    },
  },
});
console.log(response);
PUT /my-index-000001/_mapping
{
  "properties": {
    "email": {
      "type": "keyword"
    }
  }
}
Copy as curlTry in Elastic 

请求

编辑

PUT /<target>/_mapping

先决条件

编辑

  • 如果启用了 Elasticsearch 安全功能，您必须对目标数据流、索引或别名具有 manage 索引权限。

    [7.9] 在 7.9 中已弃用。 如果请求的目标是索引或索引别名，您也可以使用 create、create_doc、index 或 write 索引权限来更新其映射。

路径参数

编辑
<target>
（必需，字符串）用于限制请求的数据流、索引和别名的逗号分隔列表。支持通配符（*）。要定位所有数据流和索引，请省略此参数或使用 * 或 _all。

查询参数

编辑
allow_no_indices

（可选，布尔值）如果为 false，则如果任何通配符表达式、索引别名 或 _all 值仅定位丢失或关闭的索引，则请求将返回错误。即使请求定位其他打开的索引，此行为也适用。例如，如果索引以 foo 开头，但没有索引以 bar 开头，则定位 foo*,bar* 的请求将返回错误。

默认为 false。

expand_wildcards

（可选，字符串）通配符模式可以匹配的索引类型。如果请求可以定位数据流，则此参数确定通配符表达式是否匹配隐藏的数据流。支持逗号分隔的值，例如 open,hidden。有效值为

all
匹配任何数据流或索引，包括隐藏的数据流或索引。
open
匹配打开的非隐藏索引。也匹配任何非隐藏的数据流。
closed
匹配关闭的非隐藏索引。也匹配任何非隐藏的数据流。数据流不能关闭。
hidden
匹配隐藏的数据流和隐藏的索引。必须与 open、closed 或两者组合使用。
none
不接受通配符模式。

默认为 open。

ignore_unavailable
（可选，布尔值）如果为 false，则如果请求定位丢失或关闭的索引，则请求将返回错误。默认为 false。
master_timeout
（可选，时间单位）等待主节点的时间段。如果主节点在超时过期之前不可用，则请求失败并返回错误。默认为 30s。也可以设置为 -1 以指示请求不应超时。
timeout
（可选，时间单位）在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时过期之前未收到任何响应，则集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。
write_index_only
（可选，布尔值）如果为 true，则映射仅应用于目标的当前写入索引。默认为 false。

请求正文

编辑
properties

（必需，映射对象）字段的映射。对于新字段，此映射可以包括

对于现有字段，请参阅更改现有字段的映射。

示例

编辑

单目标示例

编辑

更新映射 API 需要现有数据流或索引。以下创建索引 API 请求创建没有映射的 publications 索引。

$params = [
    'index' => 'publications',
];
$response = $client->indices()->create($params);
resp = client.indices.create(
    index="publications",
)
print(resp)
response = client.indices.create(
  index: 'publications'
)
puts response
res, err := es.Indices.Create("publications")
fmt.Println(res, err)
const response = await client.indices.create({
  index: "publications",
});
console.log(response);
PUT /publications
Copy as curlTry in Elastic 

以下更新映射 API 请求将新的 text 字段 title 添加到 publications 索引。

$params = [
    'index' => 'publications',
    'body' => [
        'properties' => [
            'title' => [
                'type' => 'text',
            ],
        ],
    ],
];
$response = $client->indices()->putMapping($params);
resp = client.indices.put_mapping(
    index="publications",
    properties={
        "title": {
            "type": "text"
        }
    },
)
print(resp)
response = client.indices.put_mapping(
  index: 'publications',
  body: {
    properties: {
      title: {
        type: 'text'
      }
    }
  }
)
puts response
res, err := es.Indices.PutMapping(
	[]string{"publications"},
	strings.NewReader(`{
	  "properties": {
	    "title": {
	      "type": "text"
	    }
	  }
	}`),
)
fmt.Println(res, err)
const response = await client.indices.putMapping({
  index: "publications",
  properties: {
    title: {
      type: "text",
    },
  },
});
console.log(response);
PUT /publications/_mapping
{
  "properties": {
    "title":  { "type": "text"}
  }
}
Copy as curlTry in Elastic 

多目标

编辑

更新映射 API 可以通过单个请求应用于多个数据流或索引。例如，您可以同时更新 my-index-000001 和 my-index-000002 索引的映射

resp = client.indices.create(
    index="my-index-000001",
)
print(resp)

resp1 = client.indices.create(
    index="my-index-000002",
)
print(resp1)

resp2 = client.indices.put_mapping(
    index="my-index-000001,my-index-000002",
    properties={
        "user": {
            "properties": {
                "name": {
                    "type": "keyword"
                }
            }
        }
    },
)
print(resp2)
response = client.indices.create(
  index: 'my-index-000001'
)
puts response

response = client.indices.create(
  index: 'my-index-000002'
)
puts response

response = client.indices.put_mapping(
  index: 'my-index-000001,my-index-000002',
  body: {
    properties: {
      user: {
        properties: {
          name: {
            type: 'keyword'
          }
        }
      }
    }
  }
)
puts response
const response = await client.indices.create({
  index: "my-index-000001",
});
console.log(response);

const response1 = await client.indices.create({
  index: "my-index-000002",
});
console.log(response1);

const response2 = await client.indices.putMapping({
  index: "my-index-000001,my-index-000002",
  properties: {
    user: {
      properties: {
        name: {
          type: "keyword",
        },
      },
    },
  },
});
console.log(response2);
# Create the two indices
PUT /my-index-000001
PUT /my-index-000002

# Update both mappings
PUT /my-index-000001,my-index-000002/_mapping
{
  "properties": {
    "user": {
      "properties": {
        "name": {
          "type": "keyword"
        }
      }
    }
  }
}
Copy as curlTry in Elastic 

向现有对象字段添加新属性

编辑

您可以使用更新映射 API 向现有的object 字段添加新属性。要了解其工作原理，请尝试以下示例。

使用创建索引 API 创建一个包含 name 对象字段和内部 first 文本字段的索引。

resp = client.indices.create(
    index="my-index-000001",
    mappings={
        "properties": {
            "name": {
                "properties": {
                    "first": {
                        "type": "text"
                    }
                }
            }
        }
    },
)
print(resp)
response = client.indices.create(
  index: 'my-index-000001',
  body: {
    mappings: {
      properties: {
        name: {
          properties: {
            first: {
              type: 'text'
            }
          }
        }
      }
    }
  }
)
puts response
res, err := es.Indices.Create(
	"my-index-000001",
	es.Indices.Create.WithBody(strings.NewReader(`{
	  "mappings": {
	    "properties": {
	      "name": {
	        "properties": {
	          "first": {
	            "type": "text"
	          }
	        }
	      }
	    }
	  }
	}`)),
)
fmt.Println(res, err)
const response = await client.indices.create({
  index: "my-index-000001",
  mappings: {
    properties: {
      name: {
        properties: {
          first: {
            type: "text",
          },
        },
      },
    },
  },
});
console.log(response);
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "name": {
        "properties": {
          "first": {
            "type": "text"
          }
        }
      }
    }
  }
}
Copy as curlTry in Elastic 

使用更新映射 API 将新的内部 last 文本字段添加到 name 字段。

resp = client.indices.put_mapping(
    index="my-index-000001",
    properties={
        "name": {
            "properties": {
                "last": {
                    "type": "text"
                }
            }
        }
    },
)
print(resp)
response = client.indices.put_mapping(
  index: 'my-index-000001',
  body: {
    properties: {
      name: {
        properties: {
          last: {
            type: 'text'
          }
        }
      }
    }
  }
)
puts response
res, err := es.Indices.PutMapping(
	[]string{"my-index-000001"},
	strings.NewReader(`{
	  "properties": {
	    "name": {
	      "properties": {
	        "last": {
	          "type": "text"
	        }
	      }
	    }
	  }
	}`),
)
fmt.Println(res, err)
const response = await client.indices.putMapping({
  index: "my-index-000001",
  properties: {
    name: {
      properties: {
        last: {
          type: "text",
        },
      },
    },
  },
});
console.log(response);
PUT /my-index-000001/_mapping
{
  "properties": {
    "name": {
      "properties": {
        "last": {
          "type": "text"
        }
      }
    }
  }
}
Copy as curlTry in Elastic 

向现有字段添加多字段

编辑

多字段允许您以不同的方式索引同一字段。您可以使用更新映射 API 更新 fields 映射参数，并为现有字段启用多字段。

如果在添加多字段时索引（或数据流）包含文档，则这些文档将没有新多字段的值。您可以使用按查询更新 API填充新的多字段。

要了解其工作原理，请尝试以下示例。

使用创建索引 API 创建一个带有 city 文本 字段的索引。

resp = client.indices.create(
    index="my-index-000001",
    mappings={
        "properties": {
            "city": {
                "type": "text"
            }
        }
    },
)
print(resp)
response = client.indices.create(
  index: 'my-index-000001',
  body: {
    mappings: {
      properties: {
        city: {
          type: 'text'
        }
      }
    }
  }
)
puts response
res, err := es.Indices.Create(
	"my-index-000001",
	es.Indices.Create.WithBody(strings.NewReader(`{
	  "mappings": {
	    "properties": {
	      "city": {
	        "type": "text"
	      }
	    }
	  }
	}`)),
)
fmt.Println(res, err)
const response = await client.indices.create({
  index: "my-index-000001",
  mappings: {
    properties: {
      city: {
        type: "text",
      },
    },
  },
});
console.log(response);
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "city": {
        "type": "text"
      }
    }
  }
}
Copy as curlTry in Elastic 

虽然文本字段非常适合全文搜索，但 关键字字段未进行分析，可能更适合用于排序或聚合。

使用更新映射 API 为 city 字段启用多字段。此请求添加了可用于排序的 city.raw 关键字多字段。

resp = client.indices.put_mapping(
    index="my-index-000001",
    properties={
        "city": {
            "type": "text",
            "fields": {
                "raw": {
                    "type": "keyword"
                }
            }
        }
    },
)
print(resp)
response = client.indices.put_mapping(
  index: 'my-index-000001',
  body: {
    properties: {
      city: {
        type: 'text',
        fields: {
          raw: {
            type: 'keyword'
          }
        }
      }
    }
  }
)
puts response
res, err := es.Indices.PutMapping(
	[]string{"my-index-000001"},
	strings.NewReader(`{
	  "properties": {
	    "city": {
	      "type": "text",
	      "fields": {
	        "raw": {
	          "type": "keyword"
	        }
	      }
	    }
	  }
	}`),
)
fmt.Println(res, err)
const response = await client.indices.putMapping({
  index: "my-index-000001",
  properties: {
    city: {
      type: "text",
      fields: {
        raw: {
          type: "keyword",
        },
      },
    },
  },
});
console.log(response);
PUT /my-index-000001/_mapping
{
  "properties": {
    "city": {
      "type": "text",
      "fields": {
        "raw": {
          "type": "keyword"
        }
      }
    }
  }
}
Copy as curlTry in Elastic 

更改现有字段的受支持映射参数

编辑

每个映射参数的文档都指明了您是否可以使用更新映射 API 为现有字段更新它。例如，您可以使用更新映射 API 更新 ignore_above 参数。

要了解其工作原理，请尝试以下示例。

使用创建索引 API 创建一个包含 user_id 关键字字段的索引。user_id 字段的 ignore_above 参数值为 20。

resp = client.indices.create(
    index="my-index-000001",
    mappings={
        "properties": {
            "user_id": {
                "type": "keyword",
                "ignore_above": 20
            }
        }
    },
)
print(resp)
response = client.indices.create(
  index: 'my-index-000001',
  body: {
    mappings: {
      properties: {
        user_id: {
          type: 'keyword',
          ignore_above: 20
        }
      }
    }
  }
)
puts response
res, err := es.Indices.Create(
	"my-index-000001",
	es.Indices.Create.WithBody(strings.NewReader(`{
	  "mappings": {
	    "properties": {
	      "user_id": {
	        "type": "keyword",
	        "ignore_above": 20
	      }
	    }
	  }
	}`)),
)
fmt.Println(res, err)
const response = await client.indices.create({
  index: "my-index-000001",
  mappings: {
    properties: {
      user_id: {
        type: "keyword",
        ignore_above: 20,
      },
    },
  },
});
console.log(response);
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "user_id": {
        "type": "keyword",
        "ignore_above": 20
      }
    }
  }
}
Copy as curlTry in Elastic 

使用更新映射 API 将 ignore_above 参数值更改为 100。

resp = client.indices.put_mapping(
    index="my-index-000001",
    properties={
        "user_id": {
            "type": "keyword",
            "ignore_above": 100
        }
    },
)
print(resp)
response = client.indices.put_mapping(
  index: 'my-index-000001',
  body: {
    properties: {
      user_id: {
        type: 'keyword',
        ignore_above: 100
      }
    }
  }
)
puts response
res, err := es.Indices.PutMapping(
	[]string{"my-index-000001"},
	strings.NewReader(`{
	  "properties": {
	    "user_id": {
	      "type": "keyword",
	      "ignore_above": 100
	    }
	  }
	}`),
)
fmt.Println(res, err)
const response = await client.indices.putMapping({
  index: "my-index-000001",
  properties: {
    user_id: {
      type: "keyword",
      ignore_above: 100,
    },
  },
});
console.log(response);
PUT /my-index-000001/_mapping
{
  "properties": {
    "user_id": {
      "type": "keyword",
      "ignore_above": 100
    }
  }
}
Copy as curlTry in Elastic 

更改现有字段的映射

编辑

除了受支持的映射参数外，您不能更改现有字段的映射或字段类型。更改现有字段可能会使已索引的数据无效。

如果您需要更改数据流后备索引中字段的映射，请参阅更改数据流的映射和设置。

如果您需要更改其他索引中字段的映射，请创建具有正确映射的新索引，并将您的数据重新索引到该索引中。

要了解如何更改索引中现有字段的映射，请尝试以下示例。

使用创建索引 API 创建一个带有 long 字段类型的 user_id 字段的索引。

resp = client.indices.create(
    index="my-index-000001",
    mappings={
        "properties": {
            "user_id": {
                "type": "long"
            }
        }
    },
)
print(resp)
response = client.indices.create(
  index: 'my-index-000001',
  body: {
    mappings: {
      properties: {
        user_id: {
          type: 'long'
        }
      }
    }
  }
)
puts response
const response = await client.indices.create({
  index: "my-index-000001",
  mappings: {
    properties: {
      user_id: {
        type: "long",
      },
    },
  },
});
console.log(response);
PUT /my-index-000001
{
  "mappings" : {
    "properties": {
      "user_id": {
        "type": "long"
      }
    }
  }
}
Copy as curlTry in Elastic 

使用索引 API 索引几个带有 user_id 字段值的文档。

resp = client.index(
    index="my-index-000001",
    refresh="wait_for",
    document={
        "user_id": 12345
    },
)
print(resp)

resp1 = client.index(
    index="my-index-000001",
    refresh="wait_for",
    document={
        "user_id": 12346
    },
)
print(resp1)
response = client.index(
  index: 'my-index-000001',
  refresh: 'wait_for',
  body: {
    user_id: 12_345
  }
)
puts response

response = client.index(
  index: 'my-index-000001',
  refresh: 'wait_for',
  body: {
    user_id: 12_346
  }
)
puts response
const response = await client.index({
  index: "my-index-000001",
  refresh: "wait_for",
  document: {
    user_id: 12345,
  },
});
console.log(response);

const response1 = await client.index({
  index: "my-index-000001",
  refresh: "wait_for",
  document: {
    user_id: 12346,
  },
});
console.log(response1);
POST /my-index-000001/_doc?refresh=wait_for
{
  "user_id" : 12345
}

POST /my-index-000001/_doc?refresh=wait_for
{
  "user_id" : 12346
}
Copy as curlTry in Elastic 

要将 user_id 字段更改为 keyword 字段类型，请使用创建索引 API 创建一个具有正确映射的新索引。

resp = client.indices.create(
    index="my-new-index-000001",
    mappings={
        "properties": {
            "user_id": {
                "type": "keyword"
            }
        }
    },
)
print(resp)
response = client.indices.create(
  index: 'my-new-index-000001',
  body: {
    mappings: {
      properties: {
        user_id: {
          type: 'keyword'
        }
      }
    }
  }
)
puts response
const response = await client.indices.create({
  index: "my-new-index-000001",
  mappings: {
    properties: {
      user_id: {
        type: "keyword",
      },
    },
  },
});
console.log(response);
PUT /my-new-index-000001
{
  "mappings" : {
    "properties": {
      "user_id": {
        "type": "keyword"
      }
    }
  }
}
Copy as curlTry in Elastic 

使用重新索引 API 将文档从旧索引复制到新索引。

resp = client.reindex(
    source={
        "index": "my-index-000001"
    },
    dest={
        "index": "my-new-index-000001"
    },
)
print(resp)
response = client.reindex(
  body: {
    source: {
      index: 'my-index-000001'
    },
    dest: {
      index: 'my-new-index-000001'
    }
  }
)
puts response
const response = await client.reindex({
  source: {
    index: "my-index-000001",
  },
  dest: {
    index: "my-new-index-000001",
  },
});
console.log(response);
POST /_reindex
{
  "source": {
    "index": "my-index-000001"
  },
  "dest": {
    "index": "my-new-index-000001"
  }
}
Copy as curlTry in Elastic 

重命名字段

编辑

重命名字段将使已在旧字段名称下索引的数据无效。相反，添加一个alias字段以创建备用字段名称。

例如，使用创建索引 API 创建一个带有 user_identifier 字段的索引。

resp = client.indices.create(
    index="my-index-000001",
    mappings={
        "properties": {
            "user_identifier": {
                "type": "keyword"
            }
        }
    },
)
print(resp)
response = client.indices.create(
  index: 'my-index-000001',
  body: {
    mappings: {
      properties: {
        user_identifier: {
          type: 'keyword'
        }
      }
    }
  }
)
puts response
res, err := es.Indices.Create(
	"my-index-000001",
	es.Indices.Create.WithBody(strings.NewReader(`{
	  "mappings": {
	    "properties": {
	      "user_identifier": {
	        "type": "keyword"
	      }
	    }
	  }
	}`)),
)
fmt.Println(res, err)
const response = await client.indices.create({
  index: "my-index-000001",
  mappings: {
    properties: {
      user_identifier: {
        type: "keyword",
      },
    },
  },
});
console.log(response);
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "user_identifier": {
        "type": "keyword"
      }
    }
  }
}
Copy as curlTry in Elastic 

使用更新映射 API 为现有 user_identifier 字段添加 user_id 字段别名。

resp = client.indices.put_mapping(
    index="my-index-000001",
    properties={
        "user_id": {
            "type": "alias",
            "path": "user_identifier"
        }
    },
)
print(resp)
response = client.indices.put_mapping(
  index: 'my-index-000001',
  body: {
    properties: {
      user_id: {
        type: 'alias',
        path: 'user_identifier'
      }
    }
  }
)
puts response
res, err := es.Indices.PutMapping(
	[]string{"my-index-000001"},
	strings.NewReader(`{
	  "properties": {
	    "user_id": {
	      "type": "alias",
	      "path": "user_identifier"
	    }
	  }
	}`),
)
fmt.Println(res, err)
const response = await client.indices.putMapping({
  index: "my-index-000001",
  properties: {
    user_id: {
      type: "alias",
      path: "user_identifier",
    },
  },
});
console.log(response);
PUT /my-index-000001/_mapping
{
  "properties": {
    "user_id": {
      "type": "alias",
      "path": "user_identifier"
    }
  }
}
Copy as curlTry in Elastic 
« 更新索引设置 API 索引生命周期管理 API »