Text Search With Hibernate Search And Spring Boot

In modern application development, efficient search functionality is no longer a luxury – it’s a necessity. Whether you’re building an e-commerce platform, a content management system, or a knowledge base, the ability to quickly find relevant information can make or break user experience. In this guide, we’ll implement a production-ready search solution using Spring Boot 3, Java 21, and Hibernate Search, complete with embedded PostgreSQL testing.

Why This Stack?

Spring Boot 3: The latest version brings Java 21 compatibility and improved native image support
Java 21: Features like virtual threads and pattern matching enhance performance and code clarity
Hibernate Search 7.2: Tight integration with JPA and Lucene provides enterprise-grade search capabilities
Embedded PostgreSQL: Enables realistic testing without Docker dependencies

Architecture Overview

Our solution implements a classic three-tier architecture with a search-specific twist:

text<code>[Thymeleaf UI] ↔ [Spring Controller] ↔ [Search Service] ↔ [Hibernate Search] ↔ [PostgreSQL]

1 2	text<code>[Thymeleaf UI] ↔ [Spring Controller] ↔ [Search Service] ↔ [Hibernate Search] ↔ [PostgreSQL]

The magic happens at the Hibernate Search layer, which maintains a Lucene index synchronized with our database operations.

Implementation Deep Dive

1. Database Layer Configuration

We start by defining our search-optimized entity:

java<code>@Entity
@Indexed // Enables full-text indexing
public class Book {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @FullTextField(analyzer = "standard") // Basic text analysis
    private String title;

    @FullTextField(analyzer = "english") // Language-specific processing
    private String content;
    
    // Standard getters/setters
}

java<code>@Entity

@Indexed // Enables full-text indexing

public class Book {

@Id

@GeneratedValue(strategy = GenerationType.IDENTITY)

private Long id;

@FullTextField(analyzer = "standard") // Basic text analysis

private String title;

@FullTextField(analyzer = "english") // Language-specific processing

private String content;

// Standard getters/setters

}

Key Annotations:

@Indexed: Marks entity for search indexing
@FullTextField: Configures Lucene field storage and analysis

2. Search Service Implementation

The heart of our search functionality:

java<code>@Service
public class SearchService {
    private final EntityManager entityManager;

    @Async // Background indexing
    public void initializeIndex() {
        Search.session(entityManager)
           .massIndexer()
           .startAndWait(); // Blocking operation
    }

    public List<Book> search(String query) {
        return Search.session(entityManager)
           .search(Book.class)
           .where(f -> f.match()
              .fields("title", "content")
              .matching(query))
           .fetchAllHits();
    }
}

java<code>@Service

public class SearchService {

private final EntityManager entityManager;

@Async // Background indexing

public void initializeIndex() {

Search.session(entityManager)

.massIndexer()

.startAndWait(); // Blocking operation

}

public List<Book> search(String query) {

return Search.session(entityManager)

.search(Book.class)

.where(f -> f.match()

.fields("title", "content")

.matching(query))

.fetchAllHits();

}

Performance Considerations:

Asynchronous Indexing: Prevents application startup delays
Field Selection: Targeted searching improves performance
Analyzer Choice: Language-specific processing improves result relevance

3. Web Layer Integration

Our REST controller bridges the UI and search layer:

java<code>@Controller
@RequestMapping("/books")
public class BookController {
    
    @GetMapping
    public String search(@RequestParam String q, Model model) {
        model.addAttribute("results", searchService.search(q));
        return "search"; // Thymeleaf template
    }
}

java<code>@Controller

@RequestMapping("/books")

public class BookController {

@GetMapping

public String search(@RequestParam String q, Model model) {

model.addAttribute("results", searchService.search(q));

return "search"; // Thymeleaf template

}

The Thymeleaf template provides real-time feedback:

xml<code><form method="get" th:action="@{/books}">
    <input type="text" name="q" th:value="${param.q}">
    <button type="submit">Search</button>
</form>

<div th:if="${results}">
    <h3>Results:</h3>
    <ul th:each="book : ${results}">
        <li th:text="${book.title}"></li>
    </ul>
</div>

xml<code><form method="get" th:action="@{/books}">

<button type="submit">Search</button>

</form>

<h3>Results:</h3>

</ul>

</div>

4. Testing Strategy

We implement dual-layer testing using embedded PostgreSQL:

Integration Test Configuration:

java<code>@TestConfiguration
public class EmbeddedPostgresConfig {
    
    @Bean
    public DataSource dataSource() throws IOException {
        return EmbeddedPostgres.builder()
           .setPort(5432)
           .start() // In-memory PostgreSQL
           .getPostgresDatabase();
    }
}

java<code>@TestConfiguration

public class EmbeddedPostgresConfig {

@Bean

public DataSource dataSource() throws IOException {

return EmbeddedPostgres.builder()

.setPort(5432)

.start() // In-memory PostgreSQL

.getPostgresDatabase();

}

Sample Integration Test:

java<code>@SpringBootTest
@Import(EmbeddedPostgresConfig.class)
class BookSearchTest {

