개요
매핑 공식 문서: https://www.elastic.co/guide/en/elasticsearch/reference/7.17/mapping.html
매핑은 Elasticsearch에서 핵심적인 개념으로, 인덱스는 MySQL의 테이블에 해당하고, 매핑은 테이블 구조와 유사하며, 문서는 테이블의 행 데이터입니다.
매핑은 문서 구조와 데이터 타입을 정의하고, 문서 색인 방식을 설정하는 역할을 합니다.
매핑은 동적 매핑과 명시적 매핑으로 나뉩니다:
- 동적 매핑은 문서를 추가하기만 하면 새 필드가 자동으로 추가됩니다. 최상위 매핑과 내부 object, nested 필드에 필드를 추가할 수 있습니다.
- 명시적 매핑은 문서를 추가하기 전에 각 필드의 데이터 타입을 미리 정의해야 합니다. 예를 들어:
- 문자열 필드 중 전체 텍스트로 처리할 필드
- 숫자, 날짜, 위치 정보 필드
- 날짜 형식 지정
- 동적으로 필드를 추가할 때 적용할 사용자 정의 규칙
데이터 타입 소개
공식 문서: https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/field-data-types
일반적인 타입들
-
binary
-
Base64로 인코딩된 이진 데이터를 저장합니다.
-
boolean
-
true 또는 false 값만 가질 수 있습니다.
-
keyword
-
구조화된 데이터에 사용됩니다. 예: ID, 이메일 주소, 호스트명, 상태 코드, 우편번호, 태그 등. 분석기 적용 시 분할되지 않습니다.
-
text
-
전체 텍스트 내용(예: 이메일 본문, 제품 설명)에 사용되는 전통적인 필드 타입입니다. 검색에 적합합니다.
-
date
-
날짜 값을 저장하며
format옵션으로 포맷을 지정할 수 있습니다. -
숫자
-
Elasticsearch에는 다양한 숫자 타입이 있으며, Java의 데이터 타입과 비슷합니다:
-
byte: 8비트 부호 있는 정수, -128~127
-
short: 16비트 부호 있는 정수, -32,768~32,767
-
integer: 32비트 부호 있는 정수, -2^31~2^31-1
-
long: 64비트 부호 있는 정수, -2^63~2^63-1
-
double: 64비트 IEEE 754 배정밀도 부동소수점, 유한값 제한
-
float: 32비트 IEEE 754 단정밀도 부동소수점, 유한값 제한
-
half_float: 16비트 IEEE 754 반정밀도 부동소수점, 유한값 제한
-
scaled_float: 고정 배율로 스케일링된 long 기반 부동소수점
-
unsigned_long: 64비트 부호 없는 정수, 0~2^64-1
-
배열
-
Elasticsearch는 별도의 array 타입을 지원하지 않습니다. 모든 필드는 0개 이상의 값을 포함할 수 있으며, 배열 내 모든 값은 같은 데이터 타입이어야 합니다. 예:
-
문자열 배열: ["one", "two"]
-
정수 배열: [1, 2]
-
배열의 배열: [1, [2, 3]] → [1, 2, 3]
-
객체 배열: [{ "name": "Mary", "age": 12 }, { "name": "John", "age": 10 }]
-
object
-
JSON 문서는 계층적 구조입니다. 문서는 내부 객체를 포함할 수 있고, 그 내부 객체도 또 다른 내부 객체를 포함할 수 있습니다.
-
IP
-
IPv4 또는 IPv6 주소를 저장합니다.
주요 데이터 타입은 위와 같습니다. 다른 경우는 공식 문서를 참고하세요.
매핑 관리
매핑 생성
정적 매핑 (명시적 생성)
인덱스 생성 시 매핑을 정의하여 필드 타입과 설정을 제어합니다:
PUT /my_index
{
"settings": {
"number_of_shards": 3,
"number_of_replicas": 1,
"refresh_interval": "1s"
}
"mappings": {
"properties": {
"title": { "type": "text" },
"price": { "type": "double" },
"tags": { "type": "keyword" },
"created_at": { "type": "date", "format": "yyyy-MM-dd" }
}
}
}
동적 매핑 (자동 생성)
문서 삽입 시 필드가 없으면 Elasticsearch가 데이터 타입에 따라 자동으로 매핑을 생성합니다. 예:
PUT /my_index/_doc/1
{
"title": "Elasticsearch Guide",
"price": 49.99,
"tags": ["search", "database"]
}
Elasticsearch는 title(text+keyword), price(double), tags(keyword) 필드에 대해 자동 매핑을 생성합니다.
매핑 조회
- 특정 인덱스의 매핑 조회
GET /my_index/_mapping
- 여러 인덱스의 매핑 조회
GET /index1,index2/_mapping
- 모든 인덱스의 매핑 조회
GET /_mapping
매핑 업데이트
새 필드 추가 (동적 업데이트 가능) 기존 매핑에 새로운 필드를 추가할 수 있습니다:
PUT /my_index/_mapping
{
"properties": {
"description": { "type": "text" },
"in_stock": { "type": "boolean" }
}
}
필드 타입 수정 (직접 수정 불가) 기존 필드 타입을 변경하려면 새 인덱스를 만들고 데이터를 재색인해야 합니다:
// 1. 올바른 매핑을 정의한 새 인덱스 생성
PUT /new_my_index
{
"mappings": {
"properties": {
"price": { "type": "integer" } // 원래는 double, 변경 후 integer
}
}
}
// 2. _reindex API로 데이터 이전
POST /_reindex
{
"source": { "index": "my_index" },
"dest": { "index": "new_my_index" }
}
// 3. 데이터 검증 후 기존 인덱스 삭제
DELETE /my_index
매핑 삭제
- 인덱스 삭제 (매핑도 함께 삭제)
DELETE /my_index
- 매핑 재설정 (삭제 후 재생성) 인덱스를 삭제한 후 다시 생성하고 새 매핑을 정의합니다:
DELETE /my_index
PUT /my_index
{
"mappings": { ... } // 새 매핑 정의
}
매핑 파라미터 상세 설명
핵심 파라미터
- type: 필드 타입 (text, keyword, integer 등)
- index: 색인 여부 (true/false)
- analyzer: 분석기 지정 (standard, english 등)
- search_analyzer: 검색 시 사용할 분석기 (analyzer와 다를 경우 유효)
- null_value: null 값을 대체할 기본값 (필드 타입과 일치해야 함)
- dynamic: 동적 필드 추가 행동 제어 (true/false/strict)
고급 파라미터
- copy_to: 필드 값을 대상 필드로 복사하여 복합 검색 가능
- doc_values: 열 기반 데이터 저장 여부 (집계 및 정렬에 사용, 기본 true)
- norms: 정규화 요소 저장 여부 (점수에 영향, text는 기본 false)
- fields: 다중 필드 색인 (예: text와 keyword 동시에 저장)
문서 관리
Elasticsearch에서 문서는 색인 가능한 기본 데이터 단위이며, JSON 형식으로 저장됩니다.
다음은 일반적인 문서 관리 API만 설명하며, 더 많은 정보는 공식 문서 참조: https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-document
문서 기본 개념
- 문서 구조: JSON 객체로, 필드와 값으로 구성됩니다.
- 고유 식별자: 각 문서는 인덱스 내에서 고유한 ID를 가져야 합니다 (자동 생성 또는 수동 지정).
- 메타데이터 필드:
- _index: 문서가 속한 인덱스 이름.
- _id: 문서 고유 식별자.
- _source: 원본 JSON 문서.
- _version: 문서 버전 번호, 낙관적 잠금에 사용.
문서 생성
ID 지정 생성
PUT /my_index/_doc/1
{
"title": "Getting Started with ES",
"content": "First steps in Elasticsearch",
"user": "john_doe",
"views": 100
}
자동 ID 생성
응답에 자동 생성된 _id가 포함됩니다.
POST /my_index/_doc
{
"title": "Elasticsearch Tutorial",
"content": "Learn Elasticsearch basics",
"tags": ["search", "database"],
"created_at": "2023-01-01"
}
문서 조회
ID로 단일 문서 조회
GET /my_index/_doc/1
문서 존재 여부 확인
HEAD /my_index/_doc/1
지정 필드만 조회
GET /my_index/_doc/1?_source=field1,field2
문서 업데이트
전체 업데이트
PUT /my_index/_doc/1
{
"title": "Updated Title", // 기존 필드는 삭제됨
"views": 101
}
부분 업데이트
POST /my_index/_update/1
{
"doc": {
"views": 102, // views 필드만 업데이트
"updated_at": "now" // 새 필드 추가
}
}
문서 삭제
ID 기반 단일 문서 삭제
DELETE /my_index/_doc/1
조건 기반 삭제 (delete-by-query 플러그인 필요)
POST /my_index/_delete_by_query
{
"query": {
"term": {
"user": "john_doe"
}
}
}
동적 매핑 상세 설명
공식 문서: https://www.elastic.co/docs/manage-data/data-store/mapping/dynamic-mapping 동적 매핑은 Elasticsearch에 문서를 추가하기만 해도 새 필드가 자동으로 추가되는 방식입니다. 최상위 매핑과 내부 object, nested 필드에 필드를 추가할 수 있습니다.
동적 매핑 검증
매핑 없이 인덱스 생성
PUT dynamic-mapping-01
{
"settings": {
"number_of_shards": 3,
"number_of_replicas": 1,
"refresh_interval": "1s"
}
}
문서 추가
# 요청
PUT dynamic-mapping-01/_doc/1
{
"create_date": "2015/09/02",
"name": "huangsir",
"age": 18,
"addr": "BeiJing",
"ip": "10.0.0.40"
}
문서 조회
# 요청
GET dynamic-mapping-01/_doc/1
# 예상 응답
{
"_index" : "dynamic-mapping-01",
"_type" : "_doc",
"_id" : "1",
"_version" : 1,
"_seq_no" : 0,
"_primary_term" : 1,
"found" : true,
"_source" : {
"create_date" : "2015/09/02",
"name" : "huangsir",
"age" : 18,
"addr" : "BeiJing",
"ip" : "10.0.0.40"
}
}
매핑 조회
# 요청
GET /dynamic-mapping-01/_mapping
# 예상 응답
{
"dynamic-mapping-01" : {
"mappings" : {
"properties" : {
"addr" : {
"type" : "text",
"fields" : {
"keyword" : {
"type" : "keyword",
"ignore_above" : 256
}
}
},
"age" : {
"type" : "long"
},
"create_date" : {
"type" : "date",
"format" : "yyyy/MM/dd HH:mm:ss||yyyy/MM/dd||epoch_millis"
},
"ip" : {
"type" : "text",
"fields" : {
"keyword" : {
"type" : "keyword",
"ignore_above" : 256
}
}
},
"name" : {
"type" : "text",
"fields" : {
"keyword" : {
"type" : "keyword",
"ignore_above" : 256
}
}
}
}
}
}
}
위 결과에서 필드 타입이 원하는 것과 다르다는 것을 확인할 수 있으므로, 직접 타입을 지정할 수 있습니다.
정적 매핑 검증
공식 문서: https://www.elastic.co/docs/manage-data/data-store/mapping/explicit-mapping
정적 매핑은 인덱스 생성 시 필드, 데이터 타입, 기타 설정을 미리 정의하는 방식입니다.
인덱스 생성
# 요청
PUT explicit-mapping-01
{
"settings": {
"number_of_shards": 3,
"number_of_replicas": 1,
"refresh_interval": "1s"
},
"mappings": {
"properties": {
"name": {
"type": "text"
},
"age": {
"type": "byte"
},
"addr": {
"type": "keyword"
},
"ip": {
"type": "ip"
},
"create_date": {
"type": "date",
"format": "yyyy/MM/dd HH:mm:ss||yyyy/MM/dd||epoch_millis"
},
"class": {
"type": "object",
"properties": {
"name":{
"type": "text"
}
}
}
}
}
}
# 예상 응답
{
"acknowledged" : true,
"shards_acknowledged" : true,
"index" : "explicit-mapping-01"
}
매핑 조회
# 요청
GET explicit-mapping-01/_mapping
# 예상 응답
{
"explicit-mapping-01" : {
"mappings" : {
"properties" : {
"addr" : {
"type" : "keyword"
},
"age" : {
"type" : "byte"
},
"class" : {
"properties" : {
"name" : {
"type" : "text"
}
}
},
"create_date" : {
"type" : "date",
"format" : "yyyy/MM/dd HH:mm:ss||yyyy/MM/dd||epoch_millis"
},
"ip" : {
"type" : "geo_point"
},
"name" : {
"type" : "text"
}
}
}
}
}
문서 생성
# 요청
POST explicit-mapping-01/_doc
{
"create_date": "2015/09/02",
"name": "huangsir",
"age": 18,
"addr": "BeiJing",
"ip": "10.0.0.40",
"class": {
"name": "清华大学"
}
}
# 예상 응답
{
"_index" : "explicit-mapping-01",
"_type" : "_doc",
"_id" : "C0JSlpcB-K0y8avWYdSX",
"_version" : 1,
"result" : "created",
"_shards" : {
"total" : 2,
"successful" : 2,
"failed" : 0
},
"_seq_no" : 0,
"_primary_term" : 1
}
문서 조회
# 요청
GET explicit-mapping-01/_doc/C0JSlpcB-K0y8avWYdSX
# 예상 응답
{
"_index" : "explicit-mapping-01",
"_type" : "_doc",
"_id" : "C0JSlpcB-K0y8avWYdSX",
"_version" : 1,
"_seq_no" : 0,
"_primary_term" : 1,
"found" : true,
"_source" : {
"create_date" : "2015/09/02",
"name" : "huangsir",
"age" : 18,
"addr" : "BeiJing",
"ip" : "10.0.0.40",
"class" : {
"name" : "清华大学"
}
}
}