Forem: Ricardo Mello

Spring Data Unlocked: Performance Optimization Techniques With MongoDB

Ricardo Mello — Tue, 14 Apr 2026 14:49:38 +0000

Description: Learn how to optimize a Spring Data MongoDB application through indexes and read preferences. This third and final part of the series covers single field, compound, unique, and TTL/partial indexes, as well as ReadPreference strategies.

Ah, I know! Just like in the second article, you're here because you enjoyed the initial topic, right? To recap: In the first article, we covered how to get started with MongoDB and Spring Data, exploring the difference between MongoTemplate and MongoRepository and when to use one or the other. In the second part, we took it a step further by exploring advanced queries and learning powerful concepts that Spring offers. Finally (but not least), we'll look at how to optimize our application through strategies like read preferences and indexes.

Pre-requisites

Source code
MongoDB Atlas account
- Get started with MongoDB Atlas for free! If you don't already have an account, MongoDB offers a free-forever Atlas cluster.
Java 21+
Gradle 8.8+
IDE of your choice

Why focus on MongoDB speed?

Improving performance in MongoDB is crucial for ensuring fast, efficient data access and enhancing user experience. By optimizing strategies, we can reduce latency, increase throughput, and better scale applications as they grow.

Improving performance with indexes

You've probably heard countless times that indexes are essential for achieving high performance in your queries, right? However, it's important to remember that indexes come with certain rules, and even unused indexes can negatively impact your database. In collections with a high frequency of writes compared to reads, maintaining indexes can be challenging, because each write requires updating them.

You might be wondering: "Okay, but how do I know when to create an index or not?" Well, we generally create indexes when our application frequently runs queries on the same field. In our application, let's revisit the TransactionRepository class and take a look at the findByTransactionType(String type) method:

@Repository
public interface TransactionRepository extends MongoRepository<Transaction, String> {
    List<Transaction> findByTransactionType(String type);
    // Other methods ..
}

This method is responsible for retrieving transactions by type. To understand the cost of this query, we can run the explain() command:

db.transactions.find({"transactionType": "Debit"}).explain()

Or, in our case, we'll run a query directly using Spring. In CustomerService, create the following method:

public String explain() {
    MongoCollection<Document> collection = mongoOperations.getCollection("transactions");
    Document query = new Document("transactionType", "Debit");
    Document explanation = collection.find(query).explain();
    logger.info(explanation.toJson());
    return explanation.toJson();
}

The explain() command provides the query execution plan, detailing how MongoDB processes the query. In our case, since we don't have an index, it returns a COLLSCAN (collection scan).

Single field index

To optimize this, let's create an index for this query. Traditionally, we create the index as follows:

db.transactions.createIndex({"transactionType": 1})

However, since we are exploring Spring's options, we'll create the index in a different way. To do this, simply navigate to the Transaction class (which represents our collection) and annotate the desired field with the @Indexed annotation:

import lombok.Data;
import org.springframework.data.annotation.Id;
import org.springframework.data.mongodb.core.index.Indexed;
import org.springframework.data.mongodb.core.mapping.Document;

@Document(collection = "transactions")
@Data
public class Transaction {
    @Indexed
    private String transactionType;
    // Other fields
}

For this to work, we need to enable auto-index creation in the application properties by adding the following configuration:

spring:
  data:
    mongodb:
      auto-index-creation: true

Notice: While this is a convenient way to create indexes during development, it's important to exercise caution in production environments. Auto-index creation can cause the application startup to pause while the index is being created, which might lead to delays or availability issues if not handled carefully. For production scenarios, consider creating indexes explicitly during a controlled process outside the application lifecycle.

Compound index

Continuing our exploration of indexes, we now have compound indexes. As the name suggests, these indexes combine more than one field for query purposes. Let's assume we have a query that searches by both the transaction type and currency:

@Repository
public interface TransactionRepository extends MongoRepository<Transaction, String> {
    List<Transaction> findByTransactionTypeAndCurrency(String type, String currency);
    // Other methods
}

To optimize this query, we could create the compound index as follows:

@CompoundIndex(name = "type_currency", def = "{'transactionType': 1, 'currency': 1}")
@Data
public class Transaction {
    // fields
}

Unique indexes

The @Indexed interface includes a unique() method, which is set to false by default. This means that any field annotated with @Indexed will not enforce uniqueness by default. However, we can specify that we want the field to be unique.

Imagine that in our Transaction class, we have a field called authCode, responsible for ensuring that each transaction is unique. We can annotate the class as follows:

public class Transaction {
    @Indexed(unique = true)
    private String authCode;
}

This annotation ensures that the transactions collection will not have any duplicate authCode values. If a duplicate code is provided, MongoDB will throw the following exception:

com.mongodb.MongoWriteException - E11000 duplicate key error collection

TTL/partial index

Let's suppose that we have a function in our application that executes a query to find all transactions older than 40 days with a status of "COMPLETED" or "SUCCESS" and runs a delete command.

In this case, we would have two steps:

Filter all transactions in this state.
Perform a delete operation on these items.

This can be expensive for your application. An alternative is to use the TTL index, which automatically expires documents after a certain amount of time. We can tell our application:

Hey, I want you to delete all records that were created more than 40 days ago and are in the "SUCCESS" or "COMPLETED" state:

public class Transaction {
    @Indexed(
        name = "PartialIndex",
        expireAfterSeconds = 3456000, // 40 days
        partialFilter = "{ 'status': { $in: ['SUCCESS', 'COMPLETED'] } }"
    )
    private LocalDateTime createdAt;
}

In this way, the application will expire (delete) the transactions that meet this filter.

Optimizing reads with ReadPreference

Using ReadPreference can improve latency and performance by directing reads to secondary replicas that are closer, reducing the load on the primary node and optimizing data distribution in geographically distributed systems.

As shown in the image above, by default, all write operations occur on the primary node, while read operations can be directed to secondary nodes. There are several read preference modes, such as:

Let's go back to our TransactionRepository class and mark the findByTransactionType method to perform the search using the secondaryPreferred mode:

@Repository
public interface TransactionRepository extends MongoRepository<Transaction, String> {
    @ReadPreference("secondaryPreferred")
    List<Transaction> findByTransactionType(String type);
}

Another alternative is to apply the mode to the entire application through the connection settings. In MongoConfig, you can configure the read preference mode globally. Here's how you can do it:

@Configuration
public class MongoConfig {
    @Bean
    public MongoClient mongoClient() {
        MongoClientSettings settings = MongoClientSettings.builder()
            .applyConnectionString(new ConnectionString(connectionString))
            .readPreference(ReadPreference.nearest())
            .build();
        return MongoClients.create(settings);
    }
}

Conclusion

In this third and final part of the Spring Data Unlocked series, we learned how to create indexes directly through the application, adjust read preferences with ReadPreference, and optimize the performance of our queries. The complete code for the application is available in the mongodb-developer repository.

For more information on improving query performance with indexes, visit the indexes documentation.

If you have any questions, feel free to reach out to us through the MongoDB Community.

Spring Data Unlocked: Advanced Queries With MongoDB

Ricardo Mello — Tue, 14 Apr 2026 14:47:54 +0000

Description: Explore Spring Data's capabilities by creating advanced queries with MongoRepository and MongoTemplate. This second part of the series covers derived queries, @Query, @Update, @Aggregation, pagination, and bulk operations.

I bet you're here because you've already read the first article in this series, Getting Started With Java and MongoDB. But even if you haven't, don't worry—you're in the right place. In the first part of this series, we explored key concepts related to Spring and learned how to create a project and configure it to seamlessly integrate with MongoDB.

This is the second part of the series Spring Data Unlocked, where we will continue working on our project and explore Spring Data's capabilities by creating advanced queries and seeing how seamlessly it can be done.

Pre-requisites

Source code
MongoDB Atlas account
- Get started with MongoDB Atlas for free! If you don't already have an account, MongoDB offers a free-forever Atlas cluster.
Java 21+
Gradle 8.8+
IDE of your choice

Refreshing our memory

If you don't remember what we discussed earlier, don't worry. Read the previous article on how to get started with Java and MongoDB or refresh your memory with the image of our data model that we are working on.

Our transaction model contains this structure, and we will proceed with it.

The MongoRepository

Still focusing on productivity and speed, we will continue using our MongoRepository interface and create a query to retrieve our transactions by type. Open the TransactionRepository class and add the following method:

List<Transaction> findByTransactionType(String type);

As you can see, we are finding all transactions by the type. Spring, through naming conventions (derived queries), allows you to create queries based on the method names.

Tip: We can monitor the log process by enabling a DEBUG setting in the application.properties file:
logging.level.org.springframework.data.mongodb=DEBUG

We will be able to see the query in the console:

2024-10-15T18:30:33.855-03:00 DEBUG 28992 --- [SpringShop] [nio-8080-exec-6] o.s.data.mongodb.core.MongoTemplate : find using query: { "transactionType" : "Transfer"} fields: Document{{}} sort: { "transactionType" : "Transfer"} for class: class com.mongodb.Transaction in collection: transactions

Now, let's say we want all transactions where the amount is greater than 3000:

List<Transaction> findByAmountGreaterThan(double amount);

It is possible to delete records in the same way. Take a look:

void deleteByTransactionType(String type);

If everything is working correctly, your code should be similar to this:

package com.mongodb;

import org.springframework.data.mongodb.repository.MongoRepository;
import org.springframework.stereotype.Repository;
import java.util.List;

@Repository
public interface TransactionRepository extends MongoRepository<Transaction, String> {
    List<Transaction> findByTransactionType(String type);
    List<Transaction> findByAmountGreaterThan(double amount);
    void deleteByTransactionType(String type);
}

@Query

Continuing our development, we can use the Query class that Spring provides instead of working with derived queries. This alternative is also interesting. Below is an example of how to fetch transactions by status, displaying (Projection) only the fields createdAt, accountDetail, and amount, and sorting by createdAt in descending order:

@Query(
    value = "{ 'status' : ?0 }",
    fields = "{ 'createdAt': 1, 'accountDetails' : 1, 'amount' : 1 }",
    sort = "{ createdAt: -1 }"
)
List<Transaction> findByStatus(String status);

@Update

We can also perform update operations on our database using this annotation. Notice in the code below that we are combining @Query and @Update. In the first part, we apply the filter, and then we proceed to update the status.

@Query("{ '_id' : ?0 }")
@Update("{ '$set' : { 'status' : ?1 } }")
void updateStatus(String id, String status);

@Aggregation

Another important annotation in Spring Data is @Aggregation. As the name suggests, it allows us to create aggregation stages. Let's imagine the following scenario:

We want to return the total amount grouped by transaction type. To do this, we'll create the following method:

@Aggregation(pipeline = {
    "{ '$match': { 'transactionType': ?0 } }",
    "{ '$group': { '_id': '$transactionType', 'amount': { '$sum': '$amount' } } }",
    "{ '$project': { 'amount': 1 } }"
})
List<Transaction> getTotalAmountByTransactionType(String transactionType);

In the first stage, $match, we filter the transactions by the specified type.
In the second stage, $group, we group the transactions by transactionType and sum the values from the amount field.
Finally, in the $project stage, we display the total amount.

A new request from our product team has come in, and they want us to save all transactions with an error status in a new collection. We could set up a job to run once a day and trigger a method to handle this for us. For that, we can use MongoDB's $out stage:

@Aggregation(pipeline = {
    "{ '$match': { 'status': 'error' } }",
    "{ '$project': { '_id': 1, 'amount': 1, 'status': 1, 'description': 1, 'createdAt': 1 } }",
    "{ '$out': 'error_transactions' }"
})
void exportErrorTransactions();

After this method is executed, the aggregation will process, and any documents with an error status will be inserted into a new collection within the same database called error_transactions.

Let's break it down again:

$match to filter transactions with an error status
$project to specify which fields we want to include in the error collection
$out to define the collection where we will export the error transactions

Note: While we won't go into the specifics of $out, I highly recommend reviewing its behavior before using it in a production environment.

As you can see, this annotation is very powerful and can provide features for increasingly complex queries. Let's assume we now have a new collection called customers with some additional fields:

{
  "name": "Ricardo Mello",
  "email": "ricardo.mello@mongodb.com",
  "accountNumber": "2234987651",
  "phone": "5517992384610",
  "address": {
    "street": "Street 001",
    "city": "New York"
  }
}

We can use $lookup to perform a join between the transaction and customer collections using the accountNumber field and bring in extra values like phone and address.

@Aggregation(pipeline = {
    "{ '$lookup': { " +
        "'from': 'customer', " +
        "'localField': 'accountDetails.originator.accountNumber', " +
        "'foreignField': 'accountNumber', " +
        "'as': 'originatorCustomerDetails' } }",
    "{ '$project': { " +
        "'amount': 1, " +
        "'status': 1, " +
        "'accountDetails': 1, " +
        "'originatorCustomerDetails': 1 } }"
})
List<CustomerOriginatorDetail> findTransactionsWithCustomerDetails();

In the code above, we're using the $lookup operator to join the new customer collection through the accountNumber field, and returning a new list of CustomerOriginatorDetail.

public record CustomerOriginatorDetail(
    double amount,
    String status,
    Transaction.AccountDetails accountDetails,
    List<OriginatorCustomerDetails> originatorCustomerDetails
) {
    private record OriginatorCustomerDetails(
        String name,
        String accountNumber,
        String phone,
        Address address) {
        private record Address(String city, String street) {}
    }
}

Note: Remember, we're not focusing on data modeling here, just showing that it's possible to work with $lookup in this context.

Custom aggregation

Another approach with the @Aggregation annotation is to create an interface that represents an aggregation, which simplifies its usage. Our SearchAggregate annotation enables the creation of reusable search functionality using MongoDB's aggregation framework, facilitating efficient and structured querying of text data in your database.

import org.springframework.data.mongodb.repository.Aggregation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.METHOD })
@Aggregation(pipeline = {
    "{ '$search': { 'text': { 'query': ?0, 'path': ?1 } } }"
})
@interface SearchAggregate {
}

Now, to utilize our annotation in a method, we can pass the arguments for the query and path in the TransactionRepository class:

@SearchAggregate
List<Transaction> search(String query, String path);

PagingAndSortingRepository

An important aspect to note is that if we look through the interfaces extended by MongoRepository, we'll find PagingAndSortingRepository, which includes the method:

Page<T> findAll(Pageable pageable);

This method is crucial for working with pagination. Let's go back to our TransactionService and implement the following code:

public Page<Transaction> findPageableTransactions(Pageable pageable) {
    return transactionRepository.findAll(pageable);
}

Now, in the TransactionController, we can make the paginated call as follows:

@GetMapping("/pageable")
public PagedModel<Transaction> findAll(
    @RequestParam(defaultValue = "0") int page,
    @RequestParam(defaultValue = "100") int sizePerPage,
    @RequestParam(defaultValue = "ID") String sortField,
    @RequestParam(defaultValue = "DESC") Sort.Direction sortDirection) {
    Pageable pageable = PageRequest.of(page, sizePerPage, Sort.by(sortDirection, sortField));
    return new PagedModel<>(transactionService.findPageableTransactions(pageable));
}

And finally, we can call our method using the following curl command:

curl --location 'http://localhost:8080/transactions?page=0&sizePerPage=10&sortField=description&sortDirection=ASC'

The MongoTemplate

A very interesting alternative to achieve flexibility and control over MongoDB operations is MongoTemplate. This template supports operations like update, insert, and select and also provides a rich interaction with MongoDB, allowing us to map our domain objects directly to the document model in the database. Let's start by creating a new MongoConfig class:

package com.mongodb;

import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.mongodb.core.MongoOperations;
import org.springframework.data.mongodb.core.MongoTemplate;

@Configuration
public class MongoConfig {
    @Bean
    public MongoClient mongoClient() {
        MongoClientSettings settings = MongoClientSettings.builder()
            .applyConnectionString(new ConnectionString("<your connection string>"))
            .build();
        return MongoClients.create(settings);
    }

    @Bean
    MongoOperations mongoTemplate(MongoClient mongoClient) {
        return new MongoTemplate(mongoClient, "springshop");
    }
}

We can observe the @Bean annotation from Spring, which allows us to work with the injected MongoTemplate in our services. Continuing with our development, we will work with the Customer class to manipulate it. To do so, create the Customer record:

package com.mongodb;

public record Customer(
    String name,
    String email,
    String accountNumber,
    String phone,
    Address address
) {
    public record Address(
        String street,
        String city
    ) {}
}

Insert

Let's start with the basic insertion model and then evolve to other operations. To do this, we will create our CustomerService with the following method:

import org.springframework.data.mongodb.core.MongoOperations;
import org.springframework.stereotype.Service;

@Service
public class CustomerService {
    private final MongoOperations mongoOperations;

    CustomerService(MongoOperations mongoOperations) {
        this.mongoOperations = mongoOperations;
    }

    public Customer newCustomer() {
        var customer = new Customer(
            "Ricardo",
            "ricardohsmello@gmail.com",
            "123",
            "1234",
            new Customer.Address("a", "Sp")
        );
        return mongoOperations.insert(customer);
    }
}

Our service will work with mongoOperations, which will handle the insertion of our document.

Note: I am creating new Customer to illustrate the insertion. A good practice would be to receive this Customer as an argument in our function.

BulkWrite

One way to handle bulk insertions is by using bulkWrite. The MongoTemplate provides us with the bulkOps method, where we can provide a list, and it will be executed in batches:

public void bulkCustomer(List<Customer> customerList) {
    BulkWriteResult result = mongoOperations.bulkOps(
        BulkOperations.BulkMode.ORDERED, Customer.class
    ).insert(customerList)
     .execute();

    System.out.println(result.getInsertedCount());
}

Query

Moving on to queries, we have the implementation of queries in the MongoTemplate class. In the code below, we are searching for a customer by email and returning only one:

public Customer findCustomerByEmail(String email) {
    return mongoOperations.query(Customer.class)
        .matching(query(where("email").is(email)))
        .one()
        .orElseThrow(() -> new RuntimeException("Customer not found with email: " + email));
}

The query method (imported statically) expects a Criteria (where), also imported statically, where we can apply various filters such as gt(), lt(), and(), and or(). For reference, see the Spring documentation.

Aggregation

Let's imagine we need a query that returns the total number of customers by city. To do this, we need to group by city and count the number of customers. To achieve this goal, first, let's create a new record to handle it:

public record CustomersByCity(
    String id,
    int total
) {}

And then, we will create a totalCustomerByCity method:

public List<CustomersByCity> totalCustomerByCity() {
    TypedAggregation<Customer> aggregation = newAggregation(Customer.class,
        group("address.city")
            .count().as("total"),
        Aggregation.sort(Sort.Direction.ASC, "_id"),
        project(Fields.fields("total", "_id")));

    AggregationResults<CustomersByCity> result = mongoOperations.aggregate(aggregation, CustomersByCity.class);
    return result.getMappedResults();
}

The static method newAggregation offers us a good approach to manipulate our aggregation stages. We are grouping by city and using the count() function, which internally performs a sum on the total number of customers, sorting by _id in ascending order and displaying both the total and id fields.

Conclusion

In this second part of our series, Spring Data Unlocked, we explored how to create complex queries with MongoRepository and MongoTemplate. This tutorial covered concepts such as pagination, custom annotations, bulk inserts, and powerful aggregation queries.

The complete code is available in mongo-developer.

If you have any questions, feel free to leave them in the comments.

Spring Data Unlocked: Getting Started With Java and MongoDB

Ricardo Mello — Tue, 14 Apr 2026 14:39:03 +0000

Description: Learn how to integrate MongoDB with Spring Data in a simple and easy way. This first part of the series covers getting started with Spring Data, modeling your data, and using MongoRepository to perform basic CRUD operations.

If you are a Java developer who is passionate about MongoDB and Spring, I have good news: You're in the right place.

This series of articles will explore how to integrate MongoDB with Spring Data in a very simple and easy way. The main idea is to have a vision of how to take the first step and, at the same time, evolve our knowledge by exploring the capabilities that Spring Data offers us.

By the end of this series, you'll have a clear understanding of the differences between MongoRepository and MongoTemplate, know when to use each one, and be able to create complex queries while improving their performance by using indexes.

Pre-requisites

MongoDB Atlas account
- Get started with MongoDB Atlas for free! If you don't already have an account, MongoDB offers a free-forever Atlas cluster.
Java 21+
Gradle 8.8+
IDE of your choice

Spring Data

Spring Data is a solution that simplifies data access in databases like MongoDB. Its main goal is to provide an easy and consistent approach to working with data while preserving the unique characteristics of MongoDB. And, of course, all of this is within the Spring ecosystem.

We can perform basic CRUD operations easily, and the framework can automatically create queries based on method names, reducing the amount of boilerplate code we need to write. Some key points:

Repository support: Spring offers us a way to communicate with MongoDB at a high level of abstraction, providing very simple CRUD operations to use.
Query derivation: We can create quick queries using the method signature, which is ideal for those who want agility.
Mapping and serialization: Simplify the mapping and serialization of objects through annotations.
Aggregation framework: Spring provides support for the aggregation framework through annotations and also through the aggregation class itself.
Auto-index-Creation: We have the option to work with indexes managed by Spring itself (we will explore this in more detail in the second series of this article).

The business model

To explore the capabilities of Spring, we will define a data model where we will work with transactions between bank accounts. Our model will ultimately deliver a document like this:

{
   "id": "672182814338f60133ee26e1",
   "transactionType": "Debit",
   "amount": 888.0,
   "currency": "USD",
   "status": "In Progress",
   "description": "Transfer to Ricardo",
   "createdAt": "2024-10-09T14:00:00",
   "accountDetails": {
       "originator": {
           "accountNumber": "2376543213",
           "name": "Maria",
           "bank": "Bank G"
       },
       "beneficiary": {
           "accountNumber": "2234987651",
           "name": "Ricardo Mello",
           "bank": "Bank V"
       }
   }
}

As you can see, we have several types of fields and subdocuments, which will be very useful for exploring our queries.

The Java application

To build our application, let's use Spring Initializr using the following options:

Project: Gradle - Kotlin
Language: Java
Spring Boot: The latest version

We'll also add the following dependencies:

Lombok: This simplifies code by automatically generating boilerplate code, like getters and setters.
Spring Web: We'll use this to create endpoints for our application.
Spring Data MongoDB: We'll use this to store data in flexible, JSON-like (BSON) documents.

