liminfoElasticsearch Reference
Elasticsearch 검색 엔진 레퍼런스
Elasticsearch Reference 소개
Elasticsearch Reference는 Elasticsearch REST API 전체를 8개 카테고리로 정리한 검색 가능한 치트 시트입니다. 인덱스 카테고리는 샤드/레플리카 설정을 포함한 인덱스 생성 및 삭제, _cat/indices로 인덱스 목록 조회, 인덱스 설정 업데이트, _reindex를 활용한 재색인을 다룹니다. Query DSL 카테고리는 가장 많이 사용되는 쿼리 타입을 다룹니다. 전문 검색을 위한 match, 정확한 키워드 매칭을 위한 term, must/should/must_not/filter 절 조합을 위한 bool, 숫자 및 날짜 범위를 위한 range, 여러 필드 동시 검색을 위한 multi_match, 패턴 기반 매칭을 위한 wildcard가 포함됩니다. 모든 쿼리는 Kibana Dev Tools 콘솔이나 curl 요청에 바로 사용할 수 있는 완전한 JSON 형식으로 제공됩니다.
집계 카테고리는 5가지 집계 타입을 다룹니다. 버킷 기반 필드 값 그룹화를 위한 terms, 메트릭 집계(avg, sum, min, max), 달력 간격 기반 시계열 버킷팅을 위한 date_histogram, 다단계 분석을 위한 중첩 하위 집계, 고유 값 수 근사치를 위한 cardinality가 포함됩니다. 매핑 카테고리는 text/keyword/float/date/nested/geo_point 필드 타입을 가진 PUT /_mapping, 분석(전문 검색)을 위한 text와 비분석(정확 매칭 및 집계)을 위한 keyword의 차이, 중첩 객체 타입, strict 모드의 동적 매핑 제어, 지리 근접 쿼리를 위한 geo_point를 설명합니다. 분석기 카테고리는 사용자 정의 분석기 구성, 한국어 형태소 분석을 위한 nori 토크나이저, 테스트를 위한 _analyze API, 동의어 필터, 부분 단어 매칭을 위한 ngram 토크나이저를 다룹니다.
클러스터 및 모니터링 카테고리는 운영 가시성을 제공합니다. 전체 상태를 위한 _cluster/health, 노드 수와 문서 총계를 위한 _cluster/stats, 노드별 JVM 및 OS 메트릭을 위한 _nodes/stats, 할당 제어를 위한 _cluster/settings, 샤드 상태 검사를 위한 _cat/shards가 포함됩니다. 모니터링 항목은 노드별 리소스 사용량을 위한 _cat/nodes, 실행 중인 작업을 위한 _tasks, 슬로우 로그 설정, 큐 깊이를 위한 _cat/thread_pool, 라우팅 할당을 통한 핫-웜 아키텍처를 다룹니다. API 카테고리는 POST /_doc를 통한 문서 색인, 단일 문서 조회, _bulk로 일괄 작업, _mget로 다중 조회, _msearch로 다중 검색, 대용량 결과 페이지네이션을 위한 scroll API를 다룹니다.
주요 기능
- 인덱스 관리: PUT/DELETE 인덱스, _cat/indices 목록, 설정 업데이트, _reindex
- Query DSL: match, term, bool(must/should/filter), range, multi_match, wildcard 쿼리 JSON 예제
- 집계: terms 버킷, avg/sum/min/max 메트릭, date_histogram, 중첩 하위 집계, cardinality
- 매핑: text vs keyword 구분, nested 타입, geo_point, dynamic strict 모드, float/date 타입
- 분석기: 사용자 정의 분석기, nori 한국어 형태소 분석기, 동의어 필터, ngram 토크나이저
- 클러스터 운영: 상태, 통계, 노드별 JVM/OS 메트릭, 샤드 할당, 핫-웜 아키텍처
- 모니터링: _cat/nodes, _tasks, 슬로우 로그 임계값 설정, 스레드 풀 상태, 샤드 검사
- API: _doc 색인, _bulk 일괄 작업, _mget, _msearch 다중 쿼리, scroll 딥 페이지네이션
자주 묻는 질문
term 쿼리와 match 쿼리의 차이는 무엇인가요?
term 쿼리는 분석 없이 필드에서 대소문자를 구분하는 정확한 매칭을 수행합니다. 상태 코드, ID, 열거형 값 같은 정확한 값을 매칭하기 위해 keyword 필드와 함께 사용합니다. match 쿼리는 매칭 전에 필드의 분석기(토큰화, 소문자 변환, 형태소 분석)를 통해 입력을 처리하여 text 필드의 전문 검색에 적합합니다. text 필드에 term 쿼리를 사용하면 분석된 텍스트가 소문자 변환 및 토큰화되므로 일반적으로 결과가 반환되지 않습니다.
필드를 text와 keyword 중 어느 타입으로 매핑해야 하나요?
전문 분석으로 검색하려는 필드(예: 기사 제목, 설명)에는 text를 사용합니다. 값이 역색인 저장을 위해 토큰으로 분리됩니다. 정확한 매칭, 정렬, 집계가 필요한 필드(예: 상태, 카테고리, 이메일 주소)에는 keyword를 사용합니다. 값이 그대로 저장됩니다. 일반적인 패턴은 두 가지를 모두 사용하는 멀티필드 매핑입니다: "title": { "type": "text", "fields": { "keyword": { "type": "keyword" } } }.
bool 쿼리는 어떻게 동작하나요?
bool 쿼리는 여러 쿼리 절을 논리 연산자로 결합합니다. must(AND, 점수에 영향), should(OR, 점수 향상), must_not(NOT, 결과에서 제외), filter(AND, 점수 없음, 캐시 됨)가 있습니다. must와 should의 쿼리는 관련성 점수에 영향을 주고, filter와 must_not은 영향을 주지 않습니다. filter 절은 Elasticsearch가 자동으로 캐시하므로 동일한 must 절보다 반복 사용 시 더 빠릅니다.
terms 집계와 cardinality 집계의 차이는 무엇인가요?
terms 집계는 문서를 필드 값별로 버킷에 그룹화하여 문서 수와 함께 상위 N개 값을 반환합니다. SQL의 GROUP BY와 유사합니다. cardinality 집계는 HyperLogLog++ 알고리즘을 사용하여 필드의 고유 값 수를 근사치로 반환합니다. 메모리 효율적이지만 근사치입니다(기본 정확도 약 3% 오차). 상위 값 분석에는 terms를, 대용량 데이터셋의 고유 수 메트릭에는 cardinality를 사용하세요.
nori 분석기는 무엇이고 언제 필요한가요?
nori 분석기는 Nori 토크나이저(MeCab-Ko/IPadic 기반)를 사용하여 한국어 형태소 분석을 수행합니다. 단순 공백이 아닌 의미 단위(형태소)로 텍스트를 분리합니다. nori 없이는 한국어 텍스트가 종종 단일 토큰으로 처리되어 전문 검색이 제대로 동작하지 않습니다. analysis-nori 플러그인을 설치하고 인덱스 설정에서 "tokenizer": "nori_tokenizer"를 사용하는 사용자 정의 분석기를 정의하여 한국어 콘텐츠에 활용하세요.
date_histogram 집계는 어떤 역할을 하나요?
date_histogram은 날짜 필드와 달력 간격(예: month, week, day, hour)을 기반으로 문서를 시간 버킷에 그룹화합니다. 각 간격별로 문서 수가 있는 버킷을 반환하여 일일 활성 사용자, 시간별 이벤트 발생률, 월별 매출 추이 같은 시계열 분석의 주요 도구입니다. date_histogram 내부에 메트릭 집계(avg, sum)를 중첩하여 기간별 통계를 계산할 수 있습니다.
scroll API는 언제 일반 페이지네이션 대신 사용해야 하나요?
scroll API는 데이터 내보내기나 재색인 같이 수천에서 수백만 개의 문서를 효율적으로 조회하기 위해 설계되었습니다. from/size 페이지네이션과 달리 scroll은 첫 번째 요청에서 인덱스 상태의 스냅샷을 찍고 scroll_id를 통해 배치로 반환합니다. 스냅샷이 메모리에 유지되므로 실시간 사용자 대면 페이지네이션에는 사용하지 마세요(그 경우 search_after를 사용). 배치 처리와 데이터 내보내기 파이프라인에 scroll을 사용하세요.
클러스터 상태가 yellow나 red일 때 어떻게 진단하나요?
yellow 상태는 모든 기본 샤드가 할당되었지만 일부 레플리카 샤드가 할당되지 않은 경우입니다(단일 노드 클러스터에서 흔함). red 상태는 하나 이상의 기본 샤드가 할당되지 않아 데이터 손실 위험이 있는 경우입니다. GET /_cluster/health로 전체 상태를 확인한 다음 GET /_cat/shards?v로 할당되지 않은 샤드를 찾으세요. GET /_cluster/allocation/explain을 사용하면 특정 샤드가 할당되지 않는 이유를 상세히 설명합니다.