🔍
Elasticsearch 치트시트

Docker & Linux 설치, Nori 한글 형태소 분석기, 인덱스 매핑, CRUD & Bulk API, Query DSL(Full Text, Term, Bool, Range), 집계(Aggregations), 클러스터 튜닝 및 Spring/Python 연동 실무 가이드
#elasticsearch#elastic#search-engine#nosql#nori#query-dsl#docker#kibana#backend최종 업데이트: 2026-10-04
Elasticsearch 치트시트 핵심 명령어 및 실전 가이드

## 1. Elasticsearch 핵심 아키텍처 & 동작 원리 (Architecture)
```mermaid
graph LR
  subgraph Client ["Client / App"]
    Req[REST API Request<br/>JSON Query DSL]
  end

  subgraph Cluster ["Elasticsearch Cluster"]
    subgraph Node1 ["Master-Eligible / Data Node 1"]
      P0["Index: products<br/>Primary Shard 0"]
      R1["Index: products<br/>Replica Shard 1"]
    end
    subgraph Node2 ["Data Node 2"]
      P1["Index: products<br/>Primary Shard 1"]
      R0["Index: products<br/>Replica Shard 0"]
    end
  end

  Req --> Node1
  Req --> Node2
  P0 -.->|Replication| R0
  P1 -.->|Replication| R1
```
```text
■ RDBMS vs Elasticsearch 핵심 개념 매핑
─────────────────────────────────────────────────────────────────────────────
  RDBMS               Elasticsearch            설명
─────────────────────────────────────────────────────────────────────────────
  Database (DB)   ->  Index                    데이터 논리적 저장소 단위
  Table           ->  Index (과거 Type 폐지)   7.x+부터 인덱스 당 1개의 매핑 타입만 허용
  Row             ->  Document                 JSON 포맷 단일 데이터 행
  Column          ->  Field                    JSON 속성 (text, keyword, integer 등)
  Schema          ->  Mapping                  필드 데이터 타입과 분석기(Analyzer) 정의
  SQL             ->  Query DSL                JSON 기반 검색 및 집계 질의 언어
  B-Tree Index    ->  Inverted Index (역색인)  단어(Term)가 위치한 문서 ID를 매핑하는 구조
─────────────────────────────────────────────────────────────────────────────
• 역색인(Inverted Index): 텍스트를 토큰화하여 단어 사전을 만들고, 해당 단어가 포함된 Document ID 목록을 보관하여 초고속 검색 제공
• Shard: 인덱스를 물리적으로 분할한 단위 (Primary Shard: 원본 데이터, Replica Shard: 장애 복구 및 검색 분산용 복제본)
```

---

