A movie search web application built with Spring Boot and Elasticsearch, demonstrating six distinct search strategies side-by-side: standard title search, classic BM25 keyword search, sparse semantic search with ELSER, dense semantic search with E5, a hybrid approach using Reciprocal Rank Fusion (RRF), and a two-stage ELSER retrieval reranked by a cross-encoder.
Elastiflix family
- elastiflix-reloaded: the current version of this demo (Java 25, Spring Boot 4.1, Elasticsearch Serverless; full-text, k-NN and hybrid RRF search, with built-in data loading).
- elastiflix-java: previous version, which compares six search modes (ELSER, E5, reranking).
- elastiflix-loader-java: bulk loader for the
elastiflix-moviesindex thatelastiflix-javauses.- Inspired by Elastic's original demo elastic/Elastiflix (forked at bigfito/elastiflix).
-
Six search modes selectable from the UI
Mode Strategy Description TITLEStandard multi_matchontitleandoriginal_title(Default)BM25Keyword multi_matchacrosstitle,original_title,overview,plotwith field boostingELSERSparse vector semanticquery on theplot_elserfield using.elser-model-2E5Dense vector semanticquery on theplot_e5field using.multilingual-e5-smallHYBRIDBM25 + ELSER via RRF retriever.rrfcombining both standard retrievers (ES 8.14+)ELSER_JINAELSER + cross-encoder rerank retriever.text_similarity_rerankerrescoring ELSER's candidates against the query. Highest quality, highest latency — and the only mode whose paging is capped byrank_window_sizerather than the result window -
Filtering & Sorting — filter by genre, release year or rating; sort by RATING (high to low) or YEAR (newest first). Genres are picked from a closed list rather than typed free-hand, because the filter is an unanalyzed
termsquery:actionwould not match the indexedAction. Values arriving through the REST API are canonicalised the same way. -
Honest Hybrid fallback — RRF cannot combine relevance ranking with an attribute sort, so choosing a sort in Hybrid mode runs BM25 instead. The UI says so inline, and the API reports it as
effectiveMode. -
Flexible results view — toggle between Grid and List.
-
Dynamic pagination — 25, 50 or 100 results per page. Paging stops at Elasticsearch's
index.max_result_window(10 000 documents) — or, inELSER_JINA, atelasticsearch.rerank.window-size, since a document the reranker never scored can never be returned. Either way the UI says how far you can actually reach instead of offering pages that would silently serve different results. -
Movie detail page — full metadata, poster image and backdrop via TMDB.
-
REST API — JSON endpoints at
/api/searchand/api/movies/{id}. -
Graceful degradation — an inline warning when an inference endpoint is not deployed; no crash, no error page.
-
Health endpoint —
/actuator/healthreports DOWN if the cluster is unreachable or the index is missing. -
Modern sidebar UI — filters and search options on the left, results on the right. Thymeleaf and Tailwind CSS.
| Layer | Technology |
|---|---|
| Language | Java 25 |
| Framework | Spring Boot 4.1.0 (Spring Framework 7.0.8) |
| Template engine | Thymeleaf 3.1 |
| CSS | Hand-written stylesheet, self-hosted (no CDN, no Node toolchain) |
| Search engine | Elasticsearch 9.5 |
| ES Java client | co.elastic.clients:elasticsearch-java:9.5.0 |
| Build | Maven (single module, wrapper included) |
| Tests | JUnit 6, Mockito, AssertJ, Testcontainers, JaCoCo |
Note on Jackson. Spring Boot 4 serializes HTTP with Jackson 3 (
tools.jackson), while the Elasticsearch client'sJacksonJsonpMapperneeds Jackson 2. The explicitjackson-databinddependency inpom.xmlis therefore required, not redundant — removing it fails at runtime withNoClassDefFoundError.Moviemaps its snake_case fields with per-field@JsonPropertyfor the same reason: a class-level@JsonNamingstrategy would be honoured by only one of the two mappers.
- Java 25+ (the build targets 25; it will not compile on 21)
- Maven 3.8+, or just use the bundled
./mvnwwrapper - A running Elasticsearch 9.5+ (or 8.19+) cluster
- The
elastiflix-moviesindex, populated by the companion Elastiflix loader project - Docker — only for the integration test (
mvn verify); not needed to build or run the app
Credentials come from the environment. Never hardcode them in application.yml or in an IDE run
configuration — .run/ is git-ignored precisely because run configurations tend to accumulate real API keys.
| Variable | Required | Default | Description |
|---|---|---|---|
ELASTIC_HOST |
✅ | — | Cluster URL, e.g. https://my-cluster.es.europe-west1.gcp.cloud.es.io:443. Scheme and host required; a path is rejected at startup |
ELASTIC_APIKEY |
✅ | — | Base64-encoded API key, sent as Authorization: ApiKey … |
ELASTIC_SSL_VERIFY |
— | true |
Set false only for a local cluster with a self-signed certificate |
ELASTIC_RERANK_ID |
— | eis-jina-reranker |
Inference endpoint (task type rerank) used by ELSER_JINA. The default is an Elastic Inference Service endpoint running jina-reranker-v3.5 — create it once (see below); EIS holds the provider key, so none is needed here. Alternatives: the preconfigured .jina-reranker-v3.5, or .rerank-v1-elasticsearch for Elastic's in-cluster reranker |
ELASTIC_RERANK_WINDOW |
— | 50 |
Candidates ELSER hands to the reranker. Also caps how deep ELSER_JINA can page. jina-reranker-v3.5 is listwise, sharing one 131 k-token context across query + candidates, so the bound is that token budget rather than a document count — raising this mainly costs latency. If you point ELASTIC_RERANK_ID at a v3 endpoint, keep it at 64 or below |
Both required variables are validated at startup, so a missing one fails immediately with a message naming the property rather than an NPE on the first search.
ELASTIC_SSL_VERIFY=false disables TLS certificate and hostname validation. Because that would expose the API
key to anyone able to intercept the connection, the application refuses to start if it is disabled for a
non-local HTTPS host. Loopback addresses, RFC-1918 ranges, single-label hostnames (elasticsearch in
docker-compose) and .local/.internal/.test suffixes are accepted; a public FQDN is not.
Non-secret settings live in src/main/resources/application.yml:
elasticsearch:
index: elastiflix-movies
connect-timeout: 5s
socket-timeout: 30s
rerank:
inference-id: ${ELASTIC_RERANK_ID:eis-jina-reranker} # EIS endpoint running jina-reranker-v3.5
window-size: ${ELASTIC_RERANK_WINDOW:50} # candidates reranked, and the paging cap
app:
page-size: 50 # the one authority for the default page size
tmdb-image-base: https://image.tmdb.org/t/p/w500
tmdb-image-base-large: https://image.tmdb.org/t/p/w1280# 1. Point the app at your cluster
export ELASTIC_HOST="https://my-cluster.es.europe-west1.gcp.cloud.es.io:443"
export ELASTIC_APIKEY="<your-base64-encoded-api-key>"
# 2. Run it
./mvnw spring-boot:runThen open http://localhost:8080.
# Development mode — disables Thymeleaf template caching
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev
# Build an executable jar
./mvnw clean package
java -jar target/elastiflix-java-0.0.1-SNAPSHOT.jar
# Health check (reports DOWN if the cluster is unreachable or the index is absent)
curl -s localhost:8080/actuator/health | jqAt startup the application pings the cluster and checks that the index exists, logging an actionable error if either fails. It deliberately still starts: the UI degrades gracefully rather than refusing to boot.
TITLE and BM25 work with no inference endpoint at all. Semantic and Hybrid modes need these two — create them
once per cluster in Kibana → Dev Tools, or run docs/inference-endpoints.http
from your IDE.
PUT _inference/sparse_embedding/elser
{
"service": "elasticsearch",
"service_settings": {
"model_id": ".elser-model-2",
"num_allocations": 1,
"num_threads": 1
}
}PUT _inference/text_embedding/e5
{
"service": "elasticsearch",
"service_settings": {
"model_id": ".multilingual-e5-small",
"num_allocations": 1,
"num_threads": 1
}
}A reranked search additionally needs an endpoint with the rerank task type. The default is an
Elastic Inference Service endpoint running jina-reranker-v3.5 — a 0.6B multilingual listwise model
and a drop-in upgrade to v3. service: elastic means EIS holds the Jina credentials, so no provider key
appears in this request or in the application:
PUT _inference/rerank/eis-jina-reranker
{
"service": "elastic",
"service_settings": {
"model_id": "jina-reranker-v3.5"
}
}Two alternatives, both selected with ELASTIC_RERANK_ID and needing no code change:
.jina-reranker-v3.5— preconfigured on EIS, nothing to create..rerank-v1-elasticsearch— Elastic's own cross-encoder, runs in-cluster with no external service:
PUT _inference/rerank/.rerank-v1-elasticsearch
{
"service": "elasticsearch",
"service_settings": {
"model_id": ".rerank-v1",
"num_allocations": 1,
"num_threads": 1
}
}| Endpoint ID | Type | Required for |
|---|---|---|
elser |
sparse_embedding |
Semantic (ELSER), Hybrid, ELSER + Jina rerank |
e5 |
text_embedding |
Semantic (E5) |
eis-jina-reranker (or ELASTIC_RERANK_ID) |
rerank |
ELSER + Jina rerank |
Network note.
ELSER_JINAis the only mode that depends on something outside your cluster: the reranking call goes from Elasticsearch out to the Elastic Inference Service, which in turn calls Jina. The application itself makes no third-party call and holds no Jina credential — but in a restricted or air-gapped network the mode will fail where the other five keep working. PointELASTIC_RERANK_IDat.rerank-v1-elasticsearchto rerank entirely in-cluster with no egress.
If an endpoint is missing, the mode that needs it shows an inline warning naming the endpoint and suggesting BM25 instead. Nothing else breaks.
The app reads, but never writes, the elastiflix-movies index. Field types that matter to it:
| Field | Type | Used by |
|---|---|---|
id |
keyword |
/movies/{id} lookup (the domain id, not _id) |
title, original_title |
text |
TITLE, BM25 (boosted ^3 / ^2) |
overview, plot |
text |
BM25 |
genres |
keyword |
Genre filter — must be keyword, or the terms filter never matches |
rating |
keyword |
Rating filter |
release_date |
date |
Year filter, YEAR sort |
vote_average |
double |
RATING sort |
plot_elser |
semantic_text (via elser) |
Semantic (ELSER), Hybrid |
plot_e5 |
semantic_text (via e5) |
Semantic (E5) |
Remaining metadata (cast, runtime, budget, revenue, production_companies, …) is displayed on the detail
page but not queried. Unknown fields are ignored, so extra ones are harmless.
| Param | Type | Default | Notes |
|---|---|---|---|
q |
string | — | Required, non-blank; a blank value returns 400 |
mode |
enum | TITLE |
TITLE, BM25, ELSER, E5, HYBRID, ELSER_JINA; unknown values fall back to TITLE |
page |
int | 1 |
Clamped so from + size stays within the reachable window — 10 000 documents, or elasticsearch.rerank.window-size in ELSER_JINA |
size |
int | app.page-size |
Clamped to 1–100; out-of-range falls back to the configured default |
genres |
list | — | Repeatable or comma-separated; canonicalised to the indexed casing |
year |
int | — | Ignored unless plausible (1870 … current year + 5) |
rating |
string | — | G, PG, PG-13, R, NC-17 |
sort |
enum | relevance | RATING or YEAR |
curl -s "localhost:8080/api/search?q=batman&mode=HYBRID&genres=action&size=5" | jq{
"movies": [ { "id": "155", "title": "The Dark Knight", "vote_average": 8.5 } ],
"totalHits": 2,
"currentPage": 1,
"pageSize": 5,
"totalPages": 1,
"query": "batman",
"mode": "HYBRID",
"effectiveMode": "HYBRID",
"windowLimited": false
}modeis what you asked for;effectiveModeis what actually ran. They differ when Hybrid degrades to BM25 because a sort was requested.windowLimitedistruewhen more documents matched than the result window can page through, sototalPagesstops short oftotalHits / pageSize.
Returns the full movie document, or 404. Errors on both endpoints are RFC 7807 ProblemDetail JSON carrying a
stable errorCode — never an HTML error page.
errorCode |
Meaning |
|---|---|
SEARCH_UNAVAILABLE |
The cluster is unreachable, or returned an error with no more specific cause |
INFERENCE_ENDPOINT_MISSING |
The mode needs an inference endpoint that is not deployed in the cluster |
RERANK_UNAVAILABLE |
The rerank endpoint exists but the provider refused the request — rejected key, exhausted quota or rate limit |
./mvnw test # 273 unit tests + JaCoCo coverage gate
./mvnw verify # also runs MovieRepositoryIT against a real Elasticsearch (needs Docker)
# Fail instead of skipping when Docker is missing (use in CI)
./mvnw verify -Delastiflix.it.requireDocker=trueBoth run in CI on every push and pull request (.github/workflows/build.yml), together with a gitleaks
scan over the full history.
The suite is self-contained: src/test/resources/application.properties supplies dummy cluster settings, so
mvn test needs neither ELASTIC_* variables nor a running cluster.
- Unit tests mock the Elasticsearch client and assert the shape of every request the repository builds —
field boosts, filter clauses, sort, pagination offsets and the RRF retriever's
rank_window_size. MovieRepositoryIT(16 tests) starts Elasticsearch 9.5 in a container and runs TITLE, BM25, all three filters, both sorts, pagination andfindByIdagainst it, proving a real cluster accepts those queries. It skips itself when Docker is unavailable — and names the reason, since a silently skipped integration test looks exactly like a passing one. Pass-Delastiflix.it.requireDocker=trueto make that a failure instead. Semantic and Hybrid modes are out of scope there, since they need deployed ML endpoints.- Coverage is enforced by JaCoCo at 90% instruction / 85% branch (currently 98.6% / 92.4%), bound to the
testphase so a plainmvn testfails on a regression instead of deferring it toverify.lombok.configmarks generated accessors so they neither count toward nor dilute the figure. OnlyElastiflixApplicationis excluded. Report:target/site/jacoco/index.html.
Because the stylesheet and the single behaviour script are both served from /static, the policy needs no
'unsafe-inline' and no third-party origin: script-src 'self'; style-src 'self'. Page behaviour that used to
live in inline on* attributes is wired from data-* attributes in static/js/elastiflix.js.
The app applies a baseline Content-Security-Policy plus X-Content-Type-Options, Referrer-Policy,
X-Frame-Options and Permissions-Policy to every response, adds Strict-Transport-Security when the request
arrives over HTTPS (never on plain HTTP, which would pin a developer's localhost to https:// for a year),
restricts images to HTTPS, and strips any movie homepage that is not http(s) so a javascript: URL in the
index cannot become a clickable link.
/actuator/health runs with show-details: when-authorized, so an anonymous caller sees only UP/DOWN;
the dev profile opens it up for local debugging. The health payload never reports the cluster host.
It still has no authentication, authorization or rate limiting. Every endpoint is world-readable to anyone who can reach the port. This is a demo — put it behind authentication and add rate limiting before exposing it anywhere untrusted.
- Styling is a hand-written subset of Tailwind, not Tailwind itself.
src/main/resources/static/css/elastiflix.cssdefines only the ~205 utility classes the templates actually use, following Tailwind v3 names and scales. This removed thecdn.tailwindcss.comdevelopment build — which compiled classes on every page load, could not be pinned with Subresource Integrity, and left the page unstyled offline — without adding a Node toolchain to a pure-Maven build. The trade-off: a Tailwind class that is not in that file silently does nothing.TemplateAssetsTestfails the build if a template uses an undefined class, so the failure is loud rather than visual. Add new classes to the stylesheet as you use them. - Deep paging stops at 10 000 documents (
index.max_result_window). The UI says so;search_afterwould be the fix if deeper paging were ever needed. ELSER_JINAstops far sooner — atelasticsearch.rerank.window-size(50 by default). The reranker only scores that many candidates, so nothing beyond them can be returned at any page. The window is deliberately not widened for deep pages: the model is listwise, so growing the window per request would change the candidate set — and therefore the ranking — between one page and the next. The service clamps the page instead and the UI says so.- Hybrid and reranked modes cannot sort. RRF fuses ranks and a reranker rescores them, so an attribute sort
is meaningless — the request runs as BM25 and both the UI and the API report it via
effectiveMode.
To build a Gen AI agent on top of this project, use the following to define its behaviour and tool usage.
You are the Elastiflix Movie Assistant, an expert in films and a helpful guide for users exploring the Elastiflix database. Your goal is to help users find movies matching their interests, moods or specific queries using the project's search capabilities.
-
Search movies (
GET /api/search)- Params:
q,mode(TITLE,BM25,ELSER,E5,HYBRID,ELSER_JINA),genres,year,rating,sort,page,size. - Usage:
mode=HYBRIDfor natural-language questions,mode=TITLEfor a specific movie name,mode=ELSER_JINAwhen precision matters more than latency — but do not page pastelasticsearch.rerank.window-sizeresults in that mode, because nothing beyond it was ever scored. - Check
effectiveModein the response: if it differs from the mode you requested, the search degraded (you asked for Hybrid and a sort) and you should dropsortto get true hybrid ranking. - Pass genres in any casing — they are canonicalised server-side.
- Params:
-
Get movie details (
GET /api/movies/{id})- Retrieve full metadata (plot, cast, budget) for one movie.
- Context awareness: prefer
HYBRIDfor recommendations — best semantic results. - Explaining results: use
taglineandoverviewto explain why a movie matches. - Handle degradation: a
503witherrorCode: INFERENCE_ENDPOINT_MISSINGmeans the cluster has no ELSER/E5/rerank endpoint deployed. Retry withmode=BM25rather than reporting a failure — or withmode=ELSERif the mode you tried wasELSER_JINA, which keeps the semantic recall.RERANK_UNAVAILABLEmeans the reranker's provider refused the request; retry withmode=ELSER. - Search mode cheat sheet:
TITLE— exact/partial title matchBM25— keyword searchELSER/E5— semantic/vector searchHYBRID— best of both worlds; the default choice for recommendationsELSER_JINA— ELSER candidates rescored by a cross-encoder: the most precise, the slowest, and limited to the firstrank_window_sizeresults
MIT — see LICENSE.