[트러블슈팅] @Setting을 썼는데 왜 인덱스가 안 될까?

🧨 Elasticsearch 인덱스 설정이 안 된다?! @Setting 실패 기록

 

💥문제 상황

Spring Boot + Spring Data Elasticsearch 환경에서
Elasticsearch에서 검색 성능 개선을 위해 n-gram, edge-ngram 기반 인덱스 설정을 적용하려고 했다.
아래와 같이 job-opening-settings.json을 작성하고,
Spring Data Elasticsearch의 @Setting 어노테이션을 통해 자동으로 인덱스를 생성하려고 했다.

 job-opening-settings.json

{
  "settings": {
    "analysis": {
      "filter": {
        "ngram_filter": {
          "type": "ngram",
          "min_gram": 2,
          "max_gram": 3
        },
        "edge_ngram_filter": {
          "type": "edge_ngram",
          "min_gram": 1,
          "max_gram": 25
        }
      },
      "tokenizer": {
        "ngram_tokenizer": {
          "type": "ngram",
          "min_gram": 2,
          "max_gram": 3
        }
      },
      "analyzer": {
        "ngram_analyzer": {
          "type": "custom",
          "tokenizer": "ngram_tokenizer",
          "filter": ["lowercase", "ngram_filter"]
        },
        "edge_ngram_analyzer": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": ["lowercase", "edge_ngram_filter"]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "fields": {
          "ngram": {
            "type": "text",
            "analyzer": "ngram_analyzer"
          },
          "autocomplete": {
            "type": "text",
            "analyzer": "edge_ngram_analyzer"
          }
        }
      }
    }
  }
}

 

JobOpeningDocument에 @Setting 어노테이션 추가

JobOpeningDocument에 위 설정을 연결해서 애플리케이션 실행 시 자동으로 인덱스가 생성되도록 구성했다.

하지만.. 인덱싱 에러가 발생했다!

@Setting을 적용한 후 애플리케이션을 실행하자 인덱스 생성 에러가 발생했다.

Caused by: co.elastic.clients.elasticsearch._types.ElasticsearchException: 
[es/indices.create] failed: 
[illegal_argument_exception] 
unknown setting [index.settings.analysis.analyzer.ngram_analyzer.filter] 
please check that any required plugins are installed, or check the breaking changes documentation for removed settings

해당 분석기의 설정을 정상적으로 인식하지 못했다...

 

 

🔍 시도한 해결 방법

✅ JSON 설정 문법 확인
     👉 key-value 구조, 쉼표 누락 여부 등 전반적인 문법 오류 확인

✅ filter, tokenizer, analyzer 순서 바꾸기
     👉 혹시 순서 문제로 인식되지 않을까 싶어서 구조를 재배치

✅ analyzer 이름 변경해 보기
     👉 ngram_analyzer → custom_ngram_analyzer 등으로 이름 변경

✅ analyzer 설정을 최소 구성으로 줄여보기
     👉 tokenizer만 사용하거나 filter 일부 제거 등

✅ Spring 버전 확인
     👉 의존성 버전 충돌이나 호환성 문제 확인

여러 해결 방법을 모두 시도했지만.. 에러가 해결되지 않고 계속해서 같은 에러 메시지가 반복되었다...

 

 

🧪 원인 분석

여러 삽질과 함께
블로그, GitHub 이슈, 공식 문서를 찾아본 결과..

🎯 결론: Elasticsearch의 커스텀 분석기 설정을 @Setting으로 전달할 수 없다!

Spring Data Elasticsearch의 @Setting(settingPath = "...")는 내부적으로 REST API를 호출하여 인덱스를 생성하는데, 이때 전달되는 JSON은 단순한 index.settings 수준까지만 안정적으로 처리된다.

하지만 analysis.filter, analysis.tokenizer, analysis.analyzer처럼 복잡한 커스텀 분석기 구성은 클라이언트 내부에서 제대로 직렬화되지 않거나, Elasticsearch에서 unknown setting 오류로 처리된다.

📌 공식 문서에서는 이를 명시하진 않지만, 실무에서 @Setting으로 복잡한 analysis 구성이 적용되지 않는 경우가 매우 흔하며, 이는 Spring Data Elasticsearch GitHub 이슈에서도 다수 보고되었다.

추가 참고 사항

