Spring Data Elasticsearch - Quick Reference

Full Reference: See advanced.md for aggregations, autocomplete/suggestions, bulk operations, index management, and Testcontainers integration.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: spring-data-elasticsearch for comprehensive documentation.

Dependencies

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-elasticsearch</artifactId> </dependency>

Configuration

spring: elasticsearch: uris: http://localhost:9200 username: ${ELASTICSEARCH_USERNAME:} password: ${ELASTICSEARCH_PASSWORD:} connection-timeout: 5s socket-timeout: 30s

Document Mapping

@Document(indexName = "products") public class Product {

@Id
private String id;

@Field(type = FieldType.Text, analyzer = "standard")
private String name;

@Field(type = FieldType.Text, analyzer = "standard")
private String description;

@Field(type = FieldType.Keyword)
private String category;

@Field(type = FieldType.Double)
private BigDecimal price;

@Field(type = FieldType.Integer)
private Integer stock;

@Field(type = FieldType.Boolean)
private boolean active;

@Field(type = FieldType.Date, format = DateFormat.date_hour_minute_second)
private LocalDateTime createdAt;

@Field(type = FieldType.Nested)
private List<ProductAttribute> attributes;

@Field(type = FieldType.Keyword)
private List<String> tags;

}

Repository Pattern

public interface ProductRepository extends ElasticsearchRepository<Product, String> {

List<Product> findByCategory(String category);
List<Product> findByNameContaining(String name);
List<Product> findByPriceBetween(BigDecimal min, BigDecimal max);
List<Product> findByActiveTrue();

// Pagination
Page<Product> findByCategory(String category, Pageable pageable);

// Sorting
List<Product> findByCategoryOrderByPriceAsc(String category);

// Count / Exists / Delete
long countByCategory(String category);
boolean existsByName(String name);
void deleteByCategory(String category);

}

Custom Queries

public interface ProductRepository extends ElasticsearchRepository<Product, String> {

@Query("""
    {
      "multi_match": {
        "query": "?0",
        "fields": ["name^3", "description", "tags"],
        "type": "best_fields",
        "fuzziness": "AUTO"
      }
    }
    """)
Page<Product> fullTextSearch(String query, Pageable pageable);

}

ElasticsearchOperations

@Service @RequiredArgsConstructor public class ProductSearchService {

private final ElasticsearchOperations elasticsearchOperations;

public SearchHits<Product> search(ProductSearchCriteria criteria) {
    BoolQuery.Builder boolQuery = new BoolQuery.Builder();

    if (StringUtils.hasText(criteria.getQuery())) {
        boolQuery.must(MultiMatchQuery.of(m -> m
            .query(criteria.getQuery())
            .fields("name^3", "description", "tags")
            .fuzziness("AUTO")
        )._toQuery());
    }

    if (StringUtils.hasText(criteria.getCategory())) {
        boolQuery.filter(TermQuery.of(t -> t
            .field("category")
            .value(criteria.getCategory())
        )._toQuery());
    }

    NativeQuery query = NativeQuery.builder()
        .withQuery(boolQuery.build()._toQuery())
        .withPageable(PageRequest.of(criteria.getPage(), criteria.getSize()))
        .build();

    return elasticsearchOperations.search(query, Product.class);
}

}

Best Practices

Do Don't

Use appropriate field types Map everything as text

Define proper analyzers Use default for all

Use filters for exact matches Use match for keywords

Paginate large result sets Fetch all documents at once

When NOT to Use This Skill

• Raw Elasticsearch API - Use elasticsearch skill for REST API

• ELK stack setup - Use elasticsearch skill

• Primary database - Elasticsearch is for search, not ACID transactions

Anti-Patterns

Anti-Pattern Problem Solution

Refresh after each write Performance degradation Use refresh_interval, batch

Deep pagination with from/size Memory issues Use search_after

Mapping all as text Poor search, high disk Use appropriate field types

No index lifecycle Disk exhaustion Configure ILM policies

Fetching all fields Wasted bandwidth Use source filtering

Quick Troubleshooting

Problem Diagnostic Fix

Connection failed Check Elasticsearch running Start ES, check URI, SSL

Index not found Check index name Create index, check @Document

Mapping conflict Check field types Reindex with correct mapping

Search returns nothing Check analyzer Test with _analyze API

Version conflict Check @Version Handle OptimisticLockingFailureException

Production Checklist

• Cluster configured (3+ nodes)

• Shards and replicas set

• Index lifecycle management

• Proper mapping defined

• Analyzers configured

• Bulk operations for indexing

• Monitoring enabled

• Security enabled

Reference Documentation

• Spring Data Elasticsearch Reference