« 更新索引设置 API 索引生命周期管理 API »
Elastic 文档 ›Elasticsearch 指南 [8.14] ›REST API ›索引 API

更新映射 API

编辑

更新映射 API编辑

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

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

resp = client.indices.put_mapping(
    index="my-index-000001",
    body={"properties": {"email": {"type": "keyword"}}},
)
print(resp)
response = client.indices.put_mapping(
  index: 'my-index-000001',
  body: {
    properties: {
      email: {
        type: 'keyword'
      }
    }
  }
)
puts response
PUT /my-index-000001/_mapping
{
  "properties": {
    "email": {
      "type": "keyword"
    }
  }
}

请求编辑

PUT /<目标>/_mapping

先决条件编辑

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

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

路径参数编辑

<目标>
(必需，字符串) 用于限制请求的数据流、索引和别名的逗号分隔列表。支持通配符 (*)。要定位所有数据流和索引，请省略此参数或使用 * 或 _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。
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

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

$params = [
    'index' => 'publications',
    'body' => [
        'properties' => [
            'title' => [
                'type' => 'text',
            ],
        ],
    ],
];
$response = $client->indices()->putMapping($params);
resp = client.indices.put_mapping(
    index="publications",
    body={"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',
  body: {
    properties: {
      title: {
        type: 'text'
      }
    }
  }
})
console.log(response)
PUT /publications/_mapping
{
  "properties": {
    "title":  { "type": "text"}
  }
}

多个目标编辑

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

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

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

resp = client.indices.put_mapping(
    index=["my-index-000001", "my-index-000002"],
    body={
        "properties": {
            "user": {"properties": {"name": {"type": "keyword"}}}
        }
    },
)
print(resp)
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
# 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"
        }
      }
    }
  }
}

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

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

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

resp = client.indices.create(
    index="my-index-000001",
    body={
        "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)
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "name": {
        "properties": {
          "first": {
            "type": "text"
          }
        }
      }
    }
  }
}

使用更新映射 API 向 name 字段添加一个新的内部 last 文本字段。

resp = client.indices.put_mapping(
    index="my-index-000001",
    body={
        "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)
PUT /my-index-000001/_mapping
{
  "properties": {
    "name": {
      "properties": {
        "last": {
          "type": "text"
        }
      }
    }
  }
}

向现有字段添加多字段编辑

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

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

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

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

resp = client.indices.create(
    index="my-index-000001",
    body={"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)
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "city": {
        "type": "text"
      }
    }
  }
}

虽然文本字段非常适合全文本搜索，但 关键字 字段不会被分析，可能更适合排序或聚合。

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

resp = client.indices.put_mapping(
    index="my-index-000001",
    body={
        "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)
PUT /my-index-000001/_mapping
{
  "properties": {
    "city": {
      "type": "text",
      "fields": {
        "raw": {
          "type": "keyword"
        }
      }
    }
  }
}

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

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

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

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

resp = client.indices.create(
    index="my-index-000001",
    body={
        "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)
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "user_id": {
        "type": "keyword",
        "ignore_above": 20
      }
    }
  }
}

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

resp = client.indices.put_mapping(
    index="my-index-000001",
    body={
        "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)
PUT /my-index-000001/_mapping
{
  "properties": {
    "user_id": {
      "type": "keyword",
      "ignore_above": 100
    }
  }
}

更改现有字段的映射编辑

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

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

如果您需要更改其他索引中的字段映射，请使用正确的映射创建一个新索引，然后将您的数据 重新索引 到该索引中。

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

使用 创建索引 API 创建一个包含 user_id 字段的索引，该字段使用 long 字段类型。

resp = client.indices.create(
    index="my-index-000001",
    body={"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
PUT /my-index-000001
{
  "mappings" : {
    "properties": {
      "user_id": {
        "type": "long"
      }
    }
  }
}

使用 索引 API 索引几个包含 user_id 字段值的文档。

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

resp = client.index(
    index="my-index-000001",
    refresh="wait_for",
    body={"user_id": 12346},
)
print(resp)
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
POST /my-index-000001/_doc?refresh=wait_for
{
  "user_id" : 12345
}

POST /my-index-000001/_doc?refresh=wait_for
{
  "user_id" : 12346
}

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

resp = client.indices.create(
    index="my-new-index-000001",
    body={"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
PUT /my-new-index-000001
{
  "mappings" : {
    "properties": {
      "user_id": {
        "type": "keyword"
      }
    }
  }
}

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

resp = client.reindex(
    body={
        "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
POST /_reindex
{
  "source": {
    "index": "my-index-000001"
  },
  "dest": {
    "index": "my-new-index-000001"
  }
}

重命名字段编辑

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

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

resp = client.indices.create(
    index="my-index-000001",
    body={
        "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)
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "user_identifier": {
        "type": "keyword"
      }
    }
  }
}

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

resp = client.indices.put_mapping(
    index="my-index-000001",
    body={
        "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)
PUT /my-index-000001/_mapping
{
  "properties": {
    "user_id": {
      "type": "alias",
      "path": "user_identifier"
    }
  }
}
« 更新索引设置 API 索引生命周期管理 API »