## 2. Elasticsearch & Kibana 설치 & 실행 가이드 (Installation)
```bash
# 🐳 [1] Docker 단일 컨테이너 빠른 실행 (개발 & 로컬 테스트용)
# Elasticsearch 8.x는 기본적으로 보안(HTTPS/비밀번호)이 강제되므로, 로컬 테스트 시 xpack.security.enabled=false 옵션으로 간편 실행 가능
docker run -d \
  --name elasticsearch \
  -p 9200:9200 -p 9300:9300 \
  -e "discovery.type=single-node" \
  -e "xpack.security.enabled=false" \
  -e "ES_JAVA_OPTS=-Xms1g -Xmx1g" \
  -v es_data:/usr/share/elasticsearch/data \
  docker.elastic.co/elasticsearch/elasticsearch:8.13.0
```
```yaml
# 🐳 [2] Docker Compose: Elasticsearch + Kibana + Nori 한글 분석기
# docker-compose.yml
version: '3.8'

services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.13.0
    container_name: elasticsearch
    environment:
      - node.name=es01
      - cluster.name=es-docker-cluster
      - discovery.type=single-node
      - xpack.security.enabled=false
      - "ES_JAVA_OPTS=-Xms2g -Xmx2g"
    volumes:
      - es_data:/usr/share/elasticsearch/data
    ports:
      - "9200:9200"
      - "9300:9300"
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 65536
        hard: 65536

  kibana:
    image: docker.elastic.co/kibana/kibana:8.13.0
    container_name: kibana
    environment:
      - ELASTICSEARCH_HOSTS=http://elasticsearch:9200
      - I18N_LOCALE=ko-KR
    ports:
      - "5601:5601"
    depends_on:
      - elasticsearch

volumes:
  es_data:
```
```bash
# Nori 한글 형태소 분석기 플러그인 설치 (컨테이너 실행 후 1회 실행)
docker exec -it elasticsearch bin/elasticsearch-plugin install analysis-nori
docker restart elasticsearch

# 🐧 [3] Linux (Ubuntu / Debian) APT 패키지 설치
# GPG Key 등록 및 APT Repository 추가
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch-keyring.gpg
sudo apt install -y apt-transport-https
echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/8.x/apt stable main" | sudo tee /etc/apt/sources.list.d/elastic-8.x.list

sudo apt update && sudo apt install -y elasticsearch
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-nori

# 서비스 등록 및 시작
sudo systemctl daemon-reload
sudo systemctl enable --now elasticsearch
sudo systemctl status elasticsearch

# 🍏 [4] macOS (Homebrew 설치)
brew tap elastic/tap
brew install elastic/tap/elasticsearch-full
brew services start elastic/tap/elasticsearch-full

# 🪟 [5] Windows 환경
# WSL2(Ubuntu) 터미널에서 위 Linux APT 방식으로 설치하거나 Docker Desktop 실행을 적극 권장합니다.
```
```bash
# 🔍 [6] 클러스터 상태 확인 & 헬스체크 (Cluster Health & Cat APIs)
# 1. 클러스터 헬스 (status: green / yellow / red)
curl -X GET "http://localhost:9200/_cluster/health?pretty"

# 2. 노드 목록 및 리소스 점유 상태
curl -X GET "http://localhost:9200/_cat/nodes?v&h=ip,name,role,master,heap.percent,cpu"

# 3. 전체 인덱스 목록 및 문서 수/용량 확인
curl -X GET "http://localhost:9200/_cat/indices?v&s=index"

# 4. 샤드 분산 상태 점검
curl -X GET "http://localhost:9200/_cat/shards?v"
```

---

## 3. 인덱스 생성, 매핑 & Nori 한글 형태소 분석기 (Index & Mapping)
```bash
# [1] Nori 형태소 분석기 기반 인덱스 및 매핑 생성 (products 인덱스)
curl -X PUT "http://localhost:9200/products" -H 'Content-Type: application/json' -d'
{
  "settings": {
    "number_of_shards": 2,
    "number_of_replicas": 1,
    "index.refresh_interval": "1s",
    "analysis": {
      "tokenizer": {
        "nori_user_dict_tokenizer": {
          "type": "nori_tokenizer",
          "decompound_mode": "mixed",
          "user_dictionary_rules": [
            "맥북프로",
            "아이폰"
          ]
        }
      },
      "analyzer": {
        "korean_analyzer": {
          "type": "custom",
          "tokenizer": "nori_user_dict_tokenizer",
          "filter": [
            "nori_readingform",
            "lowercase",
            "nori_part_of_speech_filter"
          ]
        }
      },
      "filter": {
        "nori_part_of_speech_filter": {
          "type": "nori_part_of_speech",
          "stoptags": [
            "E", "IC", "J", "MAG", "MAJ", "MM", "SP", "SSC", "SSO", "SC", "SE", "XPN", "XSA", "XSN", "XSV", "UNA", "NA", "VSV"
          ]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "id": { "type": "keyword" },
      "title": {
        "type": "text",
        "analyzer": "korean_analyzer",
        "fields": {
          "keyword": { "type": "keyword", "ignore_above": 256 }
        }
      },
      "description": {
        "type": "text",
        "analyzer": "korean_analyzer"
      },
      "category": { "type": "keyword" },
      "tags": { "type": "keyword" },
      "price": { "type": "long" },
      "stock": { "type": "integer" },
      "is_active": { "type": "boolean" },
      "created_at": {
        "type": "date",
        "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
      }
    }
  }
}'
```
```bash
# [2] 형태소 분석기 동작 테스트 (_analyze API)
curl -X POST "http://localhost:9200/products/_analyze" -H 'Content-Type: application/json' -d'
{
  "analyzer": "korean_analyzer",
  "text": "최신 맥북프로와 애플 무선 이어폰을 구매했습니다."
}
'

# [3] 인덱스 매핑 확인 및 인덱스 삭제
curl -X GET "http://localhost:9200/products/_mapping?pretty"
curl -X DELETE "http://localhost:9200/products"
```
> [!TIP]
> **`text` vs `keyword` 타입의 차이**:
> - `text`: 형태소 분석기(Analyzer)에 의해 토큰으로 쪼개져 전문 검색(Full-text Search, match 쿼리)에 사용됩니다.
> - `keyword`: 쪼개지 않고 원문 그대로 역색인되어 완전 일치 검색(term 쿼리), 정렬(sort), 집계(aggregations, group by)에 사용됩니다.