    @Test
    void testSearch() {
        // Arrange
        Book book = new Book("Spring Security", "Authentication patterns");
        repository.save(book);
        searchService.initializeIndex();

        // Act
        List<Book> results = searchService.search("auth");

        // Assert
        assertThat(results).hasSize(1)
           .extracting(Book::getTitle)
           .containsExactly("Spring Security");
    }
}

java<code>@SpringBootTest

@Import(EmbeddedPostgresConfig.class)

class BookSearchTest {

@Test

void testSearch() {

// Arrange

Book book = new Book("Spring Security", "Authentication patterns");

repository.save(book);

searchService.initializeIndex();

// Act

List<Book> results = searchService.search("auth");

// Assert

assertThat(results).hasSize(1)

.extracting(Book::getTitle)

.containsExactly("Spring Security");

}

Testing Advantages:

Real Database Behavior: Not an in-memory mock
Isolated Environments: Fresh database per test class
CI/CD Friendly: No Docker required in pipelines

Performance Optimization Techniques

Indexing Strategies

Batch Processing: Use massIndexer() for initial imports

Incremental Updates: @IndexingDependency(reindexOnUpdate = true)

Asynchronous Operations: Leverage Spring’s @Async

Search Tuning

java<code>.search(Book.class) .where(f -> f.bool() .must(f.match().field("title").matching(query)) .should(f.match().field("content").matching(query)) ) .sort(f -> f.score()) // Relevance sorting .fetchHits(20) // Pagination</code>

1	java<code>.search(Book.class) .where(f -> f.bool() .must(f.match().field("title").matching(query)) .should(f.match().field("content").matching(query)) ) .sort(f -> f.score()) // Relevance sorting .fetchHits(20) // Pagination</code>

Analyzer Configuration

java

<code>@AnalyzerDef(name = "custom", tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class), filters = { @TokenFilterDef(factory = LowerCaseFilterFactory.class), @TokenFilterDef(factory = SnowballPorterFilterFactory.class, params = @Parameter(name = "language", value = "English")) })</code>

<code>@AnalyzerDef(name = "custom", tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class), filters = { @TokenFilterDef(factory = LowerCaseFilterFactory.class), @TokenFilterDef(factory = SnowballPorterFilterFactory.class, params = @Parameter(name = "language", value = "English")) })</code>

Production Readiness Checklist

Index Management

Scheduled reindexing

Index health monitoring

Backup/restore procedures

Security Considerations

Search query sanitization

Index access controls

TLS for database connections

Monitoring

java

<code>Search.mapping(entityManager) .scope(Object.class) .indexer() .monitor(new SearchIndexingMonitor() { /* ... */ });</code>

1	<code>Search.mapping(entityManager) .scope(Object.class) .indexer() .monitor(new SearchIndexingMonitor() { /* ... */ });</code>

Scalability Patterns

Read replicas for search-heavy workloads

Caching with Spring Cache abstraction

Horizontal scaling with shared index storage

Alternative Approaches Compared

Method	Pros	Cons
Hibernate Search	Tight JPA integration	Learning curve
Elasticsearch	Distributed scaling	Operational complexity
PostgreSQL FTS	Native implementation	Limited features
Lucene Direct	Maximum control	Boilerplate code

Migration Path from Previous Versions

For teams upgrading from older implementations:

Java 17 → 21
- Virtual thread adoption
- Pattern matching enhancements
- New HTTP client features
Spring Boot 2 → 3
- Jakarta EE 9+ namespace changes
- Native image improvements
- Security configuration updates
Hibernate Search 6 → 7
- New query DSL
- Improved index management
- Enhanced analyzer configuration

Real-World Use Cases

E-commerce Product Search
- Faceted filtering
- Synonym management
- Personalized ranking
Legal Document Analysis
- Phrase searching
- Highlighting
- Proximity queries
Healthcare Record Search
- HIPAA-compliant indexing
- Medical term expansion
- Secure access patterns

Conclusion

This implementation demonstrates how modern Java frameworks can deliver enterprise-grade search functionality with minimal boilerplate. The combination of Spring Boot’s convention-over-configuration approach and Hibernate Search’s powerful indexing capabilities creates a maintainable, testable solution that scales from prototypes to production systems.

Key Takeaways:

Rapid Development: Spring Boot’s auto-configuration enables quick setup
Realistic Testing: Embedded PostgreSQL provides production-like testing
Future-Proof Design: Java 21 features ensure long-term viability
Search Excellence: Lucene integration delivers best-in-class relevance

For teams looking to enhance existing applications or build new search-driven platforms, this stack offers an optimal balance between developer productivity and operational performance.

Target Audience: Java developers, Technical leads, System architects
Key Technologies: Spring Boot 3, Java 21, Hibernate Search, PostgreSQL
Implementation Time: 2-4 hours (depending on existing setup)
Production Ready: Yes (with additional monitoring/security layers)

This implementation provides a solid foundation that can be extended with:

Machine learning-powered relevance tuning
Voice search integration
Multi-language support
Real-time indexing updates