DEV Community: Ricardo Mello

How to Build Image Similarity Search With Atlas Functions and Triggers

Ricardo Mello — Mon, 19 Jan 2026 14:41:44 +0000

Have you ever imagined taking a photo of yourself, comparing it against a database full of celebrities, and instantly finding out who you look most alike?

Or maybe uploading any image, an object, a place, a product, and getting back the items in your database that look the most similar?

This is the idea behind image similarity search, and it’s becoming increasingly common in modern applications. The best part: You don’t need a complex architecture to build it. MongoDB Atlas already gives you everything you need.

In this article, we’ll walk through this solution in two simple stages:

Automatic embeddings generation
- You insert a document containing an image URL.
- An Atlas Trigger automatically detects the insert event.
- An Atlas Function calls Voyage AI’s multimodal model to generate the image embedding and store it back into the document.

Searching for similar images using vector search: Once your documents have embeddings, the similarity search workflow happens in three simple steps:
- Create the vector search index.
- Generate another embedding for the query image.
- Run the vector search query.

By the end, you’ll have a database that can understand images—and return the ones that look the most similar to any photo you send.

Prerequisites

To follow this tutorial, you only need:

A MongoDB Atlas account.
A Voyage AI API token.

Document model

To keep the example simple and realistic, we’ll work with a collection of articles. Each article contains basic metadata, a title, tags, authors, and a URL, along with a cover image.

{
 "title": "Getting Started With Hibernate ORM and MongoDB",
 "tags": ["Java", "ORM"],
 "publishedAt": "11-04-2025",
 "authors": ["Ricardo Mello"],
 "url": "https://foojay.io/today/getting-started-with-hibernate-orm-and-mongodb/",
 "views": 1065,
 "cover": "https://www.freelancinggig.com/blog/wp-content/uploads/2018/03/Hibernate-ORM.jpg"
}

This cover image is what we’ll use later to perform image similarity search, allowing us to find articles whose images look similar to a query image.

Once this document is inserted, we’ll set up an Atlas Trigger so that every new article automatically gets an image embedding.

Atlas Trigger

Atlas Triggers let you automatically run server-side logic whenever a change occurs in your MongoDB Atlas data. They listen to real-time insert, update, replace, and delete events through MongoDB change streams and react instantly by executing custom logic that you define.

Because Triggers run on a fully managed, serverless compute layer, they’re ideal for event-driven workflows such as enriching documents, synchronizing data, or calling external APIs.

In our case, we use a Trigger that fires on every insert and invokes an Atlas Function to generate the image embedding. In MongoDB Atlas, open your project and go to:

Project → Streaming Data → Triggers

Configure it as follows:

Trigger Type: Database
Watch Against: Collection
Cluster / Database / Collection: select your target collection
Operation Type: Insert
Full Document: Enable

Click Save to create the Trigger.

Atlas Functions

Atlas Functions let you run custom JavaScript in a fully managed, serverless environment. You don’t need to deploy or maintain any servers, you just write the code, and MongoDB Atlas takes care of executing it whenever it’s called.

They’re ideal for lightweight tasks like transforming documents, validating data, moving information between collections, or calling external APIs. For example, you might send an email notification, update related records, or, in our case, call Voyage AI to generate an image embedding.

Adding the function to the Trigger

After creating the Trigger, the next step is to attach the Function that will run whenever the event occurs.

Inside the Trigger configuration screen:

Scroll down to the Event Type section.
Select Function as the action to execute.
Paste the complete Function code provided below into the editor.
- Remember to change the serviceName if necessary.
Save the Trigger to apply the Function.

From this point on, every time a new document is inserted into the target collection, MongoDB Atlas will automatically call your Function and run the code you defined.

Function code:

exports = async function(changeEvent) {
 const fullDoc = changeEvent.fullDocument;

 const serviceName = "Cluster0";
 const db = context.services.get(serviceName).db(changeEvent.ns.db);
 const collection = db.collection(changeEvent.ns.coll);

 async function setError(message) {
   console.error("[Embedding ERROR]", message);

   const id = fullDoc && fullDoc._id ? fullDoc._id : changeEvent.documentKey._id;

   try {
     await collection.updateOne(
       { _id: id },
       { $set: { embeddingError: message } }
     );
   } catch (e) {
     console.error("Failed to persist embeddingError:", e.message);
   }
 }

 if (!fullDoc || !fullDoc.cover) {
   await setError("No image URL found in 'cover' field");
   return;
 }

 const imageUrl = fullDoc.cover;

 const requestBody = {
   model: "voyage-multimodal-3",
   inputs: [
     {
       content: [
         {
           type: "image_url",
           image_url: imageUrl
         }
       ]
     }
   ]
 };

 try {
   const key = context.values.get("Value-0");

   const response = await context.http.post({
     url: "https://api.voyageai.com/v1/multimodalembeddings",
     headers: {
       "Content-Type": ["application/json"],
       "Authorization": [`Bearer ${key}`]
     },
     body: JSON.stringify(requestBody)
   });

   const status = response.statusCode;
   const rawBody = response.body.text();

   console.log("Voyage STATUS:", status);

   if (status !== 200) {
     await setError(`Voyage returned status ${status}: ${rawBody}`);
     return;
   }

   let result;
   try {
     result = JSON.parse(rawBody);
   } catch (e) {
     await setError(`JSON.parse failed: ${e.message}`);
     return;
   }

   console.log("Voyage PARSED:", JSON.stringify(result));

   if (!result.data || !Array.isArray(result.data)) {
     await setError("Voyage response has no data[] field");
     return;
   }

   if (!result.data[0] || !result.data[0].embedding) {
     await setError("Voyage response has no data[0].embedding");
     return;
   }

   const embedding = result.data[0].embedding;

   try {
     await collection.updateOne(
       { _id: fullDoc._id },
       {
         $set: { embedding: embedding },
         $unset: { embeddingError: "" }
       }
     );

     console.log("Embedding saved successfully!");
   } catch (e) {
     await setError(`Failed to update document with embedding: ${e.message}`);
   }

 } catch (err) {
   await setError(`Unexpected error calling Voyage: ${err.message}`);
 }
};

What this Function does

Runs automatically whenever a new document is inserted
Reads the document’s cover field to get the image URL
Sends the image to Voyage AI’s multimodal model, which generates an embedding from the image
Saves the resulting embedding back into the same document
If something goes wrong, writes the error into an embeddingError field for easy debugging
Uses a Voyage AI API key (we’ll configure this key next using an Atlas Value)

Configuring the Voyage AI API Key

Before the Function can call Voyage AI to generate embeddings, we need to store the API key securely inside MongoDB Atlas. We do this using Secrets and Values in App Services.

Follow these steps:

Open App Services
1. In MongoDB Atlas, go to Project → Triggers → Linked App Services.
Go to Values & Secrets
1. In the App Services sidebar, open Values.
Create a Secret
1. Click Create Secret
2. Name it: VOYAGE_API_KEY
3. Paste your VoyageAI API key
4. Save
Create a Value
1. Click Create Value
2. Name it: Value-0
3. Choose Value Type: Secret
4. Click Link to Secret
5. Select VOYAGE_API_KEY

Once this is done, your Function can safely access the key using:

const key = context.values.get("Value-0");

This keeps your API key protected and out of the application code.

Creating the vector search index

Now that each document contains an embedding, we need to create a vector search index so MongoDB can efficiently compare those vectors.

To create the index:

In the Project Overview page of MongoDB Atlas, open Search & Vector Search.
Click Create Search Index.
Choose Vector Search as the index type.
Select your cluster, then choose the database and the articles collection.
Replace the index definition with the following configuration:

{
 "fields": [
   {
     "numDimensions": 1024,
     "path": "embedding",
     "similarity": "dotProduct",
     "type": "vector"
   }
 ]
}

Click Next, then Create Index.

Once this index is created, your collection is ready to perform fast and accurate image similarity queries using $vectorSearch.

Testing everything end-to-end

With the Trigger, Function, and vector search index in place, everything is ready. Let’s confirm that the pipeline works as expected by inserting a new document into the articles collection.

1. Insert a new article

Run the following insert in your Atlas Cluster:

db.articles.insertOne({
    "title": "Clean and Modular Java: A Hexagonal Architecture Approach",
    "tags": [
       "Java", "Architecture"
    ],
    "publishedAt": "10-23-2025",
    "authors": [
       "Ricardo Mello"
    ],
    "url": "https://foojay.io/today/clean-and-modular-java-a-hexagonal-architecture-approach/",
    "views": 17864,
    "cover": "https://m.media-amazon.com/images/I/71stxGw9JgL._SL1500_.jpg"
})

The moment this document is inserted, your database Trigger fires and executes the Function you configured.

The Function reads the cover URL.
It sends it to Voyage AI’s multimodal model.
It writes the resulting embedding back into the document.
If something goes wrong, you’ll instead see an embeddingError field showing exactly what failed. Useful for debugging.

After a few seconds, check the document again and you should see:

"embedding": [0.018554688,… ]

Now, we’re ready to run similarity search.

2. Generate an embedding for the query image

To search for similar images, you first need an embedding for the query image, the one the user wants to compare against your dataset. In a real application, this embedding is usually generated by the application itself. For this example, we’ll generate it manually using a simple curl command:

curl --location 'https://api.voyageai.com/v1/multimodalembeddings' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_VOYAGE_API_KEY>' \
--data '{
   "inputs": [
     {
       "content": [


         {
           "type": "image_url",
           "image_url": "https://blog.cleancoder.com/uncle-bob/images/2012-08-13-the-clean-architecture/CleanArchitecture.jpg"
         }
       ]
     }
   ],
   "model": "voyage-multimodal-3"
 }'

This returns an embedding vector. Copy that array and use it in queryVector to find the most similar articles based on the query embedding:

[
 {
   $vectorSearch:
     {     
       path: "embedding",
       numCandidates: 150,
       index: "vector_index",
       limit: 10,
       queryVector: [
         -0.003646851
         ...   
       ],
     }
 }
]

MongoDB will compute similarity using the vector index and return the closest matches in the articles collection, effectively giving you image similarity search inside your database.

Conclusion

At the end of the day, the most important takeaway is the core idea behind this entire workflow: image similarity search. Whether you build it with Java, Node.js, Python, or any other language, the concept remains the same: Generate embeddings, store them, and compare vectors to find what looks alike.

In this walkthrough, we intentionally used native Atlas features like Triggers, Functions, and Vector Search to show that you don’t always need a full backend to experiment with AI-driven

For more information about MongoDB and everything it can do, check out the official documentation.

Modeling Relationships With Hibernate ORM and MongoDB

Ricardo Mello — Tue, 04 Nov 2025 17:23:57 +0000

In the previous article—Getting Started With Hibernate ORM and MongoDB—we learned how to configure Hibernate to work with MongoDB, create an entity, and perform basic CRUD operations using the familiar Hibernate API.

If you haven’t read that first part yet, I recommend starting there before continuing. It covers the project setup, dependencies, and the fundamentals that we’ll build upon here.

In this second part, we’ll extend our application to model relationships between entities—introducing a Review entity and linking it to our existing Book class. This will allow us to explore more advanced capabilities of the MongoDB Hibernate integration, including:

Representing one-to-many relationships.
Storing embedded data structures.
Executing more complex queries.

By the end of this tutorial, you’ll see how Hibernate and MongoDB can work together to model richer, interconnected data, all while using the same familiar annotations and APIs from the ORM world.

Prerequisites

Before continuing, make sure you have the project from the first article up and running.
That project includes the initial configuration, the Book entity, and all CRUD operations we’ll build upon here.

If you don’t have it yet, you can clone the repository from GitHub and check out the v1.0 tag, which represents the state of the project at the end of the first article:

git clone https://github.com/mongodb-developer/mongodb-hibernate-crud.git
cd mongodb-hibernate-crud/
git checkout v1.0

Make sure your environment still meets the same requirements: Java 17+, Maven, and MongoDB 6.0+ (replica set enabled).

One-to-many relationship

In the current version of our project, we have a single entity—Book—that represents the documents stored in the MongoDB books collection. Each book contains basic information like title and number of pages:

{
  "_id": ObjectId('68f2af48650f2f612e319c61'),
  "pages": 405,
  "title": "Mastering MongoDB"
}

Now, we’ll extend this model to make it more realistic. A book can have multiple reviews, and each review belongs to a specific book, forming a classic one-to-many relationship.

Approach 1: Embedding reviews inside books

This section corresponds to Git tag v2.0.

The first approach we’ll explore is to embed the reviews directly inside the Book document.
This means each book will contain an array of reviews within the same collection, a common and simple concept in MongoDB when the relationship between entities is tightly coupled.

To represent this, we’ll define a new class called Review, annotated with @Embeddable and @Struct, inside the domain package:

package com.mongodb.domain;

import jakarta.persistence.Embeddable;
import org.hibernate.annotations.Struct;

@Embeddable
@Struct(name = "Review")
public class Review {
   private String author;
   private String title;
   private String comment;
   private double rating;
   //getters and setters
}

This tells Hibernate that the class does not represent a separate collection but rather an embedded structure inside another entity.

In the Book class, we can now add a list of reviews:

@Entity
@Table(name = "books")
public class Book {
  // other fields

   List<Review> reviews;

   public void addReview(Review review) {
      if (this.reviews == null) {
         this.reviews = new ArrayList<>();
      }

      this.reviews.add(review);
   }
 // getters and setters
}

To add a review to a book, we can use a simple method that loads the Book by ID, appends the review to the list, and merges the updated document back into MongoDB. In the BookService:

public boolean addReview(ObjectId bookId, Review review) {
   try (Session session = HibernateUtil.getSessionFactory().openSession()) {
      Transaction tx = session.beginTransaction();
      Book book = session.find(Book.class, bookId);
      if (book == null) return false;
      book.addReview(review);
      session.merge(book);
      tx.commit();
      return true;
   }
}

Finally, in the MyApplication class, add a new menu option for inserting reviews:

do {
   System.out.println("\n=== BOOK MENU ===");
   // Other options
   System.out.println("6 - Add Review");
   option = sc.nextInt();
   sc.nextLine();
   switch (option) {

   //other options
case 6 -> {
   System.out.print("Book ID: ");
   String id = sc.nextLine();
   System.out.print("Author: ");
   String author = sc.nextLine();
   System.out.print("Title: ");
   String title = sc.nextLine();
   System.out.print("Comment: ");
   String comment = sc.nextLine();
   System.out.print("Rating: ");
   double rating = sc.nextDouble();
   sc.nextLine();

   Review review = new Review(author, title, comment, rating);
   boolean ok = bookService.addReview(new ObjectId(id), review);
   System.out.println(ok ? "Review added successfully!" : "Book not found.");
}
}

When this code runs, Hibernate updates the document directly in the books collection. A Book document now looks like this:

{
  "_id": ObjectId('68f2af48650f2f612e319c61'),
  "pages": 405,
  "title": "Mastering MongoDB",
  "reviews": [
   {
     "author": "Ricardo",
     "comment": "This is my favorite book",
     "rating": 10,
     "title": "I love this book"
   },
   {
     "author": "Maria",
     "comment": "This book seems interesting",
     "rating": 8.2,
     "title": "Just started .."
   }
 ]
}

Evaluating the embedded model

This embedded approach offers some clear advantages.

Each Book document always contains its reviews, meaning that fetching a single book also retrieves all its related data—no extra queries or joins needed.
It also keeps the relationship consistent: If a book is deleted, all of its reviews are removed along with it, since they live inside the same document.

However, this strategy has an important limitation: If a book becomes extremely popular—a real best-seller—the number of reviews may grow significantly, causing the document to become very large. In MongoDB, this can lead to a massive array known as an unbounded array, where an ever-growing array field negatively impacts performance and eventually hits the document size limit (16 MB).

To address that, the next step is to move the reviews to their own collection, allowing them to scale independently while still keeping a logical relationship to their book.

Approach 2: Moving reviews to a separate collection

This section corresponds to Git tag v3.0.

As we saw earlier, embedding reviews directly inside the Book document works well for small datasets, but it's not good when a book has thousands of reviews.

To make the data model more flexible and avoid the unbounded array, we’ll now move the reviews into their own collection and store only a reference to the corresponding book.

Updating the data model

We’ll start by simplifying the Book entity, removing the list of embedded reviews and keeping only the core fields:

@Entity
@Table(name = "books")
public class Book {
   @Id
   @ObjectIdGenerator
   @GeneratedValue
   ObjectId id;
   String title;
   Integer pages;
 // getters and setters
}

Next, we’ll turn Review into a full entity mapped to its own collection:

import com.mongodb.hibernate.annotations.ObjectIdGenerator;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import org.bson.types.ObjectId;

@Entity
@Table(name = "reviews")
public class Review {

  @Id
  @ObjectIdGenerator
  @GeneratedValue
  ObjectId id;
  private ObjectId bookId;
  private String author;
  private String title;
  private String comment;
  private double rating;

  public Review() {}
  public Review(String author, ObjectId bookId, String title, String   comment, double rating) {
    this.author = author;
    this.bookId = bookId;
    this.title = title;
    this.comment = comment;
    this.rating = rating;
  }

  @Override
  public String toString() {
    return "Review{author='%s', title='%s', comment='%s', rating=%.1f}"
          .formatted(author, title, comment, rating);
  }

}

By annotating the class with @Entity and @Table("reviews"), Hibernate now treats it as a top-level document collection instead of an embedded structure. Each review references its book using the bookId field, similar to a foreign key, but in MongoDB terms, it’s just an ObjectId stored inside the document.

Updating the configuration

Since we now have two entities, we must register both in our Hibernate configuration. Open the HibernateUtil class and include the Review.class:

package com.mongodb.config;

import com.mongodb.domain.Book;
import com.mongodb.domain.Review;
import org.hibernate.SessionFactory;
import org.hibernate.cfg.Configuration;

public final class HibernateUtil {
   private static final SessionFactory SESSION_FACTORY =
         new Configuration().configure("hibernate.cfg.xml")
               .addAnnotatedClass(Book.class)
               .addAnnotatedClass(Review.class)
               .buildSessionFactory();

   private HibernateUtil() {}

   public static SessionFactory getSessionFactory() { return SESSION_FACTORY; }
}

Adding a review service

To handle review operations, we’ll add a new service class:

package com.mongodb.service;

import com.mongodb.config.HibernateUtil;
import com.mongodb.domain.Review;
import org.hibernate.Session;
import org.hibernate.Transaction;

public class ReviewService {

   public void insert(Review review) {
      try (Session session = HibernateUtil.getSessionFactory().openSession()) {
         Transaction tx = session.beginTransaction();
         session.persist(review);
         tx.commit();
         System.out.println("Review inserted: " + review);
      }
   }
}

Linking books and reviews

Now that reviews live in their own collection, the Book entity no longer manages them directly.
That means we can remove the old addReview() method from the Book class; reviews are no longer embedded inside the document, so Hibernate doesn’t update them as part of the book entity anymore.

Instead, we’ll add a helper method in the BookService to retrieve a single book along with all its associated reviews. This method loads the book document from the books collection and then queries the reviews collection to find matching entries by bookId.

Note: The @OneToMany annotation is not yet supported in the Public Preview of the MongoDB Hibernate ORM extension. For now, relationships between entities can be handled programmatically as shown below, and native support for annotations such as @OneToMany is planned for the GA release.

public BookWithReviews findAllBooksWithReviewsById(ObjectId id) {
   try (Session session = HibernateUtil.getSessionFactory().openSession()) {

      Book book = session.find(Book.class, id);
      if (book == null) {
         return null;
      }

      List<Review> reviews = session.createQuery(
                  "from Review r where r.bookId = :bookId", Review.class)
            .setParameter("bookId", book.getId())
            .list();

      return new BookWithReviews(book, reviews);
   }
}
public record BookWithReviews(Book book, List<Review> reviews) {}

Updating the console menu

Since the reviews are now stored in their own collection, the old addReview() method in BookService no longer exists. If you try to run the previous version of the menu, the option for adding a review will fail because that method was part of the embedded model.

To fix this, we’ll replace that option with a new implementation that uses the ReviewService instead, inserting reviews directly into the reviews collection, and also add a new option to list all reviews for a specific book.

Here’s how the updated section of your MyApplication class should look:

// other fields

ReviewService reviewService = new ReviewService();

int option;

do {
   System.out.println("\n=== BOOK MENU ===");
   //other options
   System.out.println("7 - List Books and Reviews by Id");

   option = sc.nextInt();
   sc.nextLine();

   switch (option) {

case 6 -> {
   System.out.print("Book ID: ");
   String bookId = sc.nextLine();
   System.out.print("Author: ");
   String author = sc.nextLine();
   System.out.print("Review Title: ");
   String rTitle = sc.nextLine();
   System.out.print("Comment: ");
   String comment = sc.nextLine();
   System.out.print("Rating: ");
   double rating = sc.nextDouble();
   sc.nextLine();

   reviewService.insert(new Review(author, new ObjectId(bookId), rTitle, comment, rating));
   System.out.println("Review added!");
}

case 7 -> {
   System.out.print("Book ID: ");
   String bookId = sc.nextLine();
   BookService.BookWithReviews br = bookService.findAllBooksWithReviewsById(new ObjectId(bookId));

   System.out.printf("\n%s - %s (%d reviews)\n",
         br.book().getId(), br.book().getTitle(), br.reviews().size());
   br.reviews().forEach(System.out::println);

}

Now, each time you insert a review, it’s stored in a separate reviews collection while keeping a reference to the corresponding bookId. This approach eliminates the growth issue of embedded arrays and allows each collection to scale independently.

Unlike the previous model, the Book document no longer contains a reviews list.
Instead, reviews are now stored as independent documents in their own collection, each linked back to its parent book through the bookId field.

Here’s what the new structure looks like in MongoDB:

books collection:

{
 "_id": ObjectId("68f2be11aa80073def51e555"),
 "pages": 549,
 "title": "Learning Java"
}

reviews collection:

{
 "_id": ObjectId("68f2be3caa80073def51e556"),
 "author": "Ricardo Mello",
 "bookId": ObjectId("68f2be11aa80073def51e555"),
 "comment": "I like how this book ..",
 "rating": 8.5,
 "title": "An excellent book"
}

While this new structure solves the size and scalability issues of the embedded model, it also introduces a trade-off. Since Book and Review are now stored in separate collections, retrieving all reviews for a specific book requires two queries, one to load the book and another to fetch its reviews using the bookId.

In relational databases, this would be handled automatically with a join, but in MongoDB, joins are simulated through aggregation pipelines or multiple lookups at the application level. That’s perfectly fine for moderate workloads, but as your dataset grows, repeated joins or multi-collection queries can impact performance and increase complexity. Because of that, it’s often better to avoid frequent joins and keep the most relevant or recently accessed data close to the parent document.

To address this, we can apply a common modeling technique known as the Subset Pattern—which we’ll explore in the next section.

Approach 3: Bringing back recent reviews (Subset Pattern)

This section corresponds to Git tag v4.0.

The Subset Pattern is useful when a document can potentially grow very large, but only a small portion of its data is frequently accessed. Instead of embedding all related documents (like every review ever written), we can embed only the most relevant subset, for example, the last three or five reviews.

Applying the Subset Pattern

In our case, we can apply the Subset Pattern by keeping only the three most recent reviews embedded inside each Book document.

{
 "_id": ObjectId("68f67da69114e74455c989ce"), 
 "pages": 406,
 "title": "High Performance with MongoDB"
 "recentReview": [
{"author": "Martha", "comment": "A very practical guide that balances theory   with hands-on .." },
{"author": "Ricardo", "comment": "The structure is well organized and the examples" },
{"author": "Pietro",    "comment": "I found this book to be both informative and inspiring.." } ]
}

This way, whenever we load a book, we immediately get its latest feedback, without the need to query another collection or perform a join.

At the same time, we’ll still store all reviews in a separate reviews collection. That means if we ever need to display the complete review history for a book (for example, on a “See all reviews” page), we can simply query that collection directly.

{
 "_id": ObjectId("68f67dd79114e74455c989d1"), 
 "author": "Martha",
 "bookId": ObjectId("68f67da69114e74455c989ce"),
 "comment": "A very practical guide that balances theory with hands-on ..",
 "rating": 8.2,
 "title": "Practical and Insightful"
}

This approach offers a great balance:

Fast access to the most relevant information (the latest reviews).
Scalability for long-term data growth (older reviews stored separately).

In this simplified example, we’re embedding only the author and comment fields inside the book. But in a real-world scenario, we could include additional fields such as rating, date, or short summaries, depending on what’s most useful for quick access.

Implementing the Subset Pattern

To keep our documents lightweight and still show the latest feedback, we’ll embed only the three most recent reviews inside each Book, while continuing to store all reviews in the separate reviews collection. Here’s the step-by-step implementation:

Create the embeddable type for recent reviews

package com.mongodb.domain;

import jakarta.persistence.Embeddable;
import org.hibernate.annotations.Struct;

@Embeddable
@Struct(name = "RecentReview")
public record RecentReview (
      String author,
      String comment)
{}

Add the recentReview field to the `Book` class

@Entity
@Table(name = "books")
public class Book {

   // other fields

   List<RecentReview> recentReview = new ArrayList<>();


   // getters and setters
}

Update the `ReviewService`

After persisting a new review, we’ll run a native MongoDB update to push the latest review into the recentReview array and keep only the last three entries.

package com.mongodb.service;

import com.mongodb.config.HibernateUtil;
import com.mongodb.domain.Book;
import com.mongodb.domain.Review;
import org.bson.types.ObjectId;
import org.hibernate.Session;
import org.hibernate.Transaction;

public class ReviewService {

   public void insert(Review review) {
      try (Session session = HibernateUtil.getSessionFactory().openSession()) {
         Transaction tx = session.beginTransaction();
         session.persist(review);
         addRecentReview(review.getBookId(), review, session);
         System.out.println("Review inserted: " + review);
         tx.commit();
      }
   }

   private void addRecentReview(ObjectId bookId, Review review, Session session) {
         var mql = """
           {
               "update": "books",
               "updates": [{
                   "q": { "_id": { "$oid": "%s" } },
                   "u": {
                       "$push": {
                           "recentReview": {
                               "$each": [{
                                   "author": "%s",
                                   "comment": "%s"
                               }],
                               "$slice": -3
                           }
                       }
                   }
               }]
           }
           """.formatted(
               bookId.toString(),
               escapeJson(review.getAuthor()),
               escapeJson(review.getComment())
         );

         int updated = session.createNativeQuery(mql, Book.class).executeUpdate();
         System.out.println(updated + " document updated.");
      }

      private String escapeJson(String input) {
         if (input == null) return "";
         return input.replace("\\", "\\\\")
               .replace("\"", "\\\"")
               .replace("\n", "\\n")
               .replace("\r", "\\r")
               .replace("\t", "\\t");
      }
   }

Notice that we’re using createNativeQuery() to execute a raw MongoDB command (MQL) directly through Hibernate.

This feature allows you to go beyond standard entity operations and run low-level MongoDB updates, inserts, or aggregates when you need full control.

It’s especially useful for applying specific operators, such as $push, $each, or $slice, that aren’t yet abstracted by Hibernate’s ORM layer.

How it works:

createNativeQuery() sends a raw MongoDB command (MQL) through Hibernate.
$push appends a new element to the array.
$slice: -3 trims the array to keep only the last three elements.

Testing the feature

To test this feature, simply run the application and choose option 6, Add Review from the console menu.

Each time you add a new review:

A document will be created in the reviews collection, containing all review details.
The corresponding Book document will be updated, adding that review to the recentReview list.

After inserting a few reviews for the same book, you should see that only the three most recent entries remain in the recentReview array, confirming that the $slice: -3 operator is working as expected.

Wrapping up

Throughout this series, we explored three different strategies for modeling one-to-many relationships with Hibernate ORM and MongoDB. From embedding data directly inside documents to referencing separate collections and finally applying the Subset Pattern, we saw how flexible MongoDB can be when paired with a familiar ORM framework like Hibernate.

The key takeaway is that working with MongoDB requires a shift in mindset. Instead of thinking in rows and joins, we design around documents—taking advantage of powerful features such as embedded data, flexible schemas, and modeling patterns that align with real-world access needs. Each approach offers its own trade-offs, and choosing the right one depends on how your application reads, writes, and scales its data.

Whenever you need more control, remember that you can always fall back to the MongoDB Java Driver to run native MQL commands directly. It’s a great option for edge cases where ORM abstractions might not yet expose certain MongoDB capabilities.

You can find the complete project—including all three strategies (tags v1.0, v2.0, v3.0, *and v4.0*)—on GitHub.

Getting Started With Hibernate ORM and MongoDB

Ricardo Mello — Tue, 04 Nov 2025 17:21:54 +0000

For years, Hibernate ORM has been one of the most popular frameworks in the Java ecosystem. It was built to simplify data persistence by letting developers work with Java objects instead of SQL statements, a technique known as object-relational mapping (ORM).

Traditionally, Hibernate ORM has been tightly associated with relational databases like PostgreSQL, MySQL, and Oracle. It manages connections, transactions, and entity state behind the scenes, and even provides Hibernate Query Language (HQL) so you can query your data using Java entity names rather than table names.

Now, that same simplicity is available in the document-oriented world. With the MongoDB Extension for Hibernate ORM, developers can use familiar annotations such as @Entity and @Id, and the same Session.persist() and HQL queries they already know, but backed by MongoDB’s flexible schema architecture.

This integration introduces a new MongoDB extension that allows Hibernate to translate entity operations and HQL queries into MongoDB commands, combining the ease of JPA with the scalability of MongoDB.

In this article, we’ll walk through the setup and first steps to get Hibernate ORM running with MongoDB, from configuration to a simple CRUD example.

How MongoDB fits in

While Hibernate ORM was originally designed for relational databases, its abstraction layer makes it a great candidate for integrating with other storage systems. MongoDB fits naturally into this model because it stores data as flexible, JSON-like documents instead of rigid tables.

Using the new MongoDB extension, Hibernate can now map your entities to MongoDB collections and translate familiar operations, such as persist, find, and even HQL queries, into MongoDB commands behind the scenes. For example, consider a simple HQL query like:

from Contact where country = ?1 and age > ?2

When executed, Hibernate replaces the parameters (?1 and ?2) with the actual values provided in your code—for example, CANADA and 18. The MongoDB Dialect then translates the query into an equivalent MongoDB aggregation pipeline such as:

{
 "aggregate": "contact",
 "pipeline": [
   { "$match": { "$and": [
     { "country": { "$eq": "CANADA" } },
     { "age": { "$gt": 18 } }
   ]}},
   { "$project": { "_id": true, "age": true, "country": true, "name": true }}
 ]
}

This translation happens transparently; developers continue using Hibernate’s familiar API while the framework builds the corresponding MongoDB Query Language (MQL) commands under the hood.

As a result, you can keep your Hibernate workflow and entity mappings exactly as before, while benefiting from MongoDB’s scalability, flexibility, and document-oriented design.

Prerequisites

Before we start building the project, make sure your environment has a few essentials ready.

Java 17+ installed and an IDE of your choice
Apache Maven—used in this project to manage dependencies and run the application (you can also use Gradle, if you prefer)
MongoDB 7 or newer (Replica set required)
- The easiest way to get started is by creating a free cluster in your MongoDB Atlas account

With these prerequisites in place, we can move on to setting up the project and adding the required dependencies.

Tag your Atlas cluster

If you’re deploying this application on MongoDB Atlas, you can use Resource Tags to label your clusters or projects for tracking and cost visibility. For instance, I recommend tagging your cluster with values that describe this tutorial:

Key: application
Value: hibernate-crud

Adding tags is a simple but powerful way to organize your MongoDB Atlas resources, especially if you manage multiple clusters, environments, or demos. Tags make it easier to:

Track which clusters belong to a specific application.
Filter and group resources in the Atlas UI.
Gain better visibility in billing and monitoring reports.

To add a tag:

Open your MongoDB Atlas dashboard.
Go to Database → Cluster → Add Tag.
Click Add Tag and use the key/value above.
Save your changes.

This step won’t affect your code, but it’s a best practice to keep your Atlas environment organized. If you’re running MongoDB locally, you can safely skip this step.

Project overview

In this article, we’ll build a simple project that uses Hibernate ORM with MongoDB to manage a single entity—Book.

The goal is to understand how the MongoDB Dialect works behind the scenes and explore the basic persistence operations that every application needs:

Create a new document (insert a new book)
Find all documents in the collection
Update existing data
Delete a document
A slightly more advanced find query using a greater than (>) filter

This first part focuses entirely on the Book entity to keep things simple and hands-on. Later, we’ll extend the same project to include a second entity called Review, introducing a one-to-many relationship between books and reviews, but that’s for another article.

If you’d like to follow along or check the complete code, it’s all available on GitHub:

The project uses tags to separate each stage of development:

Tag v1.0: includes only the content covered in this article (the Book CRUD operations)
Tag v2.0: adds the Review entity and relationship examples discussed later
Tag v3.0: extracts the Review model into its own collection to prevent unbounded array growth inside the Book document; introduces a new approach, where each review stores the bookId it belongs to
Tag v4.0: implements the subset pattern, keeping all reviews in a separate reviews collection while storing only the three most recent reviews inside each Book document under a recentReview field

With that overview out of the way, let’s set up the environment and add the necessary dependencies.

Setting up the project

For this example, I’m using IntelliJ IDEA as my IDE. To create the project, go to File → New → Project, select Java, choose Maven as the build system, and click Create as shown in the image below:

This will generate a simple Maven-based Java project with the standard structure (src/main/java and src/main/resources).

If you prefer, you can create it manually using the command line—the structure and configuration will be exactly the same. We’ll use Maven for dependency management in this example, but the same setup applies if you prefer Gradle.

Now, open your pom.xml and add the following dependencies:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>

   <groupId>com.mongodb</groupId>
   <artifactId>mongodb-hibernate-crud</artifactId>
   <version>1.0-SNAPSHOT</version>

   <properties>
       <maven.compiler.source>21</maven.compiler.source>
       <maven.compiler.target>21</maven.compiler.target>
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
   </properties>

   <dependencies>
       <dependency>
           <groupId>org.mongodb</groupId>
           <artifactId>mongodb-hibernate</artifactId>
           <version>1.0.0.alpha.1</version>
       </dependency>
   </dependencies>

</project>

The mongodb-hibernate dependency provides the MongoDB Dialect, the piece that allows Hibernate to translate HQL queries and persistence operations into MongoDB commands.

Configure Hibernate

Next, create a hibernate.cfg.xml file under src/main/resources to define the connection and mapping settings:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE hibernate-configuration PUBLIC
       "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
       "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
   <session-factory>
       <property name="hibernate.dialect">com.mongodb.hibernate.dialect.MongoDialect</property>
       <property name="hibernate.connection.provider_class">
           com.mongodb.hibernate.jdbc.MongoConnectionProvider
       </property>
       <property name="jakarta.persistence.jdbc.url">
           <REPLACE_WITH_YOUR_CONNECTION_STRING>/mydb?appName=devrel-mongodb-hibernate
       </property>       
       <property name="hibernate.show_sql">true</property>
   </session-factory>
</hibernate-configuration>

Important:

Make sure to replace <REPLACE_WITH_YOUR_CONNECTION_STRING> with your own MongoDB connection string, the one you get from your MongoDB Atlas cluster. It should look something like this:

mongodb+srv://<username>:<password>@cluster0.mongodb.net

The configuration also defines the property com.mongodb.hibernate.dialect.MongoDialect,
which tells Hibernate to use the MongoDB Dialect, the component responsible for translating your entity operations and HQL queries into MongoDB commands (MQL) behind the scenes.

With this configuration in place, Hibernate now knows how to connect to MongoDB and how to interpret your ORM operations using the MongoDB extension.

The Book entity

This class will represent the document we’ll store in MongoDB. Create a new package domain and add a class named Book.java.

package com.mongodb.domain;
import com.mongodb.hibernate.annotations.ObjectIdGenerator;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import org.bson.types.ObjectId;

@Entity
@Table(name = "books")
public class Book {
   @Id
   @ObjectIdGenerator
   @GeneratedValue
   ObjectId id;
   String title;
   Integer pages;
   public Book() {}
   public Book(String title, Integer pages) {
   this.title = title;
    this.pages = pages;
 }

 public Book(ObjectId id, String title, Integer pages) {
    this.id = id;
    this.title = title;
    this.pages = pages;
 }

   // getters and setters
}

Let’s break down what’s happening here:

The class is annotated with @Entity, telling Hibernate to treat it as a persistent object.
The @Table(name = "books") annotation defines the collection name in MongoDB, in this case, books. So, we’re simply telling Hibernate (and therefore MongoDB) that all Book documents should be stored in a collection called books.
The annotation @ObjectIdGenerator is part of the MongoDB Hibernate extension and works together with Hibernate’s identifier generation mechanism. It tells Hibernate to generate a new ObjectId automatically before inserting the document into MongoDB.

Creating the SessionFactory

To interact with the database, Hibernate needs a way to open sessions based on our configuration. For that, we define a small helper class that creates a SessionFactory from the hibernate.cfg.xml file and registers our entity. Create a new package called config and include the new class HibernateUtil.java:

package com.mongodb.config;

import com.mongodb.domain.Book;
import org.hibernate.SessionFactory;
import org.hibernate.cfg.Configuration;

public final class HibernateUtil {
  private static final SessionFactory SESSION_FACTORY =
        new Configuration().configure("hibernate.cfg.xml")
              .addAnnotatedClass(Book.class)
              .buildSessionFactory();

  private HibernateUtil() {}

  public static SessionFactory getSessionFactory() { return SESSION_FACTORY; }
}

Implementing the Book service

With the entity and configuration in place, let’s create a service class that will handle all basic database operations for the Book entity.

This class will contain methods for the standard CRUD operations and one additional query using a comparison filter (>).

Inside the src/main/java/com/mongodb folder, create a new package called service and add a class named BookService.java:

package com.mongodb;

import com.mongodb.config.HibernateUtil;
import com.mongodb.domain.Book;
import org.bson.types.ObjectId;
import org.hibernate.Session;
import org.hibernate.Transaction;

import java.util.List;

public class BookService {

   public Book create(String title, Integer pages) {
      try (Session session = HibernateUtil.getSessionFactory().openSession()) {
         Transaction tx = session.beginTransaction();
         Book book = new Book(title, pages);
         session.persist(book);
         tx.commit();
         return book;
      }
   }

   public List<Book> findAll() {
      try (Session session = HibernateUtil.getSessionFactory().openSession()) {
         return session.createQuery("from Book", Book.class).list();
      }
   }

   public boolean update(Book updatedBook) {
      try (Session session = HibernateUtil.getSessionFactory().openSession()) {
         Transaction tx = session.beginTransaction();

         Book existing = session.find(Book.class, updatedBook.getId());
         if (existing == null) return false;

         existing.setTitle(updatedBook.getTitle());
         existing.setPages(updatedBook.getPages());

         session.merge(existing);
         tx.commit();
         return true;
      }
   }

   public boolean deleteById(ObjectId id) {
      try (Session session = HibernateUtil.getSessionFactory().openSession()) {
         Transaction tx = session.beginTransaction();

         Book book = session.find(Book.class, id);
         if (book == null) {
            return false;
         }

         session.remove(book);
         tx.commit();
         return true;
      }
   }

   public List<Book> findBooksWithPagesGreaterThanOrEqual(int minPages) {
      try (Session session = HibernateUtil.getSessionFactory().openSession()) {
         return session.createQuery(
                     "from Book b where b.pages >= :minPages", Book.class)
               .setParameter("minPages", minPages)
               .list();
      }
   }
}

Managing the SessionFactory

In this example, each method opens its own session using:

 try (Session session = HibernateUtil.getSessionFactory().openSession()) { }

This is the simplest approach for demonstration purposes. It ensures that every operation runs independently and that sessions are properly closed after use. However, in a real-world application, you’d likely manage the SessionFactory more elegantly.

Understanding each method

create

session.persist(book);

This inserts a new document into the books collection. The MongoDB Dialect automatically generates the _id field and translates this into an insertOne command under the hood.

findAll

session.createQuery("from Book", Book.class).list();

This HQL query retrieves all documents from the books collection—equivalent to db.books.find() in MongoDB.

update

session.merge(existing);

Hibernate detects changes to the entity and issues an update operation in MongoDB using the document’s _id as a filter.

deleteById

session.remove(book);

This method locates a document in the books collection by its _id and deletes it.

Hibernate translates the operation into a MongoDB deleteOne command, using the document’s _id as the filter.

findBooksWithPagesGreaterThanOrEqual

from Book b where b.pages >= :minPages

This demonstrates how HQL comparison operators map directly to MongoDB operators.

In this case, >= becomes $gte, generating a pipeline similar to:

{ "$match": { "pages": { "$gte": 300 } } }

Building the main application

To test everything we’ve built so far, let’s create a simple Java class to interact with our BookService and perform the CRUD operations directly from the console.

For simplicity, we’ll use Java’s Scanner class to read user input. Of course, in a real application, you might expose these operations through a REST API or a web interface, but for testing purposes, a simple console-based menu works perfectly.

Create a new class called MyApplication.java in the com.mongodb package:

package com.mongodb;

import com.mongodb.config.HibernateUtil;
import com.mongodb.domain.Book;
import org.bson.types.ObjectId;
import org.hibernate.SessionFactory;

import java.util.List;
import java.util.Scanner;

public class MyApplication {

   public static void main(String[] args) {
      SessionFactory factory = HibernateUtil.getSessionFactory();
      Scanner sc = new Scanner(System.in);
      BookService bookService = new BookService();
      int option;

      do {
         System.out.println("\n=== BOOK MENU ===");
         System.out.println("1 - Add Book");
         System.out.println("2 - List Books");
         System.out.println("3 - Update Book");
         System.out.println("4 - Delete Book");
         System.out.println("5 - Find Books by Minimum Pages");
         System.out.println("0 - Exit");
         System.out.print("Choose: ");
         option = sc.nextInt();
         sc.nextLine();

         switch (option) {
            case 1 -> {
               System.out.print("Title: ");
               String title = sc.nextLine();

               System.out.print("Number of pages: ");
               int pages = sc.nextInt();
               sc.nextLine();

               var book = bookService.create(title, pages);
               System.out.println("Created: " + book);
            }

            case 2 -> {
               List<Book> books = bookService.findAll();
               books.forEach(System.out::println);
            }

            case 3 -> {
               System.out.print("Book ID: ");
               String id = sc.nextLine();

               System.out.print("New Title: ");
               String newTitle = sc.nextLine();

               System.out.print("New Page Count: ");
               int newPages = sc.nextInt();
               sc.nextLine();

               Book updated = new Book(new ObjectId(id), newTitle, newPages);
               boolean ok = bookService.update(updated);
               System.out.println(ok ? "Book updated successfully!" : "Book not found.");
            }

            case 4 -> {
               System.out.print("Book ID to delete: ");
               String id = sc.nextLine();
               boolean deleted = bookService.deleteById(new ObjectId(id));
               System.out.println(deleted ? "Book deleted successfully!" : "Book not found.");
            }
            case 5 -> {
               System.out.print("Enter the minimum number of pages: ");
               String pages = sc.nextLine();
               List<Book> books = bookService.findBooksWithPagesGreaterThanOrEqual(Integer.parseInt(pages));

               books.forEach(System.out::println);
            }

            case 0 -> System.out.println("Bye!");
            default -> System.out.println("Invalid option, try again.");
         }

      } while (option != 0);

      sc.close();
      factory.close();
   }
}

Running the application

Once everything is configured, you can run the project directly from the command line using Maven. In the root of your project (where the pom.xml file is located), execute:

mvn clean package

And then:

mvn compile exec:java -Dexec.mainClass="com.mongodb.MyApplication"

Maven will compile the code, download any missing dependencies, and execute the main() method in your MyApplication class.

Make sure your hibernate.cfg.xml file is inside src/main/resources and that your MongoDB connection string is correct before running the command.

That’s it: Your application should start and display the interactive menu in the terminal.

=== BOOK MENU ===
1 - Add Book
2 - List Books
3 - Update Book
4 - Delete Book
5 - Find Books by Minimum Pages
0 - Exit
Choose:

You can now test each option in the console menu to create, list, update, and delete books—and see Hibernate and MongoDB working together in action.

Current limitations (Public Preview)

The MongoDB Hibernate ORM extension is currently in Public Preview, meaning it’s stable for experimentation but still expanding toward full feature coverage compared to relational databases.

At this stage, some MongoDB-specific capabilities, such as compound indexes and geospatial queries, are not yet supported directly through Hibernate. You can still create these structures manually using the MongoDB Java Driver.

For the most up-to-date list of supported features and upcoming improvements, check the official documentation.

Wrapping up

Hibernate ORM has long been a powerful choice for Java developers who prefer working with objects instead of raw database queries.

And now, with the new MongoDB extension for Hibernate ORM, that same convenience extends to the document world, allowing developers to work with MongoDB’s flexible document model using the same familiar APIs and annotations.

This integration bridges two worlds: the stability and maturity of Hibernate with the scalability and agility of MongoDB.

It’s a great way for teams already invested in Hibernate to start exploring the benefits of document databases without changing how they write persistence code.

The complete project is available on GitHub.

Beyond Keywords: Hybrid Search With Atlas and Vector Search (Part 3)

Ricardo Mello — Wed, 17 Sep 2025 13:00:00 +0000

Bringing together semantic vectors and exact keyword matching with $rankFusion

If you’ve been following along this series, you already know we started by giving our movie search app the ability to understand meaning—not just keywords—using semantic search, as discussed in Part 1: Implementing Semantic Search in Java With Spring Data. Then, we made it even smarter by adding filters and optimizing performance with embedding strategies in Part 2: Optimizing Vector Search With Filters and Caching.

Now, in this final installment, we’re taking our search capability to its ultimate form: combining the precision of full-text search with the semantic understanding of vector search.

Welcome to hybrid search.

One search might not be enough

Think about how people actually search for movies. Sometimes, they only remember fragments—such as, “a ship that sinks at night after hitting an iceberg”—and hope the app can figure it out. Other times, they know exactly what they want—like “Titanic”—and expect to see it right away.

These two very different situations expose a critical gap: No single search technique works perfectly for every type of query.

This is because full-text search and vector search work on fundamentally different principles:

Full-text search works by matching exact keywords or their variants within specific fields, like title or description.
Vector search compares the overall meaning of the query to the meaning of documents using semantic embeddings.

Let's see how this plays out in our examples:

Case 1: When the user types, “a ship that sinks at night after hitting an iceberg”:

Vector search shines here and correctly surfaces Titanic.
Full-text search will likely return null or irrelevant results because it relies on matching specific keywords.

Case 2: When someone searches for “Titanic”:

A vector search, focused on semantic similarity, might return Poseidon (another sinking-ship movie).
A full-text search, however, nails it instantly because it finds the exact title.

Clearly, both methods have their strengths. Full-text is unbeatable for exact matches and well-known titles, while vector search excels when the query is descriptive or fuzzy. The challenge is that if we rely on only one, we risk leaving users frustrated.

Merging the best of both worlds

That’s where hybrid search comes in. By combining the precision of full-text search with the intelligence of semantic search, we can deliver results that understand both what the user wrote and what they meant. MongoDB Atlas makes this possible with the new $rankFusion operator, which merges and re-ranks results from multiple pipelines.

For more details, take a look at the Hybrid Search Explained.

Prerequisites

If you’ve been following from Part 1, you should already have everything set up: a MongoDB Atlas cluster, Java 17+, a Voyage AI API token, and the embedded_movies collection.

For this final part, there’s one more requirement:

MongoDB Atlas 8.1 or higher, since hybrid search relies on the $rankFusion operator introduced in this version.

The vector search

So far, our application uses vector search with pre-filters. That means we can run semantic queries while narrowing the search space by year, genres, and IMDb rating. Under the hood, the query looks something like this:

[
 {
   $vectorSearch: {
     filter: {
       $and: [
         { genres: { $in: ["Action", "Drama"] } },
         { year: { $gte: 1980, $lte: 2003 } },
         { "imdb.rating": { $gte: 9.0 } }
       ]
     },
     index: "vector_index",
     limit: 8,
     numCandidates: 160,
     path: "plot_embedding_voyage_3_large",
     queryVector: [
       -0.027284348, ....
     ]
   }
 }
]

This works well for descriptive searches, because the embeddings capture meaning beyond exact words.

The full-text search

But there’s a catch. In the Titanic example, vector search is perfect when the user types a descriptive query like, “a ship that sinks at night after hitting an iceberg”, since it understands intent. However, if the user knows the exact title and types simply “Titanic”, vector search may return other sinking-ship movies like Poseidon.

On top of that, vector search requires generating embeddings for every query. In this case, that means calling an external API just to embed the word “Titanic”, an unnecessary round trip when we could just match the text directly.

That’s where full-text search comes in. Unlike vector search, it looks for exact keyword matches in fields such as title. If the title is in the database, full-text search will find it right away, faster and without embedding overhead.

Implementing the full-text index

Run this command in your MongoDB shell to create a dynamic search index on the embedded_movies collection:

db.embedded_movies.createSearchIndex(
  "fulltextsearch",
  { mappings: { dynamic: true } }
)

Note on indexing: The dynamic: true parameter is ideal for prototyping as it automatically indexes every field in your documents. For production, consider a custom mapping to optimize performance and cost by indexing only necessary fields. Review the documentation on mapping for guidance.

Executing a basic text query

With the index created, we can now execute a simple query to find "Titanic" by its title:

db.embedded_movies.aggregate([
 {
   $search: {
     index:  "fulltextsearch",
     text: {
       query: "Titanic",
       path: "title"
     }
   }
 },
])

You should see something like this:

{
 "title": "Titanic",
 "year": "1996",
 "plot":  "The story of the 1912 sinking ..",
 "genres": [
     "Action",
     "Drama",
     "History"
  ],
 ...
}

Improving the experience with fuzzy search

A common user experience problem is typos. What if our user wants to find Titanic but types titani (missing the final "c")? Try running the exact-match query yourself and you’ll see it will return no results.

This is where the fuzzy option comes to the rescue. Let's modify our query:

db.embedded_movies.aggregate([ 
 {
   $search: {
     index: "fulltextsearch",
     text: {
       query: "titani",
       path: "title",
       fuzzy: {
         maxEdits: 1
       }
     }
   }
 }
])

In short: With maxEdits: 1, our search for "titani" becomes more flexible. It will now match not only the intended "Titanic" (adding one character, “c”) but also other titles like "Titans" (replacing “i” with “s”) or "Titan" (removing one character, “i”). Possible results would be:

title="Titanic"
title="Titan A.E."
title="Raise the Titanic"
title="Clash of the Titans"

Refining results with score boosting

Not all fields are equally important when searching for movies. If a user types “Titanic”, a match in the title field should clearly outweigh a match in the plot or fullplot. Without boosting, MongoDB Atlas Search would treat all matches the same, which could push less relevant results higher in the ranking.

This is where score boosting becomes essential. Boosting lets us tell the search engine which fields matter more by increasing their influence on the final relevance score.

In our case:

title gets the highest boost: direct matches on titles are prioritized.
plot receives a medium boost: useful when titles don’t match but descriptions do.
fullplot has a lower boost: still relevant, but less critical than the main plot or title.

We can apply this logic using a compound operator, which searches across multiple fields while applying different boost values:

db.embedded_movies.aggregate(
[
 {
   $search: {
     index: "fulltextsearch",
     compound: {
       should: [
         {
           text: {
             query: "titanic",
             path: "title",
             fuzzy: {
               maxEdits: 1
             },
             score: {
               boost: { value: 4.0 }
             }
           }
         },
         {
           text: {
             query: "titanic",
             path: "plot",
             fuzzy: {
               maxEdits: 1
             },
             score: {
               boost: { value: 3.0 }
             }
           }
         },
         {
           text: {
             query: "titanic",
             path: "fullplot",
             fuzzy: {
               maxEdits: 1
             },
             score: {
               boost: { value: 2.0 }
             }
           }
         }
       ]
     }
   }
 }
]
)

With this setup, the search engine understands our priorities: A movie with a matching title like Titanic will always rank higher than another movie where the query only appears in a long description.

Note: You can also project the computed relevance score in your results by adding to your $project stage.

{ "score": { "$meta": "searchScore" } }

This will include the boosted score.

Combining forces with hybrid search

We now have both components in place:

Vector search for semantic understanding
Full-text search for exact with fuzzy and boost

The question is: Why choose one when we can use both? That’s exactly what MongoDB’s $rankFusion operator enables.

The $rankFusion

$rankFusion lets us run multiple search pipelines in the same aggregation, then combine their results into a single ranked output. In our case, we’ll use two pipelines:

A searchPipeline: the full-text search
A vectorPipeline: the semantic search

Here’s the basic structure of a hybrid query using $rankFusion:

[
 {
   $rankFusion: {
     input: {
       pipelines: {
         searchPipeline: [],
         vectorPipeline: []
       }
     },
     combination: {
       weights: {
         searchPipeline: 0.5,
         vectorPipeline: 0.5
       }
     },
     scoreDetails: false
   }
 }
]

Let’s break it down:

The pipelines section defines the individual search strategies you want to combine (full-text and vector, in our case).
The weights section then decides how much influence each pipeline has on the final ranking—a higher number means greater importance, so 0.8 will outweigh 0.5.

How to decide the right weights

Once you set up the aggregate, the big question is: How much weight should each pipeline get?

There’s no universal rule for picking these values—it depends entirely on your application and how users interact with it.

In some cases, giving more weight to full-text search makes sense (when exact titles matter most). In others, boosting the vector pipeline produces better results (when queries are more descriptive).

The key is to** experiment with your own data and queries**, adjusting the weights until you find the balance that delivers the best user experience.

Refactoring the application

The full-text search pipeline

Let’s go back to our application to refactor the MovieService class and apply the new $rankFusion, combining full-text search with vector search. Create the following method:

private BsonDocument buildFullTextSearchPipeline(String query) {
   return Aggregates.search(
         compound().should(
               List.of(
                     text(SearchPath.fieldPath("title"), query)
                           .fuzzy(fuzzySearchOptions().maxEdits(1))
                           .score(boost(4.0F)),
                     text(SearchPath.fieldPath("plot"), query)
                           .fuzzy(fuzzySearchOptions().maxEdits(1))
                           .score(boost(3.0F)),
                     text(SearchPath.fieldPath("fullplot"), query)
                           .fuzzy(fuzzySearchOptions().maxEdits(1))
                           .score(boost(2.0F))
               )
         ),
         SearchOptions.searchOptions().index("fulltextsearch")
   ).toBsonDocument();
}

This method does exactly what we saw previously: It builds the full-text search pipeline. Notice how we’re using compound, should, fuzzy, text, and boost, just like before.

The vector search pipeline

Now, let’s create the method for the vector search pipeline inside MovieService:

private Bson buildVectorSearchPipeline(MovieSearchRequest req) {
   return VectorSearchOperation.search(config.vectorIndexName())
         .path(config.vectorField())
         .vector(embeddingService.embedQuery(req.query()))
         .limit(config.topK())
         .filter(req.toCriteria())
         .numCandidates(config.numCandidates())        .withSearchScore("score").toDocument(Aggregation.DEFAULT_CONTEXT);
}

What we did here was simply move the vector search code out of the searchMovies method and place it into its own dedicated method, making the code cleaner and easier to reuse.

The RankFusion in `searchMovies`

The last step is to put everything together inside the searchMovies method using $rankFusion.

public List<Movie> searchMovies(MovieSearchRequest req) {
  AggregationOperation rankFusion = context -> new Document("$rankFusion",
          new Document("input",
                  new Document("pipelines",
                          new Document("searchPipeline", List.of(buildFullTextSearchPipeline(req.query()), new Document("$limit", config.topK())))
                                  .append("vectorPipeline", List.of(buildVectorSearchPipeline(req)))))
                  .append("combination",
                          new Document("weights",
                                  new Document("searchPipeline", 0.5)
                                          .append("vectorPipeline", 0.5)))
                  .append("scoreDetails", false));
  Aggregation aggregation = Aggregation.newAggregation(rankFusion);
  return mongoTemplate.aggregate(
          aggregation,
          config.vectorCollectionName(),
          Movie.class
  ).getMappedResults();
}

Here, we combine the two pipelines we created before:

The full-text search pipeline
The vector search pipeline

And we tell MongoDB to merge their results with equal weights (0.5 each). This way, the final ranking takes into account both text relevance and vector similarity.

Note: To use Document class, make sure to import it from org.bson.Document;.

Inspecting the generated pipeline

Now, let’s run the application again and check the pipeline that is being generated. First, update your application.yml to enable debug logging for MongoDB:

logging:
 level:
   org.springframework.data:
     mongodb: DEBUG

With logging enabled, the application will print out the exact aggregation pipeline being sent to MongoDB. Next, run the following request:

### POST
POST http://localhost:8080/movies/search
Content-Type: application/json

{
 "query": "a ship that sinks at night after hitting an iceberg",
 "minIMDbRating": 5,
 "yearFrom": 1980,
 "yearTo": 2003,
 "genres": [
   "Drama", "Action"
 ],
 "excludeGenres": false
}

You’ll see both the full-text search pipeline (with fuzzy, should, and boost as we defined earlier) and the vector search pipeline (with filters on genres, year, and IMDb rating).

[
 {
   $rankFusion: {
     input: {
       pipelines: {
         searchPipeline: [
           {
             $search: {
               compound: {
                 should: [
                   {
                     text: {
                       query:
                         "a ship that sinks at night after hitting an iceberg",
                       path: "title",
                       fuzzy: { maxEdits: 1 },
                       score: {
                         boost: { value: 4.0 }
                       }
                     }
                   },
                   {
                     text: {
                       query:
                         "a ship that sinks at night after hitting an iceberg",
                       path: "plot",
                       fuzzy: { maxEdits: 1 },
                       score: {
                         boost: { value: 3.0 }
                       }
                     }
                   },
                   {
                     text: {
                       query:
                         "a ship that sinks at night after hitting an iceberg",
                       path: "fullplot",
                       fuzzy: { maxEdits: 1 },
                       score: {
                         boost: { value: 2.0 }
                       }
                     }
                   }
                 ]
               },
               index: "fulltextsearch"
             }
           },
           { $limit: 8 }
         ],
         vectorPipeline: [
           {
             $vectorSearch: {
               filter: {
                 $and: [
                   {
                     genres: {
                       $in: ["Action", "Drama"]
                     }
                   },
                   {
                     year: {
                       $gte: 1980,
                       $lte: 2003
                     }
                   },
                   {
                     "imdb.rating": { $gte: 5.0 }
                   }
                 ]
               },
               index: "vector_index",
               limit: 8,
               numCandidates: 160,
               path: "plot_embedding_voyage_3_large",
               queryVector: [
                 0.03693888, 0.026406106
                 ...
               ]
             }
           }
         ]
       }
     },
     combination: {
       weights: {
         searchPipeline: 0.5,
         vectorPipeline: 0.5
       }
     },
     scoreDetails: false
   }
 }
]

Imprecise results without proper filtering

So far, we’ve been testing step by step by running the aggregation pipeline directly (via curl). Now, let’s move to the application itself and run the same query through the web interface.

Open your browser at http://localhost:8080, and apply the same filters we used in the previous curl request:

Search term = a ship that sinks at night after hitting an iceberg
*Released year *= 1980–2003
Minimum IMDb rating = 5
Genres = (Drama, Action)

Just like in the screenshot below:

If we look closely at the results, we notice that some movies don’t satisfy the pre-filters—for example, Night at the Museum is being returned even though it’s from 2006, outside the requested year range of 1980–2003.

This happens because the filters were applied only inside the vector search pipeline. The full-text pipeline doesn’t have those restrictions, so when $rankFusion merges the results, movies that score highly in full-text (like Night at the Museum) can still appear, even if they don’t match the vector filters.

Making results accurate again

To make sure filters are applied consistently, we need to add them not only in the vector pipeline, but also in the full-text pipeline.

In practice, this means mirroring the same constraints (genres, year, IMDb rating) inside the compound.filter of the full-text query.

That way, both pipelines enforce the same rules before ranking results. Here’s how the full-text pipeline looks once we align it with the vector filters:

{
 $search: {
   index: 'fulltextsearch',
   compound: {
     filter: [
       {
         in: {
           path: 'genres',
           value: ['Action', 'Drama']
         }
       },
       {
         range: { path: 'year', gte: 1980 }
       },
       {
         range: { path: 'year', lte: 2003 }
       },
       {
         range: { path: 'imdb.rating', gte: 5}
       }
     ],     
should: [ { ... } ]
   }
 }
}

Adjusting the index for filters

If we look closely at the previous pipeline, we notice the use of the “in” operator on the genres field. For this to work correctly, we need to update our MongoDB Atlas Search index. String fields must be indexed as token type for operators like “equals” or “in” to function properly.

Here’s the update to the full-text search index:

{
 "mappings": {
   "dynamic": true,
   "fields": {
     "genres": {
       "normalizer": "lowercase",
       "type": "token"
     }
   }
 }
}

Refactoring the pipeline in code

Now that we’ve seen how the aggregation works in the shell, let’s bring it into our Java code. To make things cleaner, we’ll refactor the logic into small helper methods.

1. Creating the filters

Open the MovieService and include the following code:

private List<SearchOperator> buildFilters(MovieSearchRequest req) {
   var filters = new ArrayList<SearchOperator>();

   if (req.genres() != null && !req.genres().isEmpty()) {
      filters.add(in(SearchPath.fieldPath("genres"), req.genres()));
   }

   if (req.yearFrom() != null) {
      filters.add(numberRange(SearchPath.fieldPath("year")).gte(req.yearFrom()));
   }

   if (req.yearTo() != null) {
      filters.add(numberRange(SearchPath.fieldPath("year")).lte(req.yearTo()));
   }

   if (req.minIMDbRating() != null) {
      filters.add(numberRange(SearchPath.fieldPath("imdb.rating")).gte(req.minIMDbRating()));
   }

   return filters;
}

The buildFilters() method collects all the filtering rules based on the MovieSearchRequest. It optionally adds filters for genres, year range, and IMDb rating, if they’re provided.

2. Including search boost

The buildSearchClauses() method defines the fields where we’ll search for text, the title, plot, and fullplot. Each field gets a different boost value to indicate how much it should influence the score.

private List<SearchOperator> buildSearchClauses(MovieSearchRequest req) {
   Map<String, Float> fieldConfigs = Map.of(
         "title", 4.0F,
         "plot", 3.0F,
         "fullplot", 2.0F
   );

   return fieldConfigs.entrySet().stream()
         .map(entry -> text(SearchPath.fieldPath(entry.getKey()), req.query())
               .fuzzy(fuzzySearchOptions().maxEdits(1))
               .score(boost(entry.getValue())))
         .collect(Collectors.toList());
}

3. The final pipeline

Still in the MovieService, replace the buildFullTextSearchPipeline() with the following code:

private BsonDocument buildFullTextSearchPipeline(MovieSearchRequest req) {
   var filters = buildFilters(req);
   var searchClauses = buildSearchClauses(req);

   var compound = compound();
   compound = !filters.isEmpty() ? compound.filter(filters) : compound;

   return Aggregates.search(
         compound.should(searchClauses),
            SearchOptions.searchOptions().index("fulltextsearch")
   ).toBsonDocument();
}

In short: This method builds a compound query where the filters go into the filter() clause and the text matches go into the should() clause.

At this point, you’ll notice that the searchMovies method will cause a compilation error, because the buildFullTextSearchPipeline method now takes a MovieSearchRequest object. To fix this, just pass it instead of sending only the query:

public List<Movie> searchMovies(MovieSearchRequest req) {
  AggregationOperation rankFusion = context -> new Document("$rankFusion",
          new Document("input",
                  new Document("pipelines",
                          new Document("searchPipeline", List.of(buildFullTextSearchPipeline(req), new Document("$limit", config.topK())))
                                  .append("vectorPipeline", List.of(buildVectorSearchPipeline(req)))))
                  .append("combination",
                          new Document("weights",
                                  new Document("searchPipeline", 0.5)
                                          .append("vectorPipeline", 0.5)))
                  .append("scoreDetails", false));
  Aggregation aggregation = Aggregation.newAggregation(rankFusion);
  return mongoTemplate.aggregate(
          aggregation,
          config.vectorCollectionName(),
          Movie.class
  ).getMappedResults();
}

4. Testing the refactored pipeline

Case 1: Including genres

Let’s run the same query again with our new pipeline.

As you can see in the results, the filters look correct.

Case 2: Excluding genres

Now, suppose the user clicks Exclude selected genres while keeping the same filter.

In this case, instead of asking for movies that include Drama or Action, we want the opposite: Only return movies that do not belong to these genres.

If we run the application right now, you’ll notice that movies with Action/Drama still appear in the results:

This happens because our query doesn’t yet apply any exclusion logic. What we really want to tell MongoDB Atlas Search is:

“Return all documents that satisfy the other filters, but exclude anything with these genres.”

To fix this, we’ll make two small adjustments:

Remove the “in“ clause from the filter section.
Add the “in“ clause inside a mustNot option.

The updated pipeline will look something like this:

{
 $search: {
   index: 'fulltextsearch',
   compound: {
     filter: [
       { range: { path: 'year', gte: 1980 } },
       { range: { path: 'year', lte: 2003 } },
       { range: { path: 'imdb.rating', gte: 5 } }
     ],
     mustNot: [  { in: { path: 'genres', value: ['Action', 'Drama'] }} ],
     should: [ { … }  ]
   }
 }
}

Adding exclusion logic to the application

The final step is to update our application code so that it builds the mustNot clause. First, create the buildMustNot() method:

private List<SearchOperator> buildMustNot(MovieSearchRequest req) {
  var mustNot = new ArrayList<SearchOperator>();

  if (req.genres() != null && !req.genres().isEmpty() && req.excludeGenres()) {
     mustNot.add(in(SearchPath.fieldPath("genres"), req.genres()));
  }

  return mustNot;
}

Next, update the buildFilters() method so it only adds genres when the exclude selected genres option is not selected. Open the method and replace the current block…

if (req.genres() != null && !req.genres().isEmpty()) {
  filters.add(in(SearchPath.fieldPath("genres"), req.genres()));
}

…with this version:

if (req.genres() != null && !req.genres().isEmpty() && !req.excludeGenres()) {
  filters.add(in(SearchPath.fieldPath("genres"), req.genres()));
}

And finally, replace the buildFullTextSearchPipeline() with this:

private BsonDocument buildFullTextSearchPipeline(MovieSearchRequest req) {
  var filters = buildFilters(req);
  var searchClauses = buildSearchClauses(req);
  var mustNot = buildMustNot(req);
  var compound = compound();

  if (!filters.isEmpty()) {
     compound = compound.filter(filters);
  }

  if (!mustNot.isEmpty()) {
     compound = compound.mustNot(mustNot);
  }

  return Aggregates.search(
          compound.should(searchClauses),
          SearchOptions.searchOptions().index("fulltextsearch")
  ).toBsonDocument();
}

Once that adjustment is made, we can restart the app and run the same query again. This time, you’ll see that movies tagged with Drama or Action are no longer returned, ensuring the results respect the exclusion filter.

Prioritizing the vector pipeline

When we first run the hybrid query with equal weights (0.5 for vector and 0.5 for full-text), the results look interesting: Titanic shows up first, followed by A Knight’s Tale.

Why does this happen?

Titanic is ranked highly by the vector search. The embedding of our query, “a ship that sinks at night after hitting an iceberg”, is semantically very close to the plot of Titanic, so the vector similarity score pushes it to the top.
A Knight’s Tale, on the other hand, comes from the full-text search. The query contains the word “night”, and since we enabled fuzzy matching (maxEdits: 1), MongoDB Atlas Search interprets “knight” as close enough to “night”. Because the match happens in the title field (which we boosted with a higher score), the movie gets a strong ranking, even though it’s unrelated to our intended meaning.

Let’s tweak our pipeline to give more weight to semantic similarity: Set the vector pipeline to 0.8 and the full-text pipeline to 0.2:

public List<Movie> searchMovies(MovieSearchRequest req) {
  AggregationOperation rankFusion = context -> new Document("$rankFusion",
          new Document("input",
                  new Document("pipelines",
                          new Document("searchPipeline", List.of(buildFullTextSearchPipeline(req), new Document("$limit", config.topK())))
                                  .append("vectorPipeline", List.of(buildVectorSearchPipeline(req)))))
                  .append("combination",
                          new Document("weights",
                                  new Document("searchPipeline", 0.2)
                                          .append("vectorPipeline", 0.8)))
                  .append("scoreDetails", false));
  Aggregation aggregation = Aggregation.newAggregation(rankFusion);
  return mongoTemplate.aggregate(
          aggregation,
          config.vectorCollectionName(),
          Movie.class
  ).getMappedResults();
}

Then, run the search again with the same inputs:

Now, we can see that the top results make more sense for this descriptive query. Try yourself by changing the weights and boost, and see the results.

Conclusion

We’ve reached the end of the Beyond Keywords series, where we explored how to go beyond traditional search approaches and build smarter applications with MongoDB.

In Part 1:Implementing Semantic Search in Java With Spring Data, we focused on vector search with Spring Data, learning how to generate embeddings with Voyage AI and run semantic queries.
In Part 2: Beyond Keywords: Optimizing Vector Search With Filters and Caching, we enhanced our application with pre-filters for more precise results and explored strategies like caching embeddings to save cost and improve performance.
In this final chapter, we dug into MongoDB Atlas Search, added filters, and combined it with vector search through hybrid search, unlocking the best of both worlds: exact keyword matching and semantic understanding.

It’s important to remember: There’s no universal rule for the “right” weights, boosts, or filters. The best setup is always query-dependent—some queries benefit more from vector similarity, others from exact keyword matching. The real goal is to establish a solid baseline that works well for most use cases, then adapt and fine-tune based on how your users actually search.

This is just the beginning. Real-world applications will always require experimentation, fine-tuning, and iteration to balance precision and recall.

If you want to learn more, join the MongoDB Community to ask questions and share your experience. And if you’d like to check the full source code from this series, you can find it on GitHub.

Beyond Keywords: Optimizing Vector Search With Filters and Caching (Part 2)

Ricardo Mello — Tue, 16 Sep 2025 13:00:00 +0000

Enhancing precision with pre-filters and reducing costs with embedding caching

Welcome back! If you landed here without reading Part 1: Beyond Keywords: Implementing Semantic Search in Java With Spring Data, I recommend going back and checking it first so the steps in this article make more sense in sequence.

This is the second part of a three-part series where we’re building a movie search application. So far, our app supports semantic search using vector queries with Spring Data and Voyage AI. In this article, we’ll take things further:

Add filters to refine our vector search results.
Explore strategies with Spring (such as caching) to reduce the cost of generating embeddings.
Implement a basic frontend using only HTML, CSS, and JavaScript—just enough to test our API in a browser (UI is not the focus here).

The full source code for this part is available on GitHub.

Adding filters: From story to code

Imagine this: You’ve just finished building your shiny new semantic movie search. You type “a science fiction movie about rebels fighting an empire in space” and—boom—Star Wars pops up. Success!

But then your friend says:

Cool, but I only want movies with an IMDb rating of 9 or higher. Can your app do that?

At this point, our application can only take a query string:

public record MovieSearchRequest(String query) {}

So we need to evolve. First, let’s extend the request with a minIMDbRating field to capture this new requirement:

public record MovieSearchRequest(
      String query,
      Double minIMDbRating
) {}

First try: Add a post-filter in `MovieService`

Open the MovieService class, find the searchMovies method, and append a $match stage that enforces the minIMDbRating threshold after the vector search:

public List<Movie> searchMovies(MovieSearchRequest req) {
   VectorSearchOperation vectorSearchOperation = VectorSearchOperation.search(config.vectorIndexName())
         .path(config.vectorField())
         .vector(embeddingService.embedQuery(req.query()))
         .limit(config.topK())
         .numCandidates(config.numCandidates());

   // Post-filter: apply the IMDb constraint after nearest neighbors are found
   MatchOperation matchOperation = new MatchOperation(
         Criteria.where("imdb.rating").gte(req.minIMDbRating())
   );

   return mongoTemplate.aggregate(
         Aggregation.newAggregation(vectorSearchOperation, matchOperation),
         config.vectorCollectionName(),
         Movie.class
   ).getMappedResults();
}

Now try it:

### POST
POST http://localhost:8080/movies/search
Content-Type: application/json

{
 "query": "a science fiction movie about rebels fighting an empire in space",
 "minIMDbRating": 9
}

When you run this query against our dataset, you’ll notice it returns nothing. Why?

Because MongoDB Atlas:

First performs the semantic vector search and finds a few close matches.
Then the $match filter is applied afterwards.

Since none of those candidates have an IMDb rating ≥ 9.0, all results are discarded, meaning you still paid for the vector search, but ended up with no data. It “works,” but it’s wasteful when constraints are strict.

So how can we save this extra work?

By using the filter option on $vectorSearch, a pre-filter that lets MongoDB Atlas narrow results (e.g., by numeric fields like imdb.rating) before running the vector comparison. Let's check it.

Second try: Use a pre-filter

To implement the pre-filter, the first step is to update our MongoDB Atlas Vector Search index and include the field we want to filter by, in this case, imdb.rating:

{
 "fields": [
   {
     "type": "vector",
     "path": "plot_embedding_voyage_3_large",
     "numDimensions": 2048,
     "similarity": "dotProduct"
   },
   {
     "type": "filter",         // include this
     "path": "imdb.rating"     // include this
   }
 ]
}

Once the index finishes updating, we can adjust our code. In the searchMovies method, remove the MatchOperation and apply the filter directly in the VectorSearchOperation:

public List<Movie> searchMovies(MovieSearchRequest req) {
  VectorSearchOperation vectorSearchOperation = VectorSearchOperation.search(config.vectorIndexName())
          .path(config.vectorField())
          .vector(embeddingService.embedQuery(req.query()))
          .limit(config.topK())
          .filter(Criteria.where("imdb.rating").gte(req.minIMDbRating()))//Pre-filter: apply the IMDb rating filter here
          .numCandidates(config.numCandidates());

  return mongoTemplate.aggregate(
          Aggregation.newAggregation(vectorSearchOperation),
          config.vectorCollectionName(),
          Movie.class
  ).getMappedResults();
}

Now, when you run the same request, the filter is applied first, and only then similarity is computed, returning results that already satisfy the IMDb rating constraint.

{
 "title": "The Dark Knight",
 "year": "2008",
 "imdb": {
     "rating": 9.0
   },
 ...
}

To learn more about pre-filters, check out the official documentation.

Refining the search with extra filters

As users refine their searches, they often want more than just a keyword, like finding movies within a time period or skipping certain genres.

We’ll extend MovieSearchRequest to support year ranges and genre inclusion/exclusion:

import java.util.List;

public record MovieSearchRequest(
      String query,
      Integer yearFrom,
      Integer yearTo,
      List<String> genres,
      Double minIMDbRating,
      boolean excludeGenres
) {}

To make the filters actually work, we need a way to translate the request fields into a MongoDB query. For this, our MovieSearchRequest record implements a toCriteria() method. Here is the complete MovieSearchRequest code: \

import org.springframework.data.mongodb.core.query.Criteria;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
import java.util.Optional;

public record MovieSearchRequest(
      String query,
      Integer yearFrom,
      Integer yearTo,
      List<String> genres,
      Double minIMDbRating,
      boolean excludeGenres
) {

   public Criteria toCriteria() {
      final List<Criteria> parts = new ArrayList<>(3);

      List<String> g = cleanedGenres();
      if (!g.isEmpty()) {
         parts.add(excludeGenres
               ? Criteria.where("genres").nin(g)
               : Criteria.where("genres").in(g));
      }

      YearBounds yb = normalizedYearBounds();
      if (yb.from != null || yb.to != null) {
         Criteria y = Criteria.where("year");
         if (yb.from != null) y = y.gte(yb.from);
         if (yb.to   != null) y = y.lte(yb.to);
         parts.add(y);
      }

      if (minIMDbRating != null) {
         parts.add(Criteria.where("imdb.rating").gte(minIMDbRating));
      }

      if (parts.isEmpty()) return new Criteria();
      if (parts.size() == 1) return parts.getFirst();
      return new Criteria().andOperator(parts.toArray(Criteria[]::new));
   }

   public List<String> cleanedGenres() {
      return Optional.ofNullable(genres).orElseGet(List::of).stream()
            .filter(Objects::nonNull)
            .map(String::trim)
            .filter(s -> !s.isEmpty())
            .distinct()
            .toList();
   }

   private YearBounds normalizedYearBounds() {
      Integer f = yearFrom, t = yearTo;
      if (f != null && t != null && f > t) {
         int tmp = f; f = t; t = tmp;
      }
      assert f != null;
      assert t != null;
      return new YearBounds(f, t);
   }

   private record YearBounds(
         Integer from,
         Integer to
   ){}
}

In short: The request validates which filters are present—if any are set, it builds a criteria combining them; if not, it returns an empty criteria, meaning no filters are applied.

Applying `toCriteria()` in the search

Now, instead of hardcoding just the IMDb rating filter, we can reuse our toCriteria() method. This way, any combination of filters (genres, year range, IMDb rating) is automatically applied. In MovieService, replace the searchMovies:

public List<Movie> searchMovies(MovieSearchRequest req) {
   VectorSearchOperation vectorSearchOperation = VectorSearchOperation.search(config.vectorIndexName())
         .path(config.vectorField())
         .vector(embeddingService.embedQuery(req.query()))
         .limit(config.topK())
         .filter(req.toCriteria()) // here is the modification
         .numCandidates(config.numCandidates());

   return mongoTemplate.aggregate(
         Aggregation.newAggregation(vectorSearchOperation),
         config.vectorCollectionName(),
         Movie.class
   ).getMappedResults();
}

After these modifications, the last step is to include the additional filter fields (such as year and genres) in your MongoDB Atlas Vector Search index definition:

{
 "fields": [
   {
     "type": "vector",
     "path": "plot_embedding_voyage_3_large",
     "numDimensions": 2048,
     "similarity": "dotProduct"
   },
   {
     "type": "filter",
     "path": "imdb.rating"
   },
   {
     "type": "filter",
     "path": "year"
   },
   {
     "type": "filter",
     "path": "genres"
   }
 ]
}

Once the index finishes building, these filters will be ready to use in your queries. For example:

### POST
POST http://localhost:8080/movies/search
Content-Type: application/json

{
 "query": "a science fiction movie about rebels fighting an empire in space",
 "minIMDbRating": 9,
 "yearFrom": 2010,
 "yearTo": 2015,
 "genres": [
   "Drama", "Action"
 ],
 "excludeGenres": false
}

You should see a similar result: \

{
 "title": "The Real Miyagi",
 "year": "2015",
 "imdb": {
     "rating": 9.3
   },
 "genres": [
   "Documentary",
   "Action",
   "History"
 ],
 ...
}

Reducing embedding costs with caching

When testing the search endpoint, you might notice that embeddings are generated every single time, even if the query text doesn’t change. For example, if you keep searching for…

{
 "query": "a science fiction movie about rebels fighting an empire in space",
 "minIMDbRating": 9,
 "yearFrom": 2010,
 "yearTo": 2015,
 "genres": [
   "Drama", "Action"
 ],
 "excludeGenres": false
}

…and then repeat the same query but change only the filters (genres, year, minIMDbRating), the log still shows embeddings being generated:

2025-09-04T11:48:47.298-03:00  INFO 27180 --- [nio-8080-exec-1] com.mongodb.EmbeddingService             : Generating embeddings ..
2025-09-04T11:48:48.513-03:00  INFO 27180 --- [nio-8080-exec-1] com.mongodb.EmbeddingService             : Embeddings generated successfully!
2025-09-04T11:48:52.438-03:00  INFO 27180 --- [nio-8080-exec-2] com.mongodb.EmbeddingService             : Generating embeddings ..
2025-09-04T11:48:52.737-03:00  INFO 27180 --- [nio-8080-exec-2] com.mongodb.EmbeddingService             : Embeddings generated successfully!

But here’s the thing: If the query text doesn’t change, there’s no need to regenerate the embeddings. The conversion is deterministic, the same text always produces the same vector.

Strategy with `@Cacheable`

To avoid unnecessary API calls, we can cache embeddings for repeated queries. In Spring, this is as simple as annotating the embedQuery method in EmbeddingService:

@Cacheable("embeddings")
public List<Double> embedQuery(
      String text) {

   logger.info("Generating embeddings .. ");

   var res = client.embed(new EmbeddingsRequest(
         List.of(text), config.model(), "query", config.outputDimension()));

   logger.info("Embeddings generated successfully!");

   return res.data().getFirst().embedding();
}

And finally, don’t forget to enable it in your Spring Boot application class.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cache.annotation.EnableCaching;

@SpringBootApplication
@EnableCaching
public class SpringDataMongodbHybridSearchApplication {

   public static void main(String[] args) {
      SpringApplication.run(SpringDataMongodbHybridSearchApplication
.class, args);
   }

}

After enabling caching, run a few searches in a row with the same query text but different filters (genres, year, minIMDbRating). You’ll notice that the log message appears only the first time.

2025-09-04T11:50:04.283-03:00  INFO 27322 --- [nio-8080-exec-1] com.mongodb.EmbeddingService             : Generating embeddings ..
2025-09-04T11:50:05.086-03:00  INFO 27322 --- [nio-8080-exec-1] com.mongodb.EmbeddingService             : Embeddings generated successfully!

In short: Caching embeddings prevents redundant API calls, saves cost, and improves response time without changing your search logic. For production, there are more advanced ways to manage caching (e.g., distributed caches, eviction policies). Here, we’re just showing a simple idea to illustrate the concept.

A minimal frontend

Before wrapping up, let’s add a very simple frontend. The goal here is not to focus on UI or design, but just to provide a way to test our API in the browser. I’ll leave a small example in HTML, JavaScript, and CSS. Feel free to adapt it and build a nicer page if you’d like.

Step 1: HTML

Download the index.html file from this repository and save it inside src/main/resources/static.

Step 2: JavaScript

Download the script.js file from this repository and place it in the same folder.

Step 3: CSS

Finally, download the styles.css file from this repository and place it in the same folder.

Running the frontend

Step 1: Start the application

mvn spring-boot:run

Step 2: Open the application

With the backend already running, simply open http://localhost:8080 in your browser and search for:

Search term = a ship that sinks at night after hitting an iceberg
*Released year * = 1980–2003
Minimum IMDb rating = 5
Genres = (Drama, Action)

Then, click to view movie details.

Wrapping up

In this second part, we explored how to use pre-filters in MongoDB Atlas Vector Search to make queries more efficient, and we looked at strategies to save resources by avoiding unnecessary embedding generation with caching.

In the third and final Part 3 - Beyond Keywords: Hybrid Search with Atlas And Vector Search, we’ll adapt our code to implement hybrid search, combining MongoDB Atlas Search with vector queries for even more powerful results.

You can check out the full source code for this part on GitHub.

Beyond Keywords: Implementing Semantic Search in Java With Spring Data (Part 1)

Ricardo Mello — Mon, 15 Sep 2025 15:23:57 +0000

Building a semantic movie search app with embeddings and vector queries

Have you ever tried to search for something such as a product, a song, or a movie but couldn’t quite remember its exact name? Maybe you recall only a clue—a desert pyramid, a short melody, or “that ship that hit an iceberg.” Keyword search struggles with that. Vector search doesn’t: It lets you search by meaning.

It works by turning text into embeddings, vectors (arrays of numbers) that capture semantic similarity, so results are ranked by what they mean, not just what they say.

With recent vector query support in Spring Data, Java developers can build semantic search using familiar repositories and queries.

In this article, we’ll build a small movie search app that understands intent beyond keywords. You’ll type queries like “movie with pyramids in Egypt” or “a science fiction movie about rebels fighting an empire in space” and the app will surface relevant titles.

Along the way, we’ll explore how to generate embeddings, perform vector searches, and retrieve the most relevant results.

The magic behind vector search

When searching for a movie in the past, the most common approach was keyword-based. You’d type something like title = "Star Wars", and the system would return the exact match.

But if your query was anything different, maybe a misspelling, a synonym, or simply because you couldn’t remember the title, it became much harder to get the right result. And it got even worse if all you had in mind was a scene or a general idea of the story.

For example, if you searched for “a science fiction movie about rebels fighting an empire in space,”* a keyword engine would struggle. To make that work, you’d have to set up synonym lists, custom rules, and a lot of manual mappings to connect this description back to *Star Wars, a process that would take a lot of effort and resources to maintain.

Vector search takes a very different approach. Instead of looking for literal keywords, it looks for similarity in meaning. The process works like this:

Generate embeddings: Unstructured data such as text, audio, or images is sent to a machine learning model, which converts it into an embedding (a numerical vector), and is stored in the database.
Convert the user query: When a user types a search, the query is also transformed into an embedding by the same model.
Compare vectors: The query embedding is compared against the embeddings stored in the database, and the closest matches are returned.

Together, these three steps form the foundation of vector search.

Note: Want to go deeper? MongoDB offers a free Vector Search Fundamentals course (about 1 hour) where you can also earn a badge. This training covers:

Understand when to use semantic search to capture meaning and context.

Generate and store embeddings for your own data.

Implement vector search in your application to retrieve semantically similar results.

Prerequisites

Before we start building the application, make sure you have the following in place:

A MongoDB Atlas account
- Create a free M0 cluster to get started
Java 21+ installed and an IDE of your choice
A Voyage AI API token
The sample dataset uploaded to your cluster
- The embedded_movies collection, which we’ll query throughout the examples

Tag your Atlas cluster

Key: application
Value: hybrid-search

Adding tags is a simple but powerful way to organize your MongoDB Atlas resources, especially if you manage multiple clusters, environments, or demos. Tags make it easier to:

Track which clusters belong to a specific application.
Filter and group resources in the Atlas UI.
Gain better visibility in billing and monitoring reports.

To add a tag:

Open your MongoDB Atlas dashboard.
Go to Database → Cluster → Add Tag.
Click Add Tag and use the key/value above.
Save your changes.

This step won’t affect your code, but it’s a best practice to keep your Atlas environment organized. If you’re running MongoDB locally, you can safely skip this step.

Embeddings with Voyage AI

Voyage AI is an embedding platform offering high-quality, production-ready models behind a simple API. In this project, we use Voyage AI to generate embeddings in two places:

Generate embeddings: Each movie’s plot was sent to voyage-3-large, and the returned vector was stored in the embedded_movies collection as plot_embedding_voyage_3_large. (This preprocessing is already done.)

Generate embeddings (user query): When the user searches, we encode the query with the same voyage-3-large model and compare that query vector to the stored document vectors. We then return the most similar movies.

The similarity comparison is executed by MongoDB Atlas Vector Search against the stored vectors.

Note: It is recommended to use the same model for both creating and querying embeddings. For example, if the dataset was embedded with Voyage AI, the queries should also be embedded with Voyage AI to ensure the most accurate and meaningful results.

If you’d like to explore more details about the model we use here, you can check the official Voyage AI blog post.

Preparing the dataset

Before creating the index, make sure the embedded_movies collection has been imported into your MongoDB Atlas cluster. In our case, this dataset already comes with a field called plot_embedding_voyage_3_large, which stores the pre-computed embeddings for each movie plot.

With the dataset in place, the next step is to create a vector index so MongoDB Atlas knows which field to use, its dimensionality, and the similarity metric.

MongoDB Atlas Vector Search (index and retrieval)

To compare embeddings at query time, MongoDB Atlas needs a search index that tells it which field stores your vectors, their dimensionality, and which similarity metric to use. Once the collection is in place, create the following index:

db.embedded_movies.createSearchIndex(
  "vector_index",
  "vectorSearch",
  { "fields": [{
    "type": "vector",
    "path": "plot_embedding_voyage_3_large",
    "numDimensions": 2048,
    "similarity": "dotProduct"
  }]}
)

Let's break it down:

"vector_index”: the index name
path: the field that stores document embeddings
numDimensions: must match the model’s embedding size
similarity: metric used for nearest-neighbor ranking (e.g., dotProduct, cosine, euclidean)

Building the movie search app

Now that we’ve seen what vector search is, how embeddings are generated, and created the vector index in MongoDB Atlas, let’s put everything into practice. To get started, open Spring Initializr, create a new project, and select Spring Web and Spring Data MongoDB as dependencies. Download the project and open it in your favorite IDE.

Configuring the application

After opening the project, the first thing is to configure our MongoDB connection and a few settings for the embedding provider and vector search. Open or create your application.yml file:

spring:
 data:
   mongodb:
     uri: ${MONGODB_URI}
     database: sample_mflix
voyage:
 api-key: ${VOYAGE_API_KEY}
 base-url: https://api.voyageai.com/v1
 model: voyage-3-large
 output-dimension: 2048
 vector-index-name: vector_index
 vector-collection-name: embedded_movies
 vector-field: plot_embedding_voyage_3_large
 top-k: 8
 num-candidates: 160

What this does (briefly):

MongoDB: connects Spring Data to your Atlas cluster and the embedded_movies collection
Voyage: sets up the API key, model, and embedding size
Vector Search: tells MongoDB Atlas which index and field to use, plus how many results (top-k) to return

Next, we need to connect our application.yml settings to the code. To do that, we create a @ConfigurationProperties record (VoyageConfigProperties) that maps all voyage.* values into a strongly-typed object we can use later in the application.

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "voyage")
public record VoyageConfigProperties(
    String model,
    int outputDimension,
    String vectorIndexName,
    String vectorCollectionName,
    String vectorField,
    int topK,
    int numCandidates,
    String baseUrl,
    String apiKey) {}

The document model

Our embedded_movies collection contains several fields that describe each movie, such as title, year, plot, and cast. To work with this data in our application, we’ll define a simple record that maps to the collection but only includes the fields we want to return to the client. Create a record named Movie and annotate it with Document("embedded_movies"):

import org.springframework.data.mongodb.core.mapping.Document;
import java.util.List;

@Document("embedded_movies")
public record Movie(
   String title,
   String year,
   String fullplot,
   String plot,
   String poster,
   Imdb imdb,
   List<String> genres,
   List<String> cast)
{
   record Imdb(Double rating) {}
}

Wire the request DTO

Next, let’s create a request record with a single query field to hold the user’s search text, for now. We’ll revisit this class later to add extra fields for filtering:

public record MovieSearchRequest(
      String query
) {}

Communicating with Voyage AI

In this step, we’ll set up the classes needed to talk to the Voyage AI API. The idea is simple: We send a request with some text, and Voyage AI returns the corresponding list of embeddings.

To model this exchange, we’ll use two records:

EmbeddingsRequest: This represents the payload we send to Voyage AI. It includes the input text, the model name, and a few optional parameters like input_type and output_dimension.

import java.util.List;

public record EmbeddingsRequest(
   List<String> input,
   String model,
   String input_type,
   Integer output_dimension
) {}

EmbeddingsResponse: This represents the response from Voyage AI.

import java.util.List;

public record EmbeddingsResponse(List<Item> data) {
 public record Item(List<Double> embedding) {}
}

The VoyageEmbeddingsClient

To call the Voyage AI API, we’ll define a small HTTP client using Spring’s declarative HTTP interfaces:

import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.service.annotation.HttpExchange;
import org.springframework.web.service.annotation.PostExchange;

@HttpExchange(
       url = "/embeddings",
       contentType = MediaType.APPLICATION_JSON_VALUE,
       accept = MediaType.APPLICATION_JSON_VALUE
)
public interface VoyageEmbeddingsClient {
 @PostExchange
 EmbeddingsResponse embed(@RequestBody EmbeddingsRequest body);
}

In short: This interface acts as a strongly-typed wrapper around Voyage AI’s /embeddings endpoint, letting us call the API as if it were a regular Java method.

The VoyageClientConfig

To actually use our VoyageEmbeddingsClient, we need to configure how Spring will build it. That’s what the following class does:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestClient;
import org.springframework.web.client.support.RestClientAdapter;
import org.springframework.web.service.invoker.HttpServiceProxyFactory;

@Configuration
public class VoyageClientConfig {

  @Bean
  public VoyageEmbeddingsClient voyageEmbeddingsClient(VoyageConfigProperties props) {
      RestClient client = RestClient.builder()
          .baseUrl(props.baseUrl())
          .defaultHeader("Authorization", "Bearer " + props.apiKey())
          .defaultHeader("Content-Type", "application/json")
          .build();
      HttpServiceProxyFactory factory = HttpServiceProxyFactory.builderFor(RestClientAdapter.create(client)).build();
      return factory.createClient(VoyageEmbeddingsClient.class);
  }
}

In short: This config builds the HTTP client, injects the API key into every request, and exposes a ready-to-use VoyageEmbeddingsClient bean.

The EmbeddingService

Next, let's add an EmbeddingService that wraps our client and handles generating embeddings for a given query text.

import org.springframework.stereotype.Service;
import java.util.List;
import java.util.logging.Logger;

@Service
public class EmbeddingService {

  private final Logger logger = Logger.getLogger(EmbeddingService.class.getName());
  private final VoyageEmbeddingsClient client;
  private final VoyageConfigProperties config;

  public EmbeddingService(VoyageEmbeddingsClient client, VoyageConfigProperties config) {
     this.client = client;
     this.config = config;
  }
  public List<Double> embedQuery(
        String text) {
     logger.info("Generating embeddings .. ");
     var res = client.embed(new EmbeddingsRequest(
           List.of(text), config.model(), "query", config.outputDimension()));
     logger.info("Embeddings generated successfully!");
     return res.data().getFirst().embedding();
  }
}

This service calls the Voyage AI API with the user’s text, generates the embedding using the configured model, and returns the vector as a list of numbers.

Querying with Spring Data Vector Search operation

There are multiple ways to run a vector search. You could even work directly with raw document queries. But in this tutorial, we’ll focus on the brand-new Spring Data MongoDB support for semantic search, introduced in Spring Data MongoDB 4.5.

The VectorSearchOperation class is at the core of this feature, and it’s what we’ll use to express our queries in a clean, type-safe way.

To run the search, let’s create a MovieService that generates embeddings for the user’s query and executes the vector search against the embedded_movies collection:

import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.data.mongodb.core.MongoTemplate;
import org.springframework.data.mongodb.core.aggregation.Aggregation;
import org.springframework.data.mongodb.core.aggregation.VectorSearchOperation;
import org.springframework.stereotype.Service;
import java.util.List;

@Service
@EnableConfigurationProperties(VoyageConfigProperties.class)
public class MovieService {

   private final MongoTemplate mongoTemplate;

   private final VoyageConfigProperties config;
   private final EmbeddingService embeddingService;

   MovieService(MongoTemplate mongoTemplate, VoyageConfigProperties config, EmbeddingService embeddingService) {
      this.mongoTemplate = mongoTemplate;
      this.config = config;
      this.embeddingService = embeddingService;
   }

   public List<Movie> searchMovies(MovieSearchRequest req) {
      VectorSearchOperation vectorSearchOperation = VectorSearchOperation.search(config.vectorIndexName())
            .path(config.vectorField())
            .vector(embeddingService.embedQuery(req.query()))
            .limit(config.topK())
            .numCandidates(config.numCandidates());

      return mongoTemplate.aggregate(
            Aggregation.newAggregation(vectorSearchOperation),
            config.vectorCollectionName(),
            Movie.class
      ).getMappedResults();
   }
}

The searchMovies method takes the user’s text, generates an embedding with EmbeddingService, and uses Spring Data’s new VectorSearchOperation to query MongoDB Atlas Vector Search, returning the most relevant movies directly as mapped Movie objects.

The MovieController

With everything in place, the last step is to expose our API through a simple controller. This class wires the MovieService and makes the /movies/search endpoint available:

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;

@RestController
@RequestMapping("/movies")
public class MovieController {

   private final MovieService movieService;

   public MovieController(MovieService movieService) {
      this.movieService = movieService;
   }

   @PostMapping("/search")
   public ResponseEntity<List<Movie>> searchMovies(@RequestBody MovieSearchRequest req) {
      return ResponseEntity.ok(movieService.searchMovies(req));
   }
}

In short: The controller takes in a search request, delegates to MovieService, and returns a list of matching movies.

By the end, you’ll have a project structure similar to this.

spring-data-mongodb-hybrid-search/
├── .idea/
├── .mvn/
└── src/
   └── main/
       ├── java/
       │   └── com/
       │       └── mongodb/
       │           ├── EmbeddingService.java
       │           ├── EmbeddingsRequest.java
       │           ├── EmbeddingsResponse.java
       │           ├── Movie.java
       │           ├── MovieController.java
       │           ├── MovieSearchRequest.java
       │           ├── MovieService.java
       │           ├── SpringDataMongodbHybridSearchApplication.java
       │           ├── VoyageClientConfig.java
       │           ├── VoyageConfigProperties.java
       │           └── VoyageEmbeddingsClient.java
       └── resources/
           ├── static/
           ├── templates/
           └── application.yml

Note: There’s no strict separation into layers or packages here, since that’s not the focus of this tutorial. If you’re interested in a deeper dive into architecture, you can check out my article Clean and Modular Java: A Hexagonal Architecture Approach.

Running the application

Set the required environment variables:

export MONGODB_URI=<YOUR CONNECTION>
export VOYAGE_API_KEY=<YOUR API KEY>

Note: The <YOUR_CONNECTION> should be something like this:

mongodb+srv://<username>:<password>@cluster0.mongodb.net/sample_mflix?appName=devrel-mongodb-beyond-keywords-java-p1

Then, start the application:

mvn spring-boot:run

With the app running, let’s perform a POST request to our new endpoint:

Example request

### Searching movies
POST http://localhost:8080/movies/search
Content-Type: application/json

{
 "query": "a science fiction movie about rebels fighting an empire in space"
}

You should see results coming back from the embedded_movies collection, movies semantically close to the description, even though the exact title wasn’t mentioned.

{
 "title": "Star Wars: Episode IV - A New Hope",
 "year": "1977",
 "fullplot": "A young boy from Tatooine..",
 "plot": "Luke Skywalker joins ..",
 "imdb": {
     "rating": 8.7
   },
 "genres": [
     "Action",
     "Adventure",
     "Fantasy"
  ],
 ...
}

Looking ahead

In this first part, we explored what vector search is, its core principles, and how it enables semantic search beyond simple keywords. We saw how to generate embeddings with Voyage AI, create a vector index in MongoDB Atlas, and use the brand-new Spring Data MongoDB support for vector queries to build a working movie search application.

If you’d like to check out the full project code, you can find it on GitHub.

In Part 2: Beyond Keywords: Optimizing Vector Search with Filters and Caching, we’ll enhance this application by adding filters to our vector search, exploring how they work under the hood, and refining the overall search experience.

Queryable Encryption With Spring Data MongoDB: How to Query Encrypted Fields

Ricardo Mello — Wed, 06 Aug 2025 18:47:46 +0000

Information is one of the most valuable assets in computing and keeping it protected is even more critical. When we talk about data protection, it’s not just about preventing breaches or leaks; it’s also about complying with privacy regulations and protecting user data.

MongoDB provides strong encryption capabilities, including in transit, at rest, and in use. The Queryable Encryption feature falls into the in use category. It allows data to be encrypted on the client side, so that even with access to the database and its credentials, no one can read the protected fields without the proper encryption key. At the same time, it supports querying over encrypted fields, making it possible to filter, match, or retrieve data without compromising confidentiality.

In this tutorial, we’ll implement this feature using Spring Data MongoDB, applying encryption to sensitive fields in a sample human resources (HR) system.

Why Queryable Encryption?

Imagine a common scenario in HR systems: You receive a regulatory requirement to protect employee data using encryption. At first, encrypting fields seems enough. But then comes a second requirement—you also need to search over that encrypted data.

That’s exactly where Queryable Encryption comes in. MongoDB currently supports several query types over encrypted fields, including Equality, Range, Prefix, and Suffix.

To implement it, we typically follow four steps:

Specify which fields should be encrypted.
Define whether each field should be queryable.
Create the encrypted collection with the appropriate encryptedFields configuration.
Perform regular operations: The client handles encryption and decryption transparently.

If you're interested in seeing more advanced details about Queryable Encryption, including how to use it directly with the MongoDB Java Driver and a deeper explanation of how it works, I recommend checking out my other article: Java Meets Queryable Encryption.

A quick look at Spring Data MongoDB

Spring Data MongoDB is a module within the Spring ecosystem that makes it easier to work with MongoDB. It provides a familiar way to interact with MongoDB using the Spring programming model.

Starting with version 4.5.0, the framework introduced several important changes, including support for Queryable Encryption.

If you're new to using Spring Data with MongoDB or want to explore more advanced use cases, check the Spring Data Unlocked series that walks through these concepts in detail.

Use case: HR system with encrypted fields

To better understand how Spring Data MongoDB works with Queryable Encryption, we’ll build a simple Java application for an HR system. This application will use a document model like the one below:

{
   "name": "Ricardo",
   "pin": "001",
   "ssn": 223,
   "age": 36,
   "salary": 1000.50
}

In this scenario, fields such as pin, ssn, age, and salary will be encrypted using the new annotations introduced in Spring Data MongoDB 4.5, including @Encrypted, @Queryable, and @RangeEncrypted.

We’re not only encrypting sensitive information, but also making it searchable, with support for both:

Equality queries: find an employee by ssn
Range queries: filter employees by age or salary

To keep things simple and practical, our application will expose four basic endpoints:

Create a new employee
Retrieve all employees
Find an employee by SSN
Filter employees by age or salary range

At the end, when we open a document in MongoDB Compass, we’ll see encrypted fields as unreadable binary blobs, only decryptable by the client configured with the proper keys:

Setting up the project

TL;DR

If you just want to jump straight into the code, you can find the full project on GitHub. It includes all the setup needed to run Queryable Encryption with Spring Data MongoDB.

Let’s start by creating our Spring Boot project using the official Spring Initializr. This tool allows us to quickly generate a base project with the dependencies we need.

For this demo, we’ll add the following dependencies:

Spring Web, to expose our REST endpoints
Spring Data MongoDB, to interact with our MongoDB database

Configure the project properties as shown in the image, then generate and unzip the project to get started.

Configuring dependencies and properties

Adding mongodb-crypt

The first thing we need to do is include the mongodb-crypt library in our project. This library is essential when working with Queryable Encryption in Java applications, handling the low-level cryptographic operations required by the MongoDB driver. Open the pom.xml and include the following dependency:

<dependency>
   <groupId>org.mongodb</groupId>
   <artifactId>mongodb-crypt</artifactId>
   <version>5.5.1</version>
</dependency>

Application.yml configuration

Now, let’s open the application.yml file (or create one if it doesn’t exist) and define the following values:

app:
 mongodb:
   uri: ${MONGODB_URI}
   cryptSharedLibPath: ${CRYPT_PATH}
   keyVaultNamespace: encryption.__keyVault
   encryptedDatabaseName: hrsystem
   encryptedCollectionName: employees
logging:
 level:
   org.springframework.data.mongodb: DEBUG

Alright, we can see some familiar settings here, like the uri, which defines the connection string to MongoDB, and the database/collection names where our encrypted data will live (hrsystem and employees).

But two properties stand out and deserve a quick explanation:

keyVaultNamespace: This tells MongoDB where to store and retrieve the encryption keys. In our case, they’ll be saved in the __keyVault collection inside the encryption database.
cryptSharedLibPath: This points to the native cryptographic library that handles encryption and decryption on the client side. Without this, the app can’t use Queryable Encryption.

To resolve this library dependency, we need to download the automatic encryption shared libraryc and save it somewhere to use later.

Accessing properties in the code

Now that we've defined our configuration values in the application.yaml file, we need a way to access them inside our application. To do this, create a simple class:

@Component
@ConfigurationProperties(prefix = "app.mongodb")
public class AppProperties {
   protected String uri;
   protected String cryptSharedLibPath;
   protected String keyVaultNamespace;
   protected String encryptedDatabaseName;
   protected String encryptedCollectionName;

   // getters and setters

}

Note: Don’t forget to generate getters and setters for all the fields in the AppProperties class.

Building the application layers

The domain model

Now, let’s define the data we’ll be working with throughout the project. We’ll use a simple Employee record to represent an employee in our HR system:

@Document(collection = "employees")
public record Employee(
       @Id
       String id,

       String name,

       @Encrypted
       String pin,

       @Queryable(queryType = "equality")
       @Encrypted
       int ssn,

       @RangeEncrypted(
               contentionFactor = 0L,
               rangeOptions = "{\"min\": 0, \"max\": 150}"
       )
       Integer age,

       @RangeEncrypted(contentionFactor = 0L,
               rangeOptions = "{\"min\": {\"$numberDouble\": \"1500\"}, \"max\": {\"$numberDouble\": \"100000\"}, \"precision\": 2 }")
       double salary
) {}

Here’s a quick look at what each encrypted field does:

pin is encrypted for confidentiality only.
ssn is encrypted but also queryable using equality.
age and salary use range-based encryption, allowing queries like "find all employees with salary above X" or "age below Y". Among other things, rangeOptions define the minimum and maximum values allowed in range queries. Any value outside this range won’t match during query execution.

The repository

To query our encrypted fields, we’ll define a few methods in our repository: findBySsn, findByAgeLessThan, and findBySalaryGreaterThan:

@Repository
public interface EmployeeRepository extends MongoRepository<Employee, String> {
   Optional<Employee> findBySsn(int ssn);
   List<Employee> findByAgeLessThan(int age);   
   List<Employee> findBySalaryGreaterThan(double salary);
}

The service

Now, let’s create a service layer to interact with the repository and handle the business logic of our application:

@Service
public class EmployeeService  {
   private static final Logger logger = LoggerFactory.getLogger(EmployeeService.class);

   private final EmployeeRepository employeeRepository;

   public EmployeeService(EmployeeRepository employeeRepository) {
        this.employeeRepository = employeeRepository;
   }

   public Employee createEmployee(Employee employee) {
       logger.info("Creating employee {}", employee);
        return employeeRepository.save(employee);
    }

   public List<Employee> findAll() {
      logger.info("Finding all employees ");
      return employeeRepository.findAll();
   }

   public Optional<Employee> findBySsn(int ssn) {
       logger.info("Finding employee with ssn equals {}", ssn);
       return employeeRepository.findBySsn(ssn);
   }

   public List<Employee> findByAgeLessThan(int age) {
       Assert.isTrue(age > 0, "Age must be greater than 0");
       Assert.isTrue(age < 150, "Age must be less than 150");

       logger.info("Finding all employees where age is less than {} ", age);
       return employeeRepository.findByAgeLessThan(age);
   }

   public List<Employee> findBySalaryGreaterThan(double salary) {
       Assert.isTrue(salary >= 1500, "Salary must be at least 1500");
       Assert.isTrue(salary < 100000, "Salary must be less than 100000");

       logger.info("Finding all employees where salary is greater than {}", salary);

       return employeeRepository.findBySalaryGreaterThan(salary);
   }
}

The controller

Finally, let's expose our service layer through a REST controller, allowing the application to receive a HTTP request and interact with the encrypted data:

@RestController
@RequestMapping("/employees")
public class EmployeeController {
   private final EmployeeService employeeService;

public EmployeeController(EmployeeService employeeService) {
        this.employeeService = employeeService;
   }

   @PostMapping
   public ResponseEntity<Employee> create(@RequestBody Employee employee) {
       return ResponseEntity.ok(employeeService.createEmployee(employee));
   }

   @GetMapping
   public ResponseEntity<List<Employee>> findAll() {
       return ResponseEntity.ok(employeeService.findAll());
   }

   @GetMapping("/ssn/{ssn}")
   public ResponseEntity<Employee> findBySsn(@PathVariable int ssn) {
       return employeeService.findBySsn(ssn)
               .map(ResponseEntity::ok)
               .orElseGet(() -> ResponseEntity.notFound().build());
   }

   @GetMapping("/filter/salary-greater-than")
   public ResponseEntity<List<Employee>> findByAgeGreaterThan(@RequestParam double salary) {
       return ResponseEntity.ok(employeeService.findBySalaryGreaterThan(salary));
   }

   @GetMapping("/filter/age-less-than")
   public ResponseEntity<List<Employee>> findByAgeLessThan(@RequestParam int age) {
       return ResponseEntity.ok(employeeService.findByAgeLessThan(age));
   }
}

Setting up encryption

Before we can start encrypting data, we need a Customer Master Key (CMK), a secret key that serves as the base for encrypting other keys used by the database.

In real-world applications, this key is usually managed by a secure provider like AWS KMS, Azure Key Vault, or Google Cloud KMS, which offer strong protection and lifecycle management.

But to keep things simple in this example, we’ll generate and store the CMK locally, in a file inside the project.

Let's create a utility class called LocalCMKService to handle this process. It checks if the key file exists, creates it if needed, and loads the key into memory so it can be used when configuring the MongoDB client:

@Service
public class LocalCMKService {

   private static final String CUSTOMER_KEY_PATH = "src/main/resources/my-key.txt";
   private static final int KEY_SIZE = 96;

   private boolean isCustomerMasterKeyFileExists() {
       return new File(CUSTOMER_KEY_PATH).isFile();
   }

   private void create() throws IOException {
       byte[] cmk = new byte[KEY_SIZE];
       new SecureRandom().nextBytes(cmk);

       try (FileOutputStream stream = new FileOutputStream(CUSTOMER_KEY_PATH)) {
           stream.write(cmk);
       } catch (IOException e) {
           throw new IOException("Unable to write Customer Master Key file: " + e.getMessage(), e);
       }
   }

  private byte[] read() throws IOException {
       byte[] cmk = new byte[KEY_SIZE];

       try (FileInputStream fis = new FileInputStream(CUSTOMER_KEY_PATH)) {
           int bytesRead = fis.read(cmk);
           if (bytesRead != KEY_SIZE) {
               throw new IOException("Expected the customer master key file to be " + KEY_SIZE + " bytes, but read " + bytesRead + " bytes.");
           }
       } catch (IOException e) {
           throw new IOException("Unable to read the Customer Master Key: " + e.getMessage(), e);
       }

       return cmk;
   }

  public Map<String, Map<String, Object>> getKmsProviderCredentials() throws IOException {

       try {
           if (!isCustomerMasterKeyFileExists()) {
               create();
           }

           byte[] localCustomerMasterKey = read();

           Map<String, Object> keyMap = new HashMap<>();
           keyMap.put("key", localCustomerMasterKey);

           Map<String, Map<String, Object>> kmsProviderCredentials = new HashMap<>();
           kmsProviderCredentials.put("local", keyMap);

           return kmsProviderCredentials;
       }catch (Exception e) {
           throw new IOException("Unable to read the Customer Master Key file: " + e.getMessage(), e);
       }

   }

}

Configuring the MongoDB encryption layer

To bring everything together, let’s now create the MongoEncryptionConfiguration class. This is where we configure our MongoDB client to support Queryable Encryption, define how keys are loaded, and ensure our encrypted collection is created at startup:

@Configuration
public class MongoEncryptionConfiguration implements ApplicationRunner {

   private final AppProperties appProperties;
   private final LocalCMKService localCMKService;

   MongoEncryptionConfiguration(LocalCMKService localCMKService, AppProperties appProperties) {
       this.localCMKService = localCMKService;
       this.appProperties = appProperties;
   }

   @Override
   public void run(ApplicationArguments args) throws Exception {
      // TODO 
   }
}

Defining the encryption configuration

Great! Now, in the same MongoEncryptionConfiguration class, let’s start adding a few methods. First, we configure the path to the native mongodb_crypt library we downloaded earlier:

private Map<String, Object> createExtraOptions() {
   Map<String, Object> extraOptions = new HashMap<>();
   extraOptions.put("cryptSharedLibPath", appProperties.cryptSharedLibPath);
   return extraOptions;
}

Next, we build the AutoEncryptionSettings, which defines the encryption behavior for the client:

private AutoEncryptionSettings getAutoEncryptionSettings() throws IOException {
   Map<String, Map<String, Object>> kmsProviderCredentials = localCMKService.getKmsProviderCredentials();

   return AutoEncryptionSettings.builder()
           .keyVaultNamespace(appProperties.keyVaultNamespace)
           .extraOptions(createExtraOptions())
           .kmsProviders(kmsProviderCredentials)
           .build();
}

We then use these settings to build the custom MongoClientSettings:

private MongoClientSettings getMongoClientSettings() throws IOException {
   return MongoClientSettings.builder()
           .applyConnectionString(new ConnectionString(appProperties.uri))
           .autoEncryptionSettings(getAutoEncryptionSettings())
           .uuidRepresentation(UuidRepresentation.STANDARD)
           .build();
}

Defining Spring beans

Now that our encryption configuration is complete, we can register the two Spring beans:

MongoClient: configured with the encryption support
MongoTemplate: used to interact with the encrypted database

@Bean
public MongoClient mongoClient() throws IOException {
   return MongoClients.create(getMongoClientSettings());
}

@Bean
MongoOperations mongoTemplate(MongoClient mongoClient) {
   return new MongoTemplate(mongoClient, appProperties.encryptedDatabaseName);
}

The encrypted collection

Instead of manually defining which fields are encrypted, we generate the schema based on our Employee class using Spring's built-in MongoJsonSchemaCreator:

private void createCollectionFromSchema(MongoOperations template, ClientEncryption clientEncryption) {
   MongoJsonSchema schema = MongoJsonSchemaCreator.create(new MongoMappingContext())
           .filter(MongoJsonSchemaCreator.encryptedOnly())
           .createSchemaFor(Employee.class);

   Document encryptedFields = CollectionOptions.encryptedCollection(schema)
           .getEncryptedFieldsOptions()
           .map(CollectionOptions.EncryptedFieldsOptions::toDocument)
           .orElseThrow();

   template.execute(db -> clientEncryption.createEncryptedCollection(
           db,
           template.getCollectionName(Employee.class),
           new CreateCollectionOptions().encryptedFields(encryptedFields),
           new CreateEncryptedCollectionParams("local")
   ));
}

Creating the ClientEncryption

To interact with the key vault and create encrypted collections, we need a ClientEncryption instance:

private ClientEncryption createClientEncryption() throws IOException {
   var encryptionSettings = ClientEncryptionSettings.builder()
           .keyVaultMongoClientSettings(
                   MongoClientSettings.builder()
                           .applyConnectionString(new ConnectionString(appProperties.uri))
                           .build())
           .keyVaultNamespace(appProperties.keyVaultNamespace)
           .kmsProviders(localCMKService.getKmsProviderCredentials())
           .build();

   return ClientEncryptions.create(encryptionSettings);
}

Initializing the collection on startup

Before the application starts, we want to ensure that the encrypted collection exists. That check happens inside the run() method, which is automatically executed after the Spring Boot application starts. You can now replace the //TODO in the run() method with the following logic:

@Override
public void run(ApplicationArguments args) throws Exception {
   var mongoTemplate = mongoTemplate(mongoClient());

   if (!mongoTemplate.collectionExists(appProperties.encryptedCollectionName)) {
       initializeEncryptedCollection(mongoTemplate);
   }
}

This code uses mongoTemplate to check if the collection already exists. If it doesn't, it calls the method below to create it:

private void initializeEncryptedCollection(MongoOperations template) throws IOException {
   try (ClientEncryption clientEncryption = createClientEncryption()) {
       createCollectionFromSchema(template, clientEncryption);
   }
}

Inserting sample data for testing

To wrap things up, let’s preload some sample employee data to help us test our encrypted queries. We'll use a simple CommandLineRunner to automatically insert records into the collection when the application starts:

@Configuration
public class SampleDataLoader {
   private static final Logger logger = LoggerFactory.getLogger(SampleDataLoader.class);

   @Bean
   public CommandLineRunner loadSampleEmployees(EmployeeRepository employeeRepository) {
       return args -> {
           if (employeeRepository.count() != 0) {
               logger.info("Sample data already exists. Skipping insert");
               return;
           }

           List<Employee> employees = List.of(
                   new Employee(null, "Ricardo", "001", 1, 36, 1501),
                   new Employee(null, "Maria",   "002", 2, 28, 4200),
                   new Employee(null, "Karen",   "003", 3, 42, 2800),
                   new Employee(null, "Mark",    "004", 4, 22, 2100),
                   new Employee(null, "Pedro",   "005", 5, 50, 4000),
                   new Employee(null, "Joana",   "006", 5, 50, 99000)
           );
           employeeRepository.saveAll(employees);
           logger.info("Saved {} employees", employees.size());
       };
   }
}

If the collection already contains data, the loader will skip the insertion to avoid duplicates.

Running the application

Great! With everything in place, it's time to run the app.

Just make sure to pass the MongoDB URI and the path to the cryptographic shared library using environment variables:

export MONGODB_URI='<YOUR_CONNECTION_STRING>' CRYPT_PATH='/path/to/mongo_crypt_shared/lib/mongo_crypt.dylib' mvn spring-boot:run

Note: The <YOUR_CONNECTION_STRING> should be something like this:

mongodb+srv://<username>:<password>@cluster0.mongodb.net/hrsystem?appName=devrel-mongodb-qe

Note: The CRYPT_PATH should point to the full path of the native library you downloaded.

Once the application is running, if everything goes well, you can check the cluster specified in your connection string. Inside the hrsystem database, look for the employees collection—it should already contain six documents with encrypted fields, ready to be queried:

Testing the endpoints

With the app running, we can interact with our encrypted data through simple HTTP requests. Here are some examples:

Create a new employee

Send a new employee to the database. Fields like ssn, age, and salary will be encrypted automatically.

POST http://localhost:8080/employees
Content-Type: application/json

{
 "name": "Henrique Silva",
 "pin": "932",
 "ssn": 21,
 "age": 44,
 "salary": 32100
}

Find by ssn

Perform an equality query on an encrypted field.

GET http://localhost:8080/employees/ssn/1

Find by age (range)

Return all employees younger than a given age.

GET http://localhost:8080/employees/filter/age-less-than?age=50

Find by salary (range)

Return all employees with a salary above a given value.

GET http://localhost:8080/employees/filter/salary-greater-than?salary=3500

Conclusion

In this tutorial, we explored how to implement Queryable Encryption using Spring Data MongoDB, step by step, from setting up the project to making encrypted queries work in practice.

We saw how easily Spring and MongoDB fit together: The annotations in the domain model, the auto-generated schema, and the integration with client-side encryption all worked in harmony.

It’s not just about encrypting sensitive fields. It’s about being able to query them securely and efficiently, without giving up the developer experience we're used to with Spring.

If you have any questions, feel free to reach out to our community: MongoDB Community Forum.

For more on Spring Data MongoDB and the official docs: Spring Data MongoDB Encryption.

To access the full source code of this project: GitHub repository.

MongoDB Aggregation Framework: A Beginner’s Guide

Ricardo Mello — Tue, 10 Jun 2025 12:00:00 +0000

Finding exactly the data we need isn’t always a simple task. You’ve probably faced situations where you needed to filter information, group it, and even perform calculations to produce a final result. And often, delivering this processed data to the client is essential for the application’s success. MongoDB offers two main ways to fetch data:

find()
aggregate()

While .find() is great for basic queries, it doesn’t cover more advanced scenarios like transformations and complex data processing. That’s where the MongoDB Aggregation Framework comes in.

The MongoDB Aggregation Framework works like a pipeline—a series of stages where each step processes the data in some way. When we use the aggregate() method, we’re building this sequence of operations.

Before diving into MongoDB, here’s a simple example of a pipeline in Java:

List<String> names = Arrays.asList("Alice", "Aloisio",  "alice", "andre", "Ricardo", "Jose", "Maria");
var count = names.stream()
      .map(String::toLowerCase)
      .filter(name -> name.startsWith("a"))
      .distinct()
      .count();


System.out.println(count); 
// output = 3

If you look closely, it uses functions like map, filter, distinct, and count. \
In other words, it:

Converts each name to lowercase.
Filters names that start with "a".
Removes duplicate names.
Counts the total unique names.

This is the essence of a pipeline: chaining operations that refine data step by step until you get the final result.

\
In MongoDB, we do something very similar.

Aggregation pipeline

An aggregation pipeline consists of one or more stages. Each stage represents a step that will be executed.

For example, consider a transactions collection where we want to count how many transactions contain errors. We could filter by status and then count:

[
  {
    $match: {
      status: "error"
    }
  },
  {
    $count: "total errors"
  }
]

Here, we apply a $match filter to select only the documents with status equal to "error," and then use $count to calculate the total number of transactions in this status.

Each stage in the pipeline is executed in order, and each one only processes the results from the previous stage. So in the example above, even if there are 1,000 transactions in total, the $count stage only counts the transactions that matched the "error" status from the $match stage.

Aggregation stages

As mentioned earlier, stages are used to build a pipeline. In this section, let’s take a look at some stages that are useful for our day-to-day work.

To explore their capabilities, we’ll create a collection called articles that will contain the following documents:




db.articles.insertMany(
   [
       {
           _id: 1,
           title: "Spring Data Unlocked: Getting Started With Java and MongoDB",
           tags: ["Java", "MongoDB", "Spring"],
           publishedAt: ISODate("2024-11-11T00:00:00Z"),
           authors: ["Ricardo Mello"],
           url: "https://www.mongodb.com/developer/products/mongodb/springdata-getting-started-with-java-mongodb/"
       },


       {
           _id: 2,
           title: "Java Meets Queryable Encryption: Developing a Secure Bank Account Application",
           tags: ["Java", "Security", "MongoDB"],
           publishedAt: ISODate("2024-10-08T00:00:00Z"),
           authors: ["Ricardo Mello"],
           url: "https://www.mongodb.com/developer/products/atlas/java-queryable-encryption/"
       },    
       {
           _id: 3,
           title: "Beyond Basics: Enhancing Kotlin Ktor API With Vector Search",
           tags: ["Kotlin", "Vector Search", "MongoDB"],
           publishedAt: ISODate("2024-09-18T00:00:00Z"),
           authors: ["Ricardo Mello"],
           url: "https://www.mongodb.com/developer/products/atlas/beyond-basics-enhancing-kotlin-ktor-api-vector-search/"
       },


   ]
)

$Match

This is one of the most common stages you’ll use. It basically serves to filter documents based on a specific query. For example, if you only want to return the document with _id: 3, you can use:

db.articles.aggregate([
   { $match: { _id: 3 } }
])
// This will return Beyond Basics's article

$Project

We use this stage to specify which fields we’d like to include in our results.

Suppose we want to return all documents and project only the title and author fields.

db.articles.aggregate([
   { $project: { _id: 0, title: 1, authors: 1 } }
])

The result would look like this: \

 {
   "title": "Beyond Basics: Enhancing Kotlin Ktor API With Vector Search",
   "authors": ["Ricardo Mello"]
 },
 .. Others..

$Unwind

The $unwind stage is used to deconstruct an array into multiple documents. For example:

db.articles.aggregate([
   { $unwind: "$tags" }
])

For each tag in the tags array, the document will be repeated in the query results.

This way, you can analyze or process each tag individually:

{
   "_id": 2,
   "title": "Spring Data Unlocked: Getting Started With Java and MongoDB",
   "tags": "Java",
   // other fields...
 }
  {
   "_id": 2,
   "title": "Spring Data Unlocked: Getting Started With Java and MongoDB",
   "tags": "MongoDB",
   // other fields...
 }
  {
   "_id": 2,
   "title": "Spring Data Unlocked: Getting Started With Java and MongoDB",
   "tags": "Spring",
   // other fields...
 },
   // other Documents...

$Group

As the name suggests, we use this stage to group our results. This time, we’ll use the $unwind stage we saw earlier to deconstruct the array of tags and find out how many articles exist for each tag:

db.articles.aggregate([
   { $unwind: "$tags" },
   {
       $group: {
           _id: "$tags",
           totalArticles: { $sum: 1 }
       }
   }
])

The result would look like this:

[
   {
       "_id": "Security",
       "totalArticles": 1
   },
   {
       "_id": "MongoDB",
       "totalArticles": 4
   },
   {
       "_id": "Java",
       "totalArticles": 2
   }
   .. other tags (Kotlin, Vector Search ..)
]

$Sort

Continuing with our example—what if we want to query all articles and sort them by publication date, from newest to oldest?

db.articles.aggregate([
   { $sort: { publishedAt: -1 } }
])

And if we want to reverse the order—showing the oldest articles first—we just use 1 instead of -1.

$AddFields

This stage is useful when we want to add a new field in our result.

Let’s say our client requested that we display a field called publishedYear containing only the year:

db.articles.aggregate([
   {
     $addFields: {
       publishedYear: { $year: "$publishedAt" }
     }
   }
 ])

Our result would look something like this:

 "_id": 2,
 .. other fields
 "publishedYear": 2024 // FIELD ADDED
// Other fields ..

Here, you can see that we’re using an operator called $year to extract the year from our publishedAt field. To learn about other operators, check out our official documentation page on aggregation operators.

Combining stages

As we explored earlier, a pipeline can combine multiple stages. Let’s say we want to know the total number of articles published in 2025 and beyond. We can combine the $match and $count stages for this:

db.articles.aggregate(
   [
       {
           $match: {
             publishedAt: { $gt: ISODate("2024-12-31T00:00:00Z") }
           }
       },
       {
           $count: 'total'
       }
   ]
)

Notice that we’re using the $gt operator to filter for years greater than the specific date.

Wrapping up

Aggregation Pipeline is a powerful alternative that MongoDB offers for combining stages and extracting data in an accurate and efficient way. There’s a whole world of stages and operators for you to explore.

Always turn to the MongoDB community for your questions. I hope this article has been useful to you all.

MongoDB Compass — Convert Text into Queries with AI-Powered Natural Language

Ricardo Mello — Tue, 12 Mar 2024 05:12:08 +0000

This is a tutorial for my YouTube Video

In this tutorial, we’ll explore Query With Natural Language, a revolutionary feature in MongoDB Compass. This advanced functionality is ideal for users looking to employ AI for query generation based on text input. This hands-on approach will showcase why Query With Natural Language is not just a useful tool, but a necessary one for modern data management workflows. The article is structured as follows:

Introduction — Use Cases, Concepts and Requirements
Importing dataset with MongoDB Tools
Prompt a Natural Language in Compass
Conclusion

Introduction — Use Cases, Concepts and Requirements

Today, we’re diving into a topic that was inspired by a recent conversation I had with friends. They expressed the challenges of transitioning from a relational database to MongoDB, struggling with creating queries and aggregation pipelines due to lack of experience. This got me thinking about the broader implications for those starting new roles in MongoDB-dependent companies.

As a result, I decided to explore a feature that addresses these issues: MongoDB Compass. By harnessing AI, MongoDB Compass automates query generation from your text input, revolutionizing the querying process. This feature, available from version 1.40.x and powered by Azure Open AI, ensures your data’s security, as it’s not stored on any third-party system or used for AI model training.

To get started, create your free account on Atlas and install MongoDB Compass version 1.40 or later.

Importing dataset with MongoDB Tool

Notice: If you have already your data, you can skip ahead to the last topic.

I separated this section into three steps:

Creating an instance of MongoDB using Docker.
Downloading the dataset.
Importing the dataset using MongoDB tools.

1 — Creating an instance of MongoDB using Docker
First, we need to set up an instance of MongoDB. We will use Docker Compose for this task. Below is a docker-compose.yml file to create a MongoDB instance:

version: '3.1'

services:
  mongodb:
    image: mongo
    container_name: my_mongodb
    restart: always
    ports:
      - "27017:27017"
    volumes:
      - mongodb_data:/data/db

volumes:
  mongodb_data:
    driver: local

2 — Downloading the dataset.
Kaggle.com is an online platform that hosts data science competitions and offers datasets for exploration. Download the countries Json:

important: When downloading the file, make sure it is in JSON format. If not, use a converter, such as this one, to ensure success.

3 — Importing the dataset using MongoDB tools.
MongoDB Tools will help us to bring data into our database. Download it:

Perfect! Now it’s time to import our dataset. I’ve saved my dataset with the name countries.json. To import it, navigate to the MongoDB Tools Downloaded /bin folder run:

.\mongoimport mongodb://localhost:27017/countries_db --collection countries --jsonArray ./countries.json

Prompt a Natural Language in Compass

In this section, we will explore how to create queries based on the country’s information. We will cover finding countries with the highest and lowest populations, as well as grouping countries by region to calculate the average population in each region.

Countries with Highest Population: “Find the countries with the highest population, sorting the results in descending order by population.”
Grouping by Region: “Group the countries by region and calculate the average population in each region.”

First, click on Compass settings:

Then feature preview, and enable natural language prompt. As you can see, I’m already logged into my Atlas account, so you’ll need to do the same.

Then, return to our collections. Here, you’ll find the “Generate Query” option. Click on that:

As you can observe, MongoDB will enable a field to enter with queries. To start, paste the following sentence, click in generate then Find:

“Find the countries with the highest population, sorting the results in descending order by population.”

To conclude, let’s create some aggregation pipelines. Click on “Aggregations” and paste the following sentence:

“Group the countries by region and calculate the average population in each region.”

This will demonstrate how MongoDB Compass can simplify the creation of stages using natural language queries.

Conclusion

In conclusion, MongoDB Compass’s Query with Natural Language feature revolutionizes the way users interact with databases. By allowing users to input queries in plain language, MongoDB Compass simplifies the querying process, especially for those new to MongoDB or database queries in general.

I hope you have enjoyed this content. For those who might not be aware, I’m a member of the MongoDB Community Creator. For a deeper dive and detailed guidance, check out my video.

Do you like MongoDB? Check out my other articles:

I hope this has been informative and helpful. Until next time!

MongoDB #Query #AI #NLP

Deploying a Quarkus Application to AWS Elastic Beanstalk

Ricardo Mello — Tue, 28 Mar 2023 01:35:29 +0000

In this article, we will explore how to deploy a Quarkus application to Elastic Beanstalk, and take a closer look at some of the key benefits and best practices for using these two technologies together. Whether you’re a seasoned AWS user or a Java developer looking to modernize your application architecture, you’re sure to find something of value in this guide.

Application Sample

We’ll create a simple Quarkus application that will call an API to return Chuck Norris jokes 😎

Create Quarkus Application

Quarkus is a Java framework designed for building cloud-native applications that are lightweight, fast, and scalable. Let’s create a new project using Quarkus Initializer by clicking here.

Note: After download the project, import it in your IDE

Consuming Chuck Norris Joke API

To query the jokes we will consume this API.

For this, let’s create a class that represents the value that contains the joke.

package br.com.ricas.application.response;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;

@JsonIgnoreProperties(ignoreUnknown = true)
public class JokeResponse {

  private String value;

  public String getValue() {
      return value;
  }

}

Now, we need to create a interface that will make a call to API:

package br.com.ricas.domain.service;

import br.com.ricas.application.response.JokeResponse;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@RegisterRestClient(configKey = "chuck-norris")
public interface ChuckNorrisService {
    @GET
    @Path("/jokes/random/")
    @Produces(MediaType.APPLICATION_JSON)
    JokeResponse getRandomJoke();
}

Note: @RegisterRestClient is a JAX-RS annotation used in Quarkus to register a REST client. It allows you to define an interface that can be used to make HTTP requests to a REST API. The configKey parameter is used to specify the configuration key that points to the base URL of the REST API.

Application.properties

We will change the application port to start the server at port 5000. Also we’ll include the entire url of API and ssl validation:

quarkus.http.root-path=/
quarkus.http.port=5000
quarkus.rest-client.disable-ssl-validation=true
quarkus.rest-client.chuck-norris.url=https://api.chucknorris.io

Web Resource

Now, lets create our Resource that will respond in /api path:

package br.com.ricas.application.web;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import br.com.ricas.domain.service.ChuckNorrisService;
import org.eclipse.microprofile.rest.client.inject.RestClient;

@Path("/api")
public class ChuckNorrisJokeResource {
    @RestClient
    ChuckNorrisService chuckNorrisService;
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String getJoke() {
        return chuckNorrisService.getRandomJoke().getValue();
    }
}

Note: The above code we inject a @RestCLient reference to an instance of the ChuckNorrisService interface and use it on getJoke() method. The Path annotation is used to specify the base URI path for the resource class, which is "/api" in this case.

Creating HTML file

Inside the resource folder, create an index.html file:

<!DOCTYPE html>
<html>
<head>
    <title>Chuck Norris Jokes</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css">
    <link rel="stylesheet" href="style.css">
</head>
<body>
<div class="container-fluid">
    <div class="row justify-content-center">
        <div class="col-sm-8">
            <div class="card mt-5">
                <div class="card-body">
                    <h3 class="card-title text-center mb-4">Chuck Norris Jokes</h3>
                    <p class="card-text text-center" id="joke"></p>
                    <button class="btn btn-warning btn-block mt-3" style="background-color: #f7dc6f; color: #4a4e4d;" onclick="getRandomJoke()">New Joke</button>
                </div>
            </div>
        </div>
    </div>
</div>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.5.2/js/bootstrap.min.js"></script>
<script>
        function getRandomJoke() {
            $.get("/api", function(response) {
                $("#joke").text(response);
            });
        }
</script>
</body>
</html>

Note: The script section at the bottom of the HTML file defines a JavaScript function called getRandomJoke() that uses jQuery's $.get() method to make an AJAX request to the /api URI and get a random Chuck Norris joke. When the response is received, the function updates the text of the p element with an id of joke to display the joke text

Creating Css file:

Inside the resource folder, create an style.css file:

.card {
 max-width: 600px;
 margin: 0 auto;
 box-shadow: 0 4px 8px 0 rgba(0,0,0,0.2);
 transition: 0.3s;
 background-color: #4a4e4d;
 border-radius: 10px;
}

.card:hover {
 box-shadow: 0 8px 16px 0 rgba(0,0,0,0.2);
}

.card-title {
 font-size: 2.5rem;
 color: #fff;
 font-weight: bold;
 text-shadow: 2px 2px 2px rgba(0,0,0,0.2);
}

.card-text {
 font-size: 1.5rem;
 color: #000;
 text-align: justify;
 padding: 20px;
}

.btn-primary {
 background-color: #f7dc6f;
 border-color: #000;
 font-size: 1.5rem;
 font-weight: bold;
 text-transform: uppercase;
 letter-spacing: 2px;
 padding: 15px 50px;
}

.btn-block {
 padding: 1rem;
 font-size: 1.5rem;
}

body {
 background-image: url('https://e0.pxfuel.com/wallpapers/472/940/desktop-wallpaper-chuck-norris.jpg');
 background-size: cover;
 background-repeat: no-repeat;
}

Running Application

Navigate until root folder and run:

$ ./gradlew quarkusDev

Now, just open http://localhost:5000 and see the result:

Generating the application JAR

Now that we already have our application working, we will generate a JAR to upload it to Elastic beanstalk. To do this, we will run the following command:

$ ./gradlew build -Dquarkus.package.type=uber-jar

All right! 😀

Navigate until build folder to get the generated chuck-norris-joke1.0.0-SNAPSHOT-runner.jar that we will use in the next step:

What is AWS Elastic Beanstalk?

Elastic Beanstalk is a popular platform-as-a-service (PaaS) offering from Amazon Web Services (AWS) that allows developers to easily deploy, manage, and scale web applications. In other words, you only care about uploading your code and leave control of the infrastructure to Elastic Beanstalk.

There are some features offers such as:

Allows quick deployment of applications
Reduces management complexity
Supports a large range of platform (Java, Node.js, Python)
Load Balance, Database

Note: Elastic Beanstalk itself is free to use. You can create, deploy, and manage your applications on Elastic Beanstalk without any additional charges. However, you will be charged for the AWS resources that your application consumes, such as EC2 instances, load balancers, and data transfer.

Get started

Create an AWS account: If you don’t already have an AWS account, you can create one for free by clicking here.

Next, access the console of AWS and search for Elastic Beanstalk:

Web server environment

A web server environment is a fully managed and scalable platform that allows you to run web applications in the cloud. We are going to create our Environment and Application and deploy our web Java application.

Create Application

An application is a collection of components that work together to create an environment for your web application. Let’s select menu Applications and create a new one like this:

Create environment

An environment can include one or more Amazon Elastic Compute Cloud (EC2) instances, along with an optional Amazon RDS database instance, an Amazon S3 bucket for storage, and other AWS resources.

In this step, we will upload our generated chuck-norris-joke1.0.0-SNAPSHOT-runner.jar. We need to set Java as Platform and click on Upload your code option to select our file:

After that we just click on create environment for the process to complete

Last configurations

I decided to disable auto scaling by setting it to the single instance option to prevent AWS from scaling new instances and incurring costs for me. Feel free to configure it however you like, but keep in mind that high resource usage may result in extra charges on your account

Conclusion

Hosting the application on AWS Elastic Beanstalk simplified the deployment and scaling of the application in the cloud, allowing us to easily make it accessible to anyone with an internet connection. This exercise demonstrates the ease and flexibility of cloud computing for deploying and scaling simple web applications built with open-source technologies like Quarkus.

Well done guys, the whole project is available at my gitHub.

Thanks ❤️

Quarkus + Angular with Keycloak — Pt3

Ricardo Mello — Thu, 23 Mar 2023 02:40:41 +0000

On this article, we 'll finish the development of our daily-quotes application. If you haven’t seen the second part, click here. The main goal of this part is implement a communication between the frontend and the backend.

Angular Application

Let’s change our Angular application and generate some components that will add and list quotes. Let’s divide it into two groups:

Create quote-list
Create quote-add

Create quote-list

Generating Quote class:

$ ng generate class quote

Generating Service:

$ ng generate service quote-service

Generating quote-list component:

$ ng generate component quote-list

Implementing components
In this step we 'll change the generated components.

Open quote.ts and add the following fields:

export class Quote {
    message?: string;
    author?: string;
}

Open quote-service.service.ts and create a findAll method and define the backend restAPI http://localhost:8080/quote

import { HttpClient } from '@angular/common/http';
import { Injectable } from '@angular/core';
import { Observable } from 'rxjs';
import { Quote } from 'src/app/model/quote';

@Injectable({
  providedIn: 'root'
})
export class QuoteService {

  private quoteUrl: string;

  constructor(private http: HttpClient) {
    this.quoteUrl = 'http://localhost:8080/quote';
  }

  public findAll(): Observable<Quote[]> {
    return this.http.get<Quote[]>(this.quoteUrl);
  }
}

Open quote-list.component.ts and inject and implement service:

import { Component, OnInit } from '@angular/core';
import { Quote } from '../model/quote';
import { QuoteService } from '../services/quote/quote-service.service';

@Component({
  selector: 'app-quote-list',
  templateUrl: './quote-list.component.html',
  styleUrls: ['./quote-list.component.scss']
})
export class QuoteListComponent implements OnInit {

  quotes?: Quote[];

  constructor(private quoteService: QuoteService) {
  }

  async ngOnInit() {
      this.quoteService.findAll().subscribe(data => {
      this.quotes = data;
    });
  }

}

Open quote-list.component.html must be like this:

<div class="container">
    <div class="row" *ngFor="let quote of quotes">
        <div class="col-sm-12">

           <blockquote class="blockquote">
                <p class="mb-0">
                   {{quote.message}}
                </p>
                <footer class="blockquote-footer">
                    {{quote.author}}
                </footer>
            </blockquote>
        </div>
    </div>
</div>

Declaring QuoteListComponent and import HttpClientModule on app.module.ts:

@NgModule({
  declarations: [
    AppComponent,
    **QuoteListComponent**,
    NavbarComponent,
    AdminComponent,
  ],
  imports: [
    BrowserModule,
    CommonModule,
    AppRoutingModule,
    BrowserAnimationsModule,
    MatToolbarModule,
    MatButtonModule,
    MatMenuModule,
    MatIconModule,
    KeycloakAngularModule,
    **HttpClientModule**,
  ],

Adding QuoteListComponent route on app-routing.module.ts:

import { NgModule } from '@angular/core';
import { RouterModule, Routes } from '@angular/router';
import { AppComponent } from './app.component';
import { QuoteAddComponent } from './component/quote-add/quote-add.component.component';
import { QuoteListComponent } from './component/quote-list/quote-list.component';


const routes: Routes = [
  { path: 'home', component: AppComponent },
  { path: 'quotes', component: QuoteListComponent },
  { path: 'add', component: QuoteAddComponent },
];

@NgModule({
  imports: [RouterModule.forRoot(routes)],
  exports: [RouterModule]
})
export class AppRoutingModule { }

Finally, we have to enable http.cors on application.properties in Quarkus backend:

quarkus.http.cors=true
%dev.quarkus.http.cors.origins=/.*/

Very good 😍! We have finished implementing of quote listing route. Now, we are able to get quote from backend.

Create quote-add

Generating quote-add component:

$ ng generate component quote-add

Implementing components
In this step we 'll change the generated components.

Open quote-add.component.ts

import {Component, Inject} from '@angular/core';
import { MatDialogRef, MAT_DIALOG_DATA} from '@angular/material/dialog';
import { Quote } from 'src/app/model/quote';
import { QuoteService } from 'src/app/services/quote/quote-service.service';

export interface DialogData {
  message: string;
  author: string;
}

@Component({
  selector: 'app-quote-add',
  templateUrl: './quote-add.component.html',
  styleUrls: ['./quote-add.component.scss']
})

export class QuoteAddComponent {

  constructor(
    public dialogRef: MatDialogRef<QuoteAddComponent>,
    @Inject(MAT_DIALOG_DATA) public data: DialogData,
    private quoteService: QuoteService
  ) {}

  onNoClick(): void {
    this.dialogRef.close();
  }

}

Open quote-add.component.html

<div class="form">
    <h1 mat-dialog-title>Create new Quote</h1>

    <div mat-dialog-content>
        <mat-form-field class="field-author" appearance="outline">
            <mat-label>Author</mat-label>
            <input matInput [(ngModel)]="data.author">

        </mat-form-field>
        <mat-form-field class="field-message" appearance="outline">
            <mat-label>Message</mat-label>
            <textarea matInput [(ngModel)]="data.message"></textarea>
        </mat-form-field>
    </div>
</div>
<div mat-dialog-actions class="buttons">
    <button mat-button (click)="onNoClick()">Cancel</button>
    <button mat-button [mat-dialog-close]="data">Create</button>
</div>

Open quote-add.component.scss

.form {
    max-width: 500px;
    width: 100%;
    margin: 10px;
}

.field-author {
    align-items: center;
    margin: 10px;
}

.field-message {
    width: 400px;
    margin: 5px;
}

.buttons {
    align-items: center;
    background-color: deepskyblue;
    margin: 10px;
}

Open navbar.component.ts and change the content. It should be like this:

import { Component, OnInit } from '@angular/core';
import { KeycloakService } from 'keycloak-angular';
import { MatDialog } from '@angular/material/dialog';
import { QuoteAddComponent } from '../quote-add/quote-add.component';
import { QuoteService } from 'src/app/services/quote/quote-service.service';
import { Router } from '@angular/router';

@Component({
  selector: 'app-navbar',
  templateUrl: './navbar.component.html',
  styleUrls: ['./navbar.component.scss']
})


export class NavbarComponent implements OnInit {
  constructor(
    private readonly keycloak: KeycloakService,
    public dialog: MatDialog,
    public quoteService: QuoteService,
    public router: Router
    ) { }

  public hasAdminRole: boolean = false;

  message?: string; 
  author?: string;

  ngOnInit(): void {
    this.hasAdminRole = this.keycloak.getUserRoles().includes('admin');
   }

  public async logout() {
     this.keycloak.logout();
  }

  public add() {
    const dialogRef = this.dialog.open(QuoteAddComponent, {
      data: {message: this.message, author: this.author},
    })

    dialogRef.afterClosed().subscribe(async result => {      
      (await this.quoteService.save(result)).subscribe( result =>
        this.redirectTo('quotes')
        );      
    }    

);
  }
  redirectTo(uri:string){
    this.router.navigateByUrl('/', {skipLocationChange: true}).then(()=>
    this.router.navigate([uri]));
 }

}

Open navbar.component.html and include the add method to new quote button:

<button mat-menu-item (click)="add()">New Quote</button>

Lets create our add http method on quote-service.service.ts:

async save(quote: Quote): Promise<Observable<Quote>>{ return this.http.post<Quote>(this.quoteUrl, quote); }

Very good 😍! We have finished implementing our quote add route. Now, we are able to add new quotes.

Conclusion
On this third and last part we finished our daily-quotes application by implementing communication between the frontend and backend protected by OIDC with keycloak.

Well done guys, the whole project is available at my gitHub.

Feel comfortable to suggest, comment and contribute with this project.

Thanks ❤️

Quarkus + Angular with Keycloak — Pt2

Ricardo Mello — Thu, 23 Mar 2023 02:22:03 +0000

On this article, we 'll continue the development of our daily-quotes application. If you haven’t seen the first part, click here.

The main goal here is to implement REST API with Keycloak that will provide create and list quote endpoints.

Quakus Application

The Quarkus backend service will be responsible for create and list quotes through a REST endpoint. To get started, let’s create the project and provide some dependencies.

Type -> https://code.quarkus.io/ and create a project similar these:

Creating our project structure
I won’t go deep about architecture, therefore, we 'll be create our application using the hexagonal architecture and DDD. Let’s define some packages like this:

Configuring database
Let’s define some variable to initialize our database. Open application.properties and set:

quarkus.datasource.db-kind=postgresql 
quarkus.datasource.username=postgres
quarkus.datasource.password=postgres
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/postgres
quarkus.datasource.jdbc.max-size=16
quarkus.hibernate-orm.database.generation = drop-and-create

Notice that we have a postgres container running which was defined in docker-compose.yml file.

Defining our model
This application will have a class named Quote that will represents our model.

public class Quote {
    private Long id;
    private String message;
    private String author;

   //getters, setters ..
}

Creating QuoteService
QuoteService is an interface that provides two operations for our model. Here is the implementation :

@ApplicationScoped
@Transactional
public class QuoteServiceImpl implements QuoteService {
    @Inject
    QuoteRepository quoteRepository;

    @Override
    public Quote create(Quote quote) {
        quoteRepository.persist(quote.toEntity());
        return quote;
    }

    @Override
    public List<Quote> findAll() {
        return quoteRepository.findAll().stream().map(QuoteEntity::toDomain).toList();
    }
}

Creating QuoteController
This class will be responsible for exposing our endpoints:

@Path("/quote")
public class QuoteController {

    @Inject
    QuoteService quoteService;

    @POST()
    @Produces(MediaType.APPLICATION_JSON)
    public QuoteResponse create(Quote quote) {
        Quote q =  quoteService.create(quote);
        return new QuoteResponse(q.getMessage(), q.getAuthor());
    }

    @GET()
    public List<Quote> list() {
        return quoteService.findAll();
    }
}

Above, we injected the service that will communicate with the repository that does the write and read operations.

Note: I didn’t mention all the classes, but you can find the full implementation here.

Running the application

Let’s run our application and see the results.

$ ./gradlew quarkusDev

Accessing endpoints
Very good 😍! we create our application and define the /quote route for access.

/POST:

/GET:

Protecting our routes
Very well! our application is responding on the above two endpoints. Now let’s protect our routes using Quarkus OpenID Connect (OIDC). As like we created our frontend client, we need to do it for backend.

Creating Keycloak Client
Open Keycloak console and create a new client named backend like this:

After that, we need to enable authentication for this client:

Nice! Now, we need to get the client secret to use in our requests.

Changing our Application
Open build.gradle.kts and add Keycloak dependencies:

implementation("io.quarkus:quarkus-oidc")
implementation("io.quarkus:quarkus-keycloak-authorization")

Now, let's define some properties on application.properties

quarkus.oidc.auth-server-url=http://localhost:8188/realms/daily-quotes
quarkus.oidc.client-id=backend
quarkus.oidc.credentials.secret=secret
quarkus.oidc.tls.verification=none

As you can see, we are saying to our application that it needs to connect to Keycloak using a client-id named backend.

Now, open QuoteController and put authentication annotation on create method. It should be like this:

    @POST()
    @Authenticated
    @Produces(MediaType.APPLICATION_JSON)
    public QuoteResponse create(Quote quote) {
        quoteService.create(quote);
        return new QuoteResponse(quote.getMessage(), quote.getAuthor());
    }

Nice 😄!! When we restart our server, we 'll see that now our endpoint is protected, so it's necessary to be authenticated to access this method.

Authentication by Token

In this step, we need to get the client registration that we defined in the Keycloak (img08) and use it on client_secret to request access_token:

client_secret:

9IB9glonvC2APFdABNGNZUmNWmOkoYhR

Let’s create a post request to get access_token:

Now we just send the access_token ou Authorization key:

Conclusion
On this article we saw how to implement an authenticate Quarkus application. On the third and last post, we 'll consume those endpoints in Angular application.

Feel comfortable to suggest, comment and contribute with this project. You can find the complete source here on my GitHub.

Thanks ❤️

DEV Community: Ricardo Mello

How to Build Image Similarity Search With Atlas Functions and Triggers

Prerequisites

Document model

Atlas Trigger

Atlas Functions

Adding the function to the Trigger

What this Function does

Configuring the Voyage AI API Key

Creating the vector search index

Testing everything end-to-end

1. Insert a new article

2. Generate an embedding for the query image

Conclusion

Modeling Relationships With Hibernate ORM and MongoDB

Prerequisites

One-to-many relationship

Approach 1: Embedding reviews inside books

Evaluating the embedded model

Approach 2: Moving reviews to a separate collection

Updating the data model

Updating the configuration

Adding a review service

Linking books and reviews

Updating the console menu

Approach 3: Bringing back recent reviews (Subset Pattern)

Applying the Subset Pattern

Implementing the Subset Pattern

Create the embeddable type for recent reviews

Add the recentReview field to the Book class

Update the ReviewService

Testing the feature

Wrapping up

Getting Started With Hibernate ORM and MongoDB

How MongoDB fits in

Prerequisites

Tag your Atlas cluster

Project overview

Setting up the project

Configure Hibernate

The Book entity

Creating the SessionFactory

Implementing the Book service

Managing the SessionFactory

Understanding each method

create

findAll

update

deleteById

findBooksWithPagesGreaterThanOrEqual

Building the main application

Running the application

Current limitations (Public Preview)

Wrapping up

Beyond Keywords: Hybrid Search With Atlas and Vector Search (Part 3)

Bringing together semantic vectors and exact keyword matching with $rankFusion

One search might not be enough

Merging the best of both worlds

Prerequisites

The vector search

The full-text search

Implementing the full-text index

Executing a basic text query

Improving the experience with fuzzy search

Refining results with score boosting

Combining forces with hybrid search

The $rankFusion

How to decide the right weights

Refactoring the application

The full-text search pipeline

The vector search pipeline

The RankFusion in searchMovies

Inspecting the generated pipeline

Imprecise results without proper filtering

Making results accurate again

Adjusting the index for filters

Refactoring the pipeline in code

1. Creating the filters

2. Including search boost

3. The final pipeline

Add the recentReview field to the `Book` class

Update the `ReviewService`

The RankFusion in `searchMovies`

First try: Add a post-filter in `MovieService`

Applying `toCriteria()` in the search

Strategy with `@Cacheable`