修改数据流
编辑修改数据流
编辑更改数据流的映射和设置
编辑每个数据流都有一个匹配的索引模板。该模板中的映射和索引设置会应用于为数据流创建的新后备索引。这包括数据流的第一个后备索引,该索引在创建数据流时自动生成。
在创建数据流之前,我们建议您仔细考虑在此模板中包含哪些映射和设置。
如果以后需要更改数据流的映射或设置,您有以下几种选择
如果您的更改包括修改现有字段映射或静态索引设置,则通常需要重新索引才能将更改应用于数据流的后备索引。如果您已经执行重新索引,则可以使用相同的过程添加新的字段映射并更改动态索引设置。请参阅使用重新索引来更改映射或设置。
向数据流添加新的字段映射
编辑要为数据流中的新字段添加映射,请按照以下步骤操作
-
更新数据流使用的索引模板。这确保了将新的字段映射添加到为该流创建的未来后备索引中。
例如,
my-data-stream-template
是my-data-stream
使用的现有索引模板。以下创建或更新索引模板请求将新字段
message
的映射添加到模板。resp = client.indices.put_index_template( name="my-data-stream-template", index_patterns=[ "my-data-stream*" ], data_stream={}, priority=500, template={ "mappings": { "properties": { "message": { "type": "text" } } } }, ) print(resp)
response = client.indices.put_index_template( name: 'my-data-stream-template', body: { index_patterns: [ 'my-data-stream*' ], data_stream: {}, priority: 500, template: { mappings: { properties: { message: { type: 'text' } } } } } ) puts response
const response = await client.indices.putIndexTemplate({ name: "my-data-stream-template", index_patterns: ["my-data-stream*"], data_stream: {}, priority: 500, template: { mappings: { properties: { message: { type: "text", }, }, }, }, }); console.log(response);
-
使用更新映射 API 将新的字段映射添加到数据流。默认情况下,这会将映射添加到流的现有后备索引中,包括写入索引。
以下更新映射 API 请求将新的
message
字段映射添加到my-data-stream
。resp = client.indices.put_mapping( index="my-data-stream", properties={ "message": { "type": "text" } }, ) print(resp)
response = client.indices.put_mapping( index: 'my-data-stream', body: { properties: { message: { type: 'text' } } } ) puts response
const response = await client.indices.putMapping({ index: "my-data-stream", properties: { message: { type: "text", }, }, }); console.log(response);
PUT /my-data-stream/_mapping { "properties": { "message": { "type": "text" } } }
要仅将映射添加到流的写入索引,请将更新映射 API 的
write_index_only
查询参数设置为true
。以下更新映射请求仅将新的
message
字段映射添加到my-data-stream
的写入索引。新的字段映射不会添加到流的其他后备索引中。resp = client.indices.put_mapping( index="my-data-stream", write_index_only=True, properties={ "message": { "type": "text" } }, ) print(resp)
response = client.indices.put_mapping( index: 'my-data-stream', write_index_only: true, body: { properties: { message: { type: 'text' } } } ) puts response
const response = await client.indices.putMapping({ index: "my-data-stream", write_index_only: "true", properties: { message: { type: "text", }, }, }); console.log(response);
PUT /my-data-stream/_mapping?write_index_only=true { "properties": { "message": { "type": "text" } } }
更改数据流中现有的字段映射
编辑每个映射参数的文档都指示您是否可以使用更新映射 API 为现有字段更新它。要为现有字段更新这些参数,请按照以下步骤操作
-
更新数据流使用的索引模板。这确保了更新后的字段映射添加到为该流创建的未来后备索引中。
例如,
my-data-stream-template
是my-data-stream
使用的现有索引模板。以下创建或更新索引模板请求将
host.ip
字段的ignore_malformed
映射参数的参数更改为true
。resp = client.indices.put_index_template( name="my-data-stream-template", index_patterns=[ "my-data-stream*" ], data_stream={}, priority=500, template={ "mappings": { "properties": { "host": { "properties": { "ip": { "type": "ip", "ignore_malformed": True } } } } } }, ) print(resp)
response = client.indices.put_index_template( name: 'my-data-stream-template', body: { index_patterns: [ 'my-data-stream*' ], data_stream: {}, priority: 500, template: { mappings: { properties: { host: { properties: { ip: { type: 'ip', ignore_malformed: true } } } } } } } ) puts response
const response = await client.indices.putIndexTemplate({ name: "my-data-stream-template", index_patterns: ["my-data-stream*"], data_stream: {}, priority: 500, template: { mappings: { properties: { host: { properties: { ip: { type: "ip", ignore_malformed: true, }, }, }, }, }, }, }); console.log(response);
-
使用更新映射 API 将映射更改应用于数据流。默认情况下,这会将更改应用于流的现有后备索引,包括写入索引。
以下更新映射 API 请求以
my-data-stream
为目标。该请求将host.ip
字段的ignore_malformed
映射参数的参数更改为true
。resp = client.indices.put_mapping( index="my-data-stream", properties={ "host": { "properties": { "ip": { "type": "ip", "ignore_malformed": True } } } }, ) print(resp)
response = client.indices.put_mapping( index: 'my-data-stream', body: { properties: { host: { properties: { ip: { type: 'ip', ignore_malformed: true } } } } } ) puts response
const response = await client.indices.putMapping({ index: "my-data-stream", properties: { host: { properties: { ip: { type: "ip", ignore_malformed: true, }, }, }, }, }); console.log(response);
PUT /my-data-stream/_mapping { "properties": { "host": { "properties": { "ip": { "type": "ip", "ignore_malformed": true } } } } }
要仅将映射更改应用于流的写入索引,请将 put mapping API 的
write_index_only
查询参数设置为true
。以下更新映射请求仅更改
my-data-stream
的写入索引的host.ip
字段的映射。该更改不会应用于流的其他后备索引。resp = client.indices.put_mapping( index="my-data-stream", write_index_only=True, properties={ "host": { "properties": { "ip": { "type": "ip", "ignore_malformed": True } } } }, ) print(resp)
response = client.indices.put_mapping( index: 'my-data-stream', write_index_only: true, body: { properties: { host: { properties: { ip: { type: 'ip', ignore_malformed: true } } } } } ) puts response
const response = await client.indices.putMapping({ index: "my-data-stream", write_index_only: "true", properties: { host: { properties: { ip: { type: "ip", ignore_malformed: true, }, }, }, }, }); console.log(response);
PUT /my-data-stream/_mapping?write_index_only=true { "properties": { "host": { "properties": { "ip": { "type": "ip", "ignore_malformed": true } } } } }
除了受支持的映射参数外,我们不建议您更改现有字段的映射或字段数据类型,即使在数据流的匹配索引模板或其后备索引中也是如此。更改现有字段的映射可能会使已索引的任何数据无效。
如果需要更改现有字段的映射,请创建一个新的数据流并将数据重新索引到其中。请参阅使用重新索引来更改映射或设置。
更改数据流的动态索引设置
编辑要更改数据流的动态索引设置,请按照以下步骤操作
-
更新数据流使用的索引模板。这确保了该设置应用于为该流创建的未来后备索引。
例如,
my-data-stream-template
是my-data-stream
使用的现有索引模板。以下创建或更新索引模板请求将模板的
index.refresh_interval
索引设置更改为30s
(30 秒)。resp = client.indices.put_index_template( name="my-data-stream-template", index_patterns=[ "my-data-stream*" ], data_stream={}, priority=500, template={ "settings": { "index.refresh_interval": "30s" } }, ) print(resp)
response = client.indices.put_index_template( name: 'my-data-stream-template', body: { index_patterns: [ 'my-data-stream*' ], data_stream: {}, priority: 500, template: { settings: { 'index.refresh_interval' => '30s' } } } ) puts response
const response = await client.indices.putIndexTemplate({ name: "my-data-stream-template", index_patterns: ["my-data-stream*"], data_stream: {}, priority: 500, template: { settings: { "index.refresh_interval": "30s", }, }, }); console.log(response);
-
使用更新索引设置 API 更新数据流的索引设置。默认情况下,这会将设置应用于流的现有后备索引,包括写入索引。
以下更新索引设置 API 请求更新
my-data-stream
的index.refresh_interval
设置。resp = client.indices.put_settings( index="my-data-stream", settings={ "index": { "refresh_interval": "30s" } }, ) print(resp)
response = client.indices.put_settings( index: 'my-data-stream', body: { index: { refresh_interval: '30s' } } ) puts response
const response = await client.indices.putSettings({ index: "my-data-stream", settings: { index: { refresh_interval: "30s", }, }, }); console.log(response);
PUT /my-data-stream/_settings { "index": { "refresh_interval": "30s" } }
更改数据流的静态索引设置
编辑仅当创建后备索引时才能设置静态索引设置。您不能使用更新索引设置 API 更新静态索引设置。
要将新的静态设置应用于未来的后备索引,请更新数据流使用的索引模板。该设置会自动应用于更新后创建的任何后备索引。
例如,my-data-stream-template
是 my-data-stream
使用的现有索引模板。
以下创建或更新索引模板 API 请求将新的 sort.field
和 sort.order index
设置添加到模板。
resp = client.indices.put_index_template( name="my-data-stream-template", index_patterns=[ "my-data-stream*" ], data_stream={}, priority=500, template={ "settings": { "sort.field": [ "@timestamp" ], "sort.order": [ "desc" ] } }, ) print(resp)
response = client.indices.put_index_template( name: 'my-data-stream-template', body: { index_patterns: [ 'my-data-stream*' ], data_stream: {}, priority: 500, template: { settings: { 'sort.field' => [ '@timestamp' ], 'sort.order' => [ 'desc' ] } } } ) puts response
const response = await client.indices.putIndexTemplate({ name: "my-data-stream-template", index_patterns: ["my-data-stream*"], data_stream: {}, priority: 500, template: { settings: { "sort.field": ["@timestamp"], "sort.order": ["desc"], }, }, }); console.log(response);
PUT /_index_template/my-data-stream-template { "index_patterns": [ "my-data-stream*" ], "data_stream": { }, "priority": 500, "template": { "settings": { "sort.field": [ "@timestamp"], "sort.order": [ "desc"] } } }
如果需要,您可以滚动数据流,以立即将设置应用于数据流的写入索引。这会影响滚动后添加到流的任何新数据。但是,它不会影响数据流的现有后备索引或现有数据。
要将静态设置更改应用于现有的后备索引,您必须创建一个新的数据流并将数据重新索引到其中。请参阅使用重新索引来更改映射或设置。
使用重新索引来更改映射或设置
编辑您可以使用重新索引来更改数据流的映射或设置。通常需要这样做才能更改现有字段的数据类型或更新后备索引的静态索引设置。
要重新索引数据流,请首先创建或更新索引模板,以便它包含所需的映射或设置更改。然后,您可以将现有数据流重新索引到与模板匹配的新流中。这将模板中的映射和设置更改应用于添加到新数据流的每个文档和后备索引。这些更改还会影响新流创建的任何未来后备索引。
请按照以下步骤操作
-
为新的数据流选择一个名称或索引模式。这个新的数据流将包含来自现有流的数据。
您可以使用 resolve index API 检查该名称或模式是否与任何现有索引、别名或数据流匹配。如果匹配,您应该考虑使用其他名称或模式。
以下 resolve index API 请求检查是否存在以
new-data-stream
开头的任何现有索引、别名或数据流。如果没有,则可以使用new-data-stream*
索引模式创建新的数据流。resp = client.indices.resolve_index( name="new-data-stream*", ) print(resp)
response = client.indices.resolve_index( name: 'new-data-stream*' ) puts response
const response = await client.indices.resolveIndex({ name: "new-data-stream*", }); console.log(response);
GET /_resolve/index/new-data-stream*
该 API 返回以下响应,指示没有现有目标与此模式匹配。
{ "indices": [ ], "aliases": [ ], "data_streams": [ ] }
-
创建或更新索引模板。此模板应包含您想要应用于新数据流的后备索引的映射和设置。
此索引模板必须满足数据流模板的要求。它还应在
index_patterns
属性中包含您之前选择的名称或索引模式。如果您只是添加或更改一些内容,我们建议您通过复制现有模板并根据需要进行修改来创建新模板。
例如,
my-data-stream-template
是my-data-stream
使用的现有索引模板。以下创建或更新索引模板 API 请求创建一个新的索引模板
new-data-stream-template
。new-data-stream-template
以my-data-stream-template
为基础,具有以下更改index_patterns
中的索引模式与以new-data-stream
开头的任何索引或数据流匹配。@timestamp
字段映射使用date_nanos
字段数据类型,而不是date
数据类型。- 该模板包括
sort.field
和sort.order
索引设置,这些设置不在原始my-data-stream-template
模板中。
resp = client.indices.put_index_template( name="new-data-stream-template", index_patterns=[ "new-data-stream*" ], data_stream={}, priority=500, template={ "mappings": { "properties": { "@timestamp": { "type": "date_nanos" } } }, "settings": { "sort.field": [ "@timestamp" ], "sort.order": [ "desc" ] } }, ) print(resp)
response = client.indices.put_index_template( name: 'new-data-stream-template', body: { index_patterns: [ 'new-data-stream*' ], data_stream: {}, priority: 500, template: { mappings: { properties: { "@timestamp": { type: 'date_nanos' } } }, settings: { 'sort.field' => [ '@timestamp' ], 'sort.order' => [ 'desc' ] } } } ) puts response
const response = await client.indices.putIndexTemplate({ name: "new-data-stream-template", index_patterns: ["new-data-stream*"], data_stream: {}, priority: 500, template: { mappings: { properties: { "@timestamp": { type: "date_nanos", }, }, }, settings: { "sort.field": ["@timestamp"], "sort.order": ["desc"], }, }, }); console.log(response);
-
使用创建数据流 API 手动创建新的数据流。数据流的名称必须与新模板的
index_patterns
属性中定义的索引模式匹配。我们不建议索引新数据来创建此数据流。稍后,您将把旧数据从现有数据流重新索引到这个新流中。这可能会导致一个或多个后备索引包含新旧数据的混合。
以下创建数据流 API 请求的目标是
new-data-stream
,它与new-data-stream-template
的索引模式匹配。由于没有现有索引或数据流使用此名称,因此此请求将创建new-data-stream
数据流。resp = client.indices.create_data_stream( name="new-data-stream", ) print(resp)
response = client.indices.create_data_stream( name: 'new-data-stream' ) puts response
const response = await client.indices.createDataStream({ name: "new-data-stream", }); console.log(response);
PUT /_data_stream/new-data-stream
- 如果您不想在新数据流中混合新旧数据,请暂停索引新文档。虽然混合旧数据和新数据是安全的,但可能会干扰数据保留。请参阅在数据流中混合新旧数据。
-
如果您使用 ILM 来自动化滚动,请减少 ILM 轮询间隔。这可确保当前写入索引在等待滚动检查时不会变得太大。默认情况下,ILM 每 10 分钟检查一次滚动条件。
以下集群更新设置 API 请求将
indices.lifecycle.poll_interval
设置降低为1m
(一分钟)。resp = client.cluster.put_settings( persistent={ "indices.lifecycle.poll_interval": "1m" }, ) print(resp)
response = client.cluster.put_settings( body: { persistent: { 'indices.lifecycle.poll_interval' => '1m' } } ) puts response
const response = await client.cluster.putSettings({ persistent: { "indices.lifecycle.poll_interval": "1m", }, }); console.log(response);
PUT /_cluster/settings { "persistent": { "indices.lifecycle.poll_interval": "1m" } }
-
使用
create
的op_type
将您的数据重新索引到新的数据流中。如果您想按数据最初被索引的顺序对数据进行分区,您可以运行单独的重新索引请求。这些重新索引请求可以使用单个后备索引作为源。您可以使用获取数据流 API 来检索后备索引的列表。
例如,您计划将数据从
my-data-stream
重新索引到new-data-stream
。但是,您希望为my-data-stream
中的每个后备索引提交单独的重新索引请求,从最旧的后备索引开始。这将保留数据最初被索引的顺序。以下获取数据流 API 请求检索有关
my-data-stream
的信息,包括其后备索引的列表。resp = client.indices.get_data_stream( name="my-data-stream", ) print(resp)
response = client.indices.get_data_stream( name: 'my-data-stream' ) puts response
const response = await client.indices.getDataStream({ name: "my-data-stream", }); console.log(response);
GET /_data_stream/my-data-stream
响应的
indices
属性包含流的当前后备索引的数组。数组中的第一项包含有关流的最旧后备索引的信息。{ "data_streams": [ { "name": "my-data-stream", "timestamp_field": { "name": "@timestamp" }, "indices": [ { "index_name": ".ds-my-data-stream-2099.03.07-000001", "index_uuid": "Gpdiyq8sRuK9WuthvAdFbw", "prefer_ilm": true, "managed_by": "Unmanaged" }, { "index_name": ".ds-my-data-stream-2099.03.08-000002", "index_uuid": "_eEfRrFHS9OyhqWntkgHAQ", "prefer_ilm": true, "managed_by": "Unmanaged" } ], "generation": 2, "status": "GREEN", "next_generation_managed_by": "Unmanaged", "prefer_ilm": true, "template": "my-data-stream-template", "hidden": false, "system": false, "allow_custom_routing": false, "replicated": false, "rollover_on_write": false } ] }
以下重新索引 API 请求将文档从
.ds-my-data-stream-2099.03.07-000001
复制到new-data-stream
。请求的op_type
是create
。resp = client.reindex( source={ "index": ".ds-my-data-stream-2099.03.07-000001" }, dest={ "index": "new-data-stream", "op_type": "create" }, ) print(resp)
response = client.reindex( body: { source: { index: '.ds-my-data-stream-2099.03.07-000001' }, dest: { index: 'new-data-stream', op_type: 'create' } } ) puts response
const response = await client.reindex({ source: { index: ".ds-my-data-stream-2099.03.07-000001", }, dest: { index: "new-data-stream", op_type: "create", }, }); console.log(response);
POST /_reindex { "source": { "index": ".ds-my-data-stream-2099.03.07-000001" }, "dest": { "index": "new-data-stream", "op_type": "create" } }
您还可以使用查询来重新索引每个请求中仅一部分文档。
以下重新索引 API 请求将文档从
my-data-stream
复制到new-data-stream
。该请求使用range
查询来仅重新索引时间戳在最近一周内的文档。请注意,请求的op_type
是create
。resp = client.reindex( source={ "index": "my-data-stream", "query": { "range": { "@timestamp": { "gte": "now-7d/d", "lte": "now/d" } } } }, dest={ "index": "new-data-stream", "op_type": "create" }, ) print(resp)
response = client.reindex( body: { source: { index: 'my-data-stream', query: { range: { "@timestamp": { gte: 'now-7d/d', lte: 'now/d' } } } }, dest: { index: 'new-data-stream', op_type: 'create' } } ) puts response
const response = await client.reindex({ source: { index: "my-data-stream", query: { range: { "@timestamp": { gte: "now-7d/d", lte: "now/d", }, }, }, }, dest: { index: "new-data-stream", op_type: "create", }, }); console.log(response);
POST /_reindex { "source": { "index": "my-data-stream", "query": { "range": { "@timestamp": { "gte": "now-7d/d", "lte": "now/d" } } } }, "dest": { "index": "new-data-stream", "op_type": "create" } }
-
如果您之前更改了 ILM 轮询间隔,请在重新索引完成后将其更改回原始值。这可以防止主节点上的不必要负载。
以下集群更新设置 API 请求将
indices.lifecycle.poll_interval
设置重置为其默认值。resp = client.cluster.put_settings( persistent={ "indices.lifecycle.poll_interval": None }, ) print(resp)
response = client.cluster.put_settings( body: { persistent: { 'indices.lifecycle.poll_interval' => nil } } ) puts response
const response = await client.cluster.putSettings({ persistent: { "indices.lifecycle.poll_interval": null, }, }); console.log(response);
PUT /_cluster/settings { "persistent": { "indices.lifecycle.poll_interval": null } }
- 使用新的数据流恢复索引。在此流上搜索现在将查询您的新数据和重新索引的数据。
-
一旦您验证了所有重新索引的数据都可在新的数据流中获得,您就可以安全地删除旧的流。
以下删除数据流 API 请求删除
my-data-stream
。此请求还会删除流的后备索引以及其中包含的任何数据。resp = client.indices.delete_data_stream( name="my-data-stream", ) print(resp)
response = client.indices.delete_data_stream( name: 'my-data-stream' ) puts response
const response = await client.indices.deleteDataStream({ name: "my-data-stream", }); console.log(response);
DELETE /_data_stream/my-data-stream
更新或向数据流添加别名
编辑使用别名 API 来更新现有数据流的别名。更改现有数据流在其索引模式中的别名不起作用。
例如,logs
别名指向单个数据流。以下请求会交换别名的流。在此交换期间,logs
别名没有停机时间,并且永远不会同时指向两个流。
resp = client.indices.update_aliases( actions=[ { "remove": { "index": "logs-nginx.access-prod", "alias": "logs" } }, { "add": { "index": "logs-my_app-default", "alias": "logs" } } ], ) print(resp)
response = client.indices.update_aliases( body: { actions: [ { remove: { index: 'logs-nginx.access-prod', alias: 'logs' } }, { add: { index: 'logs-my_app-default', alias: 'logs' } } ] } ) puts response
const response = await client.indices.updateAliases({ actions: [ { remove: { index: "logs-nginx.access-prod", alias: "logs", }, }, { add: { index: "logs-my_app-default", alias: "logs", }, }, ], }); console.log(response);
POST _aliases { "actions": [ { "remove": { "index": "logs-nginx.access-prod", "alias": "logs" } }, { "add": { "index": "logs-my_app-default", "alias": "logs" } } ] }