김신건의 로그 - 위키 / search

[Search] Elasticsearch vs OpenSearch: 라이센스 분기와 차이

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

OpenSearch = AWS 가 2021 년 Elasticsearch 7.10 에서 fork 한 Apache 2.0 라이센스 search engine. Kibana → OpenSearch Dashboards 도 함께 fork.

분기 타임라인

gantt
    title ES vs OpenSearch 라이센스 / 분기
    dateFormat YYYY-MM
    axisFormat %Y-%m

    section Elastic
    Apache 2.0 (~7.10) :a1, 2010-02, 2021-01
    SSPL + ES License  :a2, 2021-01, 2024-08
    + AGPLv3 추가      :a3, 2024-08, 2026-12

    section OpenSearch
    AWS fork (Apache 2.0) :crit, b1, 2021-04, 2026-12
    OpenSearch 1.0 GA     :milestone, m1, 2021-07, 0d
    OpenSearch 2.0        :milestone, m2, 2022-05, 0d
    OpenSearch 3.0        :milestone, m3, 2025-05, 0d
    OpenSearch Linux Foundation :milestone, m4, 2024-09, 0d

시점	이벤트
2021-01	Elastic 가 SSPL + ES License 로 전환 (AWS 비판)
2021-04	AWS 가 OpenSearch 프로젝트 시작
2021-07	OpenSearch 1.0 GA
2022-05	OpenSearch 2.0
2024-08	Elastic 가 AGPLv3 추가 (8.16+, OSI 호환 복귀)
2024-09	OpenSearch 가 Linux Foundation 으로 이관
2025-05	OpenSearch 3.0

ES vs OpenSearch 매트릭스 (2026-06)

항목	Elasticsearch	OpenSearch
라이센스	AGPLv3 + SSPL + ES License (3-way)	Apache 2.0
거버넌스	Elastic (단일 회사)	Linux Foundation (다 vendor)
Cloud (managed)	Elastic Cloud + 3rd party	AWS OpenSearch Service + Aiven, ScalyR 등
출발점	original	ES 7.10 fork
ESQL	예 (8.11+)	PPL (Piped Processing Language)
Vector / kNN	dense_vector + ELSER + semantic_text	kNN plugin + Neural Search
ML 통합	강	강 (자체 ML Commons)
ILM / ISM	ILM	ISM (Index State Management)
Kibana 호환	Kibana	OpenSearch Dashboards
API 호환	(자체 진화)	ES 7.10 API + 자체 확장
학습	풍부 (긴 역사)	빠르게 성장
사용자	큰 기업 + Elastic 생태계	AWS 사용자 + 라이센스 회피

기술적 차이 (2026 시점)

Elasticsearch 만의 기능

ELSER (Elastic Learned Sparse EncodeR)
semantic_text field (8.15+) 자동 chunk + embedding
ESQL (Elasticsearch Query Language)
Better Binary Quantization (BBQ) (9.x)
Search AI Lake (storage 분리)
Universal Profiling (continuous profiling)

OpenSearch 만의 기능

PPL (Piped Processing Language) - SQL-like
Observability (자체 통합)
Anomaly Detection (자체 ML)
Security Analytics (SIEM)
Neural Search (BM25 + vector hybrid)
k-NN plugin with FAISS

[!NOTE] 2026 시점 기능 차이가 점점 벌어지고 있다. Elastic 의 ESQL + ELSER + semantic_text 가 상품 차별화. OpenSearch 는 AWS 통합 + ML Commons 강조.

결정 트리

flowchart TD
    Q1{사용 환경}
    Q1 -->|AWS managed 운영| Q2{"ES 의 최신 기능 (ESQL, ELSER) 필요?"}
    Q1 -->|self-host| Q3{라이센스 우려?}
    Q1 -->|Elastic Cloud 사용 중| Elastic_O[Elasticsearch]
    Q2 -->|예| Elastic_C[Elasticsearch on AWS]
    Q2 -->|아니오| OS_AWS[AWS OpenSearch Service]
    Q3 -->|AGPL 영향 우려| OS[OpenSearch]
    Q3 -->|문제 없음| Elastic_S[Elasticsearch self-host]

마이그레이션 (ES ↔ OpenSearch)

방향	난이도
ES 7.10 → OpenSearch	쉬움 (분기점)
ES 8.x → OpenSearch	중간 (API 차이 누적)
OpenSearch → ES 8.x	어려움 (각자 자체 기능)

Reindex API + clients-migration tool. 일반적 데이터는 OK, 고급 기능 (ESQL, ELSER, ML) 은 호환성 깨짐.

다른 검색 엔진 (참고)

도구	특징
Apache Solr	Lucene 위, ES 의 직전 표준. 옛 강함
Typesense	Go, fast, 작은 데이터셋
Meilisearch	Rust, dev 친화 UI
Algolia	SaaS, 매우 빠름
Vespa (Yahoo)	scale + ML ranking
Quickwit	Rust, log 특화

흔한 함정

[!WARNING]

“OpenSearch 는 ES” 라고 가정 = API 비호환 영역 다수. 명시 테스트.

AGPL 의 의미 오해 = SaaS 노출 시 source 공개 의무 가 켜진다. Elastic 가 AGPL 옵션 추가했지만, 상업 활용 은 SSPL/ES License.

ESQL → PPL 자동 변환 = 없음. 마이그레이션 시 수동 재작성.

[Search] ElasticSearch 기본 원리: Inverted Index, Segment, Lucene

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

ES 의 모든 동작 은 Lucene 의 inverted index 위에 얹혀있다. 문서 단위 저장 + term 단위 검색 의 분리.

Inverted Index (역색인)

{}

위 trie 의 prefix tree 구조 가 term dictionary 의 직관. Lucene 은 FST (Finite State Transducer) 라는 압축된 trie 사용.

일반 정방향 인덱스 vs 역색인

flowchart LR
    subgraph Forward["Forward Index (DB)"]
        D1["doc 1: 'rabbit hat'"]
        D2["doc 2: 'red rabbit'"]
        D3["doc 3: 'big hat'"]
    end
    subgraph Inverted["Inverted Index (Lucene)"]
        T1["'rabbit' → [1, 2]"]
        T2["'hat' → [1, 3]"]
        T3["'red' → [2]"]
        T4["'big' → [3]"]
    end

정방향	역색인
doc → terms	term → docs
RDB 의 row	검색에 최적
`LIKE '%rabbit%'` = O(N)	term 으로 즉시 lookup

검색 흐름

sequenceDiagram
    autonumber
    Client->>ES: GET /idx/_search { "match": { "title": "rabbit hat" } }
    ES->>Analyzer: 쿼리 분석 (tokenize)
    Analyzer-->>ES: tokens: ["rabbit", "hat"]
    ES->>Inv: term lookup
    Inv-->>ES: postings: rabbit=[1,2], hat=[1,3]
    ES->>ES: intersection / union (BM25 score 계산)
    ES->>ES: 정렬 (score desc)
    ES-->>Client: top hits

Segment: Lucene 의 단위

flowchart TB
    Shard[Shard]
    Shard --> Seg1["Segment 1<br/>(불변)"]
    Shard --> Seg2["Segment 2<br/>(불변)"]
    Shard --> Seg3["Segment 3<br/>(불변)"]
    Shard --> Seg4["Segment N<br/>(최신)"]

속성	의미
Immutable	segment 는 생성 후 절대 변경 안 됨
Append-only	새 문서 = 새 segment
Merge	여러 segment 를 주기적으로 큰 하나로 (background)
Delete	삭제 = 별도 `.del` 파일에 표시 (실제 제거는 merge 시)

[!IMPORTANT] Segment 의 불변성 이 ES 의 concurrent search + write 가능 의 토대. 동시 읽기에 lock 없음.

Near Real-Time: refresh

sequenceDiagram
    autonumber
    participant App
    participant Buf as In-memory Buffer
    participant FS as FS Cache (segment)
    participant Disk

    App->>Buf: index doc (즉시 검색 안 됨)
    Note over Buf: refresh interval (1초 기본)
    Buf->>FS: refresh → 새 segment (검색 가능!)
    Note over FS: 메모리 cache 에 있을 뿐 디스크 아직
    Note over FS: flush 주기
    FS->>Disk: fsync (durable)