• Elasticsearch는 버전이 올라갈수록 analysis 설정에 민감하다!
• 추가 플러그인이 필요한 것은 아니다!
  ngram, edge-ngram은 모두 Elasticsearch 기본 내장 analyzer 구성 요소이다.

 

 

🧭 최종 해결

고민 끝에..

@Setting를 활용한 자동 인덱스 생성은 포기하고, Kibana Dev Tools 콘솔을 활용해서 인덱스를 수동 생성하기로 결정했다!

현재 적용한 구조

• Spring 애플리케이션에서 @Document(indexName = "job-opening")만 유지한다.
• 기존에 @Setting은 제거한다.
• 인덱스는 배포 전에 Kibana에서 미리 수동 생성한다.

Kibana에서 인덱스 수동 생성

PUT job-opening
{
  "settings": {
    "analysis": {
      "filter": {
        "edge_ngram_filter": {
          "type": "edge_ngram",
          "min_gram": 1,
          "max_gram": 25
        },
        "ngram_filter": {
          "type": "ngram",
          "min_gram": 2,
          "max_gram": 3
        }
      },
      "analyzer": {
        "nori_analyzer": {
          "type": "custom",
          "tokenizer": "nori_tokenizer",
          "filter": ["lowercase"]
        },
        "autocomplete_analyzer": { 
          "type": "custom",
          "tokenizer": "standard",
          "filter": ["lowercase", "edge_ngram_filter"]
        },
        "ngram_analyzer": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": ["lowercase", "ngram_filter"]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "_class": {
        "type": "keyword",
        "index": false,
        "doc_values": false
      },
      "company": { 
        "type": "text",
        "fields": {
          "morph": {
            "type": "text",
            "analyzer": "nori_analyzer"
          },
          "autocomplete": {
            "type": "text",
            "analyzer": "autocomplete_analyzer"
          }
        }
      },
      "createdAt": {
        "type": "date",
        "format": "date_optional_time||epoch_millis"
      },
      "educationLevel": {
        "type": "keyword"
      },
      "employmentType": {
        "type": "keyword"
      },
      "hiringEndAt": {
        "type": "date",
        "format": "date_optional_time||epoch_millis"
      },
      "hiringStartAt": {
        "type": "date",
        "format": "date_optional_time||epoch_millis"
      },
      "id": {
        "type": "keyword"
      },
      "jobOpeningUrl": {
        "type": "text"
      },
      "location": {
        "type": "keyword"
      },
      "maxExperienceYears": {
        "type": "integer"
      },
      "minExperienceYears": {
        "type": "integer"
      },
      "position": {
        "type": "text"
      },
      "requiredSkills": {  
        "type": "text",
        "fields": {
          "ngram": {
            "type": "text",
            "analyzer": "ngram_analyzer"
          },
          "autocomplete": {
            "type": "text",
            "analyzer": "autocomplete_analyzer"
          }
        }
      },
      "salary": {
        "type": "integer"
      },
      "title": {  
        "type": "text",
        "fields": {
          "morph": {
            "type": "text",
            "analyzer": "nori_analyzer"
          },
          "autocomplete": {
            "type": "text",
            "analyzer": "autocomplete_analyzer"
          }
        }
      },
      "viewCount": {
        "type": "integer"
      }
    }
  }
}

 

📌 회고: 왜 이게 중요한가?

• Elasticsearch는 버전 간 변화가 정말 많다.
  설정 문법, 기능 지원 여부, 플러그인 여부 등이 자주 바뀐다.
• Spring Data Elasticsearch는 자동화가 좋아 보이지만, 실제로는 복잡한 설정일수록 수동이 훨씬 안정적이다.
• 오류 메시지가 항상 정확한 원인을 알려주지는 않는다..
  "unknown setting"만 보고는 구조적 제한인지, 문법 오류인지 파악하기 어렵다..
  

그래서 결국엔.. 삽질은 거의 예외 없이 필요하다 😇

 

💡 Elasticsearch는 '된다'고 해도 '믿지 말고 확인하자.

 

 

✅ 최종 정리

항목	내용
문제	@Setting으로 인덱스 자동 생성 실패
원인	Elasticsearch 버전 호환성 + 설정 구조 차이
시도	다양한 설정 변경, 구조 수정
해결	Kibana에서 수동 인덱스 생성
교훈	Elasticsearch는 늘 버전 체크부터!!