Hibernate Validator and Search

Hibernate Validator is the reference implementation of the Jakarta Bean Validation specification (formerly Java Bean Validation, javax.validation). As of Spring Boot 3 and Jakarta EE 9+, all annotations come from the jakarta.validation package.

What it does

Hibernate Validator provides a declarative, annotation-driven way to define and enforce constraints on Java objects. It validates at the application layer, before data reaches the database.

Core built-in constraints

import jakarta.persistence.*;
import jakarta.validation.constraints.*;

@Entity
public class Customer {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @NotBlank
    @Size(min = 2, max = 100)
    private String name;

    @Email
    @NotNull
    private String email;

    @Min(18)
    private int age;

    @NotNull
    @DecimalMin("0.0")
    private BigDecimal creditLimit;

    @Pattern(regexp = "^[A-Z]{2}[0-9]{6}$")
    private String passportNumber;
}

Common use cases

• Persistence layer: validates entities before persist() / merge() — Spring Boot integrates this automatically.
• Web layer: validates request bodies and method parameters with @Valid / @Validated.
• Service layer: validates method inputs/outputs with @Validated on the class.

Integration with Spring Boot 3

    org.springframework.boot
    spring-boot-starter-validation

Auto-configured. Violations throw ConstraintViolationException at the persistence layer or MethodArgumentNotValidException in the web layer.

Custom constraints

@Target({FIELD, METHOD})
@Retention(RUNTIME)
@Constraint(validatedBy = PhoneValidator.class)
public @interface ValidPhone {
    String message() default "Invalid phone number";
    Class>[] groups() default {};
    Class extends Payload>[] payload() default {};
}

Key interview gotchas

• jakarta.validation, not javax.validation — critical for Spring Boot 3 / Hibernate 6.
• Hibernate Validator is the implementation; Jakarta Bean Validation is the specification. Interviewers sometimes conflate the two.
• Database-level constraints (UNIQUE, NOT NULL in DDL) and application-level constraints (Hibernate Validator) are complementary — both should be present. Database constraints are the last line of defense.
• Validation groups allow applying different constraint sets in different contexts (e.g., different rules for Create vs Update operations).

Hibernate Search is a full-text search integration library that bridges Hibernate ORM and powerful search backends. It automatically keeps a search index in sync with your database as entities are persisted, updated, and deleted.

How it works

1. You annotate entity fields with Hibernate Search annotations to mark them as searchable.
2. Hibernate Search listens to Hibernate's entity lifecycle events (via an integration hook called the "mass indexer" and an event listener).
3. When entities are saved or updated, the indexed fields are written to the search backend.
4. You execute search queries through Hibernate Search's API, which translates them into backend-specific queries.

Supported backends (Hibernate Search 6.x)

• Apache Lucene (embedded, local index — suitable for single-node applications)
• Elasticsearch / OpenSearch (distributed, suitable for production at scale)

Setup (Spring Boot 3 + Hibernate Search 6)

    org.hibernate.search
    hibernate-search-mapper-orm
    7.1.0.Final


    org.hibernate.search
    hibernate-search-backend-lucene
    7.1.0.Final

Entity mapping

import jakarta.persistence.*;
import org.hibernate.search.mapper.pojo.mapping.definition.annotation.*;

@Entity
@Indexed
public class Product {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @FullTextField(analyzer = "english")
    private String name;

    @FullTextField
    private String description;

    @KeywordField
    private String sku;

    @GenericField
    private BigDecimal price;
}

Querying

SearchSession searchSession = Search.session(em);

SearchResult result = searchSession.search(Product.class)
    .where(f -> f.match()
        .fields("name", "description")
        .matching("laptop"))
    .fetch(20);

List hits = result.hits();
long totalCount = result.total().hitCount();

Mass indexing (initial index build)

searchSession.massIndexer(Product.class)
    .threadsToLoadObjects(4)
    .startAndWait();

Key interview gotchas

• Hibernate Search 6.x uses jakarta.persistence and requires Hibernate ORM 6.x.
• The Lucene backend stores indexes locally on disk — not suitable for multi-node deployments. Use Elasticsearch/OpenSearch for distributed setups.
• @FullTextField enables full-text (analyzed) search; @KeywordField is for exact-match (non-analyzed) fields like codes or enums.
• Hibernate Search does not replace the database — it adds a search index alongside it. The database remains the source of truth.

Hibernate Validator enforces data integrity at the application layer using the Jakarta Bean Validation specification. It acts as a guard before data reaches the database, catching invalid data early with descriptive error messages.

How constraints are enforced

Constraint annotations on entity fields are evaluated automatically by Hibernate ORM during the pre-persist and pre-update lifecycle events. If any constraint is violated, a ConstraintViolationException is thrown before any SQL is executed:

@Entity
public class Account {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @NotBlank(message = "Username is required")
    @Size(min = 3, max = 30, message = "Username must be 3-30 characters")
    private String username;

    @Email(message = "Must be a valid email")
    @NotNull
    private String email;

    @DecimalMin(value = "0.00", message = "Balance cannot be negative")
    private BigDecimal balance;
}

Attempting to persist an Account with a blank username throws ConstraintViolationException with detailed ConstraintViolation objects identifying the failing field, the violated constraint, and the invalid value.

Layers of enforcement

Hibernate Validator integrates at multiple layers in a Spring Boot 3 application:

HTTP Request → @Valid in @RestController → MethodArgumentNotValidException
                                              ↓
Service method → @Validated + @NotNull params → ConstraintViolationException
                                              ↓
JPA persist/merge → Hibernate ORM lifecycle validation → ConstraintViolationException
                                              ↓
