How to Upgrade SpringBoot 2.3.0 Projects from Elasticsearch 6.x to 7.x Without Pitfalls

Recently I decided to upgrade my mall project to SpringBoot 2.3.0, which requires moving Elasticsearch from 6.x to 7.x. During the upgrade I discovered that ElasticsearchTemplate is no longer supported, so this article records the pitfalls and solutions when migrating from Elasticsearch 6.x to 7.x.

Version Selection

To upgrade to Elasticsearch 7.x, first adjust the SpringBoot version in pom.xml to 2.3.0:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.3.0.RELEASE</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

Search the project's external libraries for the elasticsearch jar (e.g., elasticsearch-7.6.2.jar) and inspect its MANIFEST.MF for the X-Compile-Elasticsearch-Version attribute, which reveals the compatible version 7.6.2. Earlier attempts with 6.2.2 and 7.4.0 caused compatibility issues, so choosing the right version is crucial. If you use the Chinese IK analyzer, ensure it matches the same version.

Problems Encountered

After selecting a compatible Elasticsearch version, several issues arise:

In application.yml, the old configuration for Elasticsearch host and cluster name is deprecated; replace it with a direct REST URI configuration:

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

ElasticsearchTemplate

is obsolete. Switch to ElasticsearchRestTemplate. The former’s query() method no longer exists; use search() instead.

// Using ElasticsearchTemplate for complex query
return elasticsearchTemplate.query(searchQuery, response -> {
    LOGGER.info("DSL:{}", searchQuery.getQuery().toString());
    return convertProductRelatedInfo(response);
});
// Using ElasticsearchRestTemplate for complex query
SearchHits<EsProduct> searchHits = elasticsearchRestTemplate.search(searchQuery, EsProduct.class);
return convertProductRelatedInfo(searchHits);

Adjust the helper method signature:

// Before
private EsProductRelatedInfo convertProductRelatedInfo(SearchResponse response) { ... }
// After
private EsProductRelatedInfo convertProductRelatedInfo(SearchHits<EsProduct> response) { ... }

A runtime ClassCastException occurs because older code casts ParsedNested to InternalNested. The fix is to replace usage of Terms with ParsedTerms (e.g., StringTerms → ParsedStringTerms).

ElasticsearchRepository

’s search() method is also deprecated. Replace it with the RestTemplate version:

// ElasticsearchRepository complex search
return productRepository.search(searchQuery);
// ElasticsearchRestTemplate complex search
SearchHits<EsProduct> searchHits = elasticsearchRestTemplate.search(searchQuery, EsProduct.class);
if (searchHits.getTotalHits() <= 0) {
    return new PageImpl<>(null, pageable, 0);
}
List<EsProduct> searchProductList = searchHits.stream()
    .map(SearchHit::getContent)
    .collect(Collectors.toList());
return new PageImpl<>(searchProductList, pageable, searchHits.getTotalHits());

Summary

Upgrading Elasticsearch from 6.x to 7.x involves substantial changes: ElasticsearchTemplate is deprecated and should be replaced by ElasticsearchRestTemplate; the search() method of ElasticsearchRepository is also discouraged. Simple data operations can still use ElasticsearchRepository, but complex queries must rely on ElasticsearchRestTemplate.

Project source code: https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-elasticsearch