After that, simply click on "Generate" and open the project in your favorite IDE (I'm using IntelliJ).

Setting up the application

To connect to MongoDB using Spring, we'll use the application.properties file and define the following variables:

spring.application.name=SpringShop
spring.data.mongodb.uri=<YOUR_CONNECTION_STRING>
spring.data.mongodb.database=springshop

The transaction class

Next, we will create our transaction class (based on our business model). To do this, simply create a class as follows:

package com.mongodb;

import lombok.Data;
import org.springframework.data.annotation.Id;
import org.springframework.data.mongodb.core.mapping.Document;
import java.time.LocalDateTime;

@Document(collection = "transactions")
@Data
public class Transaction {
   @Id
   private String id;
   private String transactionType;
   private Double amount;
   private String currency;
   private String status;
   private String description;
   private LocalDateTime createdAt;
   private AccountDetails accountDetails;

   public record AccountDetails(Originator originator, Beneficiary beneficiary) {}
   public record Originator(String accountNumber, String name, String bank) {}
   public record Beneficiary(String accountNumber, String name, String bank) {}
}

The transaction class is quite simple and includes the information from our model. Here, we have three annotations that I would like to discuss:

@Document: This indicates to Spring that this class is a MongoDB document.
@Data: This is a Lombok annotation that generates boilerplate code such as getters, setters, toString, equals, and hashCode methods.
@Id: This will automatically generate an _id (ObjectId) for us.

MongoTemplate and MongoRepository

Before we move on to communication with MongoDB, we need to talk about the level of abstraction. MongoTemplate and MongoRepository are both part of Spring Data and offer different levels of abstraction for interacting with MongoDB.

While MongoRepository is designed for those who want faster development, MongoTemplate is better suited for those who need more flexibility.

MongoTemplate	MongoRepository
Low-level abstraction	High-level abstraction
When you require precise control over MongoDB operations	When you want Spring Data to automatically create queries for you
When you need to run complex queries or aggregations	When you need basic CRUD operations
When you need to do custom updates or bulk actions	When you prefer simplicity and convention over configuration

Alright, now that we can differentiate between them, we can choose one (or both) to work with.

TransactionRepository

Now, it's time to create our class that will handle communication with MongoDB. In this first part, we'll focus on simplicity and efficiency and use the MongoRepository interface provided by Spring. To do this, create a class called TransactionRepository as shown below:

package com.mongodb;

import org.springframework.data.mongodb.repository.MongoRepository;
import org.springframework.stereotype.Repository;

@Repository
public interface TransactionRepository extends MongoRepository<Transaction, String> {}

In this example, we're extending the MongoRepository interface, which allows us to inherit several powerful features provided by Spring Data that we can apply to our Transaction entity.

Service and controller

Let's take advantage of the high level of abstraction provided by MongoRepository and create two methods for insertion and querying. To do this, we will create a TransactionService class:

package com.mongodb;

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

@Service
public class TransactionService {
   private final TransactionRepository transactionRepository;

   public TransactionService(TransactionRepository transactionRepository) {
       this.transactionRepository = transactionRepository;
   }

   List<Transaction> getTransactions() {
       return transactionRepository.findAll();
   }

   public Transaction save(Transaction transaction) {
       return transactionRepository.save(transaction);
   }
}

Now, to finish this first part of our series, we will create our controller to test the insert and find operations. To do this, simply execute the following code:

package com.mongodb;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.List;

@RestController
@RequestMapping("/transactions")
public class TransactionController {
   private final TransactionService transactionService;

   public TransactionController(TransactionService transactionService, TransactionRepository transactionRepository) {
       this.transactionService = transactionService;
   }

   @GetMapping
   public List<Transaction> getTransactions() {
       return transactionService.getTransactions();
   }

   @PostMapping
   public ResponseEntity<Transaction> create(@RequestBody Transaction transaction) {
       return ResponseEntity.status(HttpStatus.CREATED).body(transactionService.save(transaction));
   }
}

Notice: We could create some classes to better handle our traffic objects. However, we will focus on simplicity for now.

Testing our endpoint

If you haven't run the application yet, remember to update the connection string to your database. With the application running, let's insert a document using the following cURL command:

curl --location 'http://localhost:8080/transactions' \
--header 'Content-Type: application/json' \
--data '{
    "transactionType": "Transfer",
    "amount": 1500.5,
    "currency": "USD",
    "status": "Completed",
    "description": "Transfer to Ricardo",
    "createdAt": "2024-10-09T14:00:00.000Z",
    "accountDetails": {
        "originator": {
            "accountNumber": "9876543210",
            "name": "Maria Faria",
            "bank": "Bank A"
        },
        "beneficiary": {
            "accountNumber": "1234987654",
            "name": "Ricardo Mello",
            "bank": "Bank B"
        }
    }
}'

If everything goes well, we can query our records using the findAll method:

curl --location 'http://localhost:8080/transactions'

I'm using Postman to perform the cURL requests and see the results. As you can see, our inserted document matches the model we defined initially.

Conclusion

In this first part of the Spring Data Unlocked series, we learned how to get started with Spring Data and MongoDB. The article demonstrates how to create a project from scratch and integrate it in a simple and straightforward way. We modeled our entity that will be used in the upcoming articles, where we will explore the capabilities of Spring with aggregations and more complex queries.

If you have any questions, feel free to leave them in the comments.

The complete code is available in mongo-developer GitHub.

Java Meets Queryable Encryption: Developing a Secure Bank Account Application

Ricardo Mello — Tue, 14 Apr 2026 14:24:07 +0000

Description: Learn how to seamlessly integrate Java with MongoDB Queryable Encryption in a fully automated way. This process allows you to leverage the advanced encryption features of MongoDB, ensuring that your data remains protected even during complex queries, without the need for manual encryption or decryption steps

Encryption is essential for protecting data by converting readable information (plaintext) into an unintelligible form (ciphertext) using cryptographic techniques. This process ensures that, even if unauthorized parties gain access, they cannot interpret the data without the proper decryption key. It plays a vital role in safeguarding sensitive information like personal details, financial records, and confidential communications, whether the data is stored or in transit.

Traditional encryption methods, while securing data from unauthorized access, often require decrypting the data before it can be queried or analyzed. This can pose security risks since the data is exposed in its unencrypted form during processing. The goal is to find a way to perform queries on encrypted data without compromising its security.

MongoDB Queryable Encryption makes protecting your data easier than ever. It ensures your data stays encrypted, even while running queries. All the encryption and decryption happens on the client side, meaning the server never gets access to plain, readable data. This also applies to services like MongoDB Atlas and cloud providers — they only see encrypted data, which significantly boosts your data’s privacy and security. This protects you from external threats and ensures that database administrators, who have access to the database but not to the encryption keys, can’t view or understand your data. So, even if someone manages to break into the server or cloud infrastructure, all they’ll find is encrypted information that they can’t decrypt without the proper keys.

Demonstration: How Queryable Encryption works

In this tutorial, we’ll create a Java application called "BankAccount" to demonstrate how Queryable Encryption works. Our goal is to build an app that saves and retrieves documents from a database named "digitalBank."
These documents will include:

accountHolderName.
accountNumber (encrypted).
cardVerificationCode (encrypted).
accountBalance (encrypted).

We’ll set up the application to create an endpoint that allows us to search for documents using two types of queries:

Equality queries: To find documents that match a specific accountNumber
Range queries: To find documents with values within a certain range (e.g., greater than a specified amount)

The Automatic Encryption feature will handle the encryption and decryption of data for us, so we can focus on building the application without needing to be encryption experts.

Pre-requisites

Here’s what you’ll need to follow along in this tutorial:

MongoDB 8.0 Atlas account
- Get started with MongoDB Atlas for free! If you don’t already have an account, MongoDB offers a free-forever Atlas cluster.
Java 21+
Gradle 8.8+
Automatic Encryption Shared Library version 7.0 or later
IDE of your choice

Queryable Encryption

Queryable Encryption is a MongoDB feature designed to enable secure queries on encrypted data. It allows encrypted fields to be queried using various operators, such as equality and range, while maintaining the confidentiality of the data.
With Queryable Encryption, you can:

Encrypt sensitive fields directly from the client side.
Execute expressive queries on the encrypted data.

These processes are carried out without the server having access to the unencrypted data. Sensitive information remains encrypted at all stages — in transit, at rest, during use, and in backups — and is only decrypted on the client side, where you retain control over the encryption keys.

This advanced encryption method allows for both secure storage and searching of data, developed by leading experts in the field. Importantly, the technology behind it has been published and thoroughly reviewed by peers, ensuring its robustness and credibility.

You can find more about this research and its validation at the Cryptography Research Group.

Additionally, this encryption solution is not only secure but also built to perform well in real-world scenarios, balancing both high security and practical usability.

The image above demonstrates the Queryable Encryption flow for the application we will implement

The user will perform two queries using accountNumber and accountBalance.
These queries will be detected by the MongoDB Java driver, which will identify that these fields are encrypted.
The driver will then send an encrypted query along with a token to the MongoDB server.
MongoDB will return the encrypted data from the database.
The Java driver will decrypt the data and present the results to the user.

It’s important to note that the data remains encrypted at all times
in the database. Without the decryption key, even with root access,
it would be impossible to retrieve the information from the
encrypted fields.

Creating the Java application

Creating the project

To achieve our goal, we will develop a Spring Boot application that will provide endpoints for inserting and retrieving data. To do this, we will use Spring Initializr, as usual, to set up our application. Configure your application according to the image below.

Setting up the project

At this stage, we will add some dependencies to the project and configure the automatic encryption model. To start, open the pom.xml file and include the following dependencies:

    <dependency>
       <groupId>org.projectlombok</groupId>
       <artifactId>lombok</artifactId>
       <optional>true</optional>
    </dependency>
    <dependency>
       <groupId>org.mongodb</groupId>
       <artifactId>mongodb-driver-sync</artifactId>
       <version>5.1.3</version>
    </dependency>
    <dependency>
       <groupId>org.mongodb</groupId>
       <artifactId>mongodb-crypt</artifactId>
       <version>1.11.0</version>
    </dependency>

Configuring Automatic Encryption: KMS and Crypt Shared Library

To enable automatic Queryable Encryption in our Java project, we need to configure settings in the application.properties file. This setup involves two key components:

Automatic Encryption Shared Library: The Automatic Encryption Shared Library is crucial for managing encrypted data in your application. It handles encryption and decryption, ensures that only supported operations are performed on encrypted fields, and manages which fields are encrypted.
- Download the library: Obtain the Automatic Encryption Shared Library from the MongoDB Download Center. Select the appropriate version (e.g., 0.0) and platform. Choose the crypt_shared package and download it.

Key Management Service (KMS): The KMS is responsible for managing and storing the encryption keys used to secure data. For this example, we are using a local KMS setup. However, for production environments, it is highly recommended to use a KMS service to ensure enhanced security and scalability.

Here are the settings you'll need to include in your application.properties file:

    app.mongodb.uri=mongodb+srv://user:password@cluster0.cluster.mongodb.net/
    app.mongodb.kmsProviderName=local
    app.mongodb.keyVaultNamespace=encryption.__keyVault
    app.mongodb.encryptedDatabaseName=digitalBank
    app.mongodb.encryptedCollectionName=accounts
    app.mongodb.cryptSharedLibPath=/<path-to-lib>/mongo_crypt_v1.dylib

Understanding the configurations:

app.mongodb.uri=YOUR_CONNECTION_STRING
- Specifies your MongoDB Atlas connection string
app.mongodb.kmsProviderName=local
- Specifies the KMS provider name
- app.mongodb.keyVaultNamespace=encryption.__keyVault
- Defines the namespace for the key vault where encryption keys are stored. In this setup, keys are stored in the __keyVault collection within the encryption database. These keys are secured using the customer's key, so the server never sees them in an unencrypted state. This ensures that the keys remain protected and confidential.
- app.mongodb.encryptedDatabaseName=digitalBank
  - Specifies the name of the database where encrypted data will be stored
- app.mongodb.encryptedCollectionName=accounts
- Indicates the collection within the database where encrypted account details will be held
- app.mongodb.cryptSharedLibPath=/PATH_TO_LIB/mongo_crypt_v1.dylib
- Points to the location of the Automatic Encryption Shared Library on your system. This dynamic library is essential for enabling automatic encryption and decryption. Replace /PATH_TO_LIB/ with the actual path to where the mongo_crypt_v1.dylib file is located on your machine.

Configuring encryption classes

In this section, we will configure the encryption-related classes to enable automatic encryption and decryption in our Spring Boot application using MongoDB. Our goal is to set up the necessary components to manage encrypted data securely. Create a new Java file named EncryptionConfig in the resources/config package:

    package com.mongodb.bankaccount.resources.config;

    import com.mongodb.AutoEncryptionSettings;
    import com.mongodb.ClientEncryptionSettings;
    import com.mongodb.ConnectionString;
    import com.mongodb.MongoClientSettings;
    import com.mongodb.client.MongoDatabase;
    import lombok.Data;
    import org.springframework.boot.ApplicationRunner;
    import org.springframework.boot.context.properties.ConfigurationProperties;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import java.io.File;
    import java.io.FileInputStream;
    import java.io.FileOutputStream;
    import java.io.IOException;
    import java.security.SecureRandom;
    import java.util.HashMap;
    import java.util.Map;

    @Data
    @Configuration
    @ConfigurationProperties(prefix = "app.mongodb")
    public class EncryptionConfig {

       private String uri;
       private String kmsProviderName;
       private String keyVaultNamespace;
       private String encryptedDatabaseName;
       private String encryptedCollectionName;
       private String cryptSharedLibPath;

       private static final String CUSTOMER_KEY_PATH = "src/main/resources/customer-key.txt";
       private static final int KEY_SIZE = 96;
       private final Map<String, Map<String, Object>> kmsProviderCredentials = new HashMap<>();

       @Bean
       public ApplicationRunner createEncryptedCollectionRunner(MongoDatabase db, EncryptionFieldConfig encryptionFieldConfig) {
           return args -> {
               if (!encryptionFieldConfig.collectionExists(db, encryptedCollectionName)) {
                   encryptionFieldConfig.createEncryptedCollection(db, clientEncryptionSettings());
               }
           };
       }

       private ClientEncryptionSettings clientEncryptionSettings() throws Exception {
           return ClientEncryptionSettings.builder()
                   .keyVaultMongoClientSettings(getMongoClientSettings())
                   .keyVaultNamespace(keyVaultNamespace)
                   .kmsProviders(kmsProviderCredentials)
                   .build();
       }

       protected MongoClientSettings getMongoClientSettings() throws Exception {
           kmsProviderCredentials.put("local", createLocalKmsProvider());

           AutoEncryptionSettings autoEncryptionSettings = AutoEncryptionSettings.builder()
                   .keyVaultNamespace(keyVaultNamespace)
                   .kmsProviders(kmsProviderCredentials)
                   .extraOptions(createExtraOptions())
                   .build();

           return MongoClientSettings.builder()
                   .applyConnectionString(new ConnectionString(uri))
                   .autoEncryptionSettings(autoEncryptionSettings)
                   .build();
       }

       private Map<String, Object> createLocalKmsProvider() throws IOException {
           if (!isCustomerMasterKeyFileExists()) {
               generateCustomerMasterKey();
           }

           byte[] localCustomerMasterKey = readCustomerMasterKey();
           Map<String, Object> keyMap = new HashMap<>();
           keyMap.put("key", localCustomerMasterKey);
           return keyMap;
       }

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

       private void generateCustomerMasterKey() throws IOException {
           byte[] localCustomerMasterKey = new byte[KEY_SIZE];
           new SecureRandom().nextBytes(localCustomerMasterKey);
           try (FileOutputStream stream = new FileOutputStream(CUSTOMER_KEY_PATH)) {
               stream.write(localCustomerMasterKey);
           } catch (IOException e) {
               throw new IOException("Unable to write Customer Master Key file: " + e.getMessage(), e);
           }
       }

       private byte[] readCustomerMasterKey() throws IOException {
           byte[] localCustomerMasterKey = new byte[KEY_SIZE];

           try (FileInputStream fis = new FileInputStream(CUSTOMER_KEY_PATH)) {
               int bytesRead = fis.read(localCustomerMasterKey);
               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 localCustomerMasterKey;
       }

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

In our application, the EncryptionConfig class plays a critical role in setting up and managing encryption for MongoDB. Here’s a breakdown of its key functionalities, focusing particularly on the Key Management Service (KMS) and the cryptographic library path (cryptSharedLibPath).

Key Management Service (KMS) configuration:
- KMS provider: The class is configured to use a KMS provider, specified by the kmsProviderName property. For local development and testing, we use a local KMS provider. This local setup simplifies development but is not recommended for production.
  - Customer master key: The class handles the generation and management of a local customer master key. It first checks if the key file (customer-key.txt) exists. If it does not, the class generates a new key and saves it. This key is crucial for encrypting and decrypting data. The key is then read from the file and used in the encryption process.
- KMS provider credentials: The method createLocalKmsProvider() creates a map with the customer master key, which is used in both clientEncryptionSettings() and getMongoClientSettings() methods. This setup ensures that the MongoDB client can handle encryption correctly.
Cryptographic Library Path (cryptSharedLibPath):
- Library Path Configuration: The cryptSharedLibPath property specifies the path to the Automatic Encryption Shared Library. This library is essential for enabling automatic encryption and decryption of data within MongoDB. The path to this library is included in the encryption settings through the createExtraOptions() method, allowing the MongoDB client to utilize the cryptographic functionalities provided by the library.

Key functionalities of the class:

Client encryption settings: The clientEncryptionSettings() method configures the settings required for managing encryption keys and processes. This setup is crucial for ensuring that data is encrypted and decrypted according to our specifications.
MongoDB client settings: The getMongoClientSettings() method incorporates auto-encryption settings into the MongoDB client configuration. It ensures that the client can connect to the MongoDB instance using the provided URI and handle encryption as required.
Encrypted collection creation: The createEncryptedCollectionRunner() method ensures that an encrypted collection is created if it does not already exist. This setup uses the defined encryption settings to ensure data security.

Next, create the EncryptionFieldConfig in the resources/config package:

    package com.mongodb.bankaccount.resources.config;

    import com.mongodb.ClientEncryptionSettings;
    import com.mongodb.client.MongoDatabase;
    import com.mongodb.client.model.CreateCollectionOptions;
    import com.mongodb.client.model.CreateEncryptedCollectionParams;
    import com.mongodb.client.vault.ClientEncryptions;
    import org.bson.*;
    import org.springframework.context.annotation.Configuration;
    import java.util.ArrayList;
    import java.util.Arrays;

    @Configuration
    public class EncryptionFieldConfig {

       protected boolean collectionExists(MongoDatabase db, String collectionName) {
           return db.listCollectionNames().into(new ArrayList<>()).contains(collectionName);
       }

       protected void createEncryptedCollection(MongoDatabase db, ClientEncryptionSettings clientEncryptionSettings) {
           var clientEncryption = ClientEncryptions.create(clientEncryptionSettings);
           var encryptedCollectionParams = new CreateEncryptedCollectionParams("local")
                   .masterKey(new BsonDocument());

           var createCollectionOptions = new CreateCollectionOptions().encryptedFields(encryptFields());
           clientEncryption.createEncryptedCollection(db, "accounts", createCollectionOptions, encryptedCollectionParams);
       }

       private BsonDocument encryptFields() {
           return new BsonDocument().append("fields",
                   new BsonArray(Arrays.asList(
                           createEncryptedField("accountNumber", "string", equalityQueryType()),
                           createEncryptedField("cardVerificationCode", "int", equalityQueryType()),
                           createEncryptedField("accountBalance", "double", rangeQueryType()
                           ))));
       }

       private BsonDocument createEncryptedField(String path, String bsonType, BsonDocument query) {
           return new BsonDocument()
                   .append("keyId", new BsonNull())
                   .append("path", new BsonString(path))
                   .append("bsonType", new BsonString(bsonType))
                   .append("queries", query);
       }

       private BsonDocument rangeQueryType() {
           return new BsonDocument()
                   .append("queryType", new BsonString("range"))
                   .append("min", new BsonDouble(0))
                   .append("max", new BsonDouble(999999999))
                   .append("precision", new BsonInt32(2));
       }

       private BsonDocument equalityQueryType() {
           return new BsonDocument().append("queryType", new BsonString("equality"));
       }
    }

In the EncryptionFieldConfig class, we focus on specifying which fields in our MongoDB collection will be encrypted to ensure data security. Here’s a brief overview of what this class does, with an emphasis on the fields that will be encrypted:

Defining encrypted fields:
- The primary role of this class is to configure field-level encryption. Using the encryptFields() method, we define which fields in the MongoDB collection need to be encrypted. In our case, we’re encrypting three critical fields: - accountNumber (type: string, query type: equality): This field contains sensitive account information that needs protection. - cardVerificationCode (type: int, query type: equality): This field holds sensitive verification codes, which must be encrypted to ensure security. - accountBalance (type: double, query type: range): This field represents financial data, and encryption is applied with support for range-based queries to handle financial computations securely. For range queries, the optional min, max, and precision are pretty important for performance. You can find more about this in Encrypted Fields and Enabled Queries
Creating and managing encrypted collections:
- The createEncryptedCollection() method is used to check whether the specified collection exists in the database. If it doesn’t, the method creates a new collection with the defined encryption settings. This setup is managed through ClientEncryptions.create(), which applies the encryption configurations.
Field encryption metadata:
- For each field, the createEncryptedField() method specifies essential metadata, including the field path, BSON type, and query type. This metadata helps MongoDB understand how to encrypt and decrypt the data while supporting various query operations.
Handling query types:
- Different query types are assigned to the fields to control how encrypted data can be queried. For example, equality queries allow us to search for exact matches, while range queries enable us to perform range-based searches on encrypted financial data.

And now, create the MongoConfig class in the resources/config package:

    package com.mongodb.bankaccount.resources.config;

    import com.mongodb.MongoClientSettings;
    import com.mongodb.client.MongoClient;
    import com.mongodb.client.MongoClients;
    import com.mongodb.client.MongoDatabase;
    import org.bson.codecs.configuration.CodecProvider;
    import org.bson.codecs.configuration.CodecRegistry;
    import org.bson.codecs.pojo.PojoCodecProvider;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import static com.mongodb.MongoClientSettings.getDefaultCodecRegistry;
    import static org.bson.codecs.configuration.CodecRegistries.fromProviders;
    import static org.bson.codecs.configuration.CodecRegistries.fromRegistries;

    @Configuration
    public class MongoConfig {

       private final EncryptionConfig encryptionConfig;

       public MongoConfig(EncryptionConfig encryptionConfig) {
           this.encryptionConfig = encryptionConfig;
       }

       @Bean
       public MongoClient mongoClient() throws Exception {
           MongoClientSettings mongoClientSettings = encryptionConfig.getMongoClientSettings();
           return MongoClients.create(mongoClientSettings);
       }

       @Bean
       public MongoDatabase mongoDatabase(MongoClient mongoClient) {
           CodecProvider pojoCodecProvider = PojoCodecProvider.builder().automatic(true).build();
           CodecRegistry pojoCodecRegistry = fromRegistries(getDefaultCodecRegistry(), fromProviders(pojoCodecProvider));

           return mongoClient.getDatabase(encryptionConfig.getEncryptedDatabaseName()).withCodecRegistry(pojoCodecRegistry);
       }
    }

This class is straightforward; it only contains our MongoDB configuration.

Now, to finalize, simply open the BankaccountApplication class and add the annotation @EnableConfigurationProperties(EncryptionConfig.class) to enable reading of our properties in this class.

    package com.mongodb.bankaccount;

    import com.mongodb.bankaccount.resources.config.EncryptionConfig;
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import org.springframework.boot.context.properties.EnableConfigurationProperties;

    @SpringBootApplication
    @EnableConfigurationProperties(EncryptionConfig.class)
    public class BankaccountApplication {

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

By the end, we will have this structure configured:

Creating the repository

Now that we have our encryption and database connection files defined, let's create our repository that will handle communication with Atlas and create our queries. To do this, first create a BankAccountEntity record in the resources package:

    package com.mongodb.bankaccount.resources;

    import com.mongodb.bankaccount.domain.BankAccount;

    public record BankAccountEntity(
           String accountHolderName,
           String accountNumber,
           int cardVerificationCode,
           Double accountBalance) {
       public BankAccount toDomain() {
           return new BankAccount(accountHolderName, accountNumber, cardVerificationCode, accountBalance);
       }
    }

Then, create the BankAccountRepository class also in the resources package:

    package com.mongodb.bankaccount.resources;

    import com.mongodb.bankaccount.domain.BankAccount;
    import com.mongodb.bankaccount.domain.BankAccountPort;
    import com.mongodb.client.MongoCollection;
    import com.mongodb.client.MongoDatabase;
    import com.mongodb.client.result.InsertOneResult;
    import org.bson.types.ObjectId;
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.stereotype.Repository;
    import java.util.ArrayList;
    import java.util.List;
    import java.util.Objects;
    import java.util.stream.Collectors;
    import static com.mongodb.client.model.Filters.eq;
    import static com.mongodb.client.model.Filters.gt;

    @Repository
    public class BankAccountRepository implements BankAccountPort {
       private static final Logger logger = LoggerFactory.getLogger(BankAccountRepository.class);
       private static final String COLLECTION_NAME = "accounts";
       private final MongoCollection<BankAccountEntity> collection;

       BankAccountRepository(MongoDatabase mongoDatabase) {
           this.collection = mongoDatabase.getCollection(COLLECTION_NAME, BankAccountEntity.class);
       }

       @Override
       public String insert(BankAccount bankAccount) {
           try {
               InsertOneResult insertOneResult = collection.insertOne(bankAccount.toEntity());
               ObjectId result = Objects.requireNonNull(insertOneResult.getInsertedId()).asObjectId().getValue();

               logger.info("{} was created", result);

               return result.toHexString();
           } catch (Exception e) {
               logger.error(e.getMessage(), e);
               throw new RuntimeException("Error inserting bank account", e);
           }
       }

       @Override
       public List<BankAccount> find() {
           try {
               ArrayList<BankAccountEntity> bankAccounts = new ArrayList<>();
               collection.find().into(bankAccounts);

               return bankAccounts.stream()
                       .map(BankAccountEntity::toDomain)
                       .collect(Collectors.toList());

           } catch (Exception e) {
               logger.error(e.getMessage(), e);
               throw new RuntimeException("Error finding bank account", e);
           }
       }

       @Override
       public List<BankAccount> findByBalanceGreaterThan(double value) {
           try {
               ArrayList<BankAccountEntity> bankAccounts = new ArrayList<>();
               collection.find(gt("accountBalance", value)).into(bankAccounts);

               return bankAccounts.stream()
                       .map(BankAccountEntity::toDomain)
                       .collect(Collectors.toList());

           } catch (Exception e) {
               logger.error(e.getMessage(), e);
               throw new RuntimeException("Error finding bank account", e);
           }
       }

       @Override
       public BankAccount findByAccountNumber(String accountNumber) {
           try {
               BankAccountEntity result = collection.find(eq("accountNumber", accountNumber)).first();

               if (result == null) {
                   return null;
               }

               return result.toDomain();

           } catch (Exception e) {
               logger.error(e.getMessage(), e);
               throw new RuntimeException("Error finding bank account", e);
           }

       }
    }

You might be wondering about some files that we haven't created yet, but don't worry, we'll get to those soon. Before we do, let's examine what our repository class is doing:

The BankAccountRepository class is set up to interact with our accounts collection in MongoDB, providing methods for querying and inserting data.

Notice that we have a findByBalanceGreaterThan method that performs a range query to find accounts with a balance greater than a specified value. We also have the findByAccountNumber method, which uses an equality query to locate accounts with a specific account number.

Additionally, you'll see that BankAccountRepository implements an interface called BankAccountPort. This interface acts as a contract, defining the methods that our repository class must implement. It helps to isolate the domain logic from the data access layer, promoting a cleaner architecture and easier testing.

Creating the service

Let’s continue by creating the remaining domain classes. To do this, we'll create a domain package and include the BankAccount record:

    package com.mongodb.bankaccount.domain;

    import com.mongodb.bankaccount.application.web.BankResponse;
    import com.mongodb.bankaccount.resources.BankAccountEntity;

    public record BankAccount(
       String accountHolderName,
       String accountNumber,
       int cardVerificationCode,
       Double accountBalance) {
       public BankResponse toResponse() {
           return new BankResponse(accountHolderName, accountNumber, cardVerificationCode, accountBalance);
       }

       public BankAccountEntity toEntity() {
           return new BankAccountEntity(accountHolderName, accountNumber, cardVerificationCode, accountBalance);
       }
    }

Next, in the same domain package, the BankAccountPort:

    package com.mongodb.bankaccount.domain;

    import java.util.List;

    public interface BankAccountPort {
       String insert(BankAccount bankAccount);
       List<BankAccount> find();
       List<BankAccount> findByBalanceGreaterThan(double value);
       BankAccount findByAccountNumber(String accountNumber);
    }

And finally, the BankAccountService:

    package com.mongodb.bankaccount.domain;

    import org.springframework.stereotype.Service;
    import java.util.List;
    import java.util.Objects;

    @Service
    public class BankAccountService {

       BankAccountPort bankAccountPort;

       BankAccountService(BankAccountPort bankAccountPort) {
           this.bankAccountPort = bankAccountPort;
       }

       public String insert(BankAccount bankAccount) {
           Objects.requireNonNull(bankAccount, "Bank account must not be null");    
           return bankAccountPort.insert(bankAccount);
        }

       public List<BankAccount> find() {
           return bankAccountPort.find();
       }

       public List<BankAccount> findByBalanceGreaterThan(double value) {
           return bankAccountPort.findByBalanceGreaterThan(value);
       }

       public BankAccount findByAccountNumber(String accountNumber) { 
           return bankAccountPort.findByAccountNumber(accountNumber);
       }

    }

Creating the controller

In this final step, we will provide our controller endpoints. To do this, create a package called application.web and within it, create the first class BankController class:

    package com.mongodb.bankaccount.application.web;

    import com.mongodb.bankaccount.domain.BankAccount;
    import com.mongodb.bankaccount.domain.BankAccountService;
    import org.springframework.http.ResponseEntity;
    import org.springframework.web.bind.annotation.*;
    import java.util.List;

    @RestController
    @RequestMapping("/bank")
    public class BankController {

       BankAccountService bankAccountService;

       BankController(BankAccountService bankAccountService) {
           this.bankAccountService = bankAccountService;
       }

       @PostMapping
       ResponseEntity<String> create(@RequestBody BankRequest bankRequest) {
           return ResponseEntity.ok(bankAccountService.insert(bankRequest.toDomain()));
       }

       @GetMapping
       ResponseEntity<List<BankResponse>> getAllAccounts() {
           return ResponseEntity.ok(bankAccountService.find().stream().map(BankAccount::toResponse).toList());
       }

       @GetMapping("/balance/greaterThan/{value}")
       ResponseEntity<List<BankResponse>> findByBalanceGreaterThan(@PathVariable Double value) {
           return ResponseEntity.ok(bankAccountService.findByBalanceGreaterThan(value).stream().map(BankAccount::toResponse).toList());
       }

       @GetMapping("/accountNumber/{accountNumber}")
       ResponseEntity<BankResponse> getAccountByNumber(@PathVariable String accountNumber) {
           BankAccount bankAccount = bankAccountService.findByAccountNumber(accountNumber);
           if (bankAccount != null) {
               return ResponseEntity.ok(bankAccount.toResponse());
           } else {
               return ResponseEntity.notFound().build();
           }
       }
    }

Now, let's create the two missing records and adjust the necessary imports. Still within the application.web package, create the BankRequest record:

    package com.mongodb.bankaccount.application.web;

    import com.mongodb.bankaccount.domain.BankAccount;

    record BankRequest(
           String accountHolderName,
           String accountNumber,
           int cardVerificationCode,
           Double accountBalance) {
       public BankAccount toDomain() {
           return new BankAccount(accountHolderName, accountNumber, cardVerificationCode, accountBalance);
       }
    }

And BankResponse:

    package com.mongodb.bankaccount.application.web;

    public record BankResponse(String accountHolderName,
                              String accountNumber,
                              int cardVerificationCode,
                              Double accountBalance) {
    }

Perfect! Now, just correct the imports in the classes that use our records, and everything will be set. Our structure will look like this:

Running the application

In this final step, simply execute the following command to run the application:

./mvnw spring-boot:run

If the application starts correctly, open the database we’re connecting to, and you will notice that the digitalBank and encryption databases, along with the accounts and __keyVault collections, have been created. This step happens once when we configure the files in the resources/config folder.

Creating a new document

To create a new document, simply access the @post endpoint described in the BankAccountController. Below is a curl command to insert a new document:

curl --location 'http://localhost:8080/bank' \
      --header 'Content-Type: application/json' \
      --data '{
      "accountHolderName": "Ricardo Mello",
      "accountNumber": "4527876391233218",
      "cardVerificationCode": "761",
      "accountBalance": 5000.2
      }'

After running this curl command, you will see that the document has been created with the fields accountNumber, cardVerificationCode, and accountBalance encrypted as defined in EncryptionFieldConfig class, as shown in the image below:

Note: You will see that a safeContent field has been created. This
field will be present in all encrypted documents, and it is crucial
that this data is not modified or deleted. For more information, refer
to encrypted-collection-management.

Querying by equality

To explore the equality type of encrypted search, you can search for documents by accountNumber. To do this, simply run the following curl command:

curl --location 'http://localhost:8080/bank/accountNumber/{accountNumber}

Result:

Querying by range

To explore range queries (e.g., greaterThan), use the following endpoint:

curl --location 'http://localhost:8080/bank/balance/greaterThan/{value}'

Result:

Conclusion

Our demonstration using the "BankAccount" Java application clearly illustrates how MongoDB Queryable Encryption can be implemented. By integrating automatic encryption, the workflow is simplified, enabling developers to focus on the core features without needing deep expertise in security. Queryable Encryption ensures secure execution of equality and range queries on encrypted data, offering a seamless balance between strong data protection and the ability to handle complex operations.

This tutorial illustrates one approach to leveraging Queryable Encryption, but it's important to recognize that alternative methods and configurations exist. I encourage you to explore these options to identify the most suitable solution for your specific requirements. Doing so will deepen your understanding of secure data practices and enhance your ability to implement effective data protection strategies.
For a complete view of the Java project, you can access the repository at github-mongodb-developer.

Any questions? Come chat with us in the MongoDB Developer Community

Mastering Kotlin: Creating an API With Ktor and MongoDB Atlas

Ricardo Mello — Tue, 14 Apr 2026 14:14:37 +0000

Description: Set up a Ktor project, implement CRUD operations, define API route endpoints, and run the application. Understand Kotlin's capabilities in API development.

Kotlin's simplicity, Java interoperability, and Ktor's user-friendly framework combined with MongoDB Atlas' flexible cloud database provide a robust stack for modern software development.

Together, we'll demonstrate and set up the Ktor project, implement CRUD operations, define API route endpoints, and run the application. By the end, you'll have a solid understanding of Kotlin's capabilities in API development and the tools needed to succeed in modern software development.

Demonstration

As you can see above, our application will be capable of performing the operations depicted in the image. To accomplish this, we will utilize a data model structured similarly to the example provided:

fitness {
    _id: objectId,
    exerciseType: String,
    notes: String,
    fitnessDetails: {
        durationMinutes: Int,
        distance: Double,
        caloriesBurned: Int
    }
}

Setting up the Ktor project

Ktor is a Kotlin-based, asynchronous web framework designed for building modern web applications and APIs. Developed by JetBrains, the same team behind Kotlin, Ktor simplifies the process of building web applications while offering robust support for asynchronous programming using Kotlin coroutines.

To begin our project setup, we'll make use of the Ktor project generator.

As depicted in the images, we need to configure parameters such as the project name, configuration file, etc.

In the subsequent section, we specify the following plugins:

Content Negotiation: facilitates the negotiation of media types between the client and server
GSON: offers serialization and deserialization capabilities
Routing: manages incoming requests within a server application
Swagger: simplifies API documentation and development

Once all settings are in place, simply click "Generate Project" to proceed with creating our project.

After importing the project, let's proceed by opening the build.gradle.kts file to incorporate additional dependencies. Specifically, we'll be adding dependencies for the MongoDB server-side Kotlin driver and Koin for injection dependency.

dependencies {
    implementation("io.ktor:ktor-server-core-jvm")
    implementation("io.ktor:ktor-server-swagger-jvm")
    implementation("io.ktor:ktor-server-content-negotiation-jvm")
    implementation("io.ktor:ktor-serialization-gson-jvm")
    implementation("io.ktor:ktor-server-tomcat-jvm")
    implementation("ch.qos.logback:logback-classic:$logback_version")

    //MongoDB
    implementation("org.mongodb:mongodb-driver-kotlin-coroutine:4.10.1")

    //Koin Dependency Injection
    implementation("io.insert-koin:koin-ktor:3.5.3")
    implementation("io.insert-koin:koin-logger-slf4j:3.5.3")
}

Implementing CRUD operations

Before creating our project, let's organize it into several packages. To achieve this, we'll create three packages: application, domain, and infrastructure as shown in the image below:

Now, let's create a package called entity inside domain and include a file named Fitness.kt:

domain/entity/Fitness.kt

package com.mongodb.domain.entity
import com.mongodb.application.response.FitnessResponse
import org.bson.codecs.pojo.annotations.BsonId
import org.bson.types.ObjectId

data class Fitness(
    @BsonId
    val id: ObjectId,
    val exerciseType: String,
    val notes: String,
    val details: FitnessDetails
){
    fun toResponse() = FitnessResponse(
        id = id.toString(),
        exerciseType = exerciseType,
        notes = notes,
        details = details
    )
}

data class FitnessDetails(
    val durationMinutes: Int,
    val distance: Double,
    val caloriesBurned: Int
)

As you can observe, our class has an error in the toResponse() method because we haven't created the FitnessResponse class yet. To fix this issue, we need to create the FitnessResponse class. Let's take this opportunity to create both FitnessResponse and FitnessRequest. These classes will handle the data exchanged in HTTP requests related to the Fitness entity. Inside the application package, create request and response packages. Include the FitnessRequest and FitnessResponse classes in each, respectively.

application/request/FitnessRequest.kt:

package com.mongodb.application.request

import com.mongodb.domain.entity.Fitness
import com.mongodb.domain.entity.FitnessDetails
import org.bson.types.ObjectId

data class FitnessRequest(
    val exerciseType: String,
    val notes: String,
    val details: FitnessDetails
)
fun FitnessRequest.toDomain(): Fitness {
    return Fitness(
        id = ObjectId(),
        exerciseType = exerciseType,
        notes = notes,
        details = details
    )
}

application/response/FitnessResponse.kt:

package com.mongodb.application.response


import com.mongodb.domain.entity.FitnessDetails


data class FitnessResponse(
    val id: String,
    val exerciseType: String,
    val notes: String,
    val details: FitnessDetails
)

If everything is correct, our structure will look similar to the image below:

Now, it's time to create our interface that will communicate with our database. To do this, within the domain package, we will create another package called ports, and subsequently, the FitnessRepository interface.

domain/ports/FitnessRepository:

package com.mongodb.domain.ports

import com.mongodb.domain.entity.Fitness
import org.bson.BsonValue
import org.bson.types.ObjectId

interface FitnessRepository {
    suspend fun insertOne(fitness: Fitness): BsonValue?
    suspend fun deleteById(objectId: ObjectId): Long
    suspend fun findById(objectId: ObjectId): Fitness?
    suspend fun updateOne(objectId: ObjectId, fitness: Fitness): Long
}

Perfect! Now, we need to implement the methods of our interface. We'll access the infrastructure package and create a repository package inside it. After that, create a class FitnessRepositoryImpl, then implement the methods as shown in the code below:

infrastructure/repository/FitnessRepositoryImpl

package com.mongodb.infrastructure.repository

import com.mongodb.MongoException
import com.mongodb.client.model.Filters
import com.mongodb.client.model.UpdateOptions
import com.mongodb.client.model.Updates
import com.mongodb.domain.entity.Fitness
import com.mongodb.domain.ports.FitnessRepository
import com.mongodb.kotlin.client.coroutine.MongoDatabase
import kotlinx.coroutines.flow.firstOrNull
import org.bson.BsonValue
import org.bson.types.ObjectId

class FitnessRepositoryImpl(
    private val mongoDatabase: MongoDatabase
) : FitnessRepository {

    companion object {
        const val FITNESS_COLLECTION = "fitness"
    }

    override suspend fun insertOne(fitness: Fitness): BsonValue? {
        try {
            val result = mongoDatabase.getCollection<Fitness>(FITNESS_COLLECTION).insertOne(
                fitness
            )
            return result.insertedId
        } catch (e: MongoException) {
            System.err.println("Unable to insert due to an error: $e")
        }
        return null
    }

    override suspend fun deleteById(objectId: ObjectId): Long {
        try {
            val result = mongoDatabase.getCollection<Fitness>(FITNESS_COLLECTION).deleteOne(Filters.eq("_id", objectId))
            return result.deletedCount
        } catch (e: MongoException) {
            System.err.println("Unable to delete due to an error: $e")
        }
        return 0
    }

    override suspend fun findById(objectId: ObjectId): Fitness? =
    mongoDatabase.getCollection<Fitness>(FITNESS_COLLECTION).withDocumentClass<Fitness>()
    .find(Filters.eq("_id", objectId))
    .firstOrNull()

    override suspend fun updateOne(objectId: ObjectId, fitness: Fitness): Long {
        try {
            val query = Filters.eq("_id", objectId)
            val updates = Updates.combine(
                Updates.set(Fitness::exerciseType.name, fitness.exerciseType),
                Updates.set(Fitness::notes.name, fitness.notes),
                Updates.set(Fitness::details.name, fitness.details)
            )
            val options = UpdateOptions().upsert(true)
            val result =
            mongoDatabase.getCollection<Fitness>(FITNESS_COLLECTION)
            .updateOne(query, updates, options)

            return result.modifiedCount
        } catch (e: MongoException) {
            System.err.println("Unable to update due to an error: $e")
        }
        return 0
    }
}

As observed, the class implements the FitnessRepository interface and includes a companion object. It receives a MongoDatabase instance as a constructor parameter. The companion object defines a constant named FITNESS_COLLECTION, with a value of "fitness," indicating the name of the MongoDB collection where operations such as insert, find, delete, and update are performed on fitness-related data.

If everything is correct, our structure will be as follows:

Developing API endpoints

To create our endpoints, understanding routing is crucial. In Ktor, routing dictates how the server handles incoming requests to specific URLs, enabling developers to define actions or responses for each endpoint. Before proceeding with the creation process, let's briefly review the endpoints we'll be constructing:

GET /fitness/{id}: Utilize this endpoint to fetch detailed information about a specific fitness activity based on its unique identifier (ID).
POST /fitness: With this endpoint, you can effortlessly add new fitness activities to your tracker, ensuring all your workout data is up-to-date.
PATCH /fitness/{id}: Need to update or modify an existing fitness activity? This endpoint allows you to make targeted changes to specific activities identified by their unique ID.
DELETE /fitness/{id}: Finally, this endpoint empowers you to remove unwanted or outdated fitness activities from your tracker, maintaining a clean and accurate record of your fitness journey.

Now that we know the methods we will implement, let's create our class that will do this work. Inside the application package, let's create a new one called routes and the file below with the name FitnessRoute.kt with the content below:

application/routes/FitnessRoutes.kt

package com.mongodb.application.routes

import com.mongodb.application.request.FitnessRequest
import com.mongodb.application.request.toDomain
import com.mongodb.domain.ports.FitnessRepository
import io.ktor.http.HttpStatusCode
import io.ktor.server.application.call
import io.ktor.server.request.receive
import io.ktor.server.response.respond
import io.ktor.server.response.respondText
import io.ktor.server.routing.route
import io.ktor.server.routing.Route
import io.ktor.server.routing.post
import io.ktor.server.routing.delete
import io.ktor.server.routing.get
import io.ktor.server.routing.patch
import org.bson.types.ObjectId
import org.koin.ktor.ext.inject

fun Route.fitnessRoutes() {
    val repository by inject<FitnessRepository>()
    route("/fitness") {
        post {
            val fitness = call.receive<FitnessRequest>()
            val insertedId = repository.insertOne(fitness.toDomain())
            call.respond(HttpStatusCode.Created, "Created fitness with id $insertedId")
        }

        delete("/{id?}") {
            val id = call.parameters["id"] ?: return@delete call.respondText(
                text = "Missing fitness id",
                status = HttpStatusCode.BadRequest
            )
            val delete: Long = repository.deleteById(ObjectId(id))
            if (delete == 1L) {
                return@delete call.respondText("Fitness Deleted successfully", status = HttpStatusCode.OK)
            }
            return@delete call.respondText("Fitness not found", status = HttpStatusCode.NotFound)
        }

        get("/{id?}") {
            val id = call.parameters["id"]
            if (id.isNullOrEmpty()) {
                return@get call.respondText(
                    text = "Missing id",
                    status = HttpStatusCode.BadRequest
                )
            }
            repository.findById(ObjectId(id))?.let {
                call.respond(it.toResponse())
            } ?: call.respondText("No records found for id $id")
        }

        patch("/{id?}") {
            val id = call.parameters["id"] ?: return@patch call.respondText(
                text = "Missing fitness id",
                status = HttpStatusCode.BadRequest
            )
            val updated = repository.updateOne(ObjectId(id), call.receive())
            call.respondText(
                text = if (updated == 1L) "Fitness updated successfully" else "Fitness not found",
                status = if (updated == 1L) HttpStatusCode.OK else HttpStatusCode.NotFound
            )
        }
    }
}

As you can observe, we've set up method calls and utilized call to define actions within route handlers. Ktor allows you to manage incoming requests and send responses directly within these handlers, providing flexibility in handling different request scenarios. Additionally, we're utilizing Koin for dependency injection in the FitnessRepository repository.

Now, before we proceed to run the application, we need to install the Koin dependency and incorporate it as a module.

Modules in Ktor are used to organize and encapsulate functionality within your application. They allow you to group related routes, dependencies, and configurations for easier management and maintenance.

To accomplish this, open the Application.kt class and replace all of its code with the one below:

com.mongodb.Application.kt

package com.mongodb

import com.mongodb.application.routes.fitnessRoutes
import com.mongodb.domain.ports.FitnessRepository
import com.mongodb.infrastructure.repository.FitnessRepositoryImpl
import com.mongodb.kotlin.client.coroutine.MongoClient
import io.ktor.serialization.gson.gson
import io.ktor.server.application.Application
import io.ktor.server.application.install
import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
import io.ktor.server.plugins.swagger.swaggerUI
import io.ktor.server.routing.routing
import io.ktor.server.tomcat.EngineMain
import org.koin.dsl.module
import org.koin.ktor.plugin.Koin
import org.koin.logger.slf4jLogger

fun main(args: Array<String>): Unit = EngineMain.main(args)

fun Application.module() {
    install(ContentNegotiation) {
        gson {
        }
    }
    install(Koin) {
        slf4jLogger()
        modules(module {
            single { MongoClient.create(
                environment.config.propertyOrNull("ktor.mongo.uri")?.getString() ?: throw RuntimeException("Failed to access MongoDB URI.")
            ) }
            single { get<MongoClient>().getDatabase(environment.config.property("ktor.mongo.database").getString()) }
        }, module {
            single<FitnessRepository> { FitnessRepositoryImpl(get()) }
        })
    }
    routing {
        swaggerUI(path = "swagger-ui", swaggerFile = "openapi/documentation.yaml") {
            version = "4.15.5"
        }
        fitnessRoutes()
    }
}

Let's break down what this code is doing into three main sections for easier understanding:

ContentNegotiation configuration: We're setting up ContentNegotiation to handle JSON serialization and deserialization. Specifically, we're using Gson as the default JSON formatter, ensuring seamless communication between our application and clients.
Dependency injection with Koin: In the subsequent section, we're integrating Koin for dependency injection management. Within the first module, we establish the connection to MongoDB, retrieving the URI and database name from the configuration.conf file. Subsequently, we define injection for the FitnessRepository.
Routing configuration: During the routing phase, we configure the Swagger API route, accessible at /swagger-ui. Furthermore, we specify our route for handling Fitness-related operations.

Great. Now, we need to make the final adjustments before running our application. First, open the application.conf file and include the following information:

resources/application.conf

ktor {
    deployment {
        port = 8080
    }
    application {
        modules = [ com.mongodb.ApplicationKt.module ]
    }
    mongo {
        uri = ${?MONGO_URI}
        database = ${?MONGO_DATABASE}
    }
}

Note: These variables will be used at the end of the article when we run the application.

Very well. Now, just open the documentation.yaml file and replace it with the content below. In this file, we are indicating which methods our API will provide when accessed through /swagger-ui:

resources/openapi/documentation.yaml

openapi: 3.0.0
info:
 title: Fitness API
 version: 1.0.0
 description: |
   This Swagger documentation file outlines the API specifications for a Fitness Tracker application built with Ktor and MongoDB. The API allows users to manage fitness records including creating new records, updating and deleting records by ID. The API uses the Fitness and FitnessDetails data classes to structure the fitness-related information.

paths:
 /fitness:
   post:
     summary: Create a new fitness record
     requestBody:
       required: true
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/FitnessRequest'
     responses:
       '201':
         description: Fitness created successfully
       '400':
         description: Bad request
 /fitness/{id}:
   get:
     summary: Retrieve fitness record by ID
     parameters:
       - name: id
         in: path
         required: true
         schema:
           type: string
     responses:
       '200':
         description: Successful response
         content:
           application/json:
             example: {}
       '404':
         description: Fitness not found
   delete:
     summary: Delete fitness record by ID
     parameters:
       - name: id
         in: path
         required: true
         schema:
           type: string
     responses:
       '200':
         description: Fitness deleted successfully
       '400':
         description: Bad request
       '404':
         description: Fitness not found
   patch:
     summary: Update fitness record by ID
     parameters:
       - name: id
         in: path
         required: true
         schema:
           type: string
     requestBody:
       required: true
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/FitnessRequest'
     responses:
       '200':
         description: Fitness updated successfully
       '400':
         description: Bad request
       '404':
         description: Fitness not found

components:
 schemas:
   Fitness:
     type: object
     properties:
       id:
         type: string
         format: uuid
       exerciseType:
         type: string
       notes:
         type: string
       details:
         $ref: '#/components/schemas/FitnessDetails'
     required:
       - id
       - notes
       - details

   FitnessDetails:
     type: object
     properties:
       durationMinutes:
         type: integer
         format: int32
       distance:
         type: number
         format: double
       caloriesBurned:
         type: integer
         format: int32
     required:
       - durationMinutes
       - distance
       - caloriesBurned

   FitnessRequest:
     type: object
     properties:
       exerciseType:
         type: string
       notes:
         type: string
       details:
         $ref: '#/components/schemas/FitnessDetails'
     required:
       - exerciseType
       - notes
       - details

The final adjustment is to delete the plugins folder, which contains the HTTP.kt, Routing.kt, and Serialization.kt files, as we have already included them in the Application.kt class. Additionally, delete the ApplicationTest class since our focus here is not on tests. After these changes, your structure should look similar to this:

Running the application

To run our application, we need a connection string from MongoDB Atlas. If you don't have access yet, create your account.

Once your account is created, access the Overview menu, then Connect, and select Kotlin. After that, our connection string will be available as shown in the image below:

With the connection string in hand, let's return to IntelliJ, open the Application.kt class, and click on the run button, as shown in the image:

At this stage, you will notice that our application encountered an error connecting to MongoDB Atlas. This is where we need to provide the MONGO_URI and MONGO_DATABASE defined in the application.conf file:

To do this, simply edit the configuration and include the values as shown in the image below:

-DMONGO_URI= Add your connection string
-DMONGO_DATABASE= Add your database name

Click "Apply" and run the application again.

Attention: Remember to change the connection string to your username, password, and cluster in MongoDB Atlas.

Now, simply access localhost:8080/swagger-ui and perform the operations.

Open the post method and insert an object for testing:

We can see the data recorded in our MongoDB Atlas cluster as shown in the image below:

Conclusion

MongoDB Atlas, Ktor, and Kotlin API service together form a powerful combination for building robust and scalable applications. MongoDB Atlas provides a cloud-based database solution that offers flexibility, scalability, and reliability, making it ideal for modern applications. Ktor, with its lightweight and asynchronous nature, enables rapid development of web services and APIs in Kotlin, leveraging the language's concise syntax and powerful features. When combined, MongoDB Atlas and Ktor in Kotlin allow developers to build high-performance APIs with ease, providing seamless integration with MongoDB databases while maintaining simplicity and flexibility in application development. This combination empowers developers to create modern, data-driven applications that can easily scale to meet evolving business needs.

The example source code used in this series is available in Github.

Any questions? Come chat with us in the MongoDB Developer Community.

Beyond Basics: Enhancing Kotlin Ktor API With Vector Search

Ricardo Mello — Tue, 14 Apr 2026 14:11:40 +0000

Description: Learn how to integrate Vector Search into your Kotlin with Ktor application using MongoDB.

In this article, we will delve into advanced MongoDB techniques in conjunction with the Kotlin Ktor API, building upon the foundation established in our previous article, Mastering Kotlin: Creating an API With Ktor and MongoDB Atlas. Our focus will be on integrating robust features such as Hugging Face, Vector Search, and MongoDB Atlas triggers/functions to augment the functionality and performance of our API.

We will start by providing an overview of these advanced MongoDB techniques and their critical role in contemporary API development. Subsequently, we will delve into practical implementations, showcasing how you can seamlessly integrate Hugging Face for natural language processing, leverage Vector Search for rapid data retrieval, and automate database processes using triggers and functions.

Prerequisites

MongoDB Atlas account
- Note: Get started with MongoDB Atlas for free! If you don’t already have an account, MongoDB offers a free-forever Atlas cluster.
Hugging Face account
Source code from the previous article
MongoDB Tools

Demonstration

We'll begin by importing a dataset of fitness exercises into MongoDB Atlas as documents. Then, we'll create a trigger that activates upon insertion. For each document in the dataset, a function will be invoked to request Hugging Face's API. This function will send the exercise description for conversion into an embedded array, which will be saved into the exercises collection as descEmbedding:

In the second part, we will modify the Kotlin Ktor application to incorporate HTTP client calls, enabling interaction with the Hugging Face API. Additionally, we will create a /exercises/processRequest endpoint. This endpoint will accept a text input, which will be processed using the Hugging Face API to generate an embedded array. Subsequently, we will compare this array with the descEmbedding generated in the first part. Utilizing vector search, we will return the three most proximate results (in this case, the fitness exercises that are most relevant to my search):

MongoDB Setup and Hugging Face Integration

1. Creating exercises collection

The first step in achieving our goal is to create an empty collection called "exercises" that will later store our dataset. Begin by logging in to your MongoDB Atlas account. From the Atlas dashboard, navigate to your cluster and select the database where you want to create the collection. Click on the "Collections" tab to manage your collections within that database and create an empty exercises collection:

2. Creating a trigger and function

Next, we need to create a trigger that will activate whenever a new document is inserted into the exercises collection. Navigate to the Triggers tab and create a trigger named "Trigger_Exercises" as shown in the images below:

Remember to choose the "exercises" collection, select "Insert Document" for the operation type, and enable "Full Document.”

Finally, paste the following function code into the "Function" field and click "Save":

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

    const url = 'https://api-inference.huggingface.co/pipeline/feature-extraction/sentence-transformers/all-MiniLM-L6-v2';
    const hf_key = context.values.get("HF_value");
    try {
        console.log(`Processing document with id: ${doc._id}`);

        let response = await context.http.post({
            url: url,
            headers: {
                'Authorization': [`Bearer ${hf_key}`],
                'Content-Type': ['application/json']
            },

            body: JSON.stringify({               
                inputs: [doc.description]               
            })
        });

        let responseData = EJSON.parse(response.body.text());

        if(response.statusCode === 200) {
            console.log("Successfully received embedding.");

            const embedding = responseData[0];

            const collection = context.services.get("Cluster0").db("my_database").collection("exercises");

            const result = await collection.updateOne(
                { _id: doc._id },
                { $set: { descEmbedding: embedding }}
            );

            if(result.modifiedCount === 1) {
                console.log("Successfully updated the document.");
            } else {
                console.log("Failed to update the document.");
            }
        } else {
            console.log(`Failed to receive embedding. Status code: ${response.statusCode} plus ${response}`);
        }

    } catch(err) {
        console.error(err);
    }
};

This function serves as a bridge between MongoDB and the Hugging Face API, enhancing documents stored in a MongoDB collection with embeddings generated by the API. The function is triggered by a change event in the MongoDB collection, specifically when a new document is inserted or an existing document is updated.

Now, let's explore the functionality of this function:

Event handling: The function extracts the full document from the MongoDB change event to be processed.
Hugging Face API interaction: It interacts with the Hugging Face API to obtain an embedding for the document's description. This involves sending an HTTP POST request to the API's feature extraction endpoint, with the document's description as input.
MongoDB update: Upon receiving a successful response from the Hugging Face API, the function updates the document in the MongoDB collection with the extracted embedding. This enriches the document with additional information useful for various natural language processing tasks.

3. Renaming the function

To align our environment with the demonstration image, let's change the name of our function to Function_Exercises. To do this, access the "Functions" menu and edit the function:

Then, enter the new name and click “Save”:

4. Getting the Hugging Face access token

The function we previously created requires a token to access Hugging Face. We need to obtain and configure it in Atlas. To do this, log in to your Hugging Face account, and access the settings to create your key:

After copying your key, let's return to MongoDB Atlas and configure our key for access. Click on the "Values" button in the side menu and select “Create New Value”:

Now, we need to create a secret and a value that will be associated with this secret.

First, create the secret by entering the key from Hugging Face:

Then, create a value named HF_value (which will be used in our function) and associate it with the secret, as shown in the image:

If everything has gone perfectly, our values will look like this:

We have finished configuring our environment. To recap:

Creating the empty collection:

We created an empty collection named "exercises" in MongoDB Atlas. This collection will receive input data, triggering a process to convert the exercises description into embedded values.

Setting up triggers and functions:

A trigger named "Trigger_Exercises" was created to activate upon document insertion.
The trigger calls a function named "Function_Exercises" for each inserted document.
The function processes the description using the Hugging Face API to generate embedded values, which are then added to the "exercises" collection.

Final configuration:

To complete the setup, we associated a secret and a value with the Hugging Face key in MongoDB Atlas.

5. Importing a dataset

In this step, we will import a dataset of 50 documents containing information about exercises:

To achieve this goal, I will use MongoDB Tools to import the exercises.json file via the command line. After installing MongoDB Tools, simply paste the "exercises.json" file into the "bin" folder and execute the command, as shown in the image below:

 .\mongoimport mongodb+srv://<user>:<password>@cluster0.xpto.mongodb.net/my_database --collection exercises --jsonArray .\exercises.json

Notice: Remember to change your user, password, and cluster.

If everything goes well, we will see that we have imported 50 exercises.

Now, let's check the logs of our function to ensure everything went smoothly. To do this, navigate to the "App Services" tab and click on "Logs":

And now, let's view our collection:

As we can see, we have transformed the descriptions of the 50 exercises into vector values and assigned them to the "descEmbedding" field.

Improving Kotlin Ktor With Hugging Face API and Vector Search

Let's proceed with the changes in our Kotlin application. If you haven't already, you can download the application. Our objective is to create an endpoint /processRequest to send an input to HuggingFace, such as:

"I need an exercise for my shoulders and to lose my belly fat."

We will convert this information into embedded data and utilize Vector Search to return the three exercises that most closely match this input. To begin, let's include two dependencies in the build.gradle.kts file that will allow us to make HTTP calls to Hugging Face:

build.gradle.kts

//Client
implementation("io.ktor:ktor-client-core:$ktor_version")
implementation("io.ktor:ktor-client-cio:$ktor_version")

In the ports package, we will create a repository that will retrieve exercises from the database:

domain/ports/ExercisesRepository

package com.mongodb.domain.ports

import com.mongodb.domain.entity.Exercises

interface ExercisesRepository {
    suspend fun findSimilarExercises(embedding: List<Double>): List<Exercises>
}

We will create a response to display some information to the user:

application/response/ExercisesResponse

package com.mongodb.application.response
data class ExercisesResponse(
    val exerciseNumber: Int,
    val bodyPart: String,
    val type: String,
    val description: String,
    val title: String
)

Now, create the Exercises class:

domain/entity/Exercises

package com.mongodb.domain.entity


import com.mongodb.application.response.ExercisesResponse
import org.bson.codecs.pojo.annotations.BsonId
import org.bson.types.ObjectId


data class Exercises(
    @BsonId
    val id: ObjectId,
    val exerciseNumber: Int,
    val title: String,
    val description: String,
    val type: String,
    val bodyPart: String,
    val equipment: String,
    val level: String,
    val rating: Double,
    val ratingDesc: String,
    val descEmbedding: List<Double>
){
    fun toResponse() = ExercisesResponse(
        exerciseNumber = exerciseNumber,
        title = title,
        description = description,
        bodyPart = bodyPart,
        type = type
    )
}

Next, we will implement our interface that will communicate with the database by executing an aggregate query using the vector search that we will create later.

infrastructure/ExercisesRepositoryImpl

package com.mongodb.infrastructure

import com.mongodb.domain.entity.Exercises
import com.mongodb.domain.ports.ExercisesRepository
import com.mongodb.kotlin.client.coroutine.MongoDatabase
import kotlinx.coroutines.flow.toList
import org.bson.Document

class ExercisesRepositoryImpl(
    private val mongoDatabase: MongoDatabase
) : ExercisesRepository {

    companion object {
        const val EXERCISES_COLLECTION = "exercises"
    }

    override suspend fun findSimilarExercises(embedding: List<Double>): List<Exercises> {
        val result =
        mongoDatabase.getCollection<Exercises>(EXERCISES_COLLECTION).withDocumentClass<Exercises>().aggregate(
            listOf(
                Document(
                    "\$vectorSearch",
                    Document("queryVector", embedding)
                    .append("path", "descEmbedding")
                    .append("numCandidates", 3L)
                    .append("index", "vector_index")
                    .append("limit", 3L)
                )
            )
        )

        return result.toList()
    }
}

Now, let's create our endpoint to access Hugging Face and then call the method created earlier:

application/routes/ExercisesRoutes

package com.mongodb.application.routes

import com.mongodb.application.request.SentenceRequest
import com.mongodb.domain.ports.ExercisesRepository
import com.mongodb.huggingFaceApiUrl
import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.cio.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import io.ktor.http.content.*
import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import org.koin.ktor.ext.inject

fun Route.exercisesRoutes() {
   val repository by inject<ExercisesRepository>()

   route("/exercises/processRequest") {
       post {
           val sentence = call.receive<SentenceRequest>()

           val response = requestSentenceTransform(sentence.input, call.huggingFaceApiUrl())

           if (response.status.isSuccess()) {
               val embedding = sentence.convertResponse(response.body())
               val similarDocuments = repository.findSimilarExercises(embedding)

               call.respond(HttpStatusCode.Accepted, similarDocuments.map { it.toResponse() })
           }
       }
   }
}

suspend fun requestSentenceTransform(input: String, huggingFaceURL: String): HttpResponse {

   println(huggingFaceURL)

   return HttpClient(CIO).use { client ->

       val response = client.post(huggingFaceURL) {
           val content = TextContent(input, ContentType.Text.Plain)
           setBody(content)
       }

       response
   }
}

Next, let's create the request that we will send to Hugging Face. In this class, in addition to the input, we have a converter to convert the return from String to Double:

application/request/SentenceRequest

package com.mongodb.application.request

data class SentenceRequest(
   val input: String
)
{
   fun convertResponse(body: String) =
       body
           .replace("[", "")
           .replace("]", "")
           .split(",")
           .map { it.trim().toDouble() }
}

Let's include the route created earlier and a huggingFaceApiUrl method in our Application class. Here's the complete code:

Application.kt

package com.mongodb

import com.mongodb.application.routes.exercisesRoutes
import com.mongodb.application.routes.fitnessRoutes
import com.mongodb.domain.ports.ExercisesRepository
import com.mongodb.domain.ports.FitnessRepository
import com.mongodb.infrastructure.ExercisesRepositoryImpl
import com.mongodb.infrastructure.FitnessRepositoryImpl
import com.mongodb.kotlin.client.coroutine.MongoClient
import io.ktor.serialization.gson.*
import io.ktor.server.application.*
import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.server.plugins.swagger.*
import io.ktor.server.routing.*
import io.ktor.server.tomcat.*
import org.koin.dsl.module
import org.koin.ktor.plugin.Koin
import org.koin.logger.slf4jLogger

fun main(args: Array<String>): Unit = EngineMain.main(args)
fun Application.module() {

   install(ContentNegotiation) {
       gson {
       }
   }

    // Other code..

   routing {
      // Other code..

      exercisesRoutes() 
   }
}

fun ApplicationCall.huggingFaceApiUrl(): String {
   return application.environment.config.propertyOrNull("ktor.huggingface.api.url")?.getString()
       ?: throw RuntimeException("Failed to access Hugging Face API base URL.")

}

Finally, let's include the Hugging Face endpoint in the application.conf file.

application.conf

ktor {

    // Other code ..

   huggingface {
       api {
           url = "https://api-inference.huggingface.co/pipeline/feature-extraction/sentence-transformers/all-MiniLM-L6-v2"
       }
   }
}

Creating vector search

Now, we need to go back to Atlas and create our vector search index. Follow the images below:

Select Atlas Vector Search:

If everything is okay, you will see a success message like the one below, indicating that the index was successfully created in MongoDB Atlas:

This code snippet defines a vector index on the descEmbedding field in our exercises collection. The type field specifies that this is a vector index. The path field indicates the path to the field containing the vector data. In this case, we are using the descEmbedding field. The numDimensions field specifies the number of dimensions

of the vectors, which is 384 in this case. Lastly, the similarity field specifies the similarity metric to be used for comparing vectors, which is the Euclidean distance.

{
  "fields": [
    {
      "type": "vector",
      "path": "descEmbedding",
      "numDimensions": 384,
      "similarity": "euclidean"
    }
  ]
}

After implementing the latest updates and configurations, it's time to test the application. Let's start by running the application. Open Application.kt and click on the run button:

Once the application is up and running, you can proceed with testing using the following curl command:

curl --location 'http://localhost:8081/exercises/processRequest' \
--header 'Content-Type: application/json' \
--data '{
    "input": "I need an exercise for my shoulders and to lose my belly fat"
}'

Conclusion

This article showcased how to enrich MongoDB documents with embeddings from the Hugging Face API, leveraging its powerful natural language processing capabilities. The provided function demonstrates handling change events in a MongoDB collection and interacting with an external API. This integration offers developers opportunities to enhance their applications with NLP features, highlighting the potential of combining technologies for more intelligent applications.

The example source code is available on GitHub.

If you have any questions or want to discuss further implementations, feel free to reach out to the MongoDB Developer Community forum for support and guidance.

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.