동작	주기	의미
Buffer → Refresh	1초 (`refresh_interval`)	검색 가능 (still in memory)
Refresh → Flush	`index.translog.flush_threshold_size`	디스크 fsync
Merge	백그라운드	작은 segment 들 → 큰 segment

[!TIP] 대량 인덱싱 시 refresh_interval: -1 로 끄면 수배 빠름. 인덱싱 후 명시적 _refresh.

Translog (WAL)

flowchart LR
    Write[Index API] --> Buf[Buffer]
    Write --> TL["Translog<br/>(WAL)"]
    TL -->|fsync 주기| Disk

Refresh 와 무관하게 write 가 안전. 자세한 건 [[wal-write-ahead-log]].

모드	동작
`request` (기본)	매 요청 fsync (느림, 안전)
`async`	주기적 fsync (5s 기본)

Document 와 ID

PUT /products/_doc/sku-1234
{
  "name": "Mechanical Keyboard",
  "price": 129.99,
  "tags": ["accessory", "input"]
}

필드	의미
`_index`	인덱스 이름
`_id`	문서 ID (없으면 자동 생성)
`_source`	원본 JSON (저장 + 반환용)
`_version`	낙관적 동시성 제어
`_seq_no`, `_primary_term`	versioning 의 개선판

Routing

shard = hash(routing) % number_of_primary_shards

기본 routing = _id.
같은 routing → 같은 shard.
멀티 테넌트 에서 routing = tenant_id 로 데이터 locality.

자세한 영역

인덱싱 흐름 + mapping: [[elasticsearch-indexing]]
쿼리 종류: [[elasticsearch-query]]
cluster, shard: [[elasticsearch-infrastructure]]
BM25: [[elasticsearch-relevance-scoring]]
한국어 분석: [[elasticsearch-korean-indexing]]

[Search] ElasticSearch: Lucene 위 분산 검색 엔진

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

ElasticSearch = Apache Lucene 위의 분산 RESTful 검색/분석 엔진. 2010 출시. Logstash + Kibana + Beats 와 함께 Elastic Stack (옛 ELK) 의 코어.

[!IMPORTANT] 2026-06 시점 세계 가장 많이 쓰이는 검색 엔진. 전문 검색, 로그 분석, APM, SIEM, vector search, RAG 의 de facto.

라이센스 분기 타임라인

시점	이벤트
2010	ES 출시. Apache 2.0
2021-01	SSPL + ES License 로 전환 (AWS 와의 갈등)
2021-04	AWS 가 OpenSearch fork (ES 7.10 기반, Apache 2.0)
2024-08	Elastic 가 AGPLv3 추가 (blog). 8.16+ 부터 AGPL/SSPL/ES License 3-way 선택
2026	ES 9.x stable 운영. OpenSearch 도 계속 활성

[!NOTE] Elastic 가 다시 OSI 호환 라이센스 (AGPL) 를 추가. OpenSearch 와의 경쟁 + 사용자 신뢰 회복 의 결합 결정. 단 managed cloud 운영 제약 은 SSPL 유지.

핵심 컴포넌트

flowchart LR
    Beats[Beats / Elastic Agent] -->|input| LS[Logstash<br/>또는 Ingest pipeline]
    LS --> ES[(Elasticsearch)]
    ES --> Kib["Kibana<br/>(시각화 + 관리)"]
    App[App] -->|REST + JSON| ES
    App -->|ESQL| ES

컴포넌트	역할
Elasticsearch	분산 인덱스 + 검색 + 분석
Kibana	UI, dashboard, dev tools, alerting
Logstash	데이터 수집 + 변환 (옛). 현재 Ingest pipeline 이 대안
Beats	가벼운 shipper. Elastic Agent 로 통합 진행 중
Fleet	Elastic Agent 의 중앙 관리

ES 의 본질

flowchart LR
    Doc[JSON Document] -->|index API| Analyze["Analyzer<br/>(tokenize, normalize)"]
    Analyze --> Inv["Inverted Index<br/>(term → docs)"]
    Inv --> Lucene[(Lucene segments)]
    Query[Query] -->|search API| Score[BM25 scoring]
    Score --> Sort[Sort by relevance]
    Sort --> Result[Top-K results]

JSON 문서 단위 저장.
자동 inverted index 빌드.
near real-time (인덱싱 후 1초 내 검색 가능).
RESTful + JSON: HTTP 만 알면 사용.

자세한 원리는 [[elasticsearch-basics]].

ES vs 다른 DB

	ElasticSearch	RDBMS	MongoDB	Solr
강점	full-text search + analytics	트랜잭션	문서 + flexible	full-text search
약점	트랜잭션, write-heavy	full-text 약함	검색 약함	분산 운영 어려움
Query	DSL + ESQL	SQL	MQL	DSL
Scaling	shard + replica	replica + read split	shard	shard
사용	search, log, APM	OLTP	문서 + 모바일	search (옛)

ES 8.x → 9.x 주요 변화

영역	8.x	9.x (2025+)
ESQL	도입 (8.11)	프로덕션 표준
Vector	dense_vector + kNN	quantization 자동, BBQ
ELSER	영문 모델 (sparse)	다국어 + v2
Inference API	외부 LLM 통합	endpoint 확장
Bytes/Cost	기본	Search AI Lake (storage 분리)
Snapshots	지원	searchable snapshots 강화

활용 카테고리

flowchart TB
    Use[ES 활용]
    Use --> Search[Site search, e-commerce, autocomplete]
    Use --> Log[Logs: Filebeat → ES → Kibana]
    Use --> APM[APM, OpenTelemetry 통합]
    Use --> SIEM["Security (SIEM), threat detection"]
    Use --> Metrics[Metrics, Observability]
    Use --> Vector[Vector search, RAG, semantic]
    Use --> Geo[Geo search, maps]

인접 위키

[[Redis Vector Search]] (대안 vector store)
[[mongodb]] (문서 DB)
[[Kafka]] (로그 수집 파이프)
[[prometheus]] (메트릭 대안)
[[opentelemetry]] (관측)

[Search] ES Aggregations: metric, bucket, pipeline

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Aggregations (aggs) = ES 의 집계 분석. SQL 의 GROUP BY + 함수 + window. 검색 결과 또는 전체 위에서.

3가지 카테고리

flowchart TB
    Agg[Aggregations]
    Agg --> Metric["Metric<br/>(숫자 계산)"]
    Agg --> Bucket["Bucket<br/>(그룹화)"]
    Agg --> Pipeline["Pipeline<br/>(agg 결과를 재처리)"]
    Metric --> M1["sum, avg, min, max, stats, extended_stats, percentiles, cardinality, value_count"]
    Bucket --> B1["terms, date_histogram, histogram, range, date_range, geo_distance, filter, filters, missing, nested"]
    Pipeline --> P1["derivative, moving_avg, bucket_script, cumulative_sum, max_bucket, percentiles_bucket"]

Metric Aggregations

GET /products/_search
{
  "size": 0,
  "aggs": {
    "avg_price":   { "avg":   { "field": "price" } },
    "max_price":   { "max":   { "field": "price" } },
    "total_sold":  { "sum":   { "field": "sold_count" } },
    "unique_categories": { "cardinality": { "field": "category.keyword" } },
    "stats_price": { "stats": { "field": "price" } },
    "percentiles_price": {
      "percentiles": { "field": "price", "percents": [50, 95, 99] }
    }
  }
}

Metric	의미
`avg`, `min`, `max`, `sum`	기본
`stats`	min/max/avg/sum/count 한 번에
`extended_stats`	+ variance, std_dev
`percentiles`	p50, p95, p99 (HDR 또는 t-digest)
`cardinality`	근사 unique count (HLL)
`value_count`	non-null count
`top_hits`	bucket 안의 대표 문서

[!IMPORTANT] cardinality 는 HyperLogLog 추정. 정확 unique 가 필요하면 별도 계산.

Bucket Aggregations

Terms (GROUP BY)

{
  "aggs": {
    "by_category": {
      "terms": { "field": "category.keyword", "size": 10 },
      "aggs": {
        "avg_price": { "avg": { "field": "price" } }
      }
    }
  }
}

Sub-aggregation 으로 중첩: 카테고리별 평균 가격.

Date Histogram (시계열)

