DEV Community: Ricardo Mello

Building an Agentic Warehouse Management System — Part 3: Tools, Decisions, and Actions

Ricardo Mello — Thu, 03 Sep 2026 15:44:43 +0000

If you haven’t read the first two parts yet, I recommend starting with Part 1: Where AI Agents Add Value and Part 2: Java and Spring AI. There, we introduced the WMS scenario, discussed where an AI agent can add value, and built the first stages of the implementation with Java and Spring AI.

In this third and final part, we will build on the execution plan created in Part 2 and focus on the remaining stages of the agent workflow. We will see how each task is executed using controlled tools, how operational and business context is gathered, how the replenishment decision is made, and how the agent acts on that decision when necessary.

A live version of the Agentic WMS is available here.

From Plan to Execution

Let’s revisit the complete agent flow. The first stages: Define the Agent, Trigger the Agent, and Plan, were covered in the previous article. Now we will focus on executing the tasks, using the available tools, gathering context, and making the replenishment decision.

Execute tasks with controlled tools

With the execution plan created in Part 2, the AgentRunner starts processing the tasks one at a time. For each task, the runner reads its description and capability, executes it, stores the result, and then continues with the next task:

for (int index = 0; index < tasks.size(); index++) {
    String description = tasks.get(index).description();
    String capability = tasks.get(index).capability();
    LocalDateTime startedAt = LocalDateTime.now();
    String result = executeTask(definition, goal, description, capability, tasks);
    tasks.set(index, new AgentRun.AgentTask(
            description,
            AgentRun.TaskStatus.COMPLETED,
            capability,
            result,
            startedAt,
            LocalDateTime.now()
    ));
    agentRunService.save(withTasks(agentRun, tasks));
}

Before executing a task, the runner selects only the tools associated with its capability:

private Object[] toolsOf(
        AgentDefinition definition,
        String capability
) {
    return definition.capabilities().stream()
            .filter(candidate ->
                    candidate.name().equalsIgnoreCase(capability))
            .map(AgentCapability::tools)
            .filter(Objects::nonNull)
            .flatMap(List::stream)
            .toArray();
}

When the task is executed, the executor receives the current goal, the results produced by previous tasks, the current task, and only the tools available for its capability:

return definition.executor()
        .prompt()
        .tools(tools)
        .user("""
            %s
            Results of the previous tasks:
            %s
            Execute only this task:
            %s
            Use the available tools autonomously.
            """.formatted(
                goal,
                previousResults(tasks),
                description
        ))
        .call()
        .content();

The result of each completed task becomes part of the context available to the tasks that follow. This allows the agent to progressively gather the information it needs before making the replenishment decision.

At the same time, the capability assigned to each task defines which tools are available during its execution. This preserves the boundaries we established earlier: an ANALYSIS task, for example, can inspect information from the WMS, but it does not have access to tools that create a replenishment request.

Accessing operational data

During ANALYSIS tasks, the agent can use controlled tools to retrieve operational data from the WMS, such as inventory, invoice movements, stock movements, and pending replenishments.

For example, one of the available tools retrieves the stock movements generated by an outbound invoice:

@Tool(description = """
    Get the stock movements generated by a specific invoice.
    Use this tool to discover which products and quantities were affected
    by a completed outbound invoice.
""")
public List<StockMovement> getStockMovementByInvoiceNumber(
        @ToolParam(description = "Outbound invoice number")
        String invoiceNumber
) {
    return stockMovementService.findByInvoiceNumber(invoiceNumber);
}

With Spring AI, methods like this can be exposed to the model using annotations such as @Tool and @ToolParam. The executor can then call them when the current task requires that information.

The complete application exposes additional tools for retrieving inventory, invoice movements, pending replenishments, and other operational data. We will not cover each one here, but they follow the same idea.

Retrieving depositor policies

The depositor policies are also accessed through a dedicated tool exposed by the POLICY capability. In our application, each depositor can register business rules through the Depositor Policies page. For example, a policy may define a seven-day lead time or require at least 500 units per replenishment request:

These policies are stored as natural-language documents, which allows us to retrieve them using semantic search instead of relying soley on exact keywords. For example:

new DepositorKnowledgeEntry(
 "amz",
  "replenishment-minimum",
  KnowledgeType.REPLENISHMENT,
 "Replenishment orders for Amazon must contain at least 500 units per product."
);

When a policy is stored, its text is converted into an embedding using the configured Voyage AI embedding model and added to the vector store. During a POLICY task, the agent can ask a question based on the context collected so far:

What minimum quantities, packaging rules and lead times
apply to replenishing product BR01?

This gives us a simple Retrieval-Augmented Generation (RAG) flow: the question is used to retrieve the most relevant policies, which are then added to the execution:

The retrieval uses semantic search:

return vectorStore.similaritySearch(
        SearchRequest.builder()
                .query(question)
                .topK(3)
                .filterExpression(filter)
                .build()
);

and is filtered by depositor and knowledge type:

String filter =
        "depositorId == '" + depositorId + "'"
        + " && type in ['REPLENISHMENT', 'INBOUND', 'GENERAL']";

Together with the results from the ANALYSIS tasks, these policies give the agent the operational and business context required to decide whether replenishment is needed.

Decide

After the ANALYSIS and POLICY tasks are completed, the DECISION task uses the collected context to determine whether replenishment is required. The result ends with one of two tokens:

REPLENISHMENT_REQUIRED 
REPLENISHMENT_NOT_REQUIRED

This gives the AgentRunner a simple way to determine whether the remaining tasks should continue:

private boolean decidedToStop(String capability, String result) {
    return DECISION_CAPABILITY.equals(capability)
            && result != null
            && result.contains("REPLENISHMENT_NOT_REQUIRED");
}

If replenishment is not required, the remaining REPLENISHMENT and NOTIFICATION tasks are marked as SKIPPED, and the execution is completed:

The runner marks those tasks as SKIPPED and completes the execution:

if (decidedToStop(capability, result)) {
    skipRemaining(tasks, index + 1);

    return agentRunService.save(finish(
            agentRun,
            tasks,
            AgentRun.Status.COMPLETED,
            summarize(definition, goal, tasks)
    ));
}

If replenishment is required, the execution continues with the next tasks in the plan.

Act

Once replenishment is required, the agent can use the action tools exposed by the application.

The REPLENISHMENT task can create a replenishment request:

@Tool(description = """
    Create a replenishment request when one or more products
    need to be replenished.
""")
public String createReplenishment(
        String depositorCode,
        List<Replenishment.ReplenishmentItem> items,
        String message
) {
    // Validate the request ..
    replenishmentService.save(....)
}

Again: The tool does not replace the existing WMS logic. It gives the agent a controlled way to request the operation, while validation and persistence remain inside the application services.

Once created, the replenishment ID can be used by the NOTIFICATION task to prepare the depositor email draft:

@Tool(description = """
    Draft and store the notification email for a replenishment request.
    The email is not sent by this tool.
""")
public String draftDepositorEmail(
        @ToolParam(description = ReplenishmentIds.ID_PARAM)
        String id
) {
    ....    
}

At this point, the agent has made the decision and performed the actions required by it.

Complete

When there are no more tasks to execute, the agent run is completed and a summary is generated:

If a replenishment request was created, it is now available on the Replenishments page for review:

This completes the flow: the agent gathers context through controlled tools, decides whether replenishment is necessary, and acts only when required.

Next steps

During a single execution, the agent uses the results of previous tasks as context for the tasks that follow. A natural next step would be to give the agent memory across different executions.

For example, before creating a new replenishment request, the agent could look at previous AgentRun records and use relevant outcomes from similar situations:

The last three requests for 500 units of this product were rejected. Approved requests were usually between 200 and 300 units. Based on the current consumption, I will request 250 units.

This would allow the agent to use not only the context of the current execution, but also relevant information from previous ones. One possible evolution would be to retrieve similar past executions and add them to the agent context before making a new decision.

There are many other directions in which this agent could evolve, but this is a good example of how the same design can gradually become more context-aware over time.

Conclusion

The main goal of this series was to show how an AI agent can add value in scenarios where business decisions depend on multiple sources of context and increasingly complex rules. Our replenishment example is only a small glimpse of what this approach can support in a real Warehouse Management System.

In Part 1, we explored where an AI agent can add value in a WMS. In Part 2, we translated that design into Java and Spring AI by defining the agent, its capabilities, and its execution plan.

In this third and final part, we completed the flow: tasks were executed through controlled tools, operational data and depositor policies were added to the context, and the agent used that information to decide whether replenishment was required and act when necessary.

The main idea remains the same: the application defines what the agent is allowed to do, while the agent decides what to do within those boundaries.

Explore our MongoDB JVM Showcase repository for more Java examples and use cases. If you find it useful, consider giving it a ⭐.

Building an Agentic Warehouse Management System — Part 2: Java and Spring AI

Ricardo Mello — Thu, 03 Sep 2026 15:20:38 +0000

If you arrived here without reading the first part, I recommend starting with Part 1: Where AI Agents Add Value. There, we introduced the WMS scenario, explored the replenishment problem, and discussed where an AI agent can add value without replacing deterministic application logic.

In this second part, we will move from the design to the first steps of the implementation.

We will look at how the agent is built with Java and Spring AI, how its capabilities and boundaries are defined, how it is triggered by the WMS, and how the planner turns the agent’s goal into an execution plan.

In Part 3, we will continue from that plan and see how the agent executes tasks using controlled tools, gathers the context it needs, makes the replenishment decision, and takes action when necessary.

A live version of the Agentic WMS is available here.

Designing the agent

From this point on, we will focus on the main parts of the agent implementation using Java and Spring AI. Rather than covering Spring AI from the ground up, we will concentrate on the components directly relevant to this part of our agent: prompts, capabilities, triggering, and planning. For a broader introduction to Spring AI, see this article by my colleague Tim Kelly.

In Part 1, we established an important boundary: the WMS defines what the agent is allowed to do, while the agent decides what to do within those boundaries. Now we can translate that design into code.

Before diving into the implementation, the following diagram summarizes the complete agent flow across Parts 2 and 3. In this part, we will focus on defining the agent, triggering its execution, and creating the plan.

Define the Agent

The agent is triggered after an outbound operation is completed, with the goal of determining whether that operation created a need for replenishment.

The first step is to define how the agent should behave and what it is allowed to do.

In our implementation, we organize the agent around three main components:

planner
executor
reporter.

The planner receives the goal and determines the tasks required to achieve it:

private static final String PLANNER_PROMPT = """
   - You are the planning agent for a WMS. 
   - Create a short execution plan for the provided goal using the available capabilities. 
   - Do not execute tasks, call tools or make business decisions. 
   - Assign exactly one capability to each task. """;

The executor will receive one task at a time and perform it using the tools available for that task:

private static final String EXECUTOR_PROMPT = """
   - You are an AI agent specialized in Warehouse Management Systems.
   - Analyze inventory after outbound operations and anticipate replenishment needs.
   - Execute only the task you receive, using its available tools.
   - Apply the depositor policies and avoid unnecessary replenishments.""";

Finally, the reporter summarizes what happened during the execution:

private static final String REPORTER_PROMPT = """
    - Summarize the outcome of the agent execution.
    - Explain what was decided and why.
    - Do not repeat the task list.""";

These are simplified versions of the prompts used in the complete application, but they show the responsibility of each component. Together, these components become part of our agent definition:

public record AgentDefinition(
        String trigger,
        String goal,
        ChatClient planner,
        ChatClient executor,
        ChatClient reporter,
        List<AgentCapability> capabilities
) {}

The definition also contains the capabilities available to the agent. In our replenishment workflow, we use five:

Analysis: access invoices, inventory, and stock movements.
Policy: retrieve depositor policies.
Decision: determine whether replenishment is required.
Replenishment: create a replenishment request.
Notification: draft the related email.

Each capability defines a type of operation and the tools that can be used while performing it:

public record AgentCapability(
        String name,
        String description,
        List<Object> tools
) {}

This gives us a simple boundary around each task. An ANALYSIS task, for example, can access inventory and stock movement tools, but it cannot create a replenishment request. A DECISION task does not expose any tool and uses the results collected by the previous tasks.

Finally, we can connect these pieces when defining the replenishment agent:

return new AgentDefinition(
        "OUTBOUND_INVOICE_COMPLETED",
        "Outbound invoice %s has just been completed.",
        planner,
        executor,
        reporter,
        List.of(
                new AgentCapability(
                        "ANALYSIS",
                        "Read inventory, stock movements and invoice movements.",
                        List.of(inventoryAnalysisTool)
                ),
                new AgentCapability(
                        "DECISION",
                        "Decide whether replenishment is required.",
                        List.of()
                ),
                new AgentCapability(
                        "REPLENISHMENT",
                        "Create a replenishment request.",
                        List.of(replenishmentTool)
                )
                // Other capabilities: POLICY and NOTIFICATION
        )
);