Database → column constraints (NOT NULL, UNIQUE, CHECK) → DataIntegrityViolationException

Global exception handling in Spring

@ControllerAdvice
public class ValidationExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity> handleValidation(
            MethodArgumentNotValidException ex) {
        Map errors = new HashMap<>();
        ex.getBindingResult().getFieldErrors().forEach(error ->
            errors.put(error.getField(), error.getDefaultMessage()));
        return ResponseEntity.badRequest().body(errors);
    }
}

Validation groups

Different constraint sets for different operations:

public interface OnCreate {}
public interface OnUpdate {}

@NotNull(groups = OnCreate.class)
@Null(groups = OnUpdate.class)
private String temporaryCode;

// In controller:
@PostMapping public ResponseEntity> create(@Validated(OnCreate.class) @RequestBody Dto dto) { ... }
@PutMapping  public ResponseEntity> update(@Validated(OnUpdate.class) @RequestBody Dto dto) { ... }

Key interview gotchas

• Use jakarta.validation.constraints, not javax.validation.constraints.
• Application-layer validation and database-layer constraints are both needed — validator catches errors before hitting the DB; DB constraints are the last line of defense for data coming from other sources.
• @Valid (standard) performs full validation; @Validated (Spring) additionally supports validation groups.
• Hibernate Validator validates at persist time, but you can also trigger validation manually: Validator validator = Validation.buildDefaultValidatorFactory().getValidator(); Set> violations = validator.validate(object);

Hibernate Search enhances querying capabilities by adding full-text search, relevance scoring, faceting, and advanced linguistic processing that are not possible with standard SQL or JPQL.

What Hibernate Search adds beyond SQL

Full-text and analyzed search

SQL LIKE '%laptop%' is case-sensitive, slow, and does not understand language. Hibernate Search with an english analyzer tokenizes, lowercases, stems, and removes stop words:

// Finds "laptops", "Laptop", "LAPTOP" — SQL LIKE cannot do this
searchSession.search(Product.class)
    .where(f -> f.match().field("description").matching("laptop"))
    .fetch(10);

Relevance scoring

Results are ranked by relevance (TF-IDF / BM25) — the most relevant results come first, unlike SQL which has no concept of relevance:

SearchResult result = searchSession.search(Article.class)
    .where(f -> f.match().fields("title", "body").matching("spring boot"))
    .sort(f -> f.score())  // highest relevance first
    .fetch(10);

Advanced query types

// Fuzzy search — matches typos (e.g. "hibenate" → "hibernate")
f.match().field("title").matching("hibenate").fuzzy(1)

// Phrase search
f.phrase().field("description").matching("full text search")

// Wildcard
f.wildcard().field("name").matching("spring*")

// Range
f.range().field("price").between(100.0, 500.0)

// Boolean composite
f.bool()
    .must(f.match().field("category").matching("electronics"))
    .should(f.match().field("name").matching("laptop"))

Faceting and aggregations

Count results by category, price range, etc.:

AggregationKey> countByCategory =
    AggregationKey.of("countByCategory");

searchSession.search(Product.class)
    .where(f -> f.matchAll())
    .aggregation(countByCategory, f -> f.terms().field("category", String.class))
    .fetch(0);

Geo-spatial queries (with Elasticsearch backend)

f.spatial().within().field("location")
    .circle(48.8566, 2.3522, 10, DistanceUnit.KILOMETERS)

Key interview gotchas

• Hibernate Search does not replace SQL — it is complementary. Use it for search; use SQL/JPQL for transactional data access.
• The search index is eventually consistent with the database — there can be a brief lag between a write and its appearance in search results.
• Hibernate Search 6 supports both Lucene (embedded) and Elasticsearch/OpenSearch backends; switch by changing the dependency and configuration without changing application code.
• Mass indexing must be run on initial deployment and after any offline bulk data changes to rebuild the index.

Hibernate Validator and Hibernate Search are two entirely separate libraries under the Hibernate project umbrella. They solve different problems and are not interchangeable.

Hibernate Validator

• Purpose: validates Java object state against declared constraints.
• Standard: implements the Jakarta Bean Validation specification (jakarta.validation).
• When it runs: before persist/update (JPA lifecycle), on HTTP request binding (@Valid), on service method parameters (@Validated).
• Output on failure: ConstraintViolationException with details of which fields violated which constraints.
• Database interaction: none — it operates entirely in the JVM before SQL is generated.

@NotBlank
@Size(max = 100)
private String name;  // validated at application layer by Hibernate Validator

Hibernate Search

• Purpose: enables full-text search and advanced querying on entity data by maintaining a search index.
• Standard: no external spec — it is a standalone Hibernate library.
• When it runs: continuously, in response to entity lifecycle events (index updates on persist/update/delete) and explicitly for search queries.
• Output: ranked list of matching entities with relevance scores, supporting fuzzy, phrase, wildcard, and range queries.
• Database interaction: reads entity data from the database (for indexing), then queries the search index (Lucene or Elasticsearch), not the database.

@FullTextField(analyzer = "english")
private String description;  // indexed by Hibernate Search for full-text queries

Comparison table

Key interview gotchas

• Both are "Hibernate" libraries but serve completely different purposes — confusing them signals a gap in understanding.
• In Spring Boot 3, Hibernate Validator is auto-configured via spring-boot-starter-validation; Hibernate Search requires its own explicit dependency.
• Hibernate Validator is almost always used in a Spring Boot project; Hibernate Search is added only when full-text search is required.
• Both use jakarta.* namespaces in their current versions (aligned with Hibernate ORM 6 / Spring Boot 3).