{
  "aggs": {
    "sales_by_day": {
      "date_histogram": {
        "field": "created_at",
        "calendar_interval": "1d",
        "time_zone": "Asia/Seoul",
        "min_doc_count": 0
      },
      "aggs": {
        "revenue": { "sum": { "field": "total" } }
      }
    }
  }
}

Filters (다중 조건 동시)

{
  "aggs": {
    "tiers": {
      "filters": {
        "filters": {
          "cheap":  { "range": { "price": { "lt": 50 } } },
          "mid":    { "range": { "price": { "gte": 50, "lt": 200 } } },
          "luxury": { "range": { "price": { "gte": 200 } } }
        }
      }
    }
  }
}

Pipeline Aggregations

Derivative + Cumulative Sum

{
  "aggs": {
    "sales_per_day": {
      "date_histogram": { "field": "date", "calendar_interval": "1d" },
      "aggs": {
        "revenue":           { "sum": { "field": "total" } },
        "revenue_diff":      { "derivative": { "buckets_path": "revenue" } },
        "cumulative_revenue":{ "cumulative_sum": { "buckets_path": "revenue" } },
        "moving_7d":         { "moving_avg": { "buckets_path": "revenue", "window": 7 } }
      }
    }
  }
}

bucket_script (커스텀 비율)

{
  "aggs": {
    "by_day": {
      "date_histogram": { ... },
      "aggs": {
        "revenue":      { "sum": { "field": "total" } },
        "refund":       { "sum": { "field": "refund_amount" } },
        "refund_ratio": {
          "bucket_script": {
            "buckets_path": { "r": "refund", "v": "revenue" },
            "script": "params.r / params.v"
          }
        }
      }
    }
  }
}

Composite Aggregation (pagination)

terms 의 큰 cardinality 페이지네이션:

{
  "aggs": {
    "by_user_day": {
      "composite": {
        "size": 100,
        "sources": [
          { "user":  { "terms": { "field": "user_id" } } },
          { "day":   { "date_histogram": { "field": "ts", "calendar_interval": "1d" } } }
        ],
        "after": { "user": "...", "day": ... }
      }
    }
  }
}

Doc Count Error

"buckets": [
  { "key": "A", "doc_count": 100 },
  { "key": "B", "doc_count": 80 }
],
"sum_other_doc_count": 250,
"doc_count_error_upper_bound": 5

terms 는 각 shard 의 top-N 합산 → 전역 정확도 보장 X. size 늘리면 정확도 ↑.

ESQL 의 STATS

ESQL 의 간결 표현:

FROM products
| STATS avg_price = AVG(price), max_price = MAX(price) BY category
| SORT avg_price DESC
| LIMIT 10

DSL 의 terms + avg 와 동등. 자세한 건 [[elasticsearch-query]] 의 ESQL.

시각화 (Kibana)

Agg	Kibana 시각화
`date_histogram`	line chart
`terms`	bar / pie / table
`range`	bar
`percentiles`	bar / table
`cardinality`	metric panel

흔한 함정

[!WARNING]

terms size 너무 큼 = 메모리 폭증. composite 로.

text 필드에 terms = fielddata 활성 필요 (메모리 비쌈). keyword multi-field.

scripted metric = 매 doc 평가, 느림. index time 계산 권장.

cardinality 의 정확도 = precision_threshold 옵션. 기본 3000.

[Search] ES Indexing: bulk, refresh, ingest pipeline

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Indexing = JSON 문서를 역색인에 등록 하는 행위. Lucene segment 빌드 + refresh + flush 의 흐름.

단일 인덱싱

PUT /products/_doc/sku-1
{ "name": "Keyboard", "price": 100 }

동작	결과
ID 명시	upsert (있으면 update)
ID 자동	`POST /products/_doc`
Create-only	`PUT /products/_create/sku-1` (있으면 409)

Bulk API (실전)

POST /_bulk
{ "index": { "_index": "products", "_id": "sku-1" } }
{ "name": "Keyboard", "price": 100 }
{ "index": { "_index": "products", "_id": "sku-2" } }
{ "name": "Mouse", "price": 50 }
{ "delete": { "_index": "products", "_id": "sku-old" } }
{ "update": { "_index": "products", "_id": "sku-1" } }
{ "doc": { "price": 95 } }

[!IMPORTANT] 단일 인덱싱 보다 100배 빠름. 5-15 MB / batch, 1000-10000 docs 권장.

Bulk 흐름

sequenceDiagram
    autonumber
    Client->>Coord[Coordinator Node]: _bulk
    Coord->>Coord: 각 doc 의 shard 계산
    par 각 shard 병렬
        Coord->>P1[Primary Shard 1]: 부분
        Coord->>P2[Primary Shard 2]: 부분
    end
    P1->>R1[Replica 1]: 복제
    P2->>R2[Replica 2]: 복제
    P1-->>Coord: ack
    P2-->>Coord: ack
    Coord-->>Client: 결과 (각 item 의 status)

대량 인덱싱 튜닝

PUT /products/_settings
{
  "index.refresh_interval": "-1",      # refresh 끄기
  "index.number_of_replicas": 0,       # replica 끄기
  "index.translog.durability": "async" # WAL 비동기
}

# 인덱싱...

PUT /products/_settings
{
  "index.refresh_interval": "1s",
  "index.number_of_replicas": 1
}
POST /products/_refresh
POST /products/_forcemerge?max_num_segments=1

수 배 빠름. 단 진행 중 검색 결과 stale + 실패 시 손실 위험 있어 별도 인덱스 에 작업 후 alias swap.

Index 생성 + Mapping

PUT /products
{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 1,
    "analysis": { ... }
  },
  "mappings": {
    "properties": {
      "name":    { "type": "text", "analyzer": "korean" },
      "price":   { "type": "double" },
      "tags":    { "type": "keyword" },
      "created": { "type": "date" },
      "vector":  { "type": "dense_vector", "dims": 384 }
    }
  }
}

자세한 mapping 은 [[elasticsearch-mapping]].

Ingest Pipeline (Logstash 대안)

PUT /_ingest/pipeline/products-pipeline
{
  "processors": [
    { "lowercase": { "field": "tags" } },
    { "set": { "field": "ingested_at", "value": "{{_ingest.timestamp}}" } },
    { "remove": { "field": "raw" } },
    { "grok": { "field": "log", "patterns": ["%{IP:client} %{WORD:method}"] } }
  ]
}

POST /_bulk?pipeline=products-pipeline
...

문서가 ES 에 들어오기 전 변환. Logstash 같은 별도 프로세스 없이 ES 내장. 대부분의 경량 변환 은 ingest pipeline 으로.

Update vs Reindex

동작	의미
Update	문서 재인덱싱 (Lucene 의 immutable 때문). 옛 문서 삭제 + 새 문서 등록
Update by Query	쿼리 매칭 모두 update
Reindex	다른 인덱스로 copy + 변환

POST /_update_by_query?conflicts=proceed
{
  "query": { "term": { "in_stock": true } },
  "script": { "source": "ctx._source.price *= 1.1" }
}

POST /_reindex
{
  "source": { "index": "products-old" },
  "dest":   { "index": "products-new" },
  "script": { "source": "ctx._source.version = 2" }
}

Alias + Zero-Downtime Reindex

sequenceDiagram
    Note over App: alias = products
    App->>products-v1: search
    Admin->>products-v2: 새 mapping 생성
    Admin->>products-v2: reindex from v1
    Admin->>Alias: atomic switch (v1 → v2)
    App->>products-v2: search (zero-downtime)
    Admin->>products-v1: delete

POST /_aliases
{
  "actions": [
    { "remove": { "index": "products-v1", "alias": "products" } },
    { "add":    { "index": "products-v2", "alias": "products" } }
  ]
}

[!IMPORTANT] mapping 변경 은 대부분 불가능 (immutable). 새 인덱스 + reindex + alias swap 이 정통. 자세한 무중단 패턴은 [[Zero Downtime Deployment]].

흔한 함정

[!WARNING]

Bulk size 너무 큼 = EsRejectedExecutionException (스레드 큐 초과). 5-15MB 권장.

refresh=true 매번 = 검색 즉시 가능하지만 write throughput 폭락.

수동 force_merge 자주 = I/O 폭증. 대량 인덱싱 후 1회 만.

mapping 의 dynamic 폭증 = 수만 개 field → 메모리 폭발. dynamic: strict 또는 명시적 mapping.