At this point, we have defined what the agent can do and the boundaries around those operations. Before looking at how the plan is created, let's see how the agent execution starts.

Trigger the Agent

The agent starts after an outbound operation has been successfully completed. Once the transaction is committed, the application publishes the OUTBOUND_INVOICE_COMPLETED event:

public void execute(String invoiceNumber) {
   //  registerStock()
   // saveOutboundInvoice()
   eventPublisher.publishEvent(new OutboundInvoiceCompleted(number));
}

A listener receives that event and starts the agent using the outbound invoice number as the reference:

@Async
@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void onOutboundInvoiceCompleted(OutboundInvoiceCompleted event) {
    agentRunner.run(
        replenishmentAgentDefinition,
        event.invoiceNumber()
    );
}

Using AFTER_COMMIT ensures that the agent starts only after the outbound operation has been persisted and the inventory already reflects the latest state. From there, the agent receives its goal and can begin planning how to accomplish it.

Plan

Once the agent is triggered, the first responsibility of the AgentRunner is to create an execution plan.

The application does not define this list of tasks in advance. Instead, the planner receives the goal together with the capabilities available to the agent and determines which tasks are required for its execution.

Each planned task contains two pieces of information: what needs to be done and which capability should be responsible for it:

public record PlannedTask(String description, String capability) {}

Based on this information, the planner generates an ordered list of tasks:

private List<AgentRun.AgentTask> plan(
        AgentDefinition definition,
        String goal
) {
    List<PlannedTask> planned = definition.planner()
            .prompt()
            .user("""
                %s
                Available capabilities:
                %s
                Create the execution plan required to accomplish this goal.
                Assign exactly one capability to each task.
                """.formatted(goal, capabilityCatalog(definition)))
            .call()
            .entity(new ParameterizedTypeReference<>() {});
  return planned.stream()
            .map(task -> new AgentRun.AgentTask(
                    task.description(),
                    AgentRun.TaskStatus.PENDING,
                    task.capability(),
                    null,
                    null,
                    null
            ))
            .toList();
}

Here, Spring AI maps the model response directly to our PlannedTask objects through structured output, giving the application a typed execution plan instead of requiring us to parse generated text manually.

Once the planner returns the tasks, we persist the initial state of the execution as an AgentRun in MongoDB.

At this point, the execution is marked as RUNNING, and every task generated by the planner starts with the PENDING status:

String goal = definition.goal().formatted(reference);
List<AgentRun.AgentTask> tasks =
        new ArrayList<>(plan(definition, goal));
AgentRun agentRun = agentRunService.save(new AgentRun(
        null,
        definition.trigger(),
        reference,
        AgentRun.Status.RUNNING,
        null,
        LocalDateTime.now(),
        null,
        List.copyOf(tasks)
));

This gives us a persistent representation of the execution from the beginning, including the tasks that were planned. At this point, the document may look like this:

{
  _id: ObjectId('6a8f5973315f4506564a6f5b'),
  trigger: 'OUTBOUND_INVOICE_COMPLETED',
  reference: 'NF-OUT-01',
  status: 'RUNNING',
  startedAt: ISODate('2026-08-27T17:04:03.350Z'),
  tasks: [
    {
      description: 'Identify the products affected by the outbound invoice.',
      status: 'PENDING',
      capability: 'ANALYSIS'
    },
    {
      description: 'Check the current inventory of the affected products.',
      status: 'PENDING',
      capability: 'ANALYSIS'
    },
    {
      description: 'Analyze recent stock movements and consumption.',
      status: 'PENDING',
      capability: 'ANALYSIS'
    },
    {
      description: 'Read the replenishment policies for the depositor.',
      status: 'PENDING',
      capability: 'POLICY'
    },
    {
      description: 'Determine whether replenishment is required.',
      status: 'PENDING',
      capability: 'DECISION'
    },
    {
      description: 'Create a replenishment request if required.',
      status: 'PENDING',
      capability: 'REPLENISHMENT'
    },
    {
      description: 'Draft the notification if a request was created.',
      status: 'PENDING',
      capability: 'NOTIFICATION'
    }
  ]
}

The plan is now ready, and the execution has been registered.

Conclusion

In this second part, we translated the agent design into the first pieces of the implementation. We defined its responsibilities and capabilities, connected it to the WMS workflow, and used the planner to turn the agent goal into a persistent execution plan.

At this point, the agent knows what needs to be done and which capability is responsible for each task. In Part 3, we will focus on how that plan is executed: using controlled tools, gathering operational and business context, making the replenishment decision, and acting when necessary.

The complete source code is available here.

Building an Agentic Warehouse Management System — Part 1: Where AI Agents Add Value

Ricardo Mello — Thu, 03 Sep 2026 14:41:06 +0000

I spent a large part of my career working in banking and logistics. In logistics, I spent more than eight years working across different stages of logistics systems, from development to implementation and production support.

That experience shaped the way I think about technology. Knowing a tool or framework is important, but what interests me most is understanding the business problem behind it and where technology can actually add value.

A few weeks ago, I returned as a speaker to a company where I had worked for many years. Being back there reminded me of several day-to-day logistical challenges and made me wonder how I would approach those problems today.

That is where the Agentic Warehouse Management System came from.

With this project, I am not trying to build a complete WMS. Instead, I want to use a logistics scenario I know well to explore how an AI agent can become part of a real business workflow and where it can add value.

In this first part, we will introduce the WMS scenario and identify where an AI agent can help. In Part 2, we will define and connect the agent using Java and Spring AI. Finally, in Part 3, we will execute the plan, gather context, make the replenishment decision, and act when necessary.

Try the application

A live version of the Agentic WMS is available here.

You can start with the Overview page, which walks through the main WMS flow and shows how to interact with the application. The application is built with:

Java and Spring Boot
Spring AI for the agent and tool integration
OpenAI for the language model
Voyage AI for embeddings
MongoDB for operational data, agent runs, and vector search

The complete source code is available here.

The Warehouse Management System

A Warehouse Management System, or simply WMS, is a software system used to manage and control the movement of products inside a warehouse. It typically handles processes such as receiving goods, tracking inventory, shipping products, replenishment, and many others. A warehouse may store products owned by the company operating it, but it may also store products for other companies. In this article, we will call these companies depositors:

A depositor owns the products stored in the warehouse, while the warehouse is responsible for receiving, storing, managing, and shipping them. A single warehouse may serve multiple depositors at the same time. For example, products from Amazon, Nike, or Walmart could be stored and managed in the same warehouse, while the inventory of each depositor remains separated. A real WMS can support many more processes, but for our application, we will focus on a smaller part of this flow:

An Inbound operation represents goods entering the warehouse and increases the available inventory for a depositor. An Outbound operation represents goods leaving the warehouse and reduces that inventory.

We will also include a simple Replenishment Request process. When additional units are needed, the warehouse can create a request indicating which products should be replenished and in what quantities. The depositor can then arrange a new inbound shipment to the warehouse. Once a replenishment request is created, a Depositor Email Draft is also prepared for notification.

Modeling the WMS flow

In the flow above, a traditional implementation would involve a few basic entities such as Inbound, Outbound, Inventory, and Replenishment Request, along with products and depositors. An Inbound operation represents products owned by a depositor entering the warehouse. For example:

// INBOUND COLLECTION
{ 
  number: 'NF-IN-01',
  depositor: { _id: ObjectId('6a88aaa60aab66cebc2c4e62'), name: 'Amazon' },
  items: [ { productCode: 'BR01', quantity: 1500 } ],
  status: 'COMPLETED' 
}

Once completed, those quantities are added to the Inventory:

// INVENTORY COLLECTION
{ 
  productCode: 'BR01', 
  depositor: { _id: ObjectId('6a88aaa60aab66cebc2c4e62'), name: 'Amazon' }, 
  quantity: 1500 
}

An Outbound operation does the opposite. Products leave the warehouse, and their quantities are reduced from the inventory:

// OUTBOUND COLLECTION
{
  number: 'NF-OUT-01',
  depositor: { _id: ObjectId('6a88aaa60aab66cebc2c4e62'), name: 'Amazon' }, 
  items: [ { productCode: 'BR01', quantity: 1480 } ],
  status: 'COMPLETED'
}

After this operation, the inventory for product BR01 belonging to the depositor Amazon would contain only 20 units. At this point, a Replenishment Request may be needed. In practical terms, the warehouse is essentially saying:

“Amazon, your product BR01 is down to only 20 units. Could you arrange a new inbound shipment before we run out of stock?”

In our WMS, this request can be represented by a document like the following:

{
  depositor: { _id: ObjectId('6a88aaa60aab66cebc2c4e62'), name: 'Amazon' }, 
  items: [ { productCode: 'BR01', quantity: 1500 } ],
  message: 'Replenishment is required for product BR01 due to low  stock.', 
  status: 'PENDING'
}

Deciding when to replenish

Creating a Replenishment Request is straightforward. The more interesting question is deciding when one should be created. Consider the following stock movements for product BR01:

On August 18, Amazon sent 1,500 units of the product to the warehouse. Over the following days, the warehouse processes outbound operations of 300 units per day.

After each outbound operation, the available inventory becomes:

1,500 → 1,200 → 900 → 600 → 300 → 0

If this consumption pattern continues, the warehouse will completely run out of BR01 on the fifth outbound operation.

A common way to automate this process is to define a minimum stock threshold. For example, whenever fewer than 500 units are available, a replenishment request could be created:

if (inventory.getQuantity() < 500) {
   replenishmentService.create(productCode, quantity, depositor);
}

This is a perfectly reasonable rule. Once the inventory reaches 300 units, the WMS detects that the stock is below the threshold (500) and requests more products.

However, consider that the depositor takes, on average, 7 days to deliver new products to the warehouse. If we wait until the stock falls below 500 units, the request may come too late, and the warehouse may run out of BR01 before the new shipment arrives.

We can account for this by adding the remaining days of stock to the decision:

int daysOfStock = inventory.getQuantity() / dailyConsumption;
if (inventory.getQuantity() < 500
        || daysOfStock < depositor.getLeadTimeDays()) {
    replenishmentService.create(productCode, quantity, depositor);
}

Now the WMS can react to low stock while also anticipating replenishment when the remaining inventory is not enough to cover the depositor's delivery lead time.

These are deterministic rules, and they work well when the decision can be clearly expressed through known conditions and calculations. As the business evolves, however, new rules and exceptions may continue to appear.

At some point, the challenge is no longer just adding another condition.

When the decision becomes contextual

The problem becomes more interesting when deciding what to do requires more than evaluating a predefined condition. Let's go back to the same example.

Amazon sent 1,500 units of BR01, and the warehouse has been shipping 300 units per day. After three days, only 600 units remain.

Using the rule we created earlier, the calculation is straightforward:

Current inventory: 600 units
Recent consumption: 300 units per day
Remaining stock: 2 days
Amazon lead time: 7 days

Since two days of stock are not enough to cover a seven-day lead time, our code will create a replenishment request.

But consider two different situations:

Scenario A: The recent consumption of 300 units per day is part of the normal demand range for BR01. There is no indication that it will slow down. In this case, creating a replenishment request makes sense.
Scenario B: The same 300-unit outbound operations came from a short promotion that has already ended. Previous movements show that BR01 typically consumes only around 50 units per day. In this case, immediately requesting the same replenishment may not be necessary.

Our deterministic rule sees the same values in both situations: 600 units in stock, 300 units of recent daily consumption, and a seven-day lead time, so it produces the same result.

But the situations are not the same.

To make a better decision, the system needs more context. It may need to inspect previous stock movements, understand whether the recent consumption represents the normal behavior of the product, retrieve relevant depositor policies, and then decide whether action is actually necessary.

This is where an AI agent starts to add value.

The agent does not replace deterministic operations such as inventory calculations, validations, persistence, or the creation of a replenishment request. Those operations remain regular application logic.

Instead, the agent can use controlled tools to look beyond the values used by the fixed rule. It can inspect previous stock movements, check pending replenishments, retrieve depositor policies, and gather additional information that helps explain the current situation.

The question is no longer only:

Is the inventory below 500 units, or is the remaining stock not enough to cover the depositor's lead time?

It becomes:

What does this situation actually mean, and do we need to act now?

That is the role of the agent in our WMS: gather the relevant information, understand the current situation, decide whether replenishment is necessary, and determine what should happen next, while keeping well-defined business operations in deterministic code.

Where does the agent fit?