---

## 4. 도큐먼트 CRUD & Bulk 대량 처리 (Document CRUD & Bulk)
```bash
# [1] 단건 도큐먼트 등록 (POST: ID 자동생성 / PUT: ID 지정)
# ID 1번 도큐먼트 명시적 생성
curl -X PUT "http://localhost:9200/products/_doc/1" -H 'Content-Type: application/json' -d'
{
  "id": "PROD-001",
  "title": "애플 M3 맥북프로 16인치 스페이스 블랙",
  "description": "최고의 성능을 자랑하는 전문 작업용 맥북프로 노트북입니다.",
  "category": "노트북",
  "tags": ["애플", "노트북", "M3", "맥북"],
  "price": 3690000,
  "stock": 25,
  "is_active": true,
  "created_at": "2026-10-04 10:00:00"
}'

# [2] 도큐먼트 단건 조회 (GET)
curl -X GET "http://localhost:9200/products/_doc/1?pretty"

# [3] 도큐먼트 부분 수정 (_update API)
curl -X POST "http://localhost:9200/products/_update/1" -H 'Content-Type: application/json' -d'
{
  "doc": {
    "price": 3590000,
    "stock": 20
  }
}'

# [4] 도큐먼트 삭제 (DELETE)
curl -X DELETE "http://localhost:9200/products/_doc/1"
```
```bash
# [5] Bulk API 대량 인덱싱 (NDJSON 포맷 - 명령행과 데이터행이 번갈아 배치되며 끝에 반드시 개행 포함)
curl -X POST "http://localhost:9200/_bulk" -H 'Content-Type: application/x-ndjson' -d'
{ "index" : { "_index" : "products", "_id" : "2" } }
{ "id": "PROD-002", "title": "삼성 갤럭시북4 프로 14인치", "description": "가볍고 휴대성이 뛰어난 고성능 인텔 울트라 노트북", "category": "노트북", "tags": ["삼성", "노트북", "갤럭시"], "price": 1850000, "stock": 40, "is_active": true, "created_at": "2026-10-04 11:00:00" }
{ "index" : { "_index" : "products", "_id" : "3" } }
{ "id": "PROD-003", "title": "LG 그램 프로 16 울트라", "description": "초경량 대화면 초슬림 노트북", "category": "노트북", "tags": ["LG", "노트북", "그램"], "price": 2100000, "stock": 15, "is_active": true, "created_at": "2026-10-04 12:00:00" }
{ "index" : { "_index" : "products", "_id" : "4" } }
{ "id": "PROD-004", "title": "애플 매직 마우스 화이트", "description": "블루투스 멀티 터치 제스처 지원 무선 마우스", "category": "주변기기", "tags": ["애플", "마우스", "무선"], "price": 119000, "stock": 100, "is_active": true, "created_at": "2026-10-04 13:00:00" }
{ "index" : { "_index" : "products", "_id" : "5" } }
{ "id": "PROD-005", "title": "로지텍 MX Master 3S 마우스", "description": "무소음 클릭과 초고속 휠을 탑재한 업무용 끝판왕 마우스", "category": "주변기기", "tags": ["로지텍", "마우스", "블루투스"], "price": 139000, "stock": 80, "is_active": true, "created_at": "2026-10-04 14:00:00" }

'
```

---