[Search] ES Mapping: field type, dynamic, multi-field

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Mapping = ES 의 schema. 각 필드의 type + analyzer + indexing 옵션. 대부분 immutable (재인덱싱 필요).

Field Type 카탈로그

카테고리	type
String	`text`, `keyword`, `match_only_text` (8.x), `wildcard`
Numeric	`long`, `integer`, `short`, `byte`, `double`, `float`, `half_float`, `scaled_float`, `unsigned_long`
Date	`date`, `date_nanos`
Boolean	`boolean`
Binary	`binary`
Range	`integer_range`, `date_range`, `ip_range`, `long_range`, `float_range`, `double_range`
Object	`object`, `nested`, `flattened`
Geo	`geo_point`, `geo_shape`
Specialized	`ip`, `version`, `histogram`, `percolator`, `dense_vector`, `sparse_vector`, `rank_feature`, `rank_features`, `completion` (autocomplete), `token_count`, `join`

text vs keyword

flowchart LR
    Field["title: 'Mechanical Keyboard'"]
    Field --> Text["text:<br/>analyze → [mechanical, keyboard]<br/>full-text search"]
    Field --> Keyword["keyword:<br/>그대로 'Mechanical Keyboard'<br/>exact match, aggregation, sort"]

	text	keyword
분석기	적용	없음
검색	`match`	`term`
정렬	불가 (기본)	가능
집계	불가 (기본)	가능
용도	본문, 설명	ID, tag, status, exact

Multi-Field (둘 다)

"title": {
  "type": "text",
  "analyzer": "korean",
  "fields": {
    "raw":     { "type": "keyword", "ignore_above": 256 },
    "english": { "type": "text", "analyzer": "english" },
    "search_as_you_type": { "type": "search_as_you_type" }
  }
}

title → full-text search
title.raw → 정렬 / 집계 / exact
title.english → 영어 분석
title.search_as_you_type → autocomplete

Dynamic Mapping

flowchart TB
    Doc[새 필드 포함 문서] --> ES
    ES -->|dynamic: true| Auto[자동 type 추정 + mapping 추가]
    ES -->|dynamic: false| Ignore["필드 무시 (저장만)"]
    ES -->|dynamic: strict| Reject[에러]
    ES -->|dynamic: runtime| Runtime[runtime field 추가]

Type 자동 추정

JSON value     → ES type
"hello"        → text + keyword.raw (multi-field)
123            → long
1.5            → float
true           → boolean
"2026-06-25"   → date (string + 자동 date detection)

[!WARNING] Dynamic 폭증: 사용자 입력의 임의 key → 수만 field → 메모리 폭발. dynamic: strict 또는 flattened 권장.

Object vs Nested

PUT /orders
{
  "mappings": {
    "properties": {
      "items": {
        "type": "nested",
        "properties": {
          "name":  { "type": "keyword" },
          "price": { "type": "double" }
        }
      }
    }
  }
}

PUT /orders/_doc/1
{
  "items": [
    { "name": "keyboard", "price": 100 },
    { "name": "mouse",    "price": 50 }
  ]
}

object 의 함정

object (기본) = flatten 저장:

items.name:  ["keyboard", "mouse"]
items.price: [100, 50]

→ “name=mouse AND price=100” 검색 시 잘못 매칭 (실제로는 keyboard=100, mouse=50).

nested = 각 sub-doc 을 별도 Lucene doc → 정확한 검색 + 비용 큼.

{
  "nested": {
    "path": "items",
    "query": {
      "bool": {
        "must": [
          { "term": { "items.name": "mouse" } },
          { "range": { "items.price": { "gte": 100 } } }
        ]
      }
    }
  }
}

Runtime Field (schema-on-read)

PUT /logs
{
  "mappings": {
    "runtime": {
      "duration_ms": {
        "type": "long",
        "script": "emit(doc['end'].value.toEpochMilli() - doc['start'].value.toEpochMilli())"
      }
    }
  }
}

Reindex 없이 새 필드 추가 가능. 쿼리 시 계산 → 느림. 자주 쓰는 건 index time field 로.

Aliases

POST /_aliases
{
  "actions": [
    { "add": { "index": "products-v2", "alias": "products" } }
  ]
}

자세한 건 [[elasticsearch-indexing]] 의 Alias.

Index Template

PUT _index_template/logs-template
{
  "index_patterns": ["logs-*"],
  "template": {
    "settings": { "number_of_shards": 3 },
    "mappings": { "properties": { ... } }
  }
}

패턴 매칭 인덱스 의 기본 mapping. ILM rollover 와 짝.

Best Practice

✓ text vs keyword 명시 (dynamic 의존 X)
✓ ID 같은 식별자는 keyword
✓ 본문은 text + 적절한 analyzer
✓ 정렬/집계 필요 컬럼 → multi-field 의 keyword
✓ 객체 배열에 검색 필요 → nested
✓ 임의 key JSON → flattened
✓ ignore_above: 256 으로 큰 string 의 인덱싱 회피

흔한 함정

[!WARNING]

모든 string 이 text + keyword.raw = 인덱스 2배 크기. 필요한 것만.

object 에 검색 = wrong match. nested 로.

mapping 변경 시도 = 거의 항상 reindex 필요.

자동 date detection = “2026-06-25” 가 date 로 인식 → 다른 형식 거절. 비활성 권장 ("date_detection": false).

[Search] ES Query: must / should / filter / must_not

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

ES 의 Query DSL = JSON 기반 표현력 풍부한 쿼리 언어. bool query + leaf query 의 조합.

bool query: 4가지 절

flowchart LR
    Bool[bool query]
    Bool --> Must["must<br/>(AND, score 계산)"]
    Bool --> Should["should<br/>(OR, score 가산)"]
    Bool --> Filter["filter<br/>(AND, score 없음)"]
    Bool --> MustNot["must_not<br/>(NOT, score 없음)"]

절	AND/OR	Score	Cache
`must`	AND	예	안됨
`should`	OR	예 (가산)	안됨
`filter`	AND	없음	예 (빠름!)
`must_not`	NOT	없음	예

[!IMPORTANT] Score 가 필요 없으면 항상 filter. must + 동일 조건보다 압도적으로 빠름 (cache + scoring 생략).

종합 예시

GET /products/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "title": "mechanical keyboard" } }
      ],
      "should": [
        { "match": { "tags": "rgb" } },
        { "match": { "tags": "wireless" } }
      ],
      "filter": [
        { "term": { "category": "input-device" } },
        { "range": { "price": { "gte": 50, "lte": 200 } } },
        { "term": { "in_stock": true } }
      ],
      "must_not": [
        { "term": { "brand": "Brand-X" } }
      ],
      "minimum_should_match": 1
    }
  }
}

해석:

title 에 “mechanical keyboard” 매칭 (필수, score 계산)
tags 에 “rgb” 또는 “wireless” 있으면 가산 (minimum_should_match: 1 적용)
category, 가격 50-200, 재고 있음 (필터, 빠름)
Brand-X 제외

leaf query 카테고리

flowchart TB
    Q[Leaf Queries]
    Q --> FullText[Full Text]
    Q --> TermLevel[Term Level]
    Q --> Range[Range]
    Q --> Geo[Geo]
    Q --> Vector[Vector / Semantic]
    Q --> Compound[Compound]
    FullText --> M1[match, match_phrase, multi_match, match_phrase_prefix, query_string, simple_query_string]
    TermLevel --> T1[term, terms, exists, prefix, wildcard, regexp, fuzzy, ids]
    Range --> R1[range]
    Geo --> G1[geo_distance, geo_bounding_box, geo_polygon]
    Vector --> V1[knn, sparse_vector, text_expansion]
    Compound --> C1[bool, dis_max, constant_score, function_score]

match vs term

// match: 분석기 적용 → tokenized 비교
{ "match": { "title": "Mechanical Keyboard" } }
// → tokens: ["mechanical", "keyboard"]
// → 둘 중 하나라도 매칭 (operator=or 기본)

// term: 분석 없이 *exact* (keyword 필드용)
{ "term": { "status": "active" } }

[!CAUTION] text 필드에 term 쿼리 = 원본 토큰 못 찾음 (분석기가 lowercase 등 했기 때문). text 는 match, keyword 는 term.