In our application, the agent enters the flow after an outbound operation is successfully completed. At that point, the inventory has already been updated, and the agent receives a goal:

Determine whether this outbound operation created a need for replenishment.

Before looking at the flow, it is useful to clarify what we mean by an AI agent.

In simple terms, an AI agent receives a goal, follows a set of instructions, interacts with the application through tools, observes the information it retrieves, and decides what to do next.

In our WMS, these elements have clear responsibilities:

Goal: defines what the agent needs to accomplish. In this case, determine whether the completed outbound operation created a need for replenishment.
Instructions: define how the agent should behave, what it should consider, and the boundaries it must respect.
Tools: provide controlled access to the WMS. The agent can use them to inspect inventory and stock movements, retrieve depositor policies, check pending replenishments, or perform actions such as creating a replenishment request.

The important point is that the agent does not replace the existing WMS services or take control of the entire application. Inbound processing, outbound processing, inventory updates, validations, and persistence continue to be handled by regular Java code.

Instead, the agent acts as an orchestrator, deciding which available tools to use based on the goal and the context it gathers.

The following diagram shows where the agent becomes part of the WMS flow:

The diagram may look like a sequence of steps, but this is not a traditional hard-coded workflow where the application defines every decision in advance.

The application defines the agent's configuration, instructions, boundaries, and available tools. Within those boundaries, the agent determines what information it needs, uses the results it collects as context, decides whether action is necessary, and determines what should happen next.

For one outbound operation, the agent may conclude that replenishment is required and create a request. For another, after analyzing the available context, it may decide that no action is necessary.

This is an important distinction: the WMS controls what the agent is allowed to do, while the agent is responsible for deciding what to do within those boundaries.

Once the outbound invoice is completed, the OUTBOUND_INVOICE_COMPLETED event triggers the agent. From there, the workflow can be summarized in four steps:

Plan: Based on the goal, instructions, and available capabilities, the agent determines what information and actions may be required.
Analyze: The agent uses read-only tools to inspect information such as inventory, stock movements, pending replenishments, and depositor policies.
Decide: Using the information collected, the agent determines whether replenishment is actually necessary.
Act: If action is required, the agent can use controlled tools to create the replenishment request and prepare the depositor notification. If no action is required, the workflow ends without changing anything.

Conclusion

In this first part, we focused on where an AI agent can add value inside a Warehouse Management System and, just as importantly, where it should not replace deterministic application logic.

In Part 2, we will translate this design into Java and Spring AI by defining the agent, connecting it to the WMS workflow, and creating its execution plan.

Then, in Part 3, we will see how the agent executes those tasks using controlled tools, gathers the necessary context, makes the replenishment decision, and acts when required.

The complete source code is available here.

Building a Kotlin Application with Quarkus and MongoDB: A Step-by-Step Guide

Ricardo Mello — Tue, 30 Jun 2026 13:43:36 +0000

Kotlin, Quarkus, and MongoDB — do these three technologies work well together?

In this tutorial, we’ll build a simple application that connects to MongoDB using the Panache pattern and performs aggregation queries.

Along the way, we’ll set up the project, explore the structure, and run a basic aggregation pipeline to query a movies dataset.

Prerequisites

Basic knowledge of Kotlin
Maven installed
A MongoDB instance (Atlas or local)
Docker installed and running (optional, if you want to use the local lab setup)

What we will build

We’re going to build a simple application that connects to a database containing around 21,000 movies.
Each movie document has a structure similar to this:

{
 "title": "The Great Train Robbery",
 "fullplot": "Among the earliest existing films in American cinema...",
 "plot": "A group of bandits stage a brazen train hold-up, only to find a determined posse hot on their heels.",
 "genres": [
   "Short",
   "Western"
 ],
 "cast": [
   "A.C. Abadie",
   "Gilbert M. 'Broncho Billy' Anderson",
   "George Barnes",
   "Justus D. Barnes"
 ],
...
}

Our goal is to create an aggregation that selects cast members and counts how many movies each one appears in, returning results like this:

{
 "_id": "Gérard Depardieu",
 "totalMovies": 67
},
{
 "_id": "Robert De Niro",
 "totalMovies": 58
}

Setting up MongoDB (Optional)

To get started, we first need to set up a MongoDB connection.
You have a couple of options:

Create a free MongoDB Atlas account and set up a cluster by following this tutorial
Or use a local MongoDB instance To make things easier, you can use this CLI tool to spin up a local MongoDB environment with sample data already loaded:

1 - Install the cli:

npm install -g @ricardohsmello/mongodb-cli-lab

2 - Create the cluster:

mongodb-cli-lab up --topology standalone --mongodb-version 8.2 --port 28000 --sample-databases sample_mflix

This is a community-driven initiative and not an official MongoDB product.
It is intended for development, demos, and learning purposes only.
Not intended for production use.

This command starts a local MongoDB instance and automatically loads the sample_mflix dataset, which includes the movies collection we’ll use in this tutorial.

Once your MongoDB instance is up and running, make sure you have access to the movies collection, as we’ll use it to build our aggregation queries.

Creating the Quarkus project

Now that our database is ready, let’s create our Quarkus application.
We’ll use the Quarkus Maven plugin to bootstrap the project with the required extensions:

mvn io.quarkus.platform:quarkus-maven-plugin:3.34.1:create \
   -DprojectGroupId=com.example.mongodb.lab \
   -DprojectArtifactId=kotlin-quarkus-lab \
   -Dextensions='kotlin,rest-jackson, quarkus-mongodb-panache-kotlin'

Here, we are including a few important extensions:

Kotlin – to write our application using Kotlin
REST (Jackson) – to expose HTTP endpoints and handle JSON
MongoDB Panache – to simplify data access and interactions with MongoDB

Once the project is created, open it in your favorite IDE to continue.

Configuring the MongoDB Connection

With the project open in your IDE, the first step is to configure the connection to MongoDB.
To do that, open the application.properties file and add the following properties:

%dev.quarkus.mongodb.connection-string=mongodb://localhost:28000
%dev.quarkus.mongodb.database=sample_mflix

These settings configure the application to connect to our local MongoDB instance and use the sample_mflix database.
The %dev prefix means that these properties will only be applied when running the application in development mode.

Defining the Movie entity

Now, we need to create a class to represent our movies collection.
Using Panache, we can map this collection to a Kotlin class Movie.kt, like this:

import io.quarkus.mongodb.panache.common.MongoEntity