## 5. 쿼리 DSL 핵심 검색 (Query DSL: Match, Term, Bool, Range)
```bash
# [1] match 검색 (전문 형태소 분석 검색: '맥북' 또는 '노트북' 검색)
curl -X GET "http://localhost:9200/products/_search" -H 'Content-Type: application/json' -d'
{
  "query": {
    "match": {
      "title": "맥북 노트북"
    }
  }
}'

# [2] term 검색 (정확한 완전 일치 검색 - keyword 필드에 주로 사용)
curl -X GET "http://localhost:9200/products/_search" -H 'Content-Type: application/json' -d'
{
  "query": {
    "term": {
      "category": "노트북"
    }
  }
}'

# [3] multi_match 검색 (여러 필드에 걸쳐 검색 + 가중치 boost 부여)
# title 필드 일치 시 점수를 3배(^3) 가중치 부여
curl -X GET "http://localhost:9200/products/_search" -H 'Content-Type: application/json' -d'
{
  "query": {
    "multi_match": {
      "query": "애플",
      "fields": ["title^3", "description", "tags"]
    }
  }
}'
```
```bash
# [4] 실무 표준: bool 쿼리 (must, filter, should, must_not 조합)
# • must: 점수 계산 반영 + 필수 일치
# • filter: 점수 계산 안 함 (캐싱되어 성능 매우 빠름) + 조건 필터링
# • should: 필수 아님 (매칭 시 검색 순위 점수 상승)
# • must_not: 반드시 제외
curl -X GET "http://localhost:9200/products/_search" -H 'Content-Type: application/json' -d'
{
  "query": {
    "bool": {
      "must": [
        { "match": { "title": "노트북" } }
      ],
      "filter": [
        { "term": { "is_active": true } },
        { "range": { "price": { "gte": 1500000, "lte": 4000000 } } }
      ],
      "should": [
        { "match_phrase": { "title": "맥북프로" } }
      ],
      "must_not": [
        { "term": { "category": "중고" } }
      ]
    }
  },
  "sort": [
    { "price": { "order": "desc" } },
    { "_score": { "order": "desc" } }
  ],
  "from": 0,
  "size": 10,
  "highlight": {
    "pre_tags": ["<mark class=\"hl\">"],
    "post_tags": ["</mark>"],
    "fields": {
      "title": {}
    }
  }
}'
```
```bash
# [5] 대용량 딥 페이징 (Search After 기법: from/size 10,000건 초과 시 권장)
# 첫 페이지 호출 (정렬 기준 값 _sort 결과를 확인)
curl -X GET "http://localhost:9200/products/_search" -H 'Content-Type: application/json' -d'
{
  "size": 10,
  "query": { "match_all": {} },
  "sort": [
    { "created_at": "desc" },
    { "id": "asc" }
  ]
}'

# 다음 페이지 호출 (이전 페이지 마지막 항목의 sort 배열 값을 search_after에 전달)
curl -X GET "http://localhost:9200/products/_search" -H 'Content-Type: application/json' -d'
{
  "size": 10,
  "query": { "match_all": {} },
  "search_after": [1791111600000, "PROD-004"],
  "sort": [
    { "created_at": "desc" },
    { "id": "asc" }
  ]
}'
```

---

## 6. 통계 및 데이터 분석 집계 (Aggregations)
```bash
# [1] 메트릭 집계 (Metrics: 평균, 최소, 최대, 합계, 고유값 카운트)
curl -X GET "http://localhost:9200/products/_search" -H 'Content-Type: application/json' -d'
{
  "size": 0,
  "aggs": {
    "avg_product_price": {
      "avg": { "field": "price" }
    },
    "price_stats": {
      "stats": { "field": "price" }
    },
    "unique_category_count": {
      "cardinality": { "field": "category" }
    }
  }
}'

# [2] 버킷 집계 & 서브 집계 (Category별 상품 수 그룹화 + 카테고리별 평균 가격)
curl -X GET "http://localhost:9200/products/_search" -H 'Content-Type: application/json' -d'
{
  "size": 0,
  "aggs": {
    "by_category": {
      "terms": {
        "field": "category",
        "size": 10,
        "order": { "_count": "desc" }
      },
      "aggs": {
        "avg_price": {
          "avg": { "field": "price" }
        },
        "total_stock": {
          "sum": { "field": "stock" }
        }
      }
    }
  }
}'

# [3] 시계열 날짜 히스토그램 집계 (Date Histogram: 일자별 등록 추이)
curl -X GET "http://localhost:9200/products/_search" -H 'Content-Type: application/json' -d'
{
  "size": 0,
  "aggs": {
    "daily_trends": {
      "date_histogram": {
        "field": "created_at",
        "calendar_interval": "1d",
        "format": "yyyy-MM-dd"
      }
    }
  }
}'
```

---