match_phrase + slop

{ "match_phrase": { "title": { "query": "mechanical keyboard", "slop": 1 } } }

연속된 토큰 매칭.
slop: 얼마나 떨어져도 OK (단어 거리).

multi_match

{
  "multi_match": {
    "query": "rabbit hat",
    "fields": ["title^3", "description", "tags"]
  }
}

여러 필드 동시 검색.
field^N: 가중치.
type: best_fields, most_fields, cross_fields, phrase.

function_score (커스텀 ranking)

{
  "query": {
    "function_score": {
      "query": { "match": { "title": "keyboard" } },
      "functions": [
        { "filter": { "term": { "premium": true } }, "weight": 2.0 },
        { "field_value_factor": { "field": "popularity", "modifier": "log1p" } },
        { "gauss": { "created_at": { "origin": "now", "scale": "30d", "decay": 0.5 } } }
      ],
      "boost_mode": "multiply"
    }
  }
}

function	의미
`weight`	상수 곱
`field_value_factor`	필드값 기반 (popularity 등)
`gauss` / `linear` / `exp`	거리 기반 감쇠 (시간, 위치)
`script_score`	Painless 스크립트
`random_score`	무작위 (A/B)

ESQL (2024 GA)

SQL 같은 파이프 표기:

FROM logs-*
| WHERE @timestamp > NOW() - 7 days AND status_code >= 500
| STATS error_count = COUNT(*) BY service.name, host.name
| SORT error_count DESC
| LIMIT 20

[!TIP] DSL 의 복잡함 회피. 2026 시점 대시보드 / ad-hoc 쿼리 에서 ESQL 이 표준. Kibana 의 default 쿼리도 ESQL 전환 중.

동작 흐름

{}

일반 검색 직관. ES 도 같은 query → ranking → top-K 흐름.

흔한 함정

[!WARNING]

text 에 term = 매칭 0. keyword field 사용 또는 match.

should 만 사용 = minimum_should_match 누락 → 0개 일치 OK. 명시 권장.

score 불필요한데 must = cache 못 씀. filter 로.

wildcard, regexp, prefix 남용 = 느림. 분석기 변경 + edge_ngram 으로 대체.

[Search] ES Relevance Scoring: BM25, TF-IDF, function_score

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Relevance Score (_score) = 쿼리와 문서의 매칭 강도. ES 7+ 의 기본은 BM25 (TF-IDF 의 발전형).

BM25 공식

score(D, Q) = Σ IDF(qi) · ((f(qi, D) · (k1 + 1)) / (f(qi, D) + k1 · (1 - b + b · |D|/avgdl)))

qi      = 쿼리 term i
f(qi,D) = D 에서 term qi 의 frequency
|D|     = 문서 길이 (token 수)
avgdl   = 평균 문서 길이
k1, b   = 튜닝 파라미터

부분	의미
IDF (qi)	희귀할수록 점수 ↑
f (qi, D)	term frequency. 많이 등장할수록 ↑
k1	TF saturation. 기본 1.2
b	length normalization. 기본 0.75

TF-IDF 와의 차이

flowchart LR
    TFIDF["TF-IDF<br/>TF × IDF<br/>(선형 증가)"] --> Issue1[term 100번 = 점수 100배]
    BM25["BM25<br/>TF saturated<br/>(점진 포화)"] --> Better[term 많이 등장해도 *상한선*]

TF 가 무한 늘면 점수도 무한. BM25 는 적절히 늘다 saturate. 검색 직관에 더 가깝다.

k1, b 튜닝

값	의미
`k1 = 0`	TF 무시 (term 한 번 = 여러 번 동일)
`k1 = 1.2` (기본)	균형
`k1` 크게	TF 가산 강조
`b = 0`	length 정규화 없음
`b = 0.75` (기본)	균형
`b = 1`	완전 length 정규화

PUT /products
{
  "settings": {
    "index": {
      "similarity": {
        "custom_bm25": { "type": "BM25", "k1": 1.5, "b": 0.5 }
      }
    }
  },
  "mappings": {
    "properties": {
      "title": { "type": "text", "similarity": "custom_bm25" }
    }
  }
}

explain API

GET /products/_search?explain=true
{ "query": { "match": { "title": "rabbit hat" } } }

"_explanation": {
  "value": 2.85,
  "description": "sum of:",
  "details": [
    { "value": 1.34, "description": "weight(title:rabbit in 0) ..." },
    { "value": 1.51, "description": "weight(title:hat in 0) ..." }
  ]
}

왜 이 점수 인지 디버깅. Kibana 의 Profile UI 가 더 시각적.

function_score (커스텀 boost)

자세한 건 [[elasticsearch-query]] 의 function_score.

{
  "query": {
    "function_score": {
      "query": { "match": { "title": "keyboard" } },
      "functions": [
        { "field_value_factor": { "field": "rating", "modifier": "log1p", "factor": 1.2 } },
        { "gauss": { "created_at": { "origin": "now", "scale": "30d", "decay": 0.5 } } }
      ],
      "score_mode": "sum",
      "boost_mode": "multiply"
    }
  }
}

score_mode	함수들의 결합
`multiply` (기본)	곱
`sum`	합
`avg`	평균
`max`, `min`, `first`	등

boost_mode	function vs query 결합
`multiply` (기본)	function × query
`sum`, `replace`, `avg`, `max`, `min`

Rescore (top-K 재정렬)

{
  "query": { "match": { "title": "rabbit hat" } },
  "rescore": {
    "window_size": 50,
    "query": {
      "rescore_query": {
        "match_phrase": { "title": { "query": "rabbit hat", "slop": 1 } }
      },
      "query_weight": 0.7,
      "rescore_query_weight": 1.3
    }
  }
}

값싼 쿼리로 top-K → 비싼 쿼리로 top-K 만 재정렬. 경제적 ranking.

boost 의 영향

{
  "multi_match": {
    "query": "rabbit",
    "fields": ["title^3", "description", "tags^2"]
  }
}

필드	boost	점수
title	^3	3×
description	(기본 1)	1×
tags	^2	2×

제목 매칭이 본문 매칭보다 3배 가치.

Score normalization 함정

shard 1: doc A score = 5.0
shard 2: doc B score = 4.5

→ 합칠 때 *상대 비교* OK
→ *절대값* 은 *shard 간 다르다*. 비교 불가

[!CAUTION] 0~1 정규화 불가. 상대 순위만 의미. DFS_QUERY_THEN_FETCH (정확 IDF) 옵션 가능하나 비쌈.

흔한 함정

[!WARNING]

score 절대값 의존 = shard / 인덱스 마다 다름. 순위만 신뢰.

boost 남발 = 의도 분산. 적게 시작.

should 만으로 ranking 시도 = AND/OR/NOT 조합 + score 가 핵심.

TF-IDF 시대 사고 = ES 7+ 는 BM25 가 기본. saturation 이해.

[Search] ES Sort: relevance, field, script, geo

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

ES 의 기본 정렬 = relevance score (BM25) 내림차순. 명시적 sort 로 변경 가능. doc_values 로 메모리 효율적 정렬.

5가지 정렬

flowchart TB
    Sort[Sort 종류]
    Sort --> Rel["_score (relevance, 기본)"]
    Sort --> Field["field (price asc / desc)"]
    Sort --> Script["script (커스텀)"]
    Sort --> Geo["_geo_distance"]
    Sort --> Nested["nested object"]

1. Field Sort

GET /products/_search
{
  "query": { "match_all": {} },
  "sort": [
    { "price": "asc" },
    { "created_at": "desc" },
    "_score"
  ]
}

옵션	의미
`order`: `asc` / `desc`	방향
`missing`: `_first` / `_last` / 값	NULL 처리
`mode`: `min` / `max` / `avg` / `sum` / `median`	배열 필드의 대표값
`unmapped_type`	인덱스에 없는 필드 무시

2. Relevance (_score)

"sort": ["_score"]

기본. 별도 sort 명시 안 하면 적용. 자세한 BM25 는 [[elasticsearch-relevance-scoring]].

3. Script Sort

"sort": {
  "_script": {
    "type": "number",
    "script": {
      "lang": "painless",
      "source": "doc['price'].value * (1 - doc['discount'].value)"
    },
    "order": "asc"
  }
}

