ElasticSearch의 매핑 및 문서 관리

개요

매핑 공식 문서: 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" : "清华大学"
    }
  }
}

태그: elasticsearch mapping document indexing data type

10월 16일 13:34에 게시됨