## 7. 실무 애플리케이션 연동 예제 (Python & Spring Boot)
```python
# 🐍 [1] Python (elasticsearch 공식 클라이언트)
# pip install elasticsearch
from elasticsearch import Elasticsearch

es = Elasticsearch("http://localhost:9200")

# 1. 핑 테스트
if not es.ping():
    raise ValueError("Elasticsearch 서버 연결 실패")

# 2. 도큐먼트 색인
doc = {
    "id": "PROD-010",
    "title": "애플 에어팟 프로 2세대 USB-C",
    "category": "음향기기",
    "price": 359000,
    "stock": 50,
    "is_active": True
}
res = es.index(index="products", id="10", document=doc)
print(f"인덱싱 결과: {res['result']}")

# 3. 복합 검색 쿼리 실행
query = {
    "bool": {
      "must": [{"match": {"title": "에어팟"}}],
      "filter": [{"term": {"is_active": True}}]
    }
}
response = es.search(index="products", query=query, size=5)
for hit in response["hits"]["hits"]:
    source = hit["_source"]
    print(f"[{hit['_score']:.2f}] {source['title']} - {source['price']:,}원")
```
```java
// 🍃 [2] Spring Boot (Spring Data Elasticsearch)
// build.gradle: implementation 'org.springframework.boot:spring-boot-starter-data-elasticsearch'

@Document(indexName = "products")
@Setting(replicas = 1, shards = 2)
public class ProductDocument {
    @Id
    private String id;

    @Field(type = FieldType.Text, analyzer = "korean_analyzer")
    private String title;

    @Field(type = FieldType.Keyword)
    private String category;

    @Field(type = FieldType.Long)
    private Long price;

    @Field(type = FieldType.Boolean)
    private Boolean isActive;
    
    // getters and setters...
}

public interface ProductRepository extends ElasticsearchRepository<ProductDocument, String> {
    // 메서드 쿼리 생성
    List<ProductDocument> findByCategoryAndIsActiveTrue(String category);
    
    // 네이티브 검색 쿼리
    @Query("{\"bool\": {\"must\": [{\"match\": {\"title\": \"?0\"}}], \"filter\": [{\"term\": {\"isActive\": true}}]}}")
    List<ProductDocument> searchByTitle(String keyword);
}
```

---

## 8. 실무 운영 튜닝 & 클러스터 트러블슈팅 (Performance & Ops)
```text
■ JVM Heap Memory 설정 원칙
1. 물리 시스템 RAM의 50%를 초과하지 말 것:
   - 나머지 50% 메모리는 OS의 파일 시스템 루씬 캐시(Page Cache)로 필수 활용됩니다.
2. 최대 31GB 이하로 제한할 것:
   - 32GB 이상 설정 시 JVM이 압축 객체 포인터(Compressed OOPs)를 비활성화하여 메모리 낭비와 GC 오버헤드가 급증합니다.
   - 예: /etc/elasticsearch/jvm.options -> -Xms16g -Xmx16g
```
```bash
# [1] 대량 데이터(Bulk) 적재 시 속도 극대화 설정
# 임시로 리프레시와 복제본을 비활성화한 뒤 대량 적재 -> 완료 후 복구
curl -X PUT "http://localhost:9200/products/_settings" -H 'Content-Type: application/json' -d'
{
  "index": {
    "refresh_interval": "-1",
    "number_of_replicas": 0
  }
}'

# 대량 적재 완료 후 원복 및 강제 병합(Force Merge)
curl -X PUT "http://localhost:9200/products/_settings" -H 'Content-Type: application/json' -d'
{
  "index": {
    "refresh_interval": "1s",
    "number_of_replicas": 1
  }
}'
curl -X POST "http://localhost:9200/products/_forcemerge?max_num_segments=1"
```
```bash
# [2] 클러스터 상태가 Yellow 또는 Red일 때 원인 분석 (Allocation Explain API)
# 샤드가 특정 노드에 할당되지 못하는 이유를 정확히 진단
curl -X GET "http://localhost:9200/_cluster/allocation/explain?pretty"

# [3] 디스크 용량 한도(Disk Watermark) 초과로 읽기 전용 락이 걸렸을 때 해제
# 기본 임계치: Low 85%, High 90%, Flood Stage 95%
curl -X PUT "http://localhost:9200/products/_settings" -H 'Content-Type: application/json' -d'
{
  "index.blocks.read_only_allow_delete": null
}
'
```
💬
Elasticsearch 치트시트

의견 및 질문

댓글 수정

댓글 삭제