런타임 계산. 무거움. 자주 쓰는 정렬은 index 시 계산해서 저장.

4. Geo Distance

"sort": [
  {
    "_geo_distance": {
      "location": { "lat": 37.55, "lon": 126.97 },
      "order": "asc",
      "unit": "km",
      "distance_type": "arc"
    }
  }
]

doc_values vs fielddata

flowchart LR
    Doc["doc_values<br/>(default, on-disk columnar)"] --> Fast[정렬, 집계 효율]
    Field["fielddata<br/>(in-memory, text 전용)"] --> Heavy[메모리 비용 큼]

	doc_values	fielddata
자료구조	columnar (Lucene)	in-memory (heap)
적용	거의 모든 필드 (기본)	text 필드 (옵션)
정렬 / 집계	가능	가능하지만 비쌈
비활성	`"doc_values": false`	`"fielddata": false` (기본)

[!IMPORTANT] text 필드에 정렬/집계 = 거절 (기본). keyword 또는 multi-field 사용.

"properties": {
  "title": {
    "type": "text",
    "fields": {
      "raw": { "type": "keyword" }
    }
  }
}

→ 정렬 시 "title.raw" 사용.

search_after + PIT (deep pagination)

from + size 의 깊은 페이지네이션 은 비효율. 대용량 결과는 search_after + Point in Time (PIT).

# 1. PIT 생성
POST /products/_pit?keep_alive=5m
→ { "id": "pit_id_xxx" }

# 2. 첫 페이지
GET /_search
{
  "size": 100,
  "pit": { "id": "pit_id_xxx", "keep_alive": "5m" },
  "sort": [{ "created_at": "asc" }, { "_id": "asc" }]
}
# → 결과의 sort 값을 저장: [created_at_value, id_value]

# 3. 다음 페이지
GET /_search
{
  "size": 100,
  "pit": { "id": "pit_id_xxx", "keep_alive": "5m" },
  "sort": [{ "created_at": "asc" }, { "_id": "asc" }],
  "search_after": [created_at_value, id_value]
}

[!TIP] 10K offset 이상 은 search_after 만. from + size 는 index.max_result_window 한계 (10000 기본).

track_total_hits

{
  "track_total_hits": false   // 또는 10000 (정확 카운트 한도)
}

정확한 total count 가 비싸다. 대시보드 / “수천 개+” 표시면 생략 또는 근사.

Sort 와 BM25

flowchart LR
    Q[Query] --> Match[matching docs]
    Match -->|sort 없음| BM25Sort[BM25 score 내림차순]
    Match -->|sort 명시| FieldSort[field 값 정렬]
    Note["sort 명시 → score 계산 skip (성능 ↑)"]

[!TIP] sort 가 score 무관 이면 score 계산 skip (성능 ↑). 단 function_score 같이 score 가 필요한 정렬 은 그대로 계산.

흔한 함정

[!WARNING]

text 필드로 정렬 = 에러. keyword multi-field 사용.

deep from + size = max_result_window 초과. search_after.

track_total_hits: true = 대량 매칭 시 2배 느림. 필요 없으면 false 또는 10000.

script sort 남용 = 매 쿼리 Painless 컴파일. runtime field 또는 index 시 저장 으로.

[Search] ES Vector Search: kNN, ELSER, RAG

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

ES 의 벡터 검색 = 임베딩 기반 의미 검색. kNN (Approximate Nearest Neighbor) 으로 수억 벡터 안에서 가까운 K개 찾기.

2026 시점의 ES 위치: 전통 BM25 + dense vector + sparse vector + hybrid 모두 지원하는 통합 검색 엔진.

3가지 벡터 표현

flowchart TB
    Q[Vector 표현]
    Q --> Dense["dense_vector<br/>(예: 384, 768, 1536 차원)"]
    Q --> Sparse["sparse_vector / ELSER<br/>(term:weight 맵)"]
    Q --> Hybrid["Hybrid<br/>(BM25 + Vector RRF)"]

종류	의미
Dense	모든 차원 채워진 vector (OpenAI, Cohere, BGE 등)
Sparse	대부분 0, 의미있는 term 만 가중치
Hybrid	키워드 + 의미 결합

Dense Vector (전통 임베딩)

PUT /docs
{
  "mappings": {
    "properties": {
      "content": { "type": "text" },
      "embedding": {
        "type": "dense_vector",
        "dims": 384,
        "index": true,
        "similarity": "cosine",
        "index_options": {
          "type": "hnsw",
          "m": 16,
          "ef_construction": 100
        }
      }
    }
  }
}

옵션	의미
`dims`	차원 (모델 의존)
`similarity`	`cosine`, `dot_product`, `l2_norm`, `max_inner_product`
`type`	`hnsw` (기본), `flat`, `int8_hnsw`, `int4_hnsw`, `bbq_hnsw` (8.15+)
`m`	HNSW 노드의 연결 수
`ef_construction`	빌드 시 후보군

Quantization (메모리 절감)

옵션	메모리 (vs float32)	정확도
`hnsw` (float32)	100%	기준
`int8_hnsw`	25%	95%+ recall
`int4_hnsw` (8.15+)	12.5%	90%+ recall
`bbq_hnsw` (Better Binary Quantization, 9.x)	3%	80%+ recall

[!IMPORTANT] 2026 시점 기본 = int8_hnsw. 메모리 1/4 + 거의 같은 정확도. 대용량 (수억+) = BBQ.

kNN Search

GET /docs/_search
{
  "knn": {
    "field": "embedding",
    "query_vector": [0.1, 0.2, ..., 0.05],
    "k": 10,
    "num_candidates": 100
  }
}

파라미터	의미
`k`	반환할 수
`num_candidates`	후보 풀 (정확도 vs 속도)
`filter`	bool query 와 결합
`boost`	hybrid 시 가중치

ELSER (Elastic Learned Sparse EncodeR)

flowchart LR
    Text["query / doc"] --> ELSER[ELSER 모델]
    ELSER --> Sparse["{ ml.tokens: {<br/> 'rabbit': 1.2,<br/> 'hat': 0.8,<br/> 'magic': 0.4<br/>} }"]
    Sparse --> Index[(ES sparse_vector)]
    Sparse --> Score[BM25-like score on sparse vector]

Elastic 자체 모델. 8.8+ stable.
term 단위 가중치 (sparse).
별도 GPU 없이 CPU 추론 가능.
영문 우수. 9.x 에서 multilingual 진입.

PUT /docs
{
  "mappings": {
    "properties": {
      "content_expanded": {
        "type": "sparse_vector"
      }
    }
  }
}

POST /_ml/trained_models/.elser_model_2/deployment/_start

PUT /_ingest/pipeline/elser-pipeline
{
  "processors": [
    {
      "inference": {
        "model_id": ".elser_model_2",
        "input_output": [{ "input_field": "content", "output_field": "content_expanded" }]
      }
    }
  ]
}

쿼리:

{
  "query": {
    "sparse_vector": {
      "field": "content_expanded",
      "inference_id": ".elser_model_2",
      "query": "토끼가 마술 모자에서 나오다"
    }
  }
}

semantic_text (8.15+, 추천)

PUT /docs
{
  "mappings": {
    "properties": {
      "content": {
        "type": "semantic_text",
        "inference_id": "my-elser-or-openai-or-cohere"
      }
    }
  }
}

위 한 필드면 자동 청크 + 임베딩 + 인덱싱 + 쿼리. 별도 ingest pipeline 불필요. 2026 시점 권장 접근.

Hybrid Search + RRF (Reciprocal Rank Fusion)

GET /docs/_search
{
  "retriever": {
    "rrf": {
      "retrievers": [
        { "standard": { "query": { "match": { "content": "토끼 모자" } } } },
        { "knn": { "field": "embedding", "query_vector_builder": { "text_embedding": { "model_id": "...", "model_text": "토끼 모자" } }, "k": 50, "num_candidates": 200 } }
      ],
      "rank_window_size": 50,
      "rank_constant": 60
    }
  }
}

키워드 (BM25) + 의미 (벡터) 두 ranking 을 RRF 로 결합. 최강 패턴.

자세한 RRF 공식:

RRF_score(d) = Σ 1 / (k + rank_i(d))

출처	rank	RRF (k=60)
BM25	1	1/61 ≈ 0.0164
BM25	10	1/70 ≈ 0.0143
Vector	1	1/61
둘 다 top	합산	약 0.033

