[실습] Spring Boot에 Elasitcsearch 연결하기 (feat. Spring Data Elasticsearch)

JSCODE 박재성

2026. 04. 04.

✅ Spring Boot에 Elasitcsearch 연결하기

동일한 환경에서 실습을 진행하기 위해 아래 버전을 사용할 것을 권장한다. - Spring Boot는 3.x.x 버전 - JDK 17

1. Spring Boot 프로젝트 셋팅
start.spring.io
https://start.spring.io/



• Java 17 버전을 선택하자. 아래 과정을 Java 17 버전을 기준으로 진행할 예정이다.
• Dependencies는 Spring Boot DevTools, Spring Web, Spring Data Elasticsearch (Access+Driver)를 선택해라.
• Spring Data Elasticsearch는 Spring Data JPA와 비슷한 원리로 작동하는 Elasticsearch 라이브러리이다.
 

2. 불필요한 테스트 코드 삭제

3. application.yml에 Elasticsearch 연결을 위한 정보 작성하기

이 프로젝트에서는 application.properties를 지우고 application.yml을 생성했다.

application.yml

spring:
  elasticsearch:
    uris: http://localhost:9200 # 연결할 Elasticsearch 주소

logging:
  level:
    org.elasticsearch.client: TRACE # Elasticsearch의 쿼리 로그를 출력

 

2. Document 생성하기
UserDocument

@Document(indexName = "users") // users 인덱스의 Document임을 명시
public class UserDocument {
  @Id 
  private String id; // Elasticsearch에서는 Document ID를 문자열(String)으로 다룸

  @Field(type = FieldType.Keyword) // 매핑 정의 : keyword 타입
  private String name;

  @Field(type = FieldType.Long) // 매핑 정의 : long 타입
  private Long age; 

  @Field(type = FieldType.Boolean) // 매핑 정의 : boolean 타입
  private Boolean isActive; 
  
  public UserDocument(String id, String name, Long age, Boolean isActive) {
    this.id = id;
    this.name = name;
    this.age = age;
    this.isActive = isActive;
  }

  public String getId() {
    return id;
  }

  public String getName() {
    return name;
  }

  public Long getAge() {
    return age;
  }

  public Boolean getIsActive() {
    return isActive;
  }
  
  public void setId(String id) {
    this.id = id;
  }

  public void setName(String name) {
    this.name = name;
  }

  public void setAge(Long age) {
    this.age = age;
  }

  public void setIsActive(Boolean isActive) {
    this.isActive = isActive;
  }
}

• 참고) 응답값의 형태를 위해 getActive()라고 만들지 말고 getIsActive()라고 메서드명을 지어주자. 그리고 일관성을 위해 setActive()라고 만들지 말고 setIsActive()라고 메서드명을 지어주자.
 

3. Repository 생성하기
UserDocumentRepository

public interface UserDocumentRepository extends ElasticsearchRepository<UserDocument, String> {
}

참고) 최소 1개 이상의 ElasticsearchRepository가 존재해야, Spring Boot를 실행시킬 때 Elasticsearch와 연결을 시도한다.

6. Spring Boot 프로젝트 실행시키기



Spring Boot 프로젝트를 실행시켰을 때 에러가 뜨지 않고 위 로그가 찍혀있다면 정상적으로 Elasticsearch와 연결이 된 것이다.

✅ Spring Boot와 Elasticsearch가 연결이 안 됐을 때 발생하는 에러

1. application.yml 수정하기

spring:
  elasticsearch:
	  # Elasticsearch가 실행이 안 되고 있다는 걸 가정 or 주소를 잘못 입력했을 때를 가정
    uris: http://localhost:9999

logging:
  level:
    org.elasticsearch.client: TRACE

 

2. Spring Boot 프로젝트 실행시켜보기



Elasticsearch와 연결이 안 될 경우 Connection refused라는 에러 메시지가 출력된다.
 

3. 다시 원래대로 application.yml 수정하기

spring:
  elasticsearch:
    uris: http://localhost:9200

logging:
  level:
    org.elasticsearch.client: TRACE

 

✅ users 인덱스를 지우고 실행시켜보자.

1. Kibana로 users 인덱스 삭제하기

DELETE /users

 

2. Spring Boot 프로젝트 실행시켜보기



로그를 보면 users 인덱스를 조회해보고 인덱스가 없다고 판단해서, users 인덱스를 생성하는 것 같은 로그가 찍혀있다. 정말 users 인덱스를 조회해보자.
 

3. Kibana에서 users 인덱스 조회해보기

GET /users



 
응답값

{
  "users": {
    "aliases": {},
    "mappings": {
      "properties": {
        "_class": {
          "type": "keyword",
          "index": false,
          "doc_values": false
        },
        # UserDocument에서 정의한 Field에 맞게 매핑(mapping)이 정의되어있다.
        "age": {
          "type": "long"
        },
        "isActive": {
          "type": "boolean"
        },
        "name": {
          "type": "keyword"
        }
      }
    },
    "settings": {
      "index": {
        "routing": {
          "allocation": {
            "include": {
              "_tier_preference": "data_content"
            }
          }
        },
        "refresh_interval": "1s",
        "number_of_shards": "1",
        "provided_name": "users",
        "creation_date": "1744519775043",
        "number_of_replicas": "1",
        "uuid": "FnbUnfg0QHWepqTBZEy5zQ",
        "version": {
          "created": "8521000"
        }
      }
    }
  }
}

Spring Boot에서 정의한 UserDocument에 맞게 인덱스가 생성됐다는 걸 알 수 있다.