Breaking changes

원문 보기 위키 갱신 2026.10.14

출처: 문서

본문

주요 변경 사항

OpenSearch는 Semantic Versioning을 사용하기 때문에, 호환성이 깨지는 변경 사항은 메이저 버전 릴리스 사이에서만 도입돼요. 다음 섹션에서는 OpenSearch에 도입된 호환성이 깨지는 변경 사항을 버전별로 정리해서 소개해요.

1.x

OpenSearch 1.x에서는 다음과 같은 호환성이 깨지는 변경 사항이 도입되었어요.

OpenSearch로 마이그레이션과 중첩 JSON 객체 수 제한

Elasticsearch OSS 버전 6.8에서 OpenSearch 버전 1.x로 마이그레이션할 때는, 클러스터에 모든 필드를 합쳐 10,000개가 넘는 중첩 JSON 객체를 포함한 문서가 하나라도 있으면 마이그레이션이 실패해요. Elasticsearch 버전 7.0은 out-of-memory 오류를 방지하기 위해 index.mapping.nested_objects.limit 설정을 도입했고, 이 설정의 기본값을 10000으로 지정했어요. OpenSearch는 탄생 시점부터 이 설정을 채택해 중첩 JSON 객체에 대한 제한을 적용하고 있어요. 하지만 이 설정은 Elasticsearch 6.8에는 존재하지 않고 해당 버전에서 인식되지도 않기 때문에, 어떤 문서의 중첩 JSON 객체 수가 기본 제한을 넘으면 OpenSearch 1.x로의 마이그레이션에서 Elasticsearch 6.8과 OpenSearch 1.x 버전 사이 샤드 재배치를 막는 비호환성 문제가 생길 수 있어요.

따라서 Elasticsearch 6.8에서 마이그레이션을 시도하기 전에 이런 제한 기준으로 데이터를 먼저 점검해 보시기를 권장해요.

2.0.0

OpenSearch 2.0.0에서는 다음과 같은 호환성이 깨지는 변경 사항이 도입되었어요.

매핑 타입 파라미터 제거

type 파라미터가 모든 OpenSearch API 엔드포인트에서 제거되었어요. 대신 인덱스를 문서 타입별로 분류할 수 있어요. 자세한 내용은 이슈 #1940을 참조하세요.

비포용적 용어 지원 중단

비포용적 용어는 버전 2.x에서 지원이 중단되었으며 OpenSearch 3.0에서 영구적으로 제거될 예정이에요. 다음과 같은 대체 표현을 사용하고 있어요:

"Whitelist"는 이제 "Allow list"예요
"Blacklist"는 이제 "Deny list"예요
"Master"는 이제 "Cluster Manager"예요

OpenSearch Notifications 플러그인 추가

OpenSearch 2.0에서는 Alerting 플러그인이 Notifications용 새 플러그인과 통합되었어요. Alerting 플러그인에서 알림 액션을 계속 사용하려면 새 백엔드 플러그인인 notifications-core와 notifications를 설치하세요. OpenSearch Dashboards에서 알림을 관리하려면 새 notificationsDashboards 플러그인을 사용하세요. 자세한 내용은 OpenSearch 문서 페이지의 Notifications를 참조하세요.

JDK 8 지원 중단

Lucene 업그레이드 때문에 OpenSearch는 JDK 8 지원을 중단할 수밖에 없게 되었어요. 그 결과 Java high-level REST client도 더 이상 JDK 8을 지원하지 않아요. JDK 8 지원 복원은 현재 opensearch-java 제안 #156으로 진행 중이고, 이를 위해서는 Java 클라이언트에서 OpenSearch core를 의존성에서 제거해야 해요(이슈 #262).

2.5.0

OpenSearch 2.5.0에서는 다음과 같은 호환성이 깨지는 변경 사항이 도입되었어요.

텍스트 필드에 대한 wildcard 쿼리 동작

OpenSearch 2.5에는 텍스트 필드에 대한 wildcard 쿼리의 case_insensitive 파라미터 동작을 바로잡는 버그 수정이 포함되어 있어요. 그 결과, 버그 수정 전에는 대소문자 구분을 무시하고 잘못된 결과를 반환했던 텍스트 필드 wildcard 쿼리는 이제 동일한 결과를 반환하지 않아요. 자세한 내용은 이슈 #8711을 참조하세요.

2.18.0

OpenSearch 2.18.0에서는 다음과 같은 호환성이 깨지는 변경 사항이 도입되었어요.

기본 k-NN 엔진 변경

기본 k-NN 엔진이 NMSLIB에서 Faiss로 변경되었어요. 엔진을 명시적으로 지정하지 않고 space_type: "cosinesimil"을 사용하면, 이제 인덱싱하는 동안 벡터가 자동으로 단위 길이로 정규화돼요. 이는 Faiss가 코사인 유사도를 기본적으로 지원하지 않고, 대신 정규화된 벡터에 내적을 사용하기 때문이에요. 그 결과 저장된 벡터 값이 입력 값과 달라지고, 벡터를 조회해서 비교하는 코드에 영향을 줄 수 있어요. 벡터가 이미 정규화되어 있다면, 정규화를 명시적으로 제어하면서 수학적으로 동등한 결과를 얻을 수 있도록 space_type을 cosinesimil 대신 innerproduct로 설정해 보세요. 자세한 내용은 풀 리퀘스트 #2221을 참조하세요.

2.19.0

OpenSearch 2.19.0에서는 다음과 같은 호환성이 깨지는 변경 사항이 도입되었어요.

text embedding 프로세서의 중첩 값 지원

text_embedding 프로세서는 title_tmp:_ingest._value.title_embedding 같은 필드를 평가할 때 더 이상 _ingest._value 같은 중첩 값을 치환하지 않아요. 대신 원하는 출력을 얻으려면 중첩 키를 books.title:title_embedding처럼 직접 지정해야 해요. 자세한 내용은 이슈 #1243을 참조하세요.

3.0.0

OpenSearch 3.0.0에서 다음과 같은 호환성이 깨지는 변경 사항이 도입되었어요.

JDK 요구 사항

지원되는 최소 JDK 버전은 JDK 21이에요.

버전 호환성 설정

compatibility.override_main_response_version 설정이 제거되었어요. 이 기능은 OpenSearch 1.x에서 지원 중단되었으며 더 이상 지원되지 않아요.

자세한 내용은 이슈 #18228를 참고하세요.

대안적인 접근 방법은 에이전트 및 수집 도구를 참고하세요.

인덱스 버전

2.x.x 이전 버전에서 생성된 인덱스(시스템 인덱스 포함)는 지원되지 않아요. 이러한 인덱스는 업그레이드하기 전에 재색인해야 해요. 재색인에 대한 내용은 데이터 재색인을 참고하세요.

자세한 내용은 이슈 #18717를 참고하세요.

시스템 인덱스 접근

REST API를 통한 시스템 인덱스 접근은 더 이상 제공되지 않아요. 이 기능은 OpenSearch 1.x부터 지원 중단되었어요. 자세한 내용은 이슈 #7936를 참고하세요.

문서 ID 길이 제한

512바이트 문서 ID 길이 제한이 이제 Bulk API를 포함한 모든 API에서 일관되게 적용돼요. 이전에는 Bulk API에서 512바이트보다 긴 문서 ID가 허용되었어요. 자세한 내용은 이슈 #6595를 참고하세요.

노드 역할 구성

환경 변수를 사용한 빈 노드 역할 구성이 수정되었어요. 이제 환경 변수로 node.roles=을 설정하면 opensearch.yml 구성과 일관되게 코디네이팅 전용 노드가 올바르게 구성돼요. 자세한 내용은 이슈 #3412를 참고하세요.

JSON 처리 제한

OpenSearch 전반에서 JSON 처리(Jackson 라이브러리 사용)에 대한 새로운 기본 제한이 도입되었어요:

JSON 객체와 배열의 최대 중첩 깊이는 1,000레벨로 제한돼요.
JSON 프로퍼티 이름의 최대 길이는 50,000단위(입력 소스에 따라 바이트 또는 문자)로 제한돼요.

이러한 제한은 잠재적인 메모리 문제와 서비스 거부 공격을 예방하는 데 도움이 돼요. 자세한 내용은 이슈 #11278를 참고하세요.

중첩 쿼리 깊이

nested 쿼리의 최대 중첩 레벨 수를 제한하는 새로운 index.query.max_nested_depth 설정이 도입되었어요. 기본값은 20이고 최솟값은 1이에요. 자세한 내용은 이슈 #3268를 참고하세요.

스레드 풀 설정

다음과 같은 지원 중단된 스레드 풀 설정이 제거되었어요:

thread_pool.test.max_queue_size
thread_pool.test.min_queue_size 자세한 내용은 이슈 #2595를 참고하세요.

인덱스 스토어 설정

hybridfs 파일 처리 개선의 일환으로 index.store.hybrid.mmap.extensions 설정이 제거되었어요. 자세한 내용은 풀 리퀘스트 #9392를 참고하세요.

Transport NIO 플러그인

transport-nio 플러그인이 제거되었어요. 노드 간 통신과 클라이언트-서버 통신 모두에서 Netty가 표준 네트워크 프레임워크로 계속 사용돼요. 자세한 내용은 이슈 #16887를 참고하세요.

Nodes API 응답 형식

Nodes API 응답에서 인덱싱 버퍼 값의 형식이 변경되었어요:

total_indexing_buffer_in_bytes는 이제 원시 바이트를 표시해요(예: 53687091).
total_indexing_buffer는 이제 사람이 읽기 쉬운 형식을 표시해요(예: 51.1mb).

자세한 내용은 풀 리퀘스트 #17070를 참고하세요.

PathHierarchy 토크나이저

카멜 케이스인 PathHierarchy 토크나이저 이름은 지원 중단되었으며, 대신 스네이크 케이스인 path_hierarchy를 사용해야 해요. 자세한 내용은 풀 리퀘스트 #10894를 참고하세요.

Security 플러그인

Blake2b 해시 구현이 이제 salt 파라미터를 올바르게 사용해요. 이로 인해 이전 버전과는 다른(하지만 올바른) 해시 값이 생성돼요. 자세한 내용은 풀 리퀘스트 #5089를 참고하세요.

k-NN 플러그인

k-NN 플러그인에서 다음과 같은 지원 중단된 설정이 제거되었어요:

knn.plugin.enabled 설정
index.knn.algo_param.ef_construction 인덱스 설정
index.knn.algo_param.m 인덱스 설정
index.knn.space_type 인덱스 설정

NMSLIB 엔진은 이제 지원 중단되었어요. 대신 Faiss 또는 Lucene 엔진을 사용하는 것을 추천해요.

자세한 내용은 풀 리퀘스트 #2564를 참고하세요.

Performance Analyzer 플러그인

performance-analyzer-rca 에이전트가 제거되었어요. 성능 모니터링과 분석을 위해서는 Telemetry plugin으로 전환하는 것을 추천해요. OpenTelemetry 프레임워크를 사용하는 Telemetry 플러그인은 경량 오픈 소스 에이전트와 매끄럽게 통합되어 옵저버빌리티 스토어에 성능 메트릭을 게시할 수 있어요. 자세한 내용은 이슈 #591를 참고하세요.

SQL 플러그인

OpenSearch 쿼리 도메인 특화 언어(DSL) 응답 형식이 제거되었어요.
DELETE 문 지원이 제거되었어요.
plugins.sql.delete.enabled 설정이 제거되었어요.
레거시 Spark Connector 모듈은 지원 중단되었어요. Spark 연결에 대한 내용은 async-query-core를 참고하세요.
지원 중단되었던 OpenDistro 엔드포인트와 opendistro 접두사가 붙은 레거시 설정이 제거되었어요.
plugins.sql.pagination.api가 제거되었고 Scroll API는 지원 중단되었어요. 이제 페이지네이션은 기본적으로 Point in Time을 사용해요.

자세한 내용은 이슈 #3248를 참고하세요.

OpenSearch Dashboards

Discover 환경:
- discover:newExperience 설정이 제거되었어요.
- DataGrid 테이블 기능이 제거되었어요.
자세한 내용은 풀 리퀘스트 #9511를 참고하세요.
시각화: dashboards-visualizations 플러그인(간트 차트 시각화 포함)이 제거되었어요. 다음으로 전환하는 것을 추천해요:
- 유연한 시각화가 필요한 경우에는 Vega 시각화
- 트레이스 관련 사용 사례에는 Trace analytics
자세한 내용은 이슈 #430를 참고하세요.

Dashboards Observability 플러그인

dashboards-observability에서 레거시 노트북 기능이 제거되었어요. 주요 변경 사항은 다음과 같아요:

레거시 노트북(이전에는 .opensearch-observability 인덱스에 저장됨)은 더 이상 지원되지 않아요.
버전 2.17에서 도입된 .kibana 인덱스에 저장된 노트북만 지원돼요.
버전 3.0으로 업그레이드하기 전에 노트북을 새로운 스토리지 시스템으로 마이그레이션해야 해요.

자세한 내용은 이슈 #2350를 참고하세요.

Searchable snapshots 노드 역할

searchable snapshots를 사용하는 노드는 warm 노드 역할을 가져야 해요. 주요 변경 사항은 다음과 같아요:

search 역할은 더 이상 searchable snapshots를 지원하지 않아요.
searchable snapshot 샤드를 처리하는 노드에는 warm 역할이 할당되어야 해요.
클러스터에서 searchable snapshots를 사용하는 경우 버전 3.0으로 업그레이드하기 전에 노드 역할 구성을 업데이트해야 해요.

자세한 내용은 풀 리퀘스트 #17573를 참고하세요.

Query groups

Query groups는 workload groups로 이름이 변경되었어요. 주요 변경 사항은 다음과 같아요:

wlm/query_group 엔드포인트는 이제 wlm/workload_group 엔드포인트예요.
API가 queryGroupID 대신 workloadGroupID로 응답해요.
모든 워크로드 관리 클러스터 설정 앞에는 이제 wlm.workload_group이 붙어요.

자세한 내용은 풀 리퀘스트 #9813를 참고하세요.

ML Commons 플러그인

CatIndexTool이 제거되고 ListIndexTool으로 대체되었어요.

루마니아어 분석

romanian 애널라이저는 이제 현대 유니코드 형태의 루마니아어를 지원하고, 세디유 문자를 쉼표 기반의 동등한 문자로 정규화해요. 두 형태가 모두 여전히 사용되고 있기 때문에, 일관된 분석과 검색 동작을 보장하려면 기존 루마니아어 문서를 재색인하는 것을 추천해요.

더 알아보기 (Learn more)

원문 전체: https://docs.opensearch.org/latest/about/breaking-changes/