Inference API (외부 LLM 통합)

PUT _inference/text_embedding/my-openai
{
  "service": "openai",
  "service_settings": {
    "api_key": "sk-...",
    "model_id": "text-embedding-3-small"
  }
}

PUT _inference/text_embedding/my-cohere
{
  "service": "cohere",
  "service_settings": { "api_key": "...", "model_id": "embed-multilingual-v3.0" }
}

OpenAI, Cohere, HuggingFace, Bedrock, Azure AI, Anthropic 등 공통 인터페이스.

RAG 패턴

flowchart LR
    User[User query] --> Embed[Inference API:<br/>embedding]
    Embed --> Hybrid["Hybrid Retriever<br/>(BM25 + vector + RRF)"]
    Hybrid -->|top-K chunks| Prompt[LLM prompt 구성]
    Prompt --> LLM[OpenAI / Claude / Llama]
    LLM --> Answer

ES vs 전용 Vector DB

	ES	Pinecone	Milvus	Weaviate	Qdrant
BM25 + Vector	최고	약	약	보통	보통
Filter + kNN	강	보통	강	강	강
Operation	익숙 (ES 운영자)	managed only	self-host 가능	둘 다	둘 다
가격 (자체)	무료	비쌈	무료	무료	무료

[!IMPORTANT] 기존에 ES 운영 중 = vector store 도 ES 로 통합 추천. 별도 vector DB 도입 비용 > ES 의 vector 기능 한계.

흔한 함정

[!WARNING]

차원 불일치 = mapping 의 dims 와 실제 vector 길이 다름 → 인덱싱 거절.

HNSW 빌드 메모리 = 큰 인덱스의 빌드 시간이 수십 분 ~ 시간. heap 충분.

scoring 단위 다름 = BM25 와 vector score 의 절대값 비교 무의미. RRF 가 답.

dense 만 사용 = 키워드 매치 (정확한 product code 등) 못 잡음. hybrid.

[Search] ES 인프라: cluster, shard, replica, ELK

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

ES 는 분산 시스템. cluster + multiple nodes + shards + replicas + Elastic Stack 보조 도구.

Cluster 구조

flowchart TB
    subgraph Cluster["Elasticsearch Cluster"]
        N1["Node 1 (master + data)"]
        N2["Node 2 (data + ingest)"]
        N3["Node 3 (data)"]
        N4["Node 4 (master eligible)"]
        N5["Node 5 (coord only)"]
    end
    Client --> N5
    N5 --> N1 & N2 & N3
    N1 -.gossip.-> N4

Node Role

Role	의미
master	cluster state 관리
master_eligible	master 후보
data	shard 보관 + 쿼리
data_hot / data_warm / data_cold / data_frozen	tier 별
ingest	ingest pipeline 실행
coordinating_only	라우팅 + 합치기만
ml	ML 전용
remote_cluster_client	cross-cluster search
transform	continuous transform

[!IMPORTANT] production = 분리된 dedicated master 3노드 + data nodes + coordinating-only (큰 환경). 작은 환경은 master+data 결합 OK.

Shard + Replica

flowchart TB
    Idx["Index: products<br/>(3 primary shards, 1 replica)"]
    Idx --> S0["Shard 0 (primary, Node 1)"]
    Idx --> S1["Shard 1 (primary, Node 2)"]
    Idx --> S2["Shard 2 (primary, Node 3)"]
    S0 -.replica.-> R0["Shard 0 (replica, Node 2)"]
    S1 -.replica.-> R1["Shard 1 (replica, Node 3)"]
    S2 -.replica.-> R2["Shard 2 (replica, Node 1)"]

개념	의미
Primary shard	write 의 주체
Replica shard	읽기 분산 + HA
Routing	`hash(routing) % primary_shards`
primary 다운	replica → primary 자동 승격

Shard 수 결정

flowchart TD
    Q1{인덱스 크기}
    Q1 -->|< 50GB| Small[1-3 primary shard]
    Q1 -->|50-500GB| Med[3-10]
    Q1 -->|500GB+| Big[10+, 시계열 분할]
    Note["권장: 1 shard 당 20-50GB"]

너무 많음 = cluster state 비대 + 리밸런싱 비용. 너무 적음 = 노드 추가해도 분산 안 됨.

ILM (Index Lifecycle Management)

flowchart LR
    Hot["HOT<br/>(SSD, 활발한 write/read)"] --> Warm["WARM<br/>(읽기 위주, 적은 replica)"]
    Warm --> Cold["COLD<br/>(searchable snapshot, 가끔 검색)"]
    Cold --> Frozen["FROZEN<br/>(객체 스토리지, 거의 검색 X)"]
    Frozen --> Delete["DELETE"]

PUT _ilm/policy/logs-policy
{
  "policy": {
    "phases": {
      "hot":    { "actions": { "rollover": { "max_size": "50gb", "max_age": "1d" } } },
      "warm":   { "min_age": "7d",  "actions": { "shrink": { "number_of_shards": 1 }, "forcemerge": { "max_num_segments": 1 } } },
      "cold":   { "min_age": "30d", "actions": { "searchable_snapshot": { "snapshot_repository": "s3-repo" } } },
      "frozen": { "min_age": "90d", "actions": { "searchable_snapshot": { "snapshot_repository": "s3-repo" } } },
      "delete": { "min_age": "365d", "actions": { "delete": {} } }
    }
  }
}

로그 / 메트릭 / APM 의 표준. 비용 차감 + 성능 유지 의 핵심.

Elastic Stack (옛 ELK)

flowchart LR
    Source[Apps / Servers / Containers] --> Agent["Elastic Agent<br/>(또는 Beats)"]
    Agent --> Fleet["Fleet Server<br/>(중앙 관리)"]
    Agent --> ES[(ElasticSearch)]
    Source --> LS["Logstash<br/>(복잡 변환)"]
    LS --> ES
    ES --> Kibana["Kibana<br/>(UI, alert, ML)"]

컴포넌트	의미
Elastic Agent	통합 shipper (옛 Beats 통합)
Beats (Filebeat, Metricbeat, Packetbeat, …)	가벼운 단일 목적 shipper
Logstash	강력 변환, Elastic Agent + Ingest pipeline 으로 대부분 대체 진행 중
Fleet	Elastic Agent 의 중앙 관리 + policy 배포
Kibana	시각화 + dev tools + alerting + ML UI

2026 시점: Elastic Agent + Fleet 이 표준. Beats 는 legacy (지원 계속).

Snapshot / Restore

# Repository 등록 (S3)
PUT _snapshot/my_s3_repo
{
  "type": "s3",
  "settings": { "bucket": "es-snapshots", "region": "us-east-1" }
}

# Snapshot
PUT _snapshot/my_s3_repo/snap-2026-06-25?wait_for_completion=true
{
  "indices": "products,logs-*",
  "include_global_state": false
}

# Restore
POST _snapshot/my_s3_repo/snap-2026-06-25/_restore
{
  "indices": "products",
  "rename_pattern": "(.+)",
  "rename_replacement": "restored-$1"
}

Searchable Snapshot

ILM 의 cold / frozen tier 에서 사용.
S3 의 snapshot 을 *직접 검색* (로컬 복원 없이).

비용 대폭 절감. cold 는 부분 mount, frozen 은 완전 S3 기반 + small local cache.

Cross-Cluster Search / Replication

flowchart LR
    EU[EU Cluster] -.CCR.-> US[US Cluster]
    Search[Search Query] -->|CCS| EU
    Search -->|CCS| US

CCR (Cross-Cluster Replication): leader → follower 비동기 복제.
CCS (Cross-Cluster Search): 동시에 여러 cluster 검색.
DR / 글로벌 분석.

흔한 함정

[!WARNING]

Master node 분리 안 함 + 데이터 폭증 = master 가 GC pause → split brain.

Shard 수 영구 고정 = 만들 때 결정. 늘리려면 reindex.

ILM 없는 로그 = 수 TB 누적 → cluster 다운. ILM 필수.

Replica 0 in production = 노드 다운 시 데이터 손실. 최소 1.

[Search] ES 한글 인덱싱: nori, mecab, 형태소 분석

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

