Elasticsearch - Mapping¶
본 포스팅의 모든 실습과 예제는 Elasticsearch 7.6 버전을 기준으로 작성되었다.
지난 포스팅들에서 클러스터 아키텍처, CRUD, Query DSL, 그리고 Aggregation까지 다루었다.
이번에는 RDB의 테이블 스키마에 해당하는 매핑(Mapping)의 정의와 설정 방법, 그리고 Elasticsearch가 지원하는 핵심 데이터 타입(Data Types)에 대해 알아본다.
1. 매핑(Mapping)이란?¶
매핑(Mapping)은 Elasticsearch에서 각 도큐먼트의 필드가 어떤 데이터 타입으로 저장되고, 검색 시 어떻게 인덱싱(색인)되고 처리될지 정의하는 스키마 명세서다.
매핑을 설정하는 방법은 크게 두 가지가 있다:
1. 인덱스를 생성할 때 매핑을 미리 명시하는 방법
2. _mapping API를 이용해 기존 인덱스에 신규 필드를 추가하는 방법
1.1 인덱스 생성 시 매핑 명시¶
curl -H 'Content-Type: application/json' -X PUT 'localhost:9200/mapping_user_bulk?pretty' -d '
{
"mappings": {
"properties": {
"weight": {
"type": "long"
}
}
}
}'
1.2 동적 매핑(Dynamic Mapping)과 기존 매핑 확인¶
Elasticsearch는 사전 매핑 없이 새로운 인덱스에 데이터를 넣으면, 입력된 데이터의 형식을 스스로 추론하여 자동으로 매핑을 생성해 준다.
# 인덱스의 현재 매핑 정보 확인
curl -H 'Content-Type: application/json' -X GET 'localhost:9200/user_bulk/_mapping?pretty'
1.3 기존 인덱스에 신규 필드 매핑 추가¶
기존에 운영 중인 인덱스에 새로운 필드를 추가할 때는 _mapping 엔드포인트를 사용한다:
curl -H 'Content-Type: application/json' -X PUT 'localhost:9200/user_bulk/_mapping?pretty' -d '
{
"properties": {
"new_mapping_field": {
"type": "long"
}
}
}'
⚠️ 매핑 수정의 절대 원칙 (불변성):
이미 정의된 기존 필드의 데이터 타입을 변경하거나 필드를 삭제하는 것은 불가능하다. 데이터의 인덱싱 구조가 이미 결정되어 디스크에 쓰여졌기 때문이다. 만약 기존 필드의 타입을 바꾸고 싶다면, 신규 인덱스를 올바른 매핑으로 생성한 후_reindexAPI를 통해 데이터를 마이그레이션해야 한다.
2. 엘라스틱서치 핵심 6대 데이터 타입 분석¶
2.1 문자열 타입: text vs keyword¶
문자열 필드는 목적에 따라 반드시 text와 keyword 중 올바른 것을 선택해야 한다.
| 구분 | text 타입 |
keyword 타입 |
|---|---|---|
| 형태소 분석 | Analyzer(분석기)를 거쳐 여러 개의 텀으로 쪼갬 | 분석기를 거치지 않고 원본 그대로 단일 토큰 저장 |
| 주요 목적 | 전문 검색 (Full-text Search) (기사 본문, 상품 설명 등) | 완전 일치 검색, 필터링, 정렬, 집계 (Aggregation) |
| 사용 사례 | "파전"을 검색하면 "비가 오면 파전이 땡긴다" 매칭 | ID, 이메일, 주민번호, 상태코드, 카테고리명 |
ignore_above 옵션¶
keyword 타입에서 너무 긴 문자열이 들어올 때 인덱싱 토큰 크기를 제한하는 유용한 옵션이다:
# 4글자를 초과하는 문자열은 검색용 토큰으로 색인하지 않음
curl -H 'Content-Type: application/json' -X PUT 'localhost:9200/ignore_above_sample?pretty' -d '
{
"mappings": {
"properties": {
"long_string": {
"type": "keyword",
"ignore_above": 4
}
}
}
}'
"hi"(2글자): 정상 색인되어 검색 가능"hello"(5글자): 저장은 되지만 4글자를 초과하므로 검색 인덱스에서 제외되어term검색 결과가 나오지 않음
💡 멀티 필드(Multi-fields): 문자열 필드를 동적 매핑하면 Elasticsearch는 자동으로
text타입과 함께 내부에keyword서브필드(fields.keyword)를 동시에 생성하여 전문 검색과 정렬/집계를 모두 지원한다.
2.2 숫자 타입 (Numeric)¶
long,integer,short,byte,double,float등 정수형과 실수형을 폭넓게 지원한다.- 형태소 분석을 하지 않으며, 범위 쿼리(
range)나 집계 연산에 사용된다.
coerce 옵션 (강제 형변환 제어)¶
기본적으로 문자열 형태의 숫자("1")가 들어오면 자동으로 숫자형으로 변환(coerce: true)해 준다. 엄격한 데이터 정합성을 위해 자동 변환을 막고 싶다면 coerce: false를 지정한다:
curl -H 'Content-Type: application/json' -X PUT 'localhost:9200/coerce_sample?pretty' -d '
{
"mappings": {
"properties": {
"coerce_numeric": {
"type": "integer",
"coerce": false
}
}
}
}'
{"coerce_numeric": "2"}문자열 전송 시400 Bad Request (mapper_parsing_exception)에러를 발생시킨다.
2.3 날짜 타입 (Date)¶
JSON에는 공식적인 날짜 타입이 없으므로, Elasticsearch는 다음 형식을 감지하여 date 타입으로 매핑한다:
1. "2020-05-05" 또는 "2020/05/05 12:10:30" 등의 표준 날짜 문자열
2. 밀리세컨드(epoch_millis) 또는 초(epoch_second) 정수
내부적으로는 UTC 기준의 밀리초 정수(long)로 변환되어 저장되므로 초고속 날짜 범위 검색이 가능하다.
curl -H 'Content-Type: application/json' -X GET 'localhost:9200/date_sample/_search?pretty' -d '
{
"query": {
"range": {
"date_format": { "gte": "2020-05-05", "lt": "2020-05-06" }
}
}
}'
2.4 불리언 타입 (Boolean)¶
true와 false 논리값을 저장한다. 문자열 형태인 "true", "false"가 전달되어도 불리언 값으로 정상 변환된다.
curl -H 'Content-Type: application/json' -X POST 'localhost:9200/boolean_sample/_doc/1' -d '
{ "boolean_format": "true" }'
2.5 객체 타입 (Object)¶
JSON 객체 계층 구조를 그대로 저장할 수 있다. 하위 필드는 점 표기법(object.field)을 통해 접근한다.
# 도큐먼트 추가
curl -H 'Content-Type: application/json' -X POST 'localhost:9200/object_sample/_doc/1' -d '
{
"region": "US",
"author": { "age": 20, "first": "John", "last": "Smith" }
}'
# 점 표기법을 이용한 조회
curl -H 'Content-Type: application/json' -X GET 'localhost:9200/object_sample/_search?pretty' -d '
{
"query": {
"term": { "author.first": "john" }
}
}'
2.6 중첩 타입 (Nested) ⚠️ 실무 핵심¶
배열 안에 여러 객체(Object Array)가 들어있을 때, 일반 object 타입과 nested 타입은 치명적인 동작 차이를 보인다.
❌ 일반 Object 배열의 한계 (데이터 평탄화 현상)¶
다음과 같이 두 명의 사용자 정보가 배열로 들어간 도큐먼트를 생각해보자:
{
"group": "fans",
"user": [
{ "first": "John", "last": "Smith" },
{ "first": "Alice", "last": "White" }
]
}
일반 object 타입은 루씬 내부에서 데이터를 다음과 같이 평탄화(Flattened)하여 저장한다:
user.first: ["John", "Alice"]
user.last: ["Smith", "White"]
이로 인해 user.first = John AND user.last = White로 검색하면, 실제로 존재하지 않는 John White라는 사람에 대해 엉뚱하게 매칭 성공(True)이 발생한다!
✅ 해결책: nested 타입 적용¶
도큐먼트 내의 각 객체를 독립된 숨겨진 도큐먼트(Hidden Document)로 격리 저장하여 객체 간의 관계를 온전히 유지한다.
# 1. user 필드를 nested 타입으로 인덱스 생성
curl -H 'Content-Type: application/json' -X PUT 'localhost:9200/nested_sample?pretty' -d '
{
"mappings": {
"properties": {
"user": {
"type": "nested"
}
}
}
}'
# 2. nested 전용 쿼리를 이용한 정밀 검색
curl -H 'Content-Type: application/json' -X GET 'localhost:9200/nested_sample/_search?pretty' -d '
{
"query": {
"nested": {
"path": "user",
"query": {
"bool": {
"must": [
{ "match": { "user.first": "John" } },
{ "match": { "user.last": "Smith" } }
]
}
}
}
}
}'
John Smith: 정상 매칭 (결과 1건)John White: 교차 매칭 방지 (결과 0건, 왜곡 없음)
마치며¶
이번 글에서는 Elasticsearch의 데이터 설계 뼈대인 매핑(Mapping)의 개념과 불변성, 그리고 6대 핵심 데이터 타입(text/keyword, numeric, date, boolean, object, nested)을 총정리했다.
- 대량 트래픽과 정확한 검색 결과를 보장하기 위해서는 자동 매핑에 전적으로 의존하기보다,
- 운영 인덱스 생성 시점에
text와keyword,nested를 명확히 정의하는 사전 매핑 설계가 필수적이다.