데이터 스트림 수정
원본 보기데이터 스트림 수정
모든 데이터 스트림에는 대응하는 인덱스 템플릿이 있습니다. 이 템플릿의 매핑과 인덱스 설정은 해당 스트림을 위해 새로 생성되는 백킹 인덱스에 적용됩니다. 여기에는 스트림이 생성될 때 자동으로 만들어지는 첫 번째 백킹 인덱스도 포함됩니다.
데이터 스트림을 만들기 전에, 이 템플릿에 어떤 매핑과 설정을 포함할지 신중히 검토하는 것이 좋습니다.
나중에 데이터 스트림의 매핑이나 설정을 변경해야 한다면 다음과 같은 선택지가 있습니다.
변경 사항에 기존 필드 매핑이나 정적 인덱스 설정의 수정이 포함된다면, 그 변경을 데이터 스트림의 백킹 인덱스에 적용하기 위해 리인덱싱이 필요한 경우가 많습니다. 이미 리인덱싱을 수행하고 있다면 같은 과정에서 새 필드 매핑을 추가하고 동적 인덱스 설정도 변경할 수 있습니다. 리인덱싱을 사용해 매핑 또는 설정 변경하기를 참고하세요.
데이터 스트림에 새 필드의 매핑을 추가하려면 다음 단계를 따르세요.
데이터 스트림이 사용하는 인덱스 템플릿을 업데이트합니다. 이렇게 하면 앞으로 해당 스트림을 위해 생성되는 백킹 인덱스에 새 필드 매핑이 추가됩니다.
예를 들어
my-data-stream-template은my-data-stream이 사용하는 기존 인덱스 템플릿입니다.다음 인덱스 템플릿 생성 또는 업데이트 요청은 템플릿에 새 필드
message의 매핑을 추가합니다.PUT /_index_template/my-data-stream-template{ "index_patterns": [ "my-data-stream*" ], "data_stream": { }, "priority": 500, "template": { "mappings": { "properties": { "message": { "type": "text" } } } } }- 새
message필드의 매핑을 추가합니다.
- 새
매핑 업데이트 API를 사용해 데이터 스트림에 새 필드 매핑을 추가합니다. 기본적으로 이 작업은 쓰기 인덱스를 포함한 스트림의 기존 백킹 인덱스에 매핑을 추가합니다.
다음 매핑 업데이트 API 요청은
my-data-stream에 새message필드 매핑을 추가합니다.PUT /my-data-stream/_mapping{ "properties": { "message": { "type": "text" } } }스트림의 쓰기 인덱스에만 매핑을 추가하려면 매핑 업데이트 API의
write_index_only쿼리 매개변수를true로 설정하세요.다음 매핑 업데이트 요청은
my-data-stream의 쓰기 인덱스에만 새message필드 매핑을 추가합니다. 새 필드 매핑은 스트림의 다른 백킹 인덱스에는 추가되지 않습니다.PUT /my-data-stream/_mapping?write_index_only=true{ "properties": { "message": { "type": "text" } } }
Kibana에서도 데이터 스트림에 새 필드 매핑을 추가할 수 있습니다. 스트림이 데이터 스트림에 직접 매핑되는 Streams 페이지에서 해당 데이터 스트림을 찾으세요. 스트림을 선택해 상세 정보를 확인하고 Schema 탭으로 이동해 새 필드를 추가합니다.
각 매핑 매개변수 문서에는 매핑 업데이트 API로 기존 필드에 대해 해당 매개변수를 업데이트할 수 있는지 여부가 표시되어 있습니다. 기존 필드의 이러한 매개변수를 업데이트하려면 다음 단계를 따르세요.
데이터 스트림이 사용하는 인덱스 템플릿을 업데이트합니다. 이렇게 하면 앞으로 해당 스트림을 위해 생성되는 백킹 인덱스에 업데이트된 필드 매핑이 추가됩니다.
예를 들어
my-data-stream-template은my-data-stream이 사용하는 기존 인덱스 템플릿입니다.다음 인덱스 템플릿 생성 또는 업데이트 요청은
host.ip필드의ignore_malformed매핑 매개변수 값을true로 변경합니다.PUT /_index_template/my-data-stream-template{ "index_patterns": [ "my-data-stream*" ], "data_stream": { }, "priority": 500, "template": { "mappings": { "properties": { "host": { "properties": { "ip": { "type": "ip", "ignore_malformed": true } } } } } } }host.ip필드의ignore_malformed값을true로 변경합니다.
매핑 업데이트 API를 사용해 데이터 스트림에 매핑 변경을 적용합니다. 기본적으로 이 작업은 쓰기 인덱스를 포함한 스트림의 기존 백킹 인덱스에 변경을 적용합니다.
다음 매핑 업데이트 API 요청은
my-data-stream을 대상으로 합니다. 이 요청은host.ip필드의ignore_malformed매핑 매개변수 값을true로 변경합니다.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필드의 매핑을 변경합니다. 이 변경은 스트림의 다른 백킹 인덱스에는 적용되지 않습니다.PUT /my-data-stream/_mapping?write_index_only=true{ "properties": { "host": { "properties": { "ip": { "type": "ip", "ignore_malformed": true } } } } }
Kibana에서도 기존 필드의 매핑을 업데이트할 수 있습니다. 스트림이 데이터 스트림에 직접 매핑되는 Streams 페이지에서 해당 데이터 스트림을 찾으세요. 스트림을 선택해 상세 정보를 확인하고 Schema 탭으로 이동해 업데이트를 진행합니다. 자세한 내용은 Streams에서 필드 매핑하기를 참고하세요.
지원되는 매핑 매개변수를 제외하면, 데이터 스트림에 대응하는 인덱스 템플릿이나 백킹 인덱스에서라도 기존 필드의 매핑이나 필드 데이터 타입을 변경하는 것은 권장하지 않습니다. 기존 필드의 매핑을 변경하면 이미 인덱싱된 데이터가 무효화될 수 있습니다.
기존 필드의 매핑을 변경해야 한다면, 새 데이터 스트림을 만들고 그곳으로 데이터를 리인덱싱하세요. 리인덱싱을 사용해 매핑 또는 설정 변경하기를 참고하세요.
데이터 스트림의 동적 인덱스 설정을 변경하려면 다음 단계를 따르세요.
데이터 스트림이 사용하는 인덱스 템플릿을 업데이트합니다. 이렇게 하면 앞으로 해당 스트림을 위해 생성되는 백킹 인덱스에 설정이 적용됩니다.
예를 들어
my-data-stream-template은my-data-stream이 사용하는 기존 인덱스 템플릿입니다.다음 인덱스 템플릿 생성 또는 업데이트 요청은 템플릿의
index.refresh_interval인덱스 설정을30s(30초)로 변경합니다.PUT /_index_template/my-data-stream-template{ "index_patterns": [ "my-data-stream*" ], "data_stream": { }, "priority": 500, "template": { "settings": { "index.refresh_interval": "30s" } } }index.refresh_interval설정을30s(30초)로 변경합니다.
인덱스 설정 업데이트 API를 사용해 데이터 스트림의 인덱스 설정을 업데이트합니다. 기본적으로 이 작업은 쓰기 인덱스를 포함한 스트림의 기존 백킹 인덱스에 설정을 적용합니다.
다음 인덱스 설정 업데이트 API 요청은
my-data-stream의index.refresh_interval설정을 업데이트합니다.PUT /my-data-stream/_settings{ "index": { "refresh_interval": "30s" } }
index.lifecycle.name 설정을 변경하려면 먼저 정책 제거 API로 기존 ILM 정책을 제거하세요. 라이프사이클 정책 전환을 참고하세요.
Kibana에서도 샤드 수, 복제본 수, 사용되는 리프레시 간격 등 데이터 스트림의 일부 동적 인덱스 설정을 업데이트할 수 있습니다.
스트림이 데이터 스트림에 직접 매핑되는 Streams 페이지에서 해당 데이터 스트림을 찾으세요. 스트림을 선택해 상세 정보를 확인하고 Advanced 탭으로 이동해 값을 조정합니다. 자세한 내용은 스트림 고급 설정 구성 > 인덱스 구성을 참고하세요.
정적 인덱스 설정은 백킹 인덱스가 생성될 때만 지정할 수 있습니다. 인덱스 설정 업데이트 API로는 정적 인덱스 설정을 업데이트할 수 없습니다.
앞으로 생성되는 백킹 인덱스에 새 정적 설정을 적용하려면 데이터 스트림이 사용하는 인덱스 템플릿을 업데이트하세요. 업데이트 이후 생성되는 모든 백킹 인덱스에 설정이 자동으로 적용됩니다.
예를 들어 my-data-stream-template은 my-data-stream이 사용하는 기존 인덱스 템플릿입니다.
다음 인덱스 템플릿 생성 또는 업데이트 API 요청은 템플릿에 새 sort.field 및 sort.order index 설정을 추가합니다.
PUT /_index_template/my-data-stream-template
{
"index_patterns": [ "my-data-stream*" ],
"data_stream": { },
"priority": 500,
"template": {
"settings": {
"sort.field": [ "@timestamp"],
"sort.order": [ "desc"]
}
}
}
sort.field인덱스 설정을 추가합니다.sort.order인덱스 설정을 추가합니다.
원한다면 데이터 스트림을 롤오버해 설정을 데이터 스트림의 쓰기 인덱스에 즉시 적용할 수 있습니다. 이는 롤오버 이후 스트림에 추가되는 새 데이터에 영향을 줍니다. 다만 데이터 스트림의 기존 백킹 인덱스나 기존 데이터에는 영향을 주지 않습니다.
기존 백킹 인덱스에 정적 설정 변경을 적용하려면 새 데이터 스트림을 만들고 그곳으로 데이터를 리인덱싱해야 합니다. 리인덱싱을 사용해 매핑 또는 설정 변경하기를 참고하세요.
number_of_shards 업데이트 과정을 살펴보려면 이 영상을 참고하세요.
리인덱싱을 사용해 데이터 스트림의 매핑이나 설정을 변경할 수 있습니다. 기존 필드의 데이터 타입을 변경하거나 백킹 인덱스의 정적 인덱스 설정을 업데이트할 때 흔히 필요합니다.
데이터 스트림을 리인덱싱하려면 먼저 원하는 매핑 또는 설정 변경이 담긴 인덱스 템플릿을 생성하거나 업데이트하세요. 그다음 기존 데이터 스트림을 해당 템플릿에 대응하는 새 스트림으로 리인덱싱할 수 있습니다. 이렇게 하면 템플릿의 매핑 및 설정 변경이 새 데이터 스트림에 추가되는 각 문서와 백킹 인덱스에 적용됩니다. 이 변경 사항은 새 스트림이 앞으로 생성하는 백킹 인덱스에도 적용됩니다.
다음 단계를 따르세요.
새 데이터 스트림의 이름 또는 인덱스 패턴을 정합니다. 이 새 데이터 스트림에는 기존 스트림의 데이터가 담깁니다.
resolve index API로 해당 이름이나 패턴이 기존 인덱스, 별칭, 데이터 스트림과 일치하는지 확인할 수 있습니다. 일치한다면 다른 이름이나 패턴을 사용하는 것을 고려하세요.
다음 resolve index API 요청은
new-data-stream으로 시작하는 기존 인덱스, 별칭, 데이터 스트림이 있는지 확인합니다. 없다면new-data-stream*인덱스 패턴으로 새 데이터 스트림을 만들 수 있습니다.GET /_resolve/index/new-data-stream*API는 다음과 같은 응답을 반환하며, 이 패턴에 일치하는 기존 대상이 없음을 나타냅니다.
{ "indices": [ ], "aliases": [ ], "data_streams": [ ] }인덱스 템플릿을 생성하거나 업데이트합니다. 이 템플릿에는 새 데이터 스트림의 백킹 인덱스에 적용하려는 매핑과 설정이 담겨야 합니다.
이 인덱스 템플릿은 데이터 스트림 템플릿 요건을 충족해야 합니다. 또한 앞서 정한 이름이나 인덱스 패턴이
index_patterns속성에 포함되어야 합니다.Tip몇 가지만 추가하거나 변경하는 경우라면, 기존 템플릿을 복사한 뒤 필요한 부분만 수정해 새 템플릿을 만드는 것을 권장합니다.
예를 들어
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데이터 타입 대신date_nanos필드 데이터 타입을 사용합니다.- 원래의
my-data-stream-template템플릿에는 없던sort.field및sort.order인덱스 설정이 포함됩니다.
PUT /_index_template/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"] } } }@timestamp필드 매핑을date_nanos필드 데이터 타입으로 변경합니다.sort.field인덱스 설정을 추가합니다.sort.order인덱스 설정을 추가합니다.
데이터 스트림 생성 API로 새 데이터 스트림을 직접 생성합니다. 데이터 스트림의 이름은 새 템플릿의
index_patterns속성에 정의된 인덱스 패턴과 일치해야 합니다.새 데이터를 인덱싱해 이 데이터 스트림을 생성하는 방식은 권장하지 않습니다. 이후 기존 데이터 스트림의 오래된 데이터를 이 새 스트림으로 리인덱싱하게 되는데, 그 결과 새 데이터와 오래된 데이터가 섞인 백킹 인덱스가 하나 이상 생길 수 있습니다.
Important다음 데이터 스트림 생성 API 요청은
new-data-stream-template의 인덱스 패턴에 일치하는new-data-stream을 대상으로 합니다. 이 이름을 사용하는 기존 인덱스나 데이터 스트림이 없으므로, 이 요청은new-data-stream데이터 스트림을 생성합니다.PUT /_data_stream/new-data-stream새 데이터 스트림에 새 데이터와 오래된 데이터를 섞고 싶지 않다면 새 문서의 인덱싱을 일시 중지하세요. 오래된 데이터와 새 데이터를 섞어도 안전하지만 데이터 보존에 지장을 줄 수 있습니다. 데이터 스트림에서 새 데이터와 오래된 데이터 혼합을 참고하세요.
ILM으로 롤오버를 자동화하고 있다면 ILM 폴링 간격을 줄이세요. 이렇게 하면 롤오버 검사를 기다리는 동안 현재 쓰기 인덱스가 지나치게 커지지 않습니다. 기본적으로 ILM은 10분마다 롤오버 조건을 검사합니다.
다음 클러스터 설정 업데이트 API 요청은
indices.lifecycle.poll_interval설정을1m(1분)으로 낮춥니다.PUT /_cluster/settings{ "persistent": { "indices.lifecycle.poll_interval": "1m" } }op_type을create로 지정해 데이터를 새 데이터 스트림으로 리인덱싱합니다.원래 인덱싱된 순서대로 데이터를 나누고 싶다면 리인덱싱 요청을 나눠서 실행할 수 있습니다. 각 리인덱싱 요청은 개별 백킹 인덱스를 소스로 사용할 수 있습니다. 백킹 인덱스 목록은 데이터 스트림 조회 API로 확인할 수 있습니다.
예를 들어
my-data-stream의 데이터를new-data-stream으로 리인덱싱하려 하는데,my-data-stream의 각 백킹 인덱스에 대해 가장 오래된 백킹 인덱스부터 별도의 리인덱싱 요청을 보내고자 합니다. 이렇게 하면 데이터가 원래 인덱싱된 순서가 유지됩니다.다음 데이터 스트림 조회 API 요청은 백킹 인덱스 목록을 포함해
my-data-stream의 정보를 가져옵니다.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 } ] }my-data-stream의indices배열 첫 번째 항목입니다. 이 항목에는 스트림의 가장 오래된 백킹 인덱스.ds-my-data-stream-2099.03.07-000001의 정보가 담겨 있습니다.
다음 리인덱싱 API 요청은
.ds-my-data-stream-2099.03.07-000001의 문서를new-data-stream으로 복사합니다. 요청의op_type은create입니다.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쿼리를 사용해 최근 1주일 내 타임스탬프를 가진 문서만 리인덱싱합니다. 요청의op_type이create임에 유의하세요.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설정을 기본값으로 되돌립니다.PUT /_cluster/settings{ "persistent": { "indices.lifecycle.poll_interval": null } }새 데이터 스트림으로 인덱싱을 재개합니다. 이제 이 스트림에 대한 검색은 새 데이터와 리인덱싱된 데이터를 모두 조회합니다.
리인덱싱된 모든 데이터가 새 데이터 스트림에서 사용 가능한지 확인했다면, 기존 스트림을 안전하게 제거할 수 있습니다.
다음 데이터 스트림 삭제 API 요청은
my-data-stream을 삭제합니다. 이 요청은 스트림의 백킹 인덱스와 그 안의 모든 데이터도 함께 삭제합니다.DELETE /_data_stream/my-data-stream
별칭 API로 기존 데이터 스트림의 별칭을 업데이트하세요. 기존 데이터 스트림의 인덱스 패턴에서 별칭을 변경해도 아무 효과가 없습니다.
예를 들어 logs 별칭이 단일 데이터 스트림을 가리키고 있습니다. 다음 요청은 이 별칭이 가리키는 스트림을 교체합니다. 교체 중에 logs 별칭은 다운타임이 없으며, 두 스트림을 동시에 가리키는 일도 없습니다.
POST _aliases
{
"actions": [
{
"remove": {
"index": "logs-nginx.access-prod",
"alias": "logs"
}
},
{
"add": {
"index": "logs-my_app-default",
"alias": "logs"
}
}
]
}
modify API로 데이터 스트림의 백킹 인덱스를 수정하세요. 하나의 modify 요청에 여러 작업을 지정할 수 있으며, 이들은 원자적으로 실행됩니다.
POST /_data_stream/_modify
{
"actions": [
{
"add_backing_index": {
"data_stream": "my-data-stream",
"index": "new-index"
},
"remove_backing_index": {
"data_stream": "my-data-stream",
"index": "old-index"
}
}
]
}