한국어 는 교착어 + 띄어쓰기 모호 + 형태소 변화 때문에 공백 단순 분리 로는 검색 불가. 형태소 분석 (morphological analysis) 필수.

한글이 어려운 이유

flowchart LR
    Word["사과를 먹는다"] --> Naive["공백 분리:<br/>[사과를, 먹는다]"]
    Word --> Morph["형태소 분석:<br/>[사과(N), 를(J), 먹(V), 는(E), 다(E)]"]
    Naive --> Bad["'사과' 검색 → 안 매칭"]
    Morph --> Good["'사과' 검색 → 매칭"]

영어	한국어
띄어쓰기 = 단어 경계	모호 (붙여쓰기 허용)
어형 변화 적음 (s, ed, ing)	극심 (조사, 어미, 어간)
stemmer 로 충분	형태소 분석기 필요

한국어 형태소 분석 직관

{}

Aho-Corasick (다중 패턴 매칭) 의 동작 직관. 한국어 형태소 분석도 사전 + 트라이 기반의 모든 가능한 경계 후보 동시 매칭 + 최적 분리 선택. 핵심 아이디어가 동일.

{}

사전 (dictionary) 의 trie 구조. 형태소 분석기의 내부 사전 도 trie 또는 FST.

주요 분석기 비교

분석기	출시	사전	특징
nori	2018 (Elastic 공식)	mecab-ko-dic	공식 + 안정 + Lucene 기본 통합
mecab-ko-analyzer	2014	mecab-ko-dic	옛 표준. 별도 plugin 필요
arirang	2010	자체 사전	옛, 현재 거의 안 씀
eunjeon (은전한닢)	2014	mecab-ko-dic	mecab-ko 기반
OpenKoreanText (twitter-korean)	2014	자체	트위터 특화

[!IMPORTANT] 2026 시점 권장: nori. 공식 + 활발한 유지보수 + Lucene 통합 + 한국어 search 의 de facto.

nori 사용

# 플러그인 설치
bin/elasticsearch-plugin install analysis-nori

PUT /products
{
  "settings": {
    "analysis": {
      "tokenizer": {
        "nori_user_dict": {
          "type": "nori_tokenizer",
          "decompound_mode": "mixed",
          "user_dictionary": "userdict_ko.txt"
        }
      },
      "filter": {
        "nori_pos_remove": {
          "type": "nori_part_of_speech",
          "stoptags": ["E", "IC", "J", "MAG", "MAJ", "MM", "SP", "SSC", "SSO", "SC", "SE", "XPN", "XSA", "XSN", "XSV", "UNA", "NA", "VSV"]
        }
      },
      "analyzer": {
        "korean": {
          "type": "custom",
          "tokenizer": "nori_user_dict",
          "filter": ["lowercase", "nori_readingform", "nori_pos_remove"]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "title": { "type": "text", "analyzer": "korean" }
    }
  }
}

decompound_mode (복합어 분해)

"백화점" → 백화 + 점 ?

모드	동작	결과
`none`	분해 안 함	`[백화점]`
`discard`	분해 + 원본 버림	`[백화, 점]`
`mixed` (권장)	분해 + 원본 유지	`[백화점, 백화, 점]`

[!TIP] mixed 가 권장. 원본도 검색 + 분해된 단어도 검색 가능. recall 향상.

분석 테스트

POST /_analyze
{
  "tokenizer": "nori_tokenizer",
  "text": "백화점에서 아이폰 15 프로를 샀어요"
}

{
  "tokens": [
    { "token": "백화점", "start_offset": 0, "end_offset": 3, "type": "word", "position": 0 },
    { "token": "에서",    "start_offset": 3, "end_offset": 5, "type": "word", "position": 1 },
    { "token": "아이폰",  "start_offset": 6, "end_offset": 9, "type": "word", "position": 2 },
    { "token": "15",     "start_offset": 10, "end_offset": 12, "type": "word", "position": 3 },
    { "token": "프로",    "start_offset": 13, "end_offset": 15, "type": "word", "position": 4 },
    { "token": "를",      "start_offset": 15, "end_offset": 16, "type": "word", "position": 5 },
    { "token": "샀",      "start_offset": 17, "end_offset": 18, "type": "word", "position": 6 },
    { "token": "어요",    "start_offset": 18, "end_offset": 20, "type": "word", "position": 7 }
  ]
}

품사 필터 (POS filter)

nori_part_of_speech 로 불필요 품사 제거:

태그	의미	보통 제외?
`J`	조사 (은, 는, 이, 가)	예
`E`	어미 (다, 어요, 았)	예
`MAG`	일반 부사	예
`IC`	감탄사	예
`NNG`	일반 명사	유지
`NNP`	고유 명사	유지
`VV`	동사	유지 (어간)
`VA`	형용사	유지
`XR`	어근	유지

User Dictionary (사용자 사전)

userdict_ko.txt:

아이폰
삼성갤럭시
대한항공
미스터트롯
삼성전자

신조어 / 고유명사 / 브랜드 등 분리되어선 안 될 단어 등록.

한자 / 영문 / 발음 변환

"filter": {
  "korean_readingform": { "type": "nori_readingform" }
}

한자 → 한글 발음 변환 (漢字 → 한자).
검색 시 한자 입력 OK + 한글로 매칭.

ngram 기반 한글 검색

복합어 / 부분 매칭이 필요하면 ngram 보조:

"filter": {
  "edge_ngram_filter": {
    "type": "edge_ngram",
    "min_gram": 1,
    "max_gram": 10
  }
}

자동완성 (autocomplete) 의 표준.
samsung → [s, sa, sam, samp, sams, samsu, samsun, samsung].

흔한 함정

[!WARNING]

공백 분리만 사용 = 조사 가 붙은 단어 검색 실패. nori 필수.

POS filter 안 함 = J/E 가 토큰 폭증 → 인덱스 크기 + 검색 잡음.

decompound_mode none = 백화점만 매칭, 백화 안 됨. mixed 권장.

User dictionary 갱신 후 재인덱싱 안 함 = 옛 인덱스는 그대로 옛 분석. 신조어 반영 안 됨.

김신건의 로그 - 위키 / search

[Search] Elasticsearch vs OpenSearch: 라이센스 분기와 차이

정의

분기 타임라인

ES vs OpenSearch 매트릭스 (2026-06)

기술적 차이 (2026 시점)

Elasticsearch 만의 기능

OpenSearch 만의 기능

결정 트리

마이그레이션 (ES ↔ OpenSearch)

다른 검색 엔진 (참고)

흔한 함정

관련 위키

[Search] ElasticSearch 기본 원리: Inverted Index, Segment, Lucene

정의

Inverted Index (역색인)

일반 정방향 인덱스 vs 역색인

검색 흐름

Segment: Lucene 의 단위

Near Real-Time: refresh

Translog (WAL)

Document 와 ID

Routing

자세한 영역

관련 위키

[Search] ElasticSearch: Lucene 위 분산 검색 엔진

정의

라이센스 분기 타임라인

핵심 컴포넌트

ES 의 본질

ES vs 다른 DB

ES 8.x → 9.x 주요 변화

활용 카테고리

관련 위키 (이 클러스터)

인접 위키

[Search] ES Aggregations: metric, bucket, pipeline

정의

3가지 카테고리

Metric Aggregations

Bucket Aggregations

Terms (GROUP BY)

Date Histogram (시계열)

Filters (다중 조건 동시)

Pipeline Aggregations

Derivative + Cumulative Sum

bucket_script (커스텀 비율)

Composite Aggregation (pagination)

Doc Count Error

ESQL 의 STATS

시각화 (Kibana)

흔한 함정

관련 위키

[Search] ES Indexing: bulk, refresh, ingest pipeline

정의

단일 인덱싱

Bulk API (실전)

Bulk 흐름

대량 인덱싱 튜닝

Index 생성 + Mapping

Ingest Pipeline (Logstash 대안)

Update vs Reindex

Alias + Zero-Downtime Reindex

흔한 함정

관련 위키

[Search] ES Mapping: field type, dynamic, multi-field

정의

Field Type 카탈로그

text vs keyword

Multi-Field (둘 다)

Dynamic Mapping

Type 자동 추정

Object vs Nested

object 의 함정

Runtime Field (schema-on-read)

Aliases

Index Template

Best Practice

흔한 함정

관련 위키

[Search] ES Query: must / should / filter / must_not