@MongoEntity(collection = "movies")
class Movie {
   lateinit var title: String
   var plot: String? = null
   var cast: List<String>? = null
}

The @MongoEntity annotation tells Quarkus which collection this class maps to.
Here, title is defined as a required field using lateinit, since we expect every document to have it.
On the other hand, plot and cast are optional fields, so we declare them as nullable (?) and initialize them with null. This allows the application to handle documents where these fields might be missing.

Creating the Repository

Next, we’ll create a repository to interact with MongoDB using Panache.

import io.quarkus.mongodb.panache.kotlin.PanacheMongoRepository
import jakarta.enterprise.context.ApplicationScoped

@ApplicationScoped
class MovieRepository : PanacheMongoRepository<Movie> {
}

By extending PanacheMongoRepository, we get access to built-in methods to interact with the database, such as queries and data operations.
This is where we’ll implement our aggregation logic.

Exposing the repository through a resource

Next, we’ll interact with this repository through a REST resource:

import jakarta.ws.rs.GET
import jakarta.ws.rs.Path
import jakarta.ws.rs.Produces

@Path("/movies")
@Produces("application/json")
class MovieResource(
   val repository: MovieRepository
) {
   @GET
   fun list() = repository.findAll()
       .list()
}

This resource exposes a /movies endpoint that returns all documents from the collection.

Running the Application and Testing the Endpoint

Now, let’s run the application and test the endpoint.
To make that easier, I’ll create an HTTP file called movie.http and add the following request:

### FIND
GET http://localhost:8080/movies
Accept: application/json

Once we run it, we’ll immediately notice the first problem: we are returning all 21,000 movies at once.

That is not a good idea. We should always be careful with how much data we return, both to avoid unnecessary load on the database and to make the API more efficient.

A simple improvement here is pagination.
So let’s go back to the MovieResource class and add two query parameters: page and size.

import jakarta.ws.rs.DefaultValue
import jakarta.ws.rs.QueryParam

@GET
fun list(
   @QueryParam("page") @DefaultValue("0") page: Int,
   @QueryParam("size") @DefaultValue("20") size: Int,
) = repository.findAll()
   .page(page, size)
   .list()

With this change, the endpoint will return only 20 results by default.
If we run the request again, we’ll get a much smaller, and more manageable response.

Working with the Aggregation Framework

The MongoDB Aggregation Framework is a powerful feature for transforming and analyzing data directly in the database. Instead of just retrieving documents, we can use aggregation stages to reshape the data, group values, sort results, and answer more interesting questions.

In this example, we want to find the actors who appear most frequently in the dataset. To do that, we’ll use the following aggregation pipeline:

[
 {
   $unwind:    
     {
       path: "$cast"
     }
 },
 {
   $group:    
     {
       _id: "$cast",
       totalMovies: {
         $sum: 1
       }
     }
 },
 {
   $sort:
     {
       totalMovies: -1
     }
 },
 {
   $limit: 3      
 }
]

Let’s break it down:

$unwind takes the cast field, which is an array, and splits it into multiple documents. In simple terms, if a movie has three actors in its cast, it will temporarily become three separate records during this stage, one for each actor.
$group then groups those records by actor name and counts how many times each one appears.
$sort orders the results in descending order, so the most frequent actors appear first.
$limit keeps only the top results.

Implementing the Aggregation in the Repository

Now let’s implement this pipeline inside the MovieRepository:

fun findTopFrequentActors(): List<Document> =
   mongoCollection().withDocumentClass(Document::class.java)
       .aggregate(
           listOf(
               Aggregates.unwind("\$cast"),
               Aggregates.group(
                   "\$cast", Accumulators.sum("totalMovies", 1)
               ),
               Aggregates.sort(Sorts.descending("totalMovies")),
               Aggregates.limit(3)
           )
       ).toList()

Here, we are using the underlying MongoDB collection and defining the aggregation stages with the MongoDB Java driver API.

Since the result of this pipeline does not map directly to our Movie class, returning a Document is a simple and practical choice.

Next, let’s expose this aggregation through a new endpoint in our MovieResource:

@GET
@Path("/top-frequent-actors")
fun findTopFrequentActors() = repository.findTopFrequentActors()

With this, our application now provides a dedicated endpoint to return the actors who appear in the highest number of movies.

### TOP FREQUENT ACTORS
GET http://localhost:8080/movies/top-frequent-actors
Accept: application/json

Once you run it, you should see a response similar to this:

[
 {
   "_id": "Gèrard Depardieu",
   "totalMovies": 67
 },
 {
   "_id": "Robert De Niro",
   "totalMovies": 58
 },
 {
   "_id": "Michael Caine",
   "totalMovies": 51
 }
]

And that’s it! We now have a working aggregation pipeline in a Kotlin application using Quarkus, Panache, and MongoDB.

Conclusion

Yes — Kotlin, Quarkus, and MongoDB work very well together in a practical and efficient way.
In this tutorial, we saw how to quickly build an application, map a collection using Panache, and leverage the MongoDB Aggregation Framework to work with data in a powerful yet simple way.

If you’d like to explore further, the full source code is available on GitHub.

Real-Time Fraud Detection in Java with Kafka Streams and Vector Similarity

Ricardo Mello — Wed, 29 Apr 2026 13:51:37 +0000

This content is based on a talk that my colleague Tim Kelly and I presented at DevNexus 2026 in Atlanta, one of the largest Java conferences in the world.

Imagine you’re at a supermarket or shopping online. You tap your card or click “Buy Now”. In that exact moment, your bank has to make a decision: is this transaction legitimate, or is it fraud? And it has to do that in milliseconds, and get it right. If it blocks a real transaction, it frustrates the customer. If it approves a fraudulent one, it leads to financial loss. So the question is: how do banks actually do this? What’s happening behind the scenes? In this article, we’ll explore a real-world approach to solving this problem using Java, Apache Kafka, Kafka Streams, and vector similarity with MongoDB.

What We’re Building

At a high level, a payment system works like this: a transaction is created, it goes through a validation step, and then a final decision is made to approve or decline:

Now, let’s zoom in on that validation step, because this is where fraud detection actually happens:

In our approach, this validation is not a single check but a pipeline composed of multiple stages working together:

Guardrails: Rule-based checks that catch obvious and well-known fraud patterns immediately, like impossible travel or unusual transaction velocity.
Vector Scoring: AI-powered similarity matching that compares the transaction against known patterns to detect more subtle or behavioral fraud.
Decision: The final verdict is based on the combined output of both layers: route the transaction to the approved_transactions collection or to the suspicious_transactions collection for further review or definitive blocking.

The decision flow is pretty straightforward.

If a transaction is flagged at any point, either by the guardrails or by the vector scoring stage, we treat it as suspicious and store it in the suspicious_transactions collection. From there, it can be reviewed, enriched with more context, or even blocked depending on the scenario.

On the other hand, if it passes both layers without any issues, we consider it safe and store it in the approved_transactions collection.

The Challenge: Millisecond Decisions with Resilience Under Failure

In fraud detection systems, especially in financial applications, speed is not just important, it is critical. Every transaction must be analyzed in real time, often under heavy load, with thousands of events happening every second. At the same time, the system cannot afford to break if a single component fails.

This leads to two non-negotiable constraints:

Decisions must be made in milliseconds
The system must remain resilient even when individual components fail

Before we get into how each layer works, it is important to understand how these constraints shape the entire architecture.

A natural first instinct is to build this using a simple synchronous architecture.

The payment service calls the fraud service, which then queries the database, and the flow continues to the notification service. This works fine at the beginning. It’s simple and easy to understand.

But the problem is that everything is tightly connected. One service depends on the next.

Now imagine the database takes a bit longer to respond.

That delay starts to affect the whole flow. The fraud service slows down, the payment service has to wait, and the notification service also gets delayed.

At scale, this becomes a real issue. One slow component can impact everything else.

So how do we break this dependency and make each service more independent?

This is where event-driven architecture comes in.

The Strategy: Decoupling the System with Event-Driven Architecture

Instead of having services call each other directly, we introduce an event log as the backbone of communication.

Apache Kafka allows the payment service to publish a transaction event to a topic, without knowing who will consume it. The fraud service, the notification service, and any other interested component can subscribe to that topic independently:

This fundamentally changes how the system behaves.

Services are no longer tightly coupled
Each service can fail or restart without affecting the others
The system becomes more resilient and easier to scale

At this point, we have removed the direct dependency between services and solved the resilience problem.

But we still have another challenge.

Stateful Checks Without a Database Round-Trip

Many fraud detection techniques depend on understanding recent activity.

For example, the system may need to evaluate how a card has been used within a short time window before deciding whether a new transaction is suspicious.

In a traditional architecture, this usually requires querying a database for every transaction.

At high throughput, those round-trips add latency that quickly becomes a bottleneck. In a system where decisions must be made in milliseconds, this approach does not scale.

So the question becomes: How do we perform these kinds of checks without hitting the database every time?

Solving It with Kafka Streams

Kafka Streams is a lightweight Java library that runs inside your application, processing events as they flow through Kafka topics. More importantly, it allows us to maintain state locally.

Instead of querying a remote database for every transaction, we keep the necessary data inside the same process that handles the events, using an embedded store backed by RocksDB.

In our example, we want to analyze transaction activity per card within a short time window. To do that, we group events by card number. Each card number becomes a key, and for each key, the system maintains a running view of recent activity within a defined time window. This means we eliminate network calls and database round-trips from the critical path, relying only on local lookups. For our use case, this makes a big difference.

We avoid unnecessary latency and keep everything fast enough for real-time decisions, without depending on external systems. You can see where this happens directly in the code:

return stream
    .filter((key, tx) -> tx != null)
    .selectKey((key, tx) -> tx.cardNumber())
    .groupByKey(Grouped.with(Serdes.String(), transactionSerde))
    .aggregate(
        FraudDetectionState::empty,
        (cardNumber, newTransaction, currentState) -> { countTransactionsInWindow() },
        Materialized.as("fraud-detection-store")...
    )
    .toStream()

This line is key:

Materialized.as("fraud-detection-store")

It tells Kafka Streams to keep the state locally using an embedded store.

As new transactions arrive, the state for each card is updated right there in the application, so the system can keep track of recent activity in real time.

At this point, we can evaluate transaction activity in real time without relying on database calls.

But that raises an important question: What exactly are we measuring?

Which patterns or signals should trigger a fraud decision?

This is where guardrails come in.

Stage 1: Guardrails, Fast Rule-Based Validation

Guardrails are the first layer in our flow.

They’re just simple checks based on rules, used to catch the most obvious fraud cases as early as possible.

In practice, guardrails can be any business or risk rule that makes sense for your domain. They are fully customizable and evolve over time as new fraud patterns emerge.

In our case, we will implement a couple of common examples to illustrate the approach.

Impossible Travel Check

This rule checks if the same card shows up in places that don’t make sense given the time between transactions.

For example, if a card is used in New York and then shows up in São Paulo less than an hour later, that’s not realistic. Something is clearly wrong, and we treat that as a strong fraud signal.

public boolean isImpossibleTravelFraud(Transaction previous, Transaction current) {
    double distanceKm = calculateDistanceKm(
        previous.latitude(), previous.longitude(),
        current.latitude(), current.longitude()
    );
    Duration timeBetween = Duration.between(
        previous.transactionTime(),
        current.transactionTime()
    ).abs();
    // block if physically impossible
}

Velocity Check

The velocity check looks at how many times a card is used in a short period of time. A very common pattern in fraud is when someone tests a stolen card by making several small transactions before trying something bigger.

In our case, if the same card is used more than three times within one minute, we flag it and block the transaction.

public boolean isVelocityFraud(long txCountInWindow, long maxAllowedPerWindow) {
    return txCountInWindow > maxAllowedPerWindow;
}

These are just examples. In a real system, guardrails can include a wide range of checks depending on your use case, risk tolerance, and business rules.

Where Rule-Based Detection Falls Short

Guardrails are fast and effective, but they have blind spots. Consider a transaction like this:

Amount: $2.00
City: same as the cardholder’s usual city
Card: same as always
Activity: nothing unusual on the surface

This transaction would pass every guardrail check.

But what if $2 micro-charges at gas stations are a known fraud pattern?

This is a classic card-testing technique used before a larger fraudulent purchase.

Rules alone cannot catch this, because the system would need to know the pattern in advance.

This is where a different approach becomes necessary.

Stage 2: Vector Scoring, Behavioral Fraud Detection

At this point, the question changes. Instead of asking: “Does this transaction violate a rule?”

We ask: “Does this transaction behave like something we have seen before?”

To answer that, we need a way to compare transactions based on behavior, rather than exact values.

For example:

A $12 purchase at a coffee shop
A $15 purchase at a bakery

These are not identical, but behaviorally they are very similar.

On the other hand:

A $10,000 crypto transaction at 3 AM

This is clearly very different.

So how do we represent this idea in a way that a system can understand?

From transactions to Vectors

To compare behavior, we need a consistent way to represent a transaction.

Instead of working with raw fields such as amount, merchant, or location separately, we transform the entire transaction into a single structured representation. One simple way to think about it is this:

We take a transaction like:

{ "amount": 15.90, "merchant": "Gas Station", "city": "New York" }

And turn it into a descriptive text:

String textToEmbed = "merchant=%s, city=%s, amount=%s";

This text is then passed to an embedding model, which produces a vector like:

[0.0392, 0.9323, -0.0323, ...]

In our case, we are using the voyage-finance-2 model, which is specialized for financial data from Voyage AI.

This model generates a vector with 1024 dimensions, where each value contributes to capturing a different aspect of the transaction’s behavior.

In the application, this embedding generation step can be implemented with a simple HTTP client in Spring. For example:

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

The role of this client is to send the transaction text to the embedding API and receive back the generated vector.

The model maps that description into a vector space where similar behaviors are placed closer together. This means that transactions that behave similarly will generate vectors that are close to each other.

To make this more intuitive, you can imagine a simplified 2D space.

In this space:

Everyday purchases like coffee or groceries tend to cluster together
Similar types of transactions stay close
Unusual patterns, like a late-night crypto transaction, appear far apart

In reality, this space is not 2D, but has hundreds or thousands of dimensions.

That is what allows the model to capture subtle patterns that are not obvious when looking at raw transaction data.

The result is a numerical representation of the transaction that preserves its behavior, making it possible to compare transactions efficiently using vector similarity.

Building the Baseline: Seeding the Fraud Pattern Collection

Now that we can convert transactions into vectors, we need something to compare them against. Vector similarity only works if we have a reference dataset.

This means we need a collection of known patterns that represent both normal and fraudulent behavior. To do that, we create a fraud_patterns collection in MongoDB. Each document in this collection contains:

The original transaction data
A fraud label (true or false)
The corresponding embedding

A normal pattern might look like this:

{ 
"fraud": false, 
"transaction": {
"amount": 13.45, 
"merchant": "Coffee Shop" 
},
"embedding": [ ... ]
}

A fraudulent pattern might look like this:

{ 
"fraud": true, 
"transaction": {
"amount": 87422.45, 
"merchant": "Crypto Exchange" 
},
"embedding": [ ... ]
}

This dataset acts as the baseline for comparison.

Instead of asking “Is this transaction fraudulent?”, we ask: “Does this transaction look like something we already know?”

How This Collection Evolves

This collection does not need to be perfect from the start. It typically begins with a small, curated set of known patterns. As the system runs in production:

Confirmed fraud cases can be added
New patterns can be introduced immediately
The system improves over time

One important advantage here is that we do not need to retrain a model. We simply add new examples to the dataset.

Running Vector Search with MongoDB

To run a vector search, we need to create a vector index. This index allows MongoDB to efficiently search for similar vectors.

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

java

Each field here matters.

type: "vector" tells MongoDB that this field contains embeddings
path: "embedding" defines where the vector is stored in the document
numDimensions: 1024 must match the size of the vectors produced by the model
similarity: "cosine" defines how similarity between vectors is calculated

If the number of dimensions does not match the embedding model, the index will not work correctly.

Performing the Search

Once the index is in place, MongoDB can efficiently find the nearest vectors. From Spring Data MongoDB, this becomes very straightforward:

@Repository
public interface FraudPatternRepository extends MongoRepository<FraudPattern, String> {

@VectorSearch(
indexName = "fraud_patterns_vector_index",
limit = "10",
numCandidates = "200"
)
SearchResults<FraudPattern> searchTopFraudPatternsByEmbeddingNear(
Vector vector,
Score score
);
}

This method takes the transaction embedding as input and returns the most similar patterns stored in the collection.

Not All Matches Are Equal: Introducing the Threshold

After running the search, MongoDB returns the closest matches along with similarity scores. For example:

Result 1 = score: 0.94
Result 2 = score: 0.91
Result 3 = score: 0.72
Result 4 = score: 0.60

Each score tells us how similar a stored pattern is to the transaction we are analyzing. In practice, vector search returns the closest matches available, even when the similarity is relatively low.

That is why we introduce a threshold.

A threshold defines the minimum similarity score required for a result to be considered relevant.

Any result below this value is ignored. Choosing the right threshold is critical:

Too low → many false positives
Too high → missed fraud cases

The ideal value depends on your domain and risk tolerance.

The Full Architecture

Putting it all together, the flow looks like this:

Client App produces a transaction event to a Kafka topic.
**FraudDetectorProcessor **consumes the event via Kafka Streams.
Guardrails run first: velocity check using local state store and impossible travel check. If triggered, the transaction is immediately inserted into the suspicious_transactions collection.
If it passes guardrails, it proceeds to Vector Scoring.
The transaction is converted into an embedding and compared against fraud patterns in MongoDB using cosine similarity.
If the score exceeds the threshold against a fraud-labeled pattern, the transaction is flagged as suspicious. Otherwise, it is approved.
Results flow to downstream services via Kafka.

Beyond Rules and Similarity

What we built here is just one way to approach fraud detection.

We combined simple rule-based checks with vector similarity to detect patterns in real time. Guardrails work really well for obvious cases, while vector search helps catch things that don’t follow clear rules.

But fraud detection is not the same for everyone.

Something that looks suspicious for one user might be totally normal for another. For example, a late-night crypto transaction might be unusual for most people, but not for someone who trades crypto regularly.

That’s where things can evolve.

One next step would be to include some form of user profiling, where the system learns how each user behaves over time and uses that as part of the decision.

Instead of only comparing against global patterns, we could also compare against the user’s own history. That adds more context and helps reduce false positives.

At the end of the day, it’s about combining different approaches: simple rules for quick decisions, vector similarity for behavior, and more context to better understand each user.

Source Code

The full project is available on GitHub. You can check out the code, run it locally, and see how everything fits together, from Kafka Streams and guardrails to vector scoring and MongoDB.

You’ll also find all the setup instructions in the README, including how to start Kafka, configure the embedding generator, and run simulations to test different scenarios.

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.