OpenSearch/Elasticsearch 쿼리 오류 완전 가이드: DSL 사용법·매핑 함정·페이징·집계·성능 튜닝

OpenSearch/Elasticsearch 쿼리 오류 완전 가이드: DSL 사용법·매핑 함정·페이징·집계·성능 튜닝

OpenSearch 쿼리 오류 때문에 멈춰본 적 있나요? 이 글은 OpenSearch 쿼리 오류와 Elasticsearch 쿼리 오류를 빠르게 진단하고 해결하는 실전 매뉴얼입니다. DSL 기본부터 매핑 함정(text vs keyword), 집계/정렬 오류, 깊은 페이징, 타임아웃·서킷 브레이커까지 한 번에 정리했습니다.

 

OpenSearch/Elasticsearch에서 자주 만나는 쿼리 오류(400/404/429/503 등)와 원인을 유형별로 정리하고, DSL 예제와 함께 해결책을 제공합니다. 매핑/애널라이저, 집계, 페이징(search_after), 타임아웃·서킷 브레이커 설정, 느린 쿼리 분석(explain/profile/slowlog)까지 현업 기준 트러블슈팅 루틴을 제시합니다.

반응형

 

---

 

목차

 

1. 기본 사용법: DSL 구조와 빠른 시작

 

2. 자주 나오는 OpenSearch 쿼리 오류 12가지와 해결책

 

3. 페이징·정렬·집계 실무 팁(검색 정확도 & 비용)

 

4. 성능 안정화 체크리스트(타임아웃·서킷 브레이커)

 

5. 장애 분석 루틴(explain/profile/slowlog)

 

 

---

 

1. 기본 사용법: DSL 구조와 빠른 시작

 

핵심 요약: 요청은 index/_search로, 본문은 query·sort·aggs 3축으로 생각하세요.

OpenSearch 쿼리 구조와 요청-응답 흐름 다이어그램

 

 

OpenSearch 쿼리 오류를 줄이려면 먼저 DSL 구조를 이해해야 합니다. 최소 형태는 아래와 같습니다.

curl -X POST 'http://localhost:9200/products/_search' -H 'Content-Type: application/json' -d '{
  "query": { "bool": {
    "must": [ { "match": { "name": "ssd 1tb" } } ],
    "filter": [ { "term": { "category.keyword": "storage" } } ]
  }},
  "sort": [ { "created_at": "desc" } ],
  "aggs": { "by_brand": { "terms": { "field": "brand.keyword" } } },
  "size": 10
}'

• 검색(query): match, term, range, bool 조합.
• 정렬(sort): 숫자/날짜/keyword에 유효. TEXT 필드는 정렬 불가.
• 집계(aggs): 통계·분포 파악. terms, date_histogram, avg 등.

 

---

 

2. 자주 나오는 OpenSearch 쿼리 오류 12가지와 해결책

 

핵심 요약: 매핑 불일치가 절반, 나머지는 페이징/집계 파라미터와 리소스 한도 문제입니다.

텍스트 vs 키워드 매핑 차이와 오류 사례

 

2.1 index_not_found_exception

• 원인: 존재하지 않는 인덱스/별칭.
• 해결: 인덱스 생성 혹은 * 와일드카드 확인, 읽기 권한 점검.

curl -X PUT 'localhost:9200/products'

2.2 parsing_exception / 400 Bad Request

• 원인: JSON 문법/DSL 키 오타.
• 해결: 쉼표/따옴표 확인, POST _validate/query?explain=true로 사전 검증.

2.3 mapper_parsing_exception

• 원인: 문서 색인 시 필드 타입 불일치(문자열을 날짜 필드에 넣는 등).
• 해결: 매핑 사전 정의, dynamic: strict로 스키마 고정. 변환 파이프라인 사용.

2.4 search_phase_execution_exception (원인 다양)

• 원인 후보: 잘못된 정렬 필드, 스크립트 오류, 분석기 문제.
• 해결: 스택 트레이스에서 caused_by 체인을 확인. 문제 필드만 분리 테스트.

2.5 fielddata_exception: Fielddata is disabled on text fields

• 원인: TEXT 필드를 집계/정렬에 사용.
• 해결: keyword 서브필드로 조회하거나, 임시로 fielddata: true(메모리 비용↑).

"mappings": {
  "properties": {
    "brand": { "type": "text", "fields": { "keyword": { "type": "keyword" } } }
  }
}

2.6 all shards failed

• 원인: 일부 샤드 장애/네트워크 분리/쿼리 문법 오류가 샤드 단위로 발생.
• 해결: ?ignore_unavailable=true로 일단 우회 후, 클러스터 상태/샤드 재할당 확인.

2.7 too_many_buckets_exception

• 원인: terms 집계 결과가 search.max_buckets 한도 초과(기본 10k 수준).
• 해결: 샘플링(composite/partition), 상위 n만 집계, 백오프 배치.

2.8 circuit_breaking_exception

• 원인: 메모리 사용량이 회로 차단 임계 초과.
• 해결: 응답 축소(_source 필드 선택), size 축소, 집계 버킷 제한, 쿼리 단순화.

2.9 search_context_missing_exception (scroll/PIT)

• 원인: 스크롤/PIT 만료 후 재요청.
• 해결: 재생성하고 타임아웃 늘리기. 가능하면 search_after로 대체.

2.10 read_timeout_exception / 408/504

• 원인: 느린 쿼리, 네트워크 지연.
• 해결: request_timeout 상향 + 쿼리 튜닝. profile로 병목 파악.

2.11 version_conflict_engine_exception (업서트/갱신)

• 원인: 동시 업데이트 충돌.
• 해결: retry_on_conflict, 외부 락, 낙관적 락 버전 필드.

2.12 too_many_clauses (쿼리 절 조합 과다)

• 원인: bool에 수천 개의 should나 terms를 넘김.
• 해결: 사전 필터링, 인덱스 재설계, terms_set/runtime fields로 단순화.

 

---

 

3. 페이징·정렬·집계 실무 팁(검색 정확도 & 비용)

 

핵심 요약: 깊은 페이지는 from/size 대신 search_after와 정렬 키를 쓰세요.

search_after 기반 깊은 페이징 흐름

 

3.1 깊은 페이징

# 1페이지(커서 획득)
curl -X POST 'localhost:9200/products/_search' -H 'Content-Type: application/json' -d '{
  "size": 10,
  "sort": [ { "created_at": "desc" }, { "_id": "desc" } ],
  "query": { "match": { "name": "ssd" } }
}'
# 응답의 마지막 히트에 있는 sort 값을 다음 요청의 search_after로 전달
# 2페이지
curl -X POST 'localhost:9200/products/_search' -d '{
  "size": 10,
  "search_after": [1692600000, "abc123"],
  "sort": [ { "created_at": "desc" }, { "_id": "desc" } ],
  "query": { "match": { "name": "ssd" } }
}'

• 커서 안정성: 타임스탬프+_id 2중 정렬을 권장.
• 총 건수: track_total_hits: true/false로 비용 조절.

3.2 집계 성능 팁

• 키워드 필드만 집계: TEXT는 keyword를 사용.
• 샘플링: sampler, random_sampler로 비용 절감.
• composite: 페이징 가능한 집계로 대량 버킷을 순회.

3.3 정렬 정확도

• 스코어+날짜 혼합: scripted_metric 대신 다중 정렬과 부스트 조합을 우선.
• 한국어 검색: nori/arirang 같은 한글 분석기 적용을 고려.

 

---

 

4. 성능 안정화 체크리스트(타임아웃·서킷 브레이커)

 

핵심 요약: 기본값만 믿지 마세요. 요청/응답/메모리 한도를 명시적으로 관리해야 합니다.

• 타임아웃: 게이트웨이/클라이언트/노드 세 군데에서 각각 설정.
• 서킷 브레이커: 코디네이팅 노드의 메모리 한도 초과 시 쿼리 중단. 응답 축소와 버킷 제한으로 예방.
• 슬로우로그: 인덱스별 threshold를 낮춰 병목을 상시 관찰.
• 리소스 가드: search.max_buckets, indices.query.bool.max_clause_count 등 한도 튜닝.
• 캐시: 결과 캐시 + request_cache(필터 캐시)로 반복 쿼리 최적화.

 

---

 

5. 장애 분석 루틴(explain/profile/slowlog)

 

핵심 요약: 증상→가설→검증 순서로 표준 루틴을 만들면 재발 방지가 빨라집니다.

1. 증상 수집: 에러 코드/메시지, 쿼리 본문, 대상 인덱스, 사용자 파라미터, 시간대.
2. 재현: 동일 요청을 dev 환경에서 재실행. 권한/데이터 볼륨 차이 확인.
3. 매핑 확인: GET index/_mapping으로 문제 필드 타입/애널라이저 점검.
4. Explain: 문서가 왜/왜 아닌지 진단.

curl -X GET 'localhost:9200/products/_explain/abc123' -H 'Content-Type: application/json' -d '{
  "query": { "match": { "name": "ssd" } }
}'

1. Profile: 어느 쿼리가 시간을 삼키는지 단계별 타이밍 분석.

curl -X POST 'localhost:9200/products/_search' -H 'Content-Type: application/json' -d '{
  "profile": true,
  "query": { "bool": { "must": [ { "match": { "name": "ssd" } } ] } }
}'

1. Slowlog: 인덱스 설정으로 느린 쿼리 기록.

curl -X PUT 'localhost:9200/products/_settings' -H 'Content-Type: application/json' -d '{
  "index.search.slowlog.threshold.query.warn":  "1s",
  "index.search.slowlog.threshold.fetch.warn":  "500ms"
}'

1. 재설계/학습: 매핑 교정, 인덱스 템플릿, 파이프라인 변환, 샤드/리플리카 조정.

---

 

결론

 

핵심 요약: OpenSearch 쿼리 오류는 패턴이 있다. 매핑→파라미터→리소스 순서로 점검하라.

 

대부분의 OpenSearch 쿼리 오류·Elasticsearch 쿼리 오류는 (1) 매핑/애널라이저 불일치, (2) 집계·정렬에서의 필드 선택 실수, (3) 깊은 페이징과 과도한 버킷으로 인한 리소스 초과에서 발생합니다. 오늘 소개한 DSL 체크리스트, search_after 페이징, 집계/정렬 규칙, 그리고 explain/profile/slowlog 루틴을 팀 표준으로 문서화해 두면 장애 대응 시간이 절반 이하로 줄어듭니다. 새 인덱스를 만들 때는 템플릿과 매핑을 먼저 설계하고, 운영 중에는 한도/타임아웃을 명시적으로 관리하세요. 그러면 검색 품질·안정성·비용이 모두 개선됩니다.

 

함께 보면 좋은 글

 

GPT-5 완전 가이드: 400K 컨텍스트·에이전틱 툴·가격까지, 지금 개발자가 알아야 할 모든 것

 

GitHub Actions CI/CD로 Docker 앱 자동 배포: 실전 구축 가이드