DEV Community: MongoDB

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 E-commerce AI Agents on MongoDB with CrewAI

Jordan Smith — Tue, 25 Aug 2026 17:04:18 +0000

AI-powered shopping agents are becoming a real differentiator for e-commerce teams. A 2026 Stord report on AI in e-commerce revealed a 34% year-over-year increase in the number of consumers who reported using generative AI for online shopping. The trend is even more pronounced among younger consumers: 37% of Gen Z and 29% of Millennials actively use AI to shop online. After seeing how the agentic commerce journey actually works, it's not hard to understand why.

This tutorial shows you exactly how to build one on MongoDB Atlas with CrewAI. You’ll create a chat-based shopping assistant that understands natural-language queries, retrieves relevant products with MongoDB Vector Search and MongoDB Search, and uses Change Streams, Atlas Triggers, and Atlas Stream Processing to keep inventory, checkout, and post-purchase experiences in sync with real-time data.

By the end, you’ll be able to:

Build a CrewAI shopping agent that calls MongoDB Vector Search tools with structured filters (price, availability).
Model an e-commerce catalog on MongoDB and generate high-quality product embeddings for semantic search.
Use MongoDB Change Streams to make checkout flows inventory-aware at the moment of purchase.
Trigger post-purchase workflows and customer notifications with MongoDB Atlas Triggers.
Detect emerging delivery issues with MongoDB Atlas Stream Processing so agents can respond proactively.

This GitHub repository wires up the code samples in this post. The code will help you build a CrewAI shopping agent and use MongoDB Vector Search on Atlas to understand the semantic meaning of customer queries, implement atomic inventory checkout with Change Streams, and (as deploy-ready artifacts) create an Atlas Trigger and an Atlas Stream Processing pipeline for post-purchase intelligence.

What is the agentic commerce journey?

Here is how a fully agentic shopping experience (a.k.a zero-click buying) works in practice:

A customer asks a question: Via voice or text, they describe what he/she needs. The agent interprets the intent behind the query, not just the keywords.
The agent finds and curates the best options: It surfaces a short list of products with detailed specifications, pricing, deals, quality ratings, and reviews.
The customer makes a purchase decision: With curated options in the chat interface, the customer asks follow-up questions and then decides to purchase. What used to take hours of browsing now takes minutes.
The agent completes the transaction: For products that support instant checkout, the agent handles the entire payment process end-to-end (provided the customer’s payment information is on file). If not, the agent can safely ask the customer to provide payment information, encrypt it, and securely store it in the database for future use.
The agent handles everything post-purchase: It tracks the order, surfaces proactive updates when status changes, and manages returns or follow-ups if something goes wrong.

Each step in this journey places real technical demands on the underlying platform. The agent needs to understand natural language, retrieve semantically relevant products, evaluate quality and price across thousands of options, confirm inventory accuracy at the moment of purchase, and stay aware of order events without waiting to be asked. That's a lot of moving parts. Most teams choose to build them on a collection of separate systems, each adding its own overhead, latency, and points of failure. But what if a single platform could support these capabilities without requiring teams to stitch together multiple specialized systems?

That is where MongoDB comes in. By combining operational data, semantic search, real-time updates, and transactional capabilities into a single platform, MongoDB can support the different stages of the agentic commerce journey.

How do MongoDB capabilities fit into each step of the agentic commerce journey?

Agent Journey Step	MongoDB Feature
Understand customer intent	Atlas Vector Search + LLM integration + Voyage AI embedding model
Produce relevant results	Atlas Vector Search + MongoDB Search
Answer follow-up questions	Atlas Vector Search + MongoDB Search
Confirm inventory at checkout	Change Streams
Proactive order status updates	Atlas Triggers
Detect delivery patterns before they escalate	Atlas Stream Processing

MongoDB is a strong candidate because it offers the native features required to power each step of the agentic commerce journey. Let's see how.

Step 1–3: How do MongoDB Vector Search on Atlas and MongoDB Search power agent discovery and decision-making?

When a customer types "lightweight running shoes under $100 with good arch support," they're describing an intent. The agent needs to understand the semantic meaning behind that query and match it to products that fit that intent. The agent needs to understand the user's intent, not just focus on keywords.

MongoDB Vector Search on Atlas handles this natively. Your product embeddings are stored alongside your product data in the same cluster. When a query comes in, the agent converts it to a vector using a best-in-class embedding model (Voyage AI), runs a search in your product catalog, and retrieves the most semantically relevant results, ranked by relevance rather than just keyword frequency. We can refer to this as a product-search tool. Let’s see exactly how to build it.

First, use the code below to create a Vector Search index that includes both the embedding field and the fields the agent will use as filters. For the query to work, the collection needs a Vector Search index that matches the fields used in the code. The embedding field is indexed as the vector field, with 2048 dimensions to match the Voyage AI embedding model. The price and in_stock fields are indexed as filter fields, which lets MongoDB apply those constraints before running the vector similarity search. That means the agent searches only for products under $100 and available to buy, rather than retrieving relevant products first and filtering them afterward.

function productToEmbeddingText(product) {
  return [
    `Name: ${product.name}`,
    `Brand: ${product.brand}`,
    `Category: ${product.category}`,
    `Description: ${product.description}`,
    `Features: ${(product.features || []).join(", ")}`,
    `Review summary: ${product.reviewSummary}`,
    `Price: ${product.price}`,
    `In stock: ${product.in_stock}`
  ].filter(Boolean).join("\n");
}

const embeddingText = productToEmbeddingText(product);
const embedding = await createEmbedding(embeddingText);

await db.collection("products").updateOne(
  { _id: product._id },
  {
    $set: {
      embedding,
      embedding_text: embeddingText
    }
  }
);

With that index in place, the agent can run a semantic search and apply price and inventory constraints before performing similarity ranking. Here is the code for that:

{
  "fields": [
    {
      "type": "vector",
      "path": "embedding",
      "numDimensions": 2048,
      "similarity": "cosine"
    },
    {
      "type": "filter",
      "path": "price"
    },
    {
      "type": "filter",
      "path": "in_stock"
    }
  ]
}

Next, use the code below to create the CrewAI shopping agent that uses the product search tool. The agent is given a role, a goal, and a backstory so it understands how to behave during the shopping experience. By attaching search_product_catalog (defined next) as a tool, we give the agent access to MongoDB Vector Search in Atlas and the live product catalog. When a customer asks for a recommendation, the agent can call that tool, retrieve relevant in-stock products, and use the results to provide a helpful, context-aware answer.

from crewai import Agent

shopping_agent = Agent(
    role="Shopping assistant",
    goal="Help customers find products that match their intent and constraints.",
    backstory=(
        "You help customers discover relevant products using MongoDB Atlas "
        "Vector Search and real-time product data."
    ),
    tools=[search_product_catalog],
    llm="gpt-4o",
)

The search_product_catalog function is the tool attached to the CrewAI shopping agent. When the agent needs to search the catalog, this tool connects to the product collection, uses Voyage AI to convert the customer’s request into a query embedding, and runs MongoDB Vector Search in Atlas against the embedding field using product_vector_index. The semantic part of the request, such as “lightweight running shoes with good arch support,” is handled by Vector Search, while the hard constraints, price <= 100 and in_stock: true, are applied as pre-filters. The result is a reusable CrewAI tool that returns products that are both semantically relevant and eligible for the customer to buy.

import os
from bson import json_util
from pymongo import MongoClient
from crewai.tools import tool

client = MongoClient(os.environ["MONGODB_URI"])
collection = client["ecommerce"]["products"]


@tool("Search product catalog")
def search_product_catalog(query: str) -> str:
    """Find in-stock products under $100 that semantically match the query.

    This version uses Atlas Vector Search auto-embedding. The application sends
    natural-language query text directly to MongoDB; Atlas generates the query
    embedding using the model configured in the Vector Search index.
    """

    pipeline = [
        {
            "$vectorSearch": {
                "index": "product_autoembed_index",
                "path": "search_text",
                "query": {
                    "text": query
                },
                "numCandidates": 100,
                "limit": 5,
                "filter": {
                    "$and": [
                        {"price": {"$lte": 100}},
                        {"in_stock": True}
                    ]
                }
            }
        },
        {
            "$project": {
                "_id": 0,
                "name": 1,
                "description": 1,
                "price": 1,
                "in_stock": 1,
                "score": {"$meta": "vectorSearchScore"}
            }
        }
    ]

    results = list(collection.aggregate(pipeline))
    return json_util.dumps(results, indent=2)

Alternative: Let Atlas generate embeddings automatically

The previous example shows manual embedding generation. If you want less application code, MongoDB Vector Search on Atlas can generate document and query embeddings automatically using an autoEmbed index. In that version, the app sends natural language query text directly to $vectorSearch. The code below explains how MongoDB Vector Search on Atlas generates document and query embeddings automatically.

{
  "fields": [
    {
      "type": "autoEmbed",
      "modality": "text",
      "path": "search_text",
      "model": "voyage-4"
    },
    {
      "type": "filter",
      "path": "price"
    },
    {
      "type": "filter",
      "path": "in_stock"
    }
  ]
}

For structured filtering, such as price ranges, brand filters, and in-stock flags, MongoDB Search layers on top of Vector Search. The agent can combine semantic similarity with exact filters in a single query, returning results that are both contextually relevant and within the customer's stated constraints.

Because your product catalog, inventory levels, reviews, and pricing (i.e., operational data) all reside in the same MongoDB database, the agent retrieves a complete, enriched product document in a single call.

Example output:

This is an example of the application's output in response to “Find in-stock products under $100 that semantically match the query.”

[
  {
    "name": "AeroFlex Runner 2",
    "description": "Lightweight daily running shoe with responsive foam and built-in arch support.",
    "price": 89.99,
    "in_stock": true,
    "score": 0.91
  },
  {
    "name": "CloudStep Support Knit",
    "description": "Breathable road running shoe designed for moderate overpronation and arch comfort.",
    "price": 94.5,
    "in_stock": true,
    "score": 0.88
  }
]

Optional: Connect your agent with the MongoDB MCP Server

The product-search tool above is one way to expose MongoDB to the agent. For more dynamic agent workflows, you can also connect the agent to MongoDB through the MongoDB MCP Server. MCP provides a standard tool interface that lets the agent discover MongoDB resources and issue structured database operations with the permissions you configure. In an e-commerce shopping flow, the agent could use MCP to look up product metadata, inspect inventory fields, retrieve customer order context, or run follow-up queries after Vector Search returns candidate products.

In the code below, the CrewAI agent is connected to MongoDB in two ways. The search_product_catalog tool handles the primary product discovery flow using Atlas Vector Search, while the MongoDB MCP Server provides the agent with a standard tool interface for follow-up database operations. The MCP server runs in read-only mode and exposes only selected tools, such as collection schema, find, and aggregate, so the agent can look up product details, inventory fields, or customer context without being given unrestricted database access.

import os
from crewai import Agent
from crewai.mcp import MCPServerStdio
from crewai.mcp.filters import create_static_tool_filter

mongo_mcp = MCPServerStdio(
    command="npx",
    args=[
        "-y",
        "mongodb-mcp-server@latest",
        "--readOnly",
    ],
    env={
        "MDB_MCP_CONNECTION_STRING": os.environ["MDB_MCP_CONNECTION_STRING"],
    },
    tool_filter=create_static_tool_filter(
        allowed_tool_names=[
            "list-databases",
            "list-collections",
            "collection-schema",
            "collection-indexes",
            "find",
            "aggregate",
        ]
    ),
    cache_tools_list=True,
)

shopping_agent = Agent(
    role="Shopping assistant",
    goal="Help customers find products that match their intent and constraints.",
    backstory=(
        "You help customers discover relevant products using MongoDB Atlas "
        "Vector Search, Atlas auto-embedding, live product data, and MongoDB MCP tools."
    ),
    tools=[search_product_catalog],
    mcps=[mongo_mcp],
    llm="gpt-4o",
)

Step 4: How do MongoDB Change Streams help with the checkout process?

This is where most teams don't anticipate the problem until they're already in production.

A customer has found the product, decided to buy it, and initiated checkout. At that exact moment, the agent needs to confirm that the item is still available.

During a high-traffic sale, inventory moves fast. The last unit of a limited-edition product can sell in the seconds between when a customer adds it to their cart and when the transaction is confirmed. If the agent is working with inventory data that doesn't reflect the final sale, the purchase goes through, the inventory system immediately rejects it, and the customer receives an "item not available" notification along with a refund. At scale, that failure pattern compounds quickly into frustrated customers, support overhead, and refund costs that add up fast.

MongoDB solves this in two parts: an atomic inventory update keeps checkout running smoothly, while Change Streams let the agent react immediately after inventory changes are committed. Change Streams is a cursor-based API that subscribes to document-level changes in a collection as soon as a write is committed to the database. There is no polling interval and therefore no sync gap. When inventory for a product drops to zero, the Change Stream fires instantly, and the agent receives the data instantly.

In the code below, checkout is protected by an atomic inventory update. The function looks for a product with the requested sku and enough remaining quantity, then decrements the quantity in the same database operation. If another customer has already purchased the last unit, the query no longer matches, and MongoDB returns None, so the checkout flow can stop before confirming the item is unavailable. Using ReturnDocument.AFTER returns the updated inventory document, giving the agent the freshest committed state after the reservation succeeds.

from pymongo import MongoClient, ReturnDocument

client = MongoClient(MONGODB_URI)
inventory = client["ecommerce"]["inventory"]


def reserve_inventory(sku: str, quantity: int = 1):
    """Atomically reserve inventory during checkout."""
    updated_product = inventory.find_one_and_update(
        {
            "sku": sku,
            "quantity": {"$gte": quantity},
        },
        {
            "$inc": {"quantity": -quantity},
        },
        return_document=ReturnDocument.AFTER,
    )

    if updated_product is None:
        raise ValueError(f"Product {sku} is no longer available.")

    return updated_product

In the code below, Change Streams detect when a product's inventory drops to zero. That event kicks off a CrewAI workflow: an inventory recovery agent finds active carts that still contain the sold-out SKU, suggests alternatives, and notifies affected customers. MongoDB handles the real-time event stream, while CrewAI handles the agent’s reasoning and tool orchestration.

from pymongo import MongoClient
from crewai import Agent, Task, Crew, Process
from crewai.tools import tool

client = MongoClient(MONGODB_URI)
inventory = client["ecommerce"]["inventory"]


@tool("Find active sessions with SKU")
def find_active_sessions_with_sku(sku: str) -> list[str]:
    """Find active shopping sessions that currently have this SKU in cart."""
    # Replace with a query against your sessions/carts collection.
    return []


@tool("Suggest alternative product")
def suggest_alternative(sku: str) -> str:
    """Suggest a similar in-stock product for the provided SKU."""
    # Replace with MongoDB Vector Search or product recommendation logic.
    return f"Suggested replacement for {sku}"


@tool("Notify customer")
def notify_customer(session_id: str, message: str) -> str:
    """Send a message to a customer shopping session."""
    # Replace with chat, email, SMS, or app notification logic.
    return f"Queued notification for {session_id}"


stock_recovery_agent = Agent(
    role="Inventory recovery specialist",
    goal=(
        "Recover active shopping sessions when a product sells out by finding "
        "affected carts, suggesting alternatives, and notifying customers."
    ),
    backstory=(
        "You support an e-commerce shopping agent. When inventory changes, "
        "you help customers continue checkout with the least possible friction."
    ),
    tools=[
        find_active_sessions_with_sku,
        suggest_alternative,
        notify_customer,
    ],
    llm="gpt-4o",
)

stock_recovery_task = Task(
    description=(
        "Product {sku} just sold out. Find active sessions that still have "
        "this item in cart, suggest suitable alternatives, and notify each "
        "affected customer clearly."
    ),
    expected_output=(
        "A summary of affected sessions, suggested alternatives, and customer "
        "notifications that were queued."
    ),
    agent=stock_recovery_agent,
)

stock_recovery_crew = Crew(
    agents=[stock_recovery_agent],
    tasks=[stock_recovery_task],
    process=Process.sequential,
)

pipeline = [
    {
        "$match": {
            "operationType": "update",
            "fullDocument.quantity": 0,
        }
    }
]

with inventory.watch(pipeline, full_document="updateLookup") as stream:
    for event in stream:
        product = event["fullDocument"]
        sku = product["sku"]

        stock_recovery_crew.kickoff(
            inputs={
                "sku": sku,
            }
        )

Step 5: How do Atlas Triggers and Atlas Stream Processing help with Post-purchase intelligence?

The post-purchase stage is where most shopping agents stop short. A customer who has paid expects to be kept informed without having to ask. That means the agent needs to respond when order data changes, especially when a shipment enters a state that matters to the customer.

Atlas Triggers: Reacting to individual order events

When an order’s status changes to "shipped", that update is a committed database event. Atlas Triggers are a fully managed way to react to that event: Atlas opens and maintains the underlying change stream, applies your trigger filter, and invokes a serverless function when a matching order update occurs.

In the code below, the Trigger is configured on the orders collection to run only when an order status changes to "shipped", with full-document lookup enabled for update events. The function receives the updated order document through changeEvent.fullDocument builds a JSON request body with API-friendly values, then sends it to the post-purchase agent endpoint.

From there, the agent can pull the customer’s order history, anticipate likely follow-up questions such as delivery window, return policy, and product setup, and prepare a personalized response so the next customer interaction feels informed and seamless.

// Atlas Trigger Function — fires when an order status changes to "shipped"
exports = async function(changeEvent) {
  const order = changeEvent.fullDocument;

  if (!order || order.status !== "shipped") {
    return { skipped: true };
  }

  const response = await context.http.post({
    url: "https://your-agent-endpoint.com/post-purchase",
    body: {
      customerId: order.customerId,
      orderId: order._id.toString(),
      product: order.product,
      estimatedDelivery: order.estimatedDelivery
    },
    encodeBodyAsJSON: true
  });

  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw new Error(
      `Post-purchase agent request failed with status ${response.statusCode}`
    );
  }

  return {
    ok: true,
    orderId: order._id.toString(),
    statusCode: response.statusCode
  };
};

Atlas Stream Processing: Detecting patterns before they become problems

Some post-purchase issues don't surface as a single event but emerge as a pattern. A carrier delay affecting multiple orders in the same region, such as due to an unexpected weather event, doesn't appear as a single document change. It shows up as a sustained pattern of delivery estimates shifting across an order cohort.

Atlas Stream Processing runs continuous aggregation pipelines over your order data and surfaces confirmed patterns before they reach customers. As illustrated in the code below, Atlas Stream Processing monitors delivery-estimate updates in the orders collection. Each update represents one order whose delivery date changed, but a single delayed order usually is not enough to involve an agent. The processor first filters for meaningful delays, such as orders whose estimated delivery time has moved by 30 minutes or more, then waits for a two-minute tumbling window to evaluate a batch of recent updates together.

Within each window, it groups delayed orders by carrier and shippingRegion. If at least 10 orders in the same carrier-region cohort are delayed, and the average delay across that group is at least 45 minutes, the processor writes one confirmed signal to agent_triggers.

A separate Change Stream can then watch that collection and invoke the demand-management agent. Then, the demand management agent can proactively draft customer communications, alert the logistics team, and flag the issue for resolution before customers start calling about missing orders. Imagine how many fewer calls your customer support team will receive if customers are proactively informed about shipping delays.

[
  {
    "$source": {
      "connectionName": "mongodb-atlas",
      "db": "ecommerce",
      "coll": "orders",
      "fullDocument": "updateLookup",
      "pipeline": [
        {
          "$match": {
            "operationType": "update",
            "updateDescription.updatedFields.estimatedDelivery": {
              "$exists": true
            }
          }
        }
      ]
    }
  },
  {
    "$replaceRoot": {
      "newRoot": "$fullDocument"
    }
  },
  {
    "$match": {
      "status": {
        "$in": ["shipped", "in_transit"]
      },
      "carrier": {
        "$exists": true
      },
      "shippingRegion": {
        "$exists": true
      },
      "originalEstimatedDelivery": {
        "$exists": true
      },
      "estimatedDelivery": {
        "$exists": true
      }
    }
  },
  {
    "$addFields": {
      "delayMinutes": {
        "$dateDiff": {
          "startDate": "$originalEstimatedDelivery",
          "endDate": "$estimatedDelivery",
          "unit": "minute"
        }
      }
    }
  },
  {
    "$match": {
      "delayMinutes": {
        "$gte": 30
      }
    }
  },
  {
    "$tumblingWindow": {
      "boundary": "processingTime",
      "interval": {
        "size": 2,
        "unit": "minute"
      },
      "pipeline": [
        {
          "$group": {
            "_id": {
              "carrier": "$carrier",
              "region": "$shippingRegion",
              "windowStart": {
                "$meta": "stream.window.start"
              }
            },
            "affectedOrderCount": {
              "$sum": 1
            },
            "averageDelayMinutes": {
              "$avg": "$delayMinutes"
            },
            "maxDelayMinutes": {
              "$max": "$delayMinutes"
            },
            "affectedOrders": {
              "$push": "$_id"
            }
          }
        }
      ]
    }
  },
  {
    "$match": {
      "affectedOrderCount": {
        "$gte": 10
      },
      "averageDelayMinutes": {
        "$gte": 45
      }
    }
  },
  {
    "$project": {
      "_id": {
        "$concat": [
          "delivery-delay:",
          "$_id.carrier",
          ":",
          "$_id.region",
          ":",
          {
            "$toString": "$_id.windowStart"
          }
        ]
      },
      "type": "delivery_delay_pattern",
      "severity": "warning",
      "carrier": "$_id.carrier",
      "region": "$_id.region",
      "windowStart": "$_id.windowStart",
      "affectedOrderCount": 1,
      "averageDelayMinutes": {
        "$round": ["$averageDelayMinutes", 0]
      },
      "maxDelayMinutes": 1,
      "affectedOrders": {
        "$slice": ["$affectedOrders", 25]
      },
      "agentAction": "draft_customer_delay_notice"
    }
  },
  {
    "$merge": {
      "into": {
        "connectionName": "mongodb-atlas",
        "db": "ecommerce",
        "coll": "agent_triggers"
      },
      "on": "_id",
      "whenMatched": "replace",
      "whenNotMatched": "insert"
    }
  }
]

Decision framework: How to choose the right event-driven service?

The decision framework below helps you choose the right event-driven service for your use case:

Figure 1. Choosing between Change Streams, Atlas Triggers, and Atlas Stream Processing based on your agent's use case.

Conclusion

Building a fully agentic shopping experience requires more than a good model and a well-tuned prompt. Every step of the journey, from product discovery to post-purchase follow-up, places real demands on the underlying data platform. The agent needs to retrieve semantically relevant products, confirm inventory at the moment of purchase, and react to order events without waiting to be asked.

Most teams solve this by assembling a stack of specialized systems: a search service, a vector database, a message broker, event processing infrastructure, and an operational database underneath it all. That architecture can work, but every handoff adds latency, synchronization headaches, operational overhead, and another point where data can drift from reality. For an agent that needs to reason and act in the moment, those gaps mean the agent fails to provide customers with valuable information when needed. Not because there is anything wrong with the agent, but because the data it relied on was outdated.

MongoDB consolidates these into a single platform. Vector Search, MongoDB Search, Change Streams, Atlas Triggers, and Atlas Stream Processing are all native features of the same cluster that holds your operational data. The agent works with data that reflects the world as it actually is, and the architecture stays simple enough to debug when something inevitably needs attention.

Build your first agent with MongoDB and CrewAI

If you want to put this into practice, MongoDB has an official integration with CrewAI. Use this GitHub repository to start building your E-commerce AI agents on MongoDB.

If you are already running on MongoDB Atlas, you have everything you need to get started. Sign up for MongoDB Atlas and follow the CrewAI integration tutorial to deploy your first e-commerce agent today.

Building a Movie Recommendation Agent with Microsoft Agent Framework and MongoDB

MongoDB Guests — Mon, 17 Aug 2026 11:06:18 +0000

This tutorial was written by Markus Wildgruber.

In October 2025, Microsoft announced a new iteration of their AI Agent framework, called Microsoft Agent Framework. General Availability of the framework was announced in April 2026.

This framework is directed at C# and Python developers and seeks to consolidate the previous frameworks, Semantic Kernel, and AutoGen. If you have used Semantic Kernel before, some of the interfaces will be familiar to you, but especially the RAG part has changed a bit. This is what we will focus on throughout this article.

The sample: a Movie Recommendation Agent

In their sample_mflix-database, MongoDB provides a collection embedded_movies that already has embeddings created for a part of their movies collection. Equipped with this dataset, we can easily create a Movie Recommendation Agent that queries the collection using a vector search and provides answers grounded in this data.

To run this sample, you need the following components:

An instance of the MongoDB sample_mflix database with the embedded_movies collection. Please see this link for instructions on creating a free MongoDB Atlas M0 cluster. This article shows how to load the sample data into your cluster.
A vector search index named default on the embedded_movies collection. You can create this index in the MongoDB Atlas UI or have the sample code create it for you. Please note that creating the index will take a small amount of time. Use the following parameters when creating the index manually:
- Vector similarity: Cosine
- Dimensions: 1536 (the embeddings have been generated with text-embedding-ada-002 that yields vectors with 1536 dimensions)
A large language model (LLM) that is used for generating chat messages. This model must be capable of using tools. In this sample, we have used a deployment of OpenAI's gpt-4.1 model hosted on Azure OpenAI.
An embedding model that is used to vectorize the queries that the LLM generates when retrieving data for its chat messages. As the embeddings in the collection have been created using text-embedding-ada-002, we also need to use this model. In our case, this model was also hosted on Azure OpenAI.

The sample uses Blazor to create a basic user interface for the agent and shows two methods on how to put together the vector search:

Using MongoDB C# Driver directly
Using MongoDB Vector Store Connector

You can clone the repository with the sample code from Github. After downloading the sample, you can open it in Visual Studio Code or Visual Studio. To configure the secrets, you can use dotnet user-secrets and set at least the following configuration settings for the database connection string, the Azure OpenAI endpoint, and the name of the chat deployment:

dotnet user-secrets set MongoDB:ConnectionString "mongodb+srv://..."
dotnet user-secrets set Endpoint "https://..."
dotnet user-secrets set ChatDeployment "gpt-4.1"

The following two settings are optional:

dotnet user-secrets set MongoDB:Database "sample_mflix"
dotnet user-secrets set EmbeddingDeployment "text-embedding-ada-002"

A central piece is our Movie class that maps the MongoDB documents to a C# POCO:

using Microsoft.Extensions.VectorData;
using MongoDB.Bson.Serialization.Attributes;

namespace MongoDBSamples;

[BsonIgnoreExtraElements]
public record Movie(
    [property: BsonRepresentation(
        MongoDB.Bson.BsonType.ObjectId), 
        VectorStoreKey()] string Id,
    [property: BsonElement("title")] string Title,
    [property: BsonElement("plot")] string Plot,
    [property: BsonElement("fullplot")] string FullPlot,
    [property: BsonElement("cast")] List<string> Cast,
    [property: BsonElement("genres")] List<string> Genres,
    [property: BsonElement("plot_embedding"), VectorStoreVector(1536)]
        ReadOnlyMemory<float> PlotEmbedding
);

As you can see, the definition contains both attributes for declarative MongoDB mappings and also an attribute for the Vector Store implementation.

Setting up the clients

The first step when creating an agent with Microsoft Agent Framework is to set up a ChatClient instance. In our case, we will use dependency injection to set up singleton instances of AzureOpenAIClient and ChatClient:

builder.Services.AddSingleton<AzureOpenAIClient>(prov =>
    new(new Uri(cfg.Endpoint), new DefaultAzureCredential())
);
builder.Services.AddSingleton<ChatClient>(prov =>
    prov.GetRequiredService<AzureOpenAIClient>().GetChatClient(cfg.ChatDeployment)
);

In this case, it is a two-step process: first, we create an instance of AzureOpenAIClient, which is initialized with our configuration settings and uses a DefaultAzureCredential for access (in a production scenario, we would use a more fine-grained approach to explicitly use the authentication method of your choosing). Your user needs to be authenticated with Azure and have access to the models in Azure OpenAI for access to work.

Afterwards, we create the ChatClient instance that is the centerpiece of our agent.

In addition, we need an EmbeddingClient to generate the vectors for our queries:

builder.Services.AddSingleton<EmbeddingClient>(prov =>
    prov.GetRequiredService<AzureOpenAIClient>().GetEmbeddingClient(cfg.EmbeddingDeployment)
);

In addition, we register singleton instances of IMongoClient, IMongoDatabase and IMongoCollection<Movie> with the IoC-container. Please note that a vector search index named default is created when requesting the IMongoCollection<Movie> instance, in case it does not exist yet. This is to simplify running the sample, but the index should be created explicitly in a production scenario. Should the index be created, wait a bit for the index to be ready before hitting it with queries.

If you are working on a MongoDB Atlas M0 cluster, there is a limit on the number of search indexes you can create. If you already have three search indexes in your cluster, you need to remove one to run the sample.

Movie recommendation service implementation

In order to reuse the common parts of the Movie Recommendation Service, there is an interface IMovieRecommendationService that is implemented in the following class hierarchy:

Both approaches demonstrated in the following chapters share a lot of common code, e.g., the need to keep the chat history and the common steps for asking the agent for a recommendation. By creating a class hierarchy, the services can share a general approach and only have their specific logic for finding the relevant context via vector search.

Program.cs also contains the keyed registrations for the instances of the relevant services:

MongoDBVectorSearchMovieRecommendationService performs a vector search directly with the tools of the MongoDB C# Driver.
MongoDBVectorStoreMovieRecommendationService uses the MongoDB Vector Store Connector that has been created for Microsoft Semantic Kernel. So if you are already using this approach, the sample shows how to continue using a MongoDB-specific implementation of a VectorStore.

Through these keyed registrations, we can later on have a shared UI that uses the value of a route parameter to decide which implementation to use.

Creating recommendations

Let's have a closer look at the base class MovieRecommendationServiceBase. This class implements the general algorithm and contains the shared logic for the agents.

In its constructor, it injects the ChatClient instance and creates the agent with a common set of TextSearchOptions:

        _agent = chatClient.AsAIAgent(
            new ChatClientAgentOptions
            {
                ChatOptions = new()
                {
                    Instructions = """
                    You are a conversational movie recommendation agent. 
                    ...lengthy system prompt
                    """,
                },
               AIContextProviders = 
                   [new TextSearchProvider(RetrieveContextAsync, textSearchOptions)]
            }
        );

A crucial part when creating the agent is providing the instructions or system prompt that describes its capabilities:

You are a conversational and enthusiastic movie recommendation agent. Your goal is to help users find films based on their preferences.

**Core Guidelines:**
1. **Tool Usage:** You have access to the `TextSearch` tool. You must use this tool to verify plots, cast, genres, and release dates before answering. Do not rely on general training data for specific movie details.
2. **Citations:** When providing movie details, include a source link in your answer. Use ONLY the relative links found in the tool search results (e.g., [Link Text](/movies/123)). Do not invent or link to external URLs.
3. **Accuracy:** If the search tool returns no results for a specific query, do not hallucinate. State clearly that the movie or details are not found in your database.
4. **Conciseness & Tone:** Keep responses concise (maximum 2-3 sentences) but maintain an energetic, helpful tone. Use Markdown formatting (bolding, lists) to improve readability.
5. **Scope:** You specialize in movies. If a user asks about non-movie topics, politely redirect the conversation back to film recommendations.

**Response Format:**
- Use Markdown.
- Prioritize tool-verified information.
- Ensure all links are relative to the current application.

As you can see from the prompt above, it strongly encourages the agent to use context rather than rely on its own training data when providing recommendations. It also guides it to only use relative links within the current web application. This way, we can provide further details based on the data in our MongoDB database.

The AIContextProviders property is initialized with a list of context providers that - in our case - contains a TextSearchProvider instance.

The textSearchOptions are set up like this:

TextSearchProviderOptions textSearchOptions = new()
{
    SearchTime = 
        TextSearchProviderOptions.TextSearchBehavior.OnDemandFunctionCalling,
};

This defines how the agent should retrieve the context: OnDemandFunctionCalling tells the agent to use the provider like a tool and use it as it sees fit when answering the question, while BeforeAIInvoke leads to a context search being conducted before calling the LLM - the classic RAG approach. In our case, we use OnDemandFunctionCalling so that the LLM has a chance to adjust the query that is used to retrieve the context and optimize it for the query.

The most important part of the TextSearchProvider is the provided RetrieveContextAsync method. This method calls the RetrieveContextAsync method that is responsible for finding the relevant context:

private async Task<IEnumerable<TextSearchProvider.TextSearchResult>> RetrieveContextAsync(
    string query,
    CancellationToken ct
)
{
    _logger.LogInformation(
        "Retrieving context using method {Method} with query: {Query}",
        Name,
        query
    );

    List<Movie> movies = await RetrieveMoviesAsync(query, ct);

    _logger.LogInformation(
        "Retrieved {Count} movies for query {Query} with method {Method}",
        movies.Count,
        query,
        Name
    );

    return movies.Select(m => MapToSearchResult(m));
}

At the end, it converts the movies to TextSearchResult objects that the agent uses. This format contains a title, a link to details, and relevant information about the movie in text form:

private static TextSearchProvider.TextSearchResult MapToSearchResult(Movie m)
{
    var cast = m.Cast ?? new List<string>();
    var genres = m.Genres ?? new List<string>();

    return new TextSearchProvider.TextSearchResult
    {
        SourceName = m.Title,
        SourceLink = $"/movies/{m.Id}",
        Text =
            $@"""
            Title: {m.Title}
            Plot: {m.Plot}
            Full plot: {m.FullPlot}
            Cast: {string.Join(", ", cast)}
            Genres: {string.Join(", ", genres)}
            """,
    };
}

The base class then defines the abstract method that the derived classes need to implement:

protected abstract Task<List<Movie>> RetrieveMoviesAsync(string query, CancellationToken ct);

The main input is the query parameter that is used to retrieve matching documents from MongoDB.

This method is used by the implementations to convert the Movie objects returned into TextSearchResults for the agent.

The user interface

As stated above, this sample uses a Blazor application to let the user chat with the implementations of the agent. This application is kept very simple and would be much more sophisticated in terms of state management, etc.

The main component MovieRecommendator.razor receives the chosen implementation as a route parameter, creates the requested instance, and uses this to chat with the agent:

@page "/movie-recommendator/{key}"

// ...

protected override void OnParametersSet()
{
    base.OnParametersSet();
    RecommendationService = 
        ServiceProvider.GetRequiredKeyedService<IMovieRecommendationService>(key);
}

private async Task SendMessage()
{
    if (!string.IsNullOrWhiteSpace(userInput))
    {
        isLoading = true;
        StateHasChanged();
        try
        {
            AgentResponse response = 
                await RecommendationService.RecommendAsync(
                    userInput, CancellationToken.None);
            userInput = string.Empty;
        }
        finally
        {
            isLoading = false;
            StateHasChanged();
            await inputRef.FocusAsync();
        }
    }
}

Approach #1: MongoDB Vector Search with MongoDB C# Driver

The first implementation uses the methods that are provided by the MongoDB C# Driver directly, after vectorizing the query:

protected override async Task<List<Movie>> RetrieveMoviesAsync(
    string query,
    CancellationToken ct
)
{
    OpenAIEmbedding embedding = 
        await _embeddingClient.GenerateEmbeddingAsync(query);
    QueryVector queryVector = new(embedding.ToFloats());

    VectorSearchOptions<Movie>? vectorSearchOptions = new()
    {
        IndexName = "default",
        NumberOfCandidates = 100,
    };

    return await _moviesCollection
        .Aggregate()
        .VectorSearch(
            x => x.PlotEmbedding, 
            queryVector, 
            10, 
            vectorSearchOptions)
        .ToListAsync(cancellationToken: ct);
}

We limit our results to 10 movies, which should be enough for the LLM to pick a good match for the query.

Approach #2: Using the MongoDB Vector Store Connector

This implementation makes use of the MongoDB Vector Store Connector to perform the search. In the constructor, the VectorStore instance is created:

public MongoDBVectorStoreMovieRecommendationService(
    IMongoDatabase database,
    ChatClient chatClient,
    EmbeddingClient embeddingClient,
    ILogger<MongoDBVectorStoreMovieRecommendationService> logger
)
    : base(chatClient, logger)
{
    VectorStore vectorStore = new MongoVectorStore(database);
    _coll = vectorStore.GetCollection<string, Movie>("embedded_movies");
    _embeddingClient = embeddingClient;
}

When retrieving the data, the Vector Store is used to perform the vector search:

protected override async Task<List<Movie>> RetrieveMoviesAsync(
    string query,
    CancellationToken ct
)
{
    OpenAIEmbedding embedding = 
        await _embeddingClient.GenerateEmbeddingAsync(query);
    return await _coll
        .SearchAsync(new ReadOnlyMemory<float>(
            embedding.ToFloats().ToArray()), 
            10)
        .Select(m => m.Record)
        .ToListAsync();
}

As you can see, this is very similar to the first approach, but it shortens the code for the search considerably.

Wrapping it up

These two methods show how easy it is to provide an LLM with data from your MongoDB database and create a powerful agent that runs on your data. With Microsoft Agent Framework, you can integrate these functions directly into your application. It allows you to extend a wide range of .NET applications with AI and give powerful tools to your users.

Streaming MongoDB Change Events to Amazon Redshift via Atlas Stream Processing and Kinesis

MongoDB Guests — Wed, 05 Aug 2026 13:13:42 +0000

This tutorial was written by Igor Alekseev.

Real-time data pipelines that move operational data into analytical systems are a cornerstone of modern architectures. In this post, I’ll walk through how to stream MongoDB change events into Amazon Redshift using MongoDB Atlas Stream Processing and AWS Kinesis Data Streams — with no S3 staging or Firehose in between.

Architecture Overview

The flow is straightforward:

MongoDB Atlas — Changes (inserts, updates, replaces) occur in a collection.
Atlas Stream Processing — A stream processor captures these changes via a change stream, filters and reshapes them into flat JSON, and emits records to Kinesis.
AWS Kinesis Data Stream — Acts as the durable, ordered buffer between the source and the analytical store.
Amazon Redshift — A streaming materialized view reads directly from Kinesis and exposes the data as queryable columns.

The key advantage here is simplicity: there’s no intermediate S3 bucket, no Firehose delivery stream, and no ETL job to manage. Data flows from operational writes to analytical queries in near real-time.

Why This Combination?

Atlas Stream Processing handles the hardest part of change data capture — it connects natively to MongoDB change streams, handles resume tokens, and provides a pipeline language (aggregation framework) for reshaping documents on the fly. Instead of writing and hosting a custom consumer, you declare a pipeline, and Atlas manages the execution.

Kinesis provides a durable, ordered stream that decouples the producer (Atlas) from the consumer (Redshift). If Redshift has a maintenance window or you need to replay data, Kinesis retains records for up to 365 days.

Redshift Streaming Ingestion eliminates the traditional pattern of landing data in S3 first. A materialized view reads directly from the Kinesis stream, making new records queryable within seconds of arrival.

Implementation

Step 1: Create the Kinesis Data Stream

aws kinesis create-stream \
  --stream-name atlas-change-events \
  --shard-count 1 \
  --region us-east-1

A single shard handles up to 1 MB/s or 1,000 records/s ingest. Scale shards based on your change event volume.

Step 2: Set Up IAM for Atlas

Atlas Stream Processing authenticates to Kinesis via IAM AssumeRole. Create a role with a trust policy that allows the Atlas AWS account to assume it, and attach minimal Kinesis write permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kinesis:PutRecords",
        "kinesis:DescribeStreamSummary"
      ],
      "Resource": "arn:aws:kinesis:us-east-1:<YOUR_ACCOUNT>:stream/atlas-change-events"
    }
  ]
}

That’s it — just two permissions. Atlas uses the batch API (PutRecords) exclusively, so you don’t need the single-record API (PutRecord) or the full DescribeStream.

Step 3: Register the Kinesis Connection in Atlas

In the Atlas UI, navigate to Stream Processing → Connection Registry → Add Connection → Kinesis, and provide:

The stream name
The AWS region
The IAM role ARN

Step 4: Create the Stream Processor

The stream processor is an aggregation pipeline that runs continuously. Here’s the pattern:

sp.createStreamProcessor("atlasToKinesisProcessor", [
  // 1. Filter for relevant operation types
  { $match: { operationType: { $in: ["insert", "update", "replace"] } } },

  // 2. Flatten the change event — promote fullDocument fields to top level
  { $replaceRoot: {
      newRoot: { $mergeObjects: ["$fullDocument", { _operationType: "$operationType" }] }
  }},

  // 3. Project into a flat structure for Kinesis/Redshift
  { $project: {
      device_id: "$device_id",
      timestamp: "$timestamp",
      watts: "$obs.watts",
      temp: "$obs.temp",
      _operationType: 1
  }},

  // 4. Emit to Kinesis
  { $emit: {
      connectionName: "myKinesisConnection",
      stream: "atlas-change-events",
      region: "us-east-1",
      partitionKey: "$device_id"
  }}
]);

The $emit stage is Kinesis-specific. Note that stream, region, and partitionKey are all top-level fields — not nested inside a config object.

After creating the processor, start it in mongosh connected to your Stream Processing Instance (SPI):

sp.atlasToKinesisProcessor.start();

Step 5: Set Up Redshift Streaming Ingestion

On the Redshift side, create an external schema pointing to Kinesis:

CREATE EXTERNAL SCHEMA IF NOT EXISTS kinesis_schema
FROM KINESIS
IAM_ROLE 'arn:aws:iam::<YOUR_ACCOUNT>:role/<REDSHIFT_ROLE>';

Then create a streaming materialized view that parses the JSON records:

CREATE MATERIALIZED VIEW mdb_change_events AUTO REFRESH YES AS
SELECT
  approximate_arrival_timestamp,
  JSON_EXTRACT_PATH_TEXT(from_varbyte(kinesis_data, 'utf-8'), 'device_id') AS device_id,
  JSON_EXTRACT_PATH_TEXT(from_varbyte(kinesis_data, 'utf-8'), 'timestamp') AS event_timestamp,
  CAST(JSON_EXTRACT_PATH_TEXT(from_varbyte(kinesis_data, 'utf-8'), 'watts') AS DOUBLE PRECISION) AS watts,
  CAST(JSON_EXTRACT_PATH_TEXT(from_varbyte(kinesis_data, 'utf-8'), 'temp') AS DOUBLE PRECISION) AS temp,
  JSON_EXTRACT_PATH_TEXT(from_varbyte(kinesis_data, 'utf-8'), '_operationType') AS operation_type
FROM kinesis_schema."atlas-change-events";

With AUTO REFRESH YES, Redshift continuously ingests new records. You can also trigger a manual REFRESH MATERIALIZED VIEW mdb_change_events; if needed.

Step 6: Query Your Data

SELECT * FROM mdb_change_events
ORDER BY approximate_arrival_timestamp DESC
LIMIT 10;

That’s it. Operational writes in MongoDB are now queryable in Redshift within seconds.

Lessons Learned

Flatten before emitting. Redshift’s JSON_EXTRACT_PATH_TEXT is limited to 5 levels of nesting, has a 16MB record cap, and AWS recommends migrating to JSON_PARSE with SUPER type instead. By flattening in Atlas Stream Processing ($replaceRoot + $project), Kinesis receives simple flat JSON, and the Redshift materialized view stays clean.
The materialized view only captures new records. Records already in the stream when the view is created may not appear. Create the view before starting the processor, or insert fresh test data after creation.
External schema creation requires a superuser. The CREATE EXTERNAL SCHEMA statement must be run by the database owner or a user with the CREATE SCHEMA privilege. If your IAM-federated session doesn’t have these privileges, connect with the admin user and password instead.

When to Use This Pattern

This architecture works well when:

You need near-real-time analytics on operational MongoDB data
You want to avoid managing CDC infrastructure (Debezium, Kafka Connect, custom consumers)i
Your analytical queries run in Redshift, and you want columnar performance
You prefer a serverless, managed approach with minimal operational overhead

For higher throughput or more complex transformations, you might add more Kinesis shards and scale the Atlas Stream Processing instance accordingly. The architecture stays the same — just the capacity changes.

References

An agent is a graph

MongoDB Guests — Tue, 04 Aug 2026 16:04:18 +0000

This tutorial was written by Néstor Daza.

This is the fourth article in a series about building Claudius, my own Claude-based chatbot (Github). In the previous article, we scaffolded the core components of the app.

We already built the foundation: the data model, an identity the client cannot tamper with, and a health check that proves the application can reach both Atlas and Bedrock. We can now move to the streaming chat backbone, the phase where the conversation finally becomes real and Claudius turns into something you can use every day as your favorite AI tool.

We are going to build the live path, everything that happens between hitting send and tokens arriving on screen. The model runs as a small agent that can pause to search the web, stream its answer back word by word, and let you switch from a cheap model to a strong one in the middle of a thread without losing your place. The next article will be about where the conversation lives once the tokens stop, the persistence, the metering, and the guarded writing operations that keep the whole thing grounded. Here, the question is narrower and more immediate: what actually happens when you hit send?

The agent is not a prompt

The chat engine is not a single call to a model wrapped in a clever prompt; it’s a small state machine built with LangGraph, a design choice that lets the model do more than answer in one shot.

The graph has three nodes. load_context runs but does nothing yet, as a deliberate placeholder where memory retrieval will land in a later phase. agent is the model itself, bound to the tools it is allowed to call. tools is the executor that runs whatever the model asks for. A conditional edge sits after the agent; if the model requests a tool call, control passes to the tools node. If it returns a plain answer, the run ends. The tools node always loops back to the agent.

const builder = new StateGraph(MessagesAnnotation)
  .addNode("load_context", loadContext)
  .addNode("agent", agent)
  .addNode("tools", new ToolNode(tools))
  .addEdge(START, "load_context")
  .addEdge("load_context", "agent")
  .addConditionalEdges("agent", toolsCondition, ["tools", END])
  .addEdge("tools", "agent");

That loop keeps running until the model has what it needs, then returns a natural language answer instead of another tool call. A prompt answers once and stops, a graph keeps working until the task is finished.

Choose the model per run, not per graph

Here is the design decision that took the most thought, and it is invisible in the diagram above. The model is not compiled into the graph.

You might expect the agent node to close over a fixed model instance when the graph is constructed. Instead, the model is chosen per run and passed through LangGraph's configurable channel, the per-invocation configuration that travels alongside the graph state. The agent node reads the inference profile from that channel and builds its model client fresh on every turn.

async function agent(
  state: typeof MessagesAnnotation.State,
  config: RunnableConfig,
): Promise<typeof MessagesAnnotation.Update> {
  const { inferenceProfileId, maxTokens } = readConfigurable(config);
  const model = buildChatModel(
    inferenceProfileId,
    maxTokens !== undefined ? { maxTokens } : {},
  ).bindTools(tools);

  const response = await model.invoke(
    [new SystemMessage(SYSTEM_PROMPT), ...state.messages],
    config,
  );

  return { messages: [response] };
}

readConfigurable pulls the inference profile and token ceiling from the per-run config. buildChatModel constructs the ChatBedrockConverse client for that profile, and bindTools attaches the tool schema so the model knows what it is allowed to call (i.e, web_search). The node then invokes the model with the system prompt followed by the full message history, and returns the model's reply as the one update to the graph state.

Why go to this trouble? Because it is what makes switching models mid-conversation almost free. When you move from Haiku to Sonnet halfway through a thread, nothing about the stored conversation changes. The message history is untouched; on the next turn, we read a different inference profile from the config and build a different client using the same history. There is no graph to rebuild and no checkpoint to migrate. The model is a parameter of the turn, not a property of the conversation.

Model-switching appears in the request the client sends, not in the thread you see on screen. The rendered conversation carries no per-message model label, and the conversation row stores only the current model as a single field, so neither one records which model produced which turn. The request payload does, with each send carrying the conversation identifier, the chosen model, and the new text. Two consecutive sends in one conversation, sharing a conversationId and differing only in modelId, show up like this:

// Turn 3, sent while the selector was on Haiku
{
  "conversationId": "6770f1a2b3c4d5e6f7a8b9c0",
  "modelId": "claude-haiku",
  "text": "Summarize the tradeoffs we just covered."
}
// Turn 4, same conversation, selector now on Sonnet
{
  "conversationId": "6770f1a2b3c4d5e6f7a8b9c0",
  "modelId": "claude-sonnet",
  "text": "Now make the strongest case against that position."
}

The second turn still reads the full prior history that the server holds, so Sonnet answers turn four with turn three already in context, even though turn three ran on Haiku. The modelId is the public catalog identifier that the selector handed the client, paired with the display name on screen; the cross-region inference profile it resolves to remains on the server.

One tool, one predictable shape

The agent has just one tool in this phase, web_search, and it is a thin wrapper over Tavily. It returns exactly three fields per result: title, url, and snippet. Nothing else comes through.

The wrapper is hand-rolled rather than pulled from a library, to have a bit more control over the output shape. The model reads a compact JSON block, and the user interface renders it as a list of sources. Both sides depend on the shape staying fixed. Tavily returns its result text in a field called content, and the wrapper renames it to snippet at that boundary. Replace Tavily with another search service later, and the only code that changes is what's inside that wrapper.

This is a habit worth keeping past this one tool. A predictable shape at a boundary is cheap to build and prevents the rest of the system from developing a quiet dependency on a particular vendor's response format.

Bridging the event gap

The graph produces one kind of stream, the browser expects another; the route between them is a translation layer, the most intricate piece of this phase.

LangGraph emits a flat event log through its streamEvents interface. Model token chunks, tool starts, tool ends, and run boundaries all arrive as a sequence of typed events that you consume in order. The frontend uses the Vercel AI SDK, which expects something different, a typed stream of user-interface message parts. Natural text arrives as a text-start, then a run of text-delta events, then a text-end. Tool activity arrives as tool-input and tool-output parts. The two formats describe the same conversation, but they are not the same format. We need to close the gap between them.

A small state machine takes care of it. It walks the LangGraph event log and emits AI SDK parts as it goes.

for await (const ev of events) {
  switch (ev.event) {
    case "on_chat_model_stream": {
      const chunk = ev.data?.chunk as BaseMessage | undefined;
      const delta = chunk?.text ?? "";
      if (delta.length > 0) {
        if (textId === null) {
          textId = `text-${textSegment++}`;
          writer.write({ type: "text-start", id: textId });
        }
        writer.write({ type: "text-delta", id: textId, delta });
        assistantText += delta;
      }
      break;
    }
    case "on_chat_model_end": {
      endText();
      const output = ev.data?.output as
        | { usage_metadata?: UsageMetadata }
        | undefined;
      addUsage(totals, output?.usage_metadata);
      break;
    }
    case "on_tool_start": {
      writer.write({ type: "tool-input-start", toolCallId: ev.run_id, toolName: ev.name, dynamic: true });
      writer.write({ type: "tool-input-available", toolCallId: ev.run_id, toolName: ev.name, input: ev.data?.input ?? {}, dynamic: true });
      break;
    }
    case "on_tool_end": {
      writer.write({ type: "tool-output-available", toolCallId: ev.run_id, output: parseToolOutput(ev.data?.output), dynamic: true });
      break;
    }
  }
}

Read it event by event. On a model token chunk (on_chat_model_stream), if no text part is open yet, the machine opens one with a fresh identifier and a text-start, then writes the token as a text-delta and appends it to the running answer it keeps in assistantText. On the model turn ending (on_chat_model_end), endText closes the open part, emitting the text-end and resetting the identifier to null so the next token will open a new segment; the same handler pulls the token usage out of the event and adds it to the running totals, which the companion article picks up. On a tool starting (on_tool_start), the machine emits the tool-input parts. On a tool ending (on_tool_end), it parses the tool's JSON output back into a structured part that the renderer can show as sources.

Because the model finishes its turn before the tools it requires run, on_chat_model_end always fires ahead of on_tool_start. So each tool call sits cleanly between closed text segments, never inside an open one. The textSegment counter increments each time, so the answer the model writes after reading its search results opens as a fresh segment rather than reopening the one that came before the search. The renderer sees a clean sequence: natural text, then a tool call with its sources, then more text.

The tool parts are flagged dynamic. The web_search tool is not registered on the client with a schema, so as far as the AI SDK is concerned, its part is a dynamic tool, one whose shape is not known in advance. Marking it dynamic on the server lets the client assemble it into a cleanly typed part that the renderer can switch on, even though the client was never handed the tool's signature.

The conversation identifier rides back on a transient data part. When you send the first message in a brand-new conversation, the server creates the conversation row and needs to tell the client its identifier, without forcing a second request to get it. So it writes a one-off data-conversation part at the very top of the stream.

writer.write({ type: "start" });
writer.write({
  type: "data-conversation",
  data: { id: threadId, title: conversationTitle },
  transient: true,
});
writer.write({ type: "start-step" });

The client reads that part, adopts the identifier, updates the URL, and shows the new conversation in the sidebar, the part itself never becoming a message in the thread. transient marks it as out-of-band, a signal rather than content. No extra round trip, and the conversation is addressable from the first token onward.

The user sees what the agent did

The payoff of all that plumbing is visible on screen. Tokens animate in as they arrive, so the answer builds in front of you instead of appearing in one block after a wait. When the agent decides to search, a live line appears reading "Searching the web," and once results return, it collapses into an expandable list of the sources the tool found, each with its title and link.

That last behavior is a principle that runs through the whole product. Every tool call is visible and inspectable. The user should always be able to see what the agent did on their behalf, not only the polished answer that came out the other end. The event bridge is what makes this possible, because it carries tool activity through as first-class parts rather than burying it inside the model's turn.

There is one more thing to notice about the round trip, and it sets up the second half of the backbone. When you send a message, the client sends only the new text. It does not send back the transcript of everything said before. It cannot, really, because it does not hold the authoritative history. It holds only what it has rendered on screen. The full conversation lives elsewhere, and the model reads it from there on every turn.

Where it lives, and why one small identity decision makes reopening a week-old conversation as cheap as opening a fresh one, is the theme of the next article. The agent is a graph. The conversation, it turns out, is a database.

Building the foundation Claudius runs on

MongoDB Guests — Tue, 04 Aug 2026 15:21:07 +0000

This tutorial was written by Néstor Daza.

This is the third article in a series about building Claudius, my own Claude-based chatbot (Github). The previous article discussed the MongoDB data model to use for the app.

The previous article decided the shape of the data. None of it matters until the app around it is working, and getting it there is the unglamorous half of this phase. It comes down to three things: an identity system the client cannot tamper with, proof that Claudius can reach the two services it depends on, and the deployment realities that decide whether any of it runs at all. This is the boring work that quietly decides whether a project survives contact with production.

Identity: the client never gets a vote

Any Google account on Earth can sign into Claudius safely because a user's role is never something the client sends. It is decided on the server every time.

One piece of this lives outside the code. The Google provider needs an OAuth (Open Authorization) client that you register once in the Google Cloud Console, and the client identifier and secret from that registration are set in corresponding env variables. These setup steps live in the Auth.js and Google documentation, so I am not repeating them here.

Sign-in runs on Auth.js v5 with the Google provider and the MongoDB adapter. There are three roles, admin, member, and guest, and they resolve in exactly one place on the server, with a clear precedence:

export async function resolveRole(email: string | null | undefined): Promise<Role> {
  if (!email) return "guest";

  const normalized = email.toLowerCase();
  if (normalized === env.ADMIN_EMAIL.toLowerCase()) return "admin";

  const settings = await settingsCol();
  const allowlist = await settings.findOne({ _id: "allowlist" });
  if (allowlist && "emails" in allowlist) {
    const allowed = allowlist.emails.some((e) => e.toLowerCase() === normalized);
    if (allowed) return "member";
  }

  return "guest";
}

The bootstrap admin email wins outright, an allowlist of member emails in the settings collection comes next, and everyone else falls through to guest, the least-privileged default. The client supplies a Google identity and nothing more. It never names its own role, so there is no request a user can forge to promote themselves.

The session uses a JWT (JSON Web Token) rather than a database-backed session, so the resolved role is stored in the token and is available without a database read on every request. That choice has one small downside: the token caches the role until it refreshes, so adding someone to the member allowlist takes effect on their next sign-in, not the moment you edit the list. For a personal project, that is a fine trade.

The wiring is small: on first sign-in, the jwt callback calls provisionUser and stores the returned role on the token, and the session callback then copies it onto session.user for the app to read.

Provisioning is the other half of sign-in. The adapter has already written a bare user document, just the name, email, and image Google returns. It fills in the Claudius-specific fields with a single aggregation-pipeline update built around $ifNull, so each field defaults only when it is absent, and an admin's later change is never overwritten. The role is the exception, recomputed every time, since that is the field on which the whole security model rests:

export async function provisionUser(
  userId: string,
  email: string | null | undefined,
): Promise<Role> {
  const role = await resolveRole(email);
  const users = await usersCol();

  const resetsAt = new Date(Date.now() + 24 * 60 * 60 * 1000);

  await users.updateOne({ _id: new ObjectId(userId) }, [
    {
      $set: {
        role,
        allowedModels: { $ifNull: ["$allowedModels", null] },
        monthlyTokenBudget: { $ifNull: ["$monthlyTokenBudget", null] },
        status: { $ifNull: ["$status", "active"] },
        dailyMessageCount: {
          $ifNull: ["$dailyMessageCount", { count: 0, resetsAt }],
        },
      },
    },
  ]);

  return role;
}

One TypeScript detail in this layer was a bit of a pain. Augmenting the session type works through the next-auth module as you would expect, but the JWT type does not! It is only re-exported from next-auth/jwt and lives in @auth/core/jwt, so a declaration written against next-auth/jwt silently fails to merge, and the token field you were trying to type lands as unknown instead. You have to target the real module:

declare module "next-auth" {
  interface Session {
    user: {
      id: string;
      role: Role;
    } & DefaultSession["user"];
  }
}

// JWT lives in @auth/core/jwt; next-auth/jwt only re-exports it, so the
// augmentation must target the real module to merge rather than shadow.
declare module "@auth/core/jwt" {
  interface JWT {
    uid?: string;
    role?: Role;
  }
}

That silent failure is the worst kind: when there are no errors, the type just quietly goes wrong.

Connectivity: prove it reaches Atlas and Bedrock

The last piece of the skeleton is a single protected route that proves the app can talk to the things it depends on. Any signed-in role can call /api/health. It always pings Atlas, and given ?probe=bedrock it goes one step further and makes a one-token Converse call against Claude Haiku 4.5, to prove the credentials can invoke a real model. The probe is the interesting part: capped at a single output token, wrapped so no AWS internals leak back to the caller, and returning the counts read from the Converse usage metadata.

export async function bedrockHealthProbe(): Promise<BedrockHealth> {
  try {
    const llm = new ChatBedrockConverse({
      model: HAIKU_INFERENCE_PROFILE,
      region: env.AWS_REGION,
      credentials: {
        accessKeyId: env.AWS_ACCESS_KEY_ID,
        secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
      },
      maxTokens: 1,
      temperature: 0,
    });

    const response = await llm.invoke([["human", "ping"]]);

    const usage = response.usage_metadata as TokenUsage | undefined;

    return {
      ok: true,
      inputTokens: usage?.input_tokens ?? null,
      outputTokens: usage?.output_tokens ?? null,
    };
  } catch {
    // Do not surface the underlying AWS/SDK error to callers.
    return { ok: false, error: "Bedrock probe failed" };
  }
}

On a live run, it comes back with the result you want:

{"ok":true,"inputTokens":8,"outputTokens":1}

Eight tokens in, one token out. That is the signal you want from a health check on an AI app, not only that the network is up, but that the credentials work and the meter is running.

The models, the probe, and the rest of the app are seeded into settings as a catalog. Each entry carries a real Bedrock cross-region inference profile ID rather than a bare model ID, which is the correct choice for cross-region routing:

[
{"id":"haiku","inferenceProfileId":"us.anthropic.claude-haiku-4-5-20251001-v1:0"},
  {"id":"sonnet","inferenceProfileId":"us.anthropic.claude-sonnet-4-6"},
  {"id":"opus","inferenceProfileId":"us.anthropic.claude-opus-4-8"}
]

Each entry also carries per-million-token input and output pricing, which a later phase uses to enforce tier costs. For now, those fields are a deliberate placeholder, to be confirmed against current Bedrock pricing before any billing math depends on them, so I am not quoting numbers here that would only mislead.

Env: validate only what this phase uses

As we work through this series, each development phase validates only the environment variables it uses, rather than declaring the project's entire surface up front. So far, we need just eight, for the database, Google auth, Bedrock, and the admin bootstrap, so the env schema gates exactly those. A missing or malformed value throws at startup, naming the offending variable and never printing its value:

const EnvSchema = z.object({
  MONGODB_URI: z.string().url(),
  AUTH_SECRET: z.string().min(1),
  AUTH_GOOGLE_ID: z.string().min(1),
  AUTH_GOOGLE_SECRET: z.string().min(1),
  AWS_ACCESS_KEY_ID: z.string().min(1),
  AWS_SECRET_ACCESS_KEY: z.string().min(1),
  AWS_REGION: z.string().min(1),
  ADMIN_EMAIL: z.string().email(),
});

const parsed = EnvSchema.safeParse(process.env);
if (!parsed.success) {
  // List the offending variable names only, never their values.
  const offenders = parsed.error.issues
    .map((issue) => issue.path.join("."))
    .join(", ");
  throw new Error(
    `Invalid environment configuration. Check these variables: ${offenders}`,
  );
}
export const env = parsed.data;

Other variables that will be introduced later, like Tavily for web search, Voyage for embeddings, Blob for file storage, and LangSmith for tracing, are not here yet.

The gotchas that cost real time

The skeleton works, but it did not the first time, and the failures are perhaps the most useful part of this build report.

The first was the most painful: the connection string has no database path, so anything that does not explicitly name the database falls back to test, which the Atlas credentials cannot touch. It bit twice, first in the index script:

MongoServerError: not authorized on test to execute command { listCollections: 1, ... $db: "test" }

Then again, after deployment, in production sign-in, because the Auth.js adapter does not go through the app's database helper and quietly defaults to test until it is told otherwise:

[auth][error] AdapterError
[auth][cause]: MongoServerError: not authorized on test to execute command
{ find: "accounts", ... $db: "test" }

The fix is to name the database explicitly in both places. The adapter gets its own databaseName:

// databaseName is set explicitly because the connection string has no default
// database; without it the adapter would target "test" (which the Atlas
// credentials cannot access).
export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: MongoDBAdapter(clientPromise, { databaseName: DB_NAME }),
  ...authConfig,
});

And the app reaches the database through one helper that names it the same way. That helper is also where the second gotcha lives. A naive new MongoClient() per request would leak a connection pool on every serverless invocation and every dev hot reload, so the client is cached on globalThis as a single instance, and DB_NAME is a constant rather than an env var because the database name is neither secret nor environment-specific:

const globalForMongo = globalThis as unknown as {
  _claudiusMongoClientPromise?: Promise<MongoClient>;
};

const client = new MongoClient(env.MONGODB_URI);

export const clientPromise: Promise<MongoClient> =
  globalForMongo._claudiusMongoClientPromise ??
  (globalForMongo._claudiusMongoClientPromise = client.connect());

export const DB_NAME = "claudius";

export async function getDb(): Promise<Db> {
  const connected = await clientPromise;
  return connected.db(DB_NAME);
}

The adapter is handed the same clientPromise, so auth, and the app shares one client and one pool rather than opening two. Making them agree on a single driver version took one line at the repo root, since the adapter and the app can otherwise resolve different ones:

"overrides": { "mongodb": "7.3.0" }

The third is a monorepo trap. The shared package is consumed as raw TypeScript and transpiled by the app's build through transpilePackages: ["@claudius/shared"], with no separate build step. That is convenient, but it means every runtime dependency the shared code imports has to resolve from the app workspace, because Vercel scopes its install to the app's root directory. The rule that keeps the build green is to declare a runtime dependency in every workspace that imports it, even when that looks like duplication.

The last is the kind of thing that only shows up on deploy. A lockfile generated on macOS omitted the Linux binaries that Tailwind's build needs, and Vercel's Linux install could not find them:

Error: Cannot find module '../lightningcss.linux-x64-gnu.node'

Declaring those binaries as optionalDependencies puts them in the lockfile for every platform, and the deploy goes green:

"optionalDependencies": {
  "@tailwindcss/oxide-linux-x64-gnu": "4.3.1",
  "lightningcss-linux-x64-gnu": "1.32.0"
}

What stands, and what a headless build cannot prove

No chat yet, but the foundation is real. Identity resolves on the server and rides safely in the token. The health route confirms Claudius can reach both Atlas and Bedrock, and the configuration fails loud and early when something is missing. The data model from the last article now has something solid underneath it.

The role-resolution logic is unit-tested, but the actual sign-in is an OAuth round trip, and that needs a real browser, not just this headless build. Confirming that an admin email lands as admin on the page and on the persisted user document is the one step I finish by hand.

Next is the streaming chat backbone, where the conversation finally gets a place to live, and I open the real checkpoint document I have been promising since the start.

Finally! MongoDB Atlas supports partial restore

MongoDB Guests — Mon, 03 Aug 2026 09:00:00 +0000

This article was written by Darshan Jayarama.

Reflecting on my tenure as a MongoDB TSE, I recall a specific incident where a DBA mistakenly dropped a production collection instead of a UAT one. At the time, we were compelled to restore the total cluster to a secondary instance, isolate the required data, and then re-import it into the live environment. The process was inefficient and expensive. We had to recover an entire 760GB cluster just to retrieve a single 50MB collection. You can imagine the massive resource drain involved.

One might wonder why we couldn't restore a single collection or select databases. That’s the new feature I am going to share with you today.

What is partial restore?

As explained in the MongoDB documentation, you can now simply restore any database or collection from the cloud backup; there is no need to restore the full cluster.

It means that if one collection is all you want, you can recover it without touching the entire dataset from the cloud backup.

Real-World Example

A production cluster will have a combination of multiple databases:

Live Production Environment

├── Customer_Profiles
├── Transaction_History
├── Stock_Management
├── Billing_Records
└── Data_Insights

If someone accidentally drops Billing_Records.invoices collection. To resolve this:

Before the Partial Restore feature:

Restore the entire cluster to a temporary Atlas cluster.
Wait for the restore to complete.
Export the required collection.
Import it back into production.
Delete the temporary cluster.

With the Partial Restore feature,simply choose:

Backup Snapshot
Database
Collection
Restore

Here is the workflow:
Click on the Backup tab, select the cluster, and select the backup snapshot as shown below.

Click the 3 dots per the selected snapshot, then click Restore.

In the next window, select the Restore Databases/Collection tab:

You will now have 2 options:

Create as new: With this option, you can choose not to remove the existing collection. If the restoring collection/DB name already exists, Atlas automatically renames the restoring collection to avoid a conflict.
Overwrite existing: Atlas replaces the existing collection with the restored version.

If you want to compare the existing and restored collection, then choose the "Create as new" option. If you want to replace the existing collection, then choose the "Overwrite existing" option. But please be aware that all the data written after the snapshot time will no longer exist.

After choosing your option, you can go ahead and select exactly the data you need. You have two ways to do this:

Using the UI: Just tick the checkboxes for the database or collection you want. Or, if you prefer, you can use the search bar to find what you need using a regex pattern.
Using List Entry: Type the database name or the database. collection name, one per line. For example, if you want everything from the Billing_records database, but only the NRI and HNI collections from the Customer_profile database, you just enter it like this: Billing_records Customer_profile.NRI Customer_profile.HNI

Keep one thing in mind —you cannot use a dot in your database name. If you use a dot, the system will treat it as a combined DB and collection name.

Once you are done with this part, just click Next. On the next screen, you will need to select the Destination details.

Developing a World Cup Stats application with Django MongoDB Extensions' MQL Panel

Abigail Afi Gbadago — Fri, 31 Jul 2026 13:32:12 +0000

Django MongoDB Extensions is a package that contains additional developer tools for the Django MongoDB Backend. One of these tools is the MongoDB Query Language (MQL) panel, and it shows MQL queries that your application runs during a request, including execution times and query plans. This tutorial shows you how to configure and use the panel.

We will highlight the functionality of Django Debug Toolbar by building a World Cup 2026 analytics application that queries match data using the Django ORM and raw aggregation pipelines. We'll use the Django Debug Toolbar to inspect the pipelines these queries generate as MQL.

There are two ways to follow this tutorial.
Option A: Clone the GitHub repo containing the finished code from this tutorial, set it up using the repo's README, and explore it on your own. Link to the GitHub project:django-mongodb-world-cup

Option B: Start the project from scratch by following the steps below.

Start the project from scratch

Prerequisites
NB: This tutorial uses config as the Django project name and world_cup as the app name throughout. If you use different names, you'll need to update every reference to them in the code examples that follow (imports, INSTALLED_APPS, and urls.py).

Before starting this tutorial, you will need to complete the following steps:

Download and install Django MongoDB Backend
Create a MongoDB deployment
Create a connection string
Create a Django project As a quick reference, you can create the Django project with the following command:

django-admin startproject config --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/6.0.x.zip

(NB: I used config here, but you can also specify a Django project name of your choice, for example, world_cup_project)

Configure your MongoDB connection

These steps are explained in detail in the Get Started with Django MongoDB Backend tutorial.

Once these prerequisites are complete, the next step is installing Django MongoDB Extensions.

Install Django MongoDB Extensions

Navigate to your project's root directory; either the folder created by startproject, or the folder created when you clone the repository (i.e., django-mongodb-world-cup). This is also where you should create and activate your virtual environment, if you haven't already:

python3 -m venv venv
source venv/bin/activate

Create a requirements.txt file at the root of the project with the following contents:

#requirements.txt
django-mongodb-extensions
django-debug-toolbar
python-dotenv

Run the following command in your terminal to install the packages:
pip install -r requirements.txt
Create a .env file at the root of the project with the following contents and replace the placeholders with your own values.

For the SECRET_KEY, copy the value Django already generated in your settings.py when you ran startproject; it's normally hardcoded there by default, but we move it into .env to keep it out of version control, since it's used to sign session cookies, CSRF tokens, and other security-sensitive data.

#.env 
SECRET_KEY=[REPLACE_WITH_YOUR_SECRET_KEY]
MONGODB_URI="mongodb+srv://<username>:<password>@<cluster>.mongodb.net/?retryWrites=true&w=majority&appName=world_cup"
DB_NAME=[REPLACE_WITH_YOUR_DB_NAME]

Then update DATABASES and SECRET_KEY variables in settings.py to read from the environment instead of being hardcoded. Your settings.py should now include the following:

import os
from dotenv import load_dotenv
load_dotenv()
SECRET_KEY = os.getenv('SECRET_KEY')
DATABASES = {
    'default': {
        'ENGINE': 'django_mongodb_backend',
        'HOST': os.getenv('MONGODB_URI'),
        'NAME': os.getenv('DB_NAME'),
    },
}

Add Django MongoDB Extensions and Django Debug Toolbar to your installed apps: Navigate to your project's(or cloned repo) settings.py file and add "django_mongodb_extensions" to the INSTALLED_APPS setting, as shown in the following example:

INSTALLED_APPS = [
    'django_mongodb_extensions',
    'debug_toolbar',
]

Register the MQL panel

Replace your existing DEBUG_TOOLBAR_PANELS setting with the list below. This is Django Debug Toolbar's default panel list with one change: SQLPanel is swapped out for MQLPanel.

DEBUG_TOOLBAR_PANELS = [
    'debug_toolbar.panels.history.HistoryPanel',
    'debug_toolbar.panels.versions.VersionsPanel',
    'debug_toolbar.panels.timer.TimerPanel',
    'debug_toolbar.panels.settings.SettingsPanel',
    'debug_toolbar.panels.headers.HeadersPanel',
    'debug_toolbar.panels.request.RequestPanel',
    'django_mongodb_extensions.mql_panel.MQLPanel',
    'debug_toolbar.panels.staticfiles.StaticFilesPanel',
    'debug_toolbar.panels.templates.TemplatesPanel',
    'debug_toolbar.panels.alerts.AlertsPanel',
    'debug_toolbar.panels.cache.CachePanel',
    'debug_toolbar.panels.signals.SignalsPanel',
    'debug_toolbar.panels.community.CommunityPanel',
    'debug_toolbar.panels.redirects.RedirectsPanel',
    'debug_toolbar.panels.profiling.ProfilingPanel',
]

Configure Django Debug Toolbar Middleware

Add DebugToolbarMiddleware as the first item in MIDDLEWARE, and set INTERNAL_IPS:

MIDDLEWARE = [
    'debug_toolbar.middleware.DebugToolbarMiddleware',
    'django.middleware.security.SecurityMiddleware',
    # ... rest of middleware
]
INTERNAL_IPS = ['127.0.0.1']

Add Django Debug Toolbar’s URLs

In urls.py, add the following:

from django.conf import settings
from django.urls import include, path
urlpatterns = [
    # ... your app urls
]
if settings.DEBUG:
    urlpatterns += [path("__debug__/", include("debug_toolbar.urls"))]

Create an Application

From your project's root directory, run the following command to create a new Django app. This tutorial uses the name world_cup throughout, so if you use a different name, you'll need to update it in every file this tutorial references (INSTALLED_APPS, imports, urls.py):
python manage.py startapp world_cup

Next, include your app in your project by opening the settings.py file in config and editing your INSTALLED_APPS setting to resemble the following code:

INSTALLED_APPS = [
    'config.apps.MongoAdminConfig',
    'config.apps.MongoAuthConfig',
    'config.apps.MongoContentTypesConfig',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django_mongodb_backend',
    'django_mongodb_extensions',
    'debug_toolbar',
    'world_cup',
]

Create models for Goal and Match data

The world_cup application stores the World Cup match data using two models: Match and Goal. The Goal model is embedded inside Match as an array of goal events because it is usually queried together with the corresponding matches.

Open the models.py file in the world_cup directory and replace its contents with the following code:

from django.db import models
from django_mongodb_backend.fields import EmbeddedModelArrayField
from django_mongodb_backend.managers import MongoManager
from django_mongodb_backend.models import EmbeddedModel

class Goal(EmbeddedModel):
    team = models.CharField(max_length=100)
    name = models.CharField(max_length=100)
    minute = models.CharField(max_length=10)     
    penalty = models.BooleanField(default=False)
    own_goal = models.BooleanField(default=False)

    def __str__(self):
        return f"{self.name} (({self.team}, {self.minute}')"
class Match(models.Model):
    num = models.IntegerField(null=True, blank=True)        
    round = models.CharField(max_length=50)
    date = models.DateField()
    kickoff_time = models.CharField(max_length=20)           
    group = models.CharField(max_length=20, blank=True)      
    ground = models.CharField(max_length=100)
    team1 = models.CharField(max_length=100)
    team2 = models.CharField(max_length=100)
#Fields ending in "1" refer to team1, fields ending in "2" refer to team2
    ft_score1 = models.IntegerField(null=True, blank=True)      #ft = full-time
    ft_score2 = models.IntegerField(null=True, blank=True)
    ht_score1 = models.IntegerField(null=True, blank=True)  #ht = half-time
    ht_score2 = models.IntegerField(null=True, blank=True)
    et_score1 = models.IntegerField(null=True, blank=True)  #et = extra-time
    et_score2 = models.IntegerField(null=True, blank=True)
    pen_score1 = models.IntegerField(null=True, blank=True) #penalty score
    pen_score2 = models.IntegerField(null=True, blank=True)
   goals = EmbeddedModelArrayField(Goal, default=list, blank=True)
objects = MongoManager()

    def __str__(self):
        return f"{self.team1} vs {self.team2} ({self.round})"

The Goal model represents the world_cup.world_cup_match collection and stores information about the goals. This model contains fields such as name, minute, penalty, and own goal. The Goal model contains the embedded document values stored in the Match model.

Run Migrations

Generate and apply the migration for the world_cup app:

python manage.py makemigrations world_cup
python manage.py migrate

Loading Data

mkdir -p world_cup/management/commands
mkdir -p world_cup/data
touch world_cup/management/__init__.py
touch world_cup/management/commands/__init__.py
touch world_cup/management/commands/load_matches.py

For the World Cup data, we use the JSON file from Open Football GitHub source and save it to the data folder under the world_cup folder (/world_cup/data/worldcup_2026.json).

After obtaining the data (JSON file), we create a script (world_cup/management/commands/load_matches.py) to load the matches. Replace the following content in the load_matches.py file.

# world_cup/management/commands/load_matches.py
import json
from datetime import datetime
from pathlib import Path

from django.core.management.base import BaseCommand

from world_cup.models import Goal, Match

WORLD_CUP_DATA = Path(__file__).resolve().parent.parent.parent / "data" / "worldcup_2026.json"


def build_goals(raw_goals, team_name):
    return [
        Goal(
            team=team_name,
            name=g["name"],
            minute=g["minute"],
            penalty=g.get("penalty", False),
            own_goal=g.get("owngoal", False),
        )
        for g in raw_goals
    ]
def to_match_kwargs(raw_match):
    score = raw_match.get("score", {})
    ft = score.get("ft", [None, None])
    ht = score.get("ht", [None, None])
    et = score.get("et", [None, None])
    p = score.get("p", [None, None])

    return dict(
        num=raw_match.get("num"),
        round=raw_match["round"],
        date=datetime.strptime(raw_match["date"], "%Y-%m-%d").date(),
        kickoff_time=raw_match["time"],
        group=raw_match.get("group", ""),
        ground=raw_match["ground"],
        team1=raw_match["team1"],
        team2=raw_match["team2"],
        ft_score1=ft[0],
        ft_score2=ft[1],
        ht_score1=ht[0],
        ht_score2=ht[1],
        et_score1=et[0],
        et_score2=et[1],
        pen_score1=p[0],
        pen_score2=p[1],
        goals=build_goals(raw_match.get("goals1", []), raw_match["team1"]) + build_goals(raw_match.get("goals2", []), raw_match["team2"]),
    )
class Command(BaseCommand):
    help = (
        "Load the curated World Cup 2026 matches (Groups A, B, I, J) into MongoDB. "
        "Source: worldcup_data/worldcup_2026.json — 24 matches total, "
        "16 completed with real goals, 8 unplayed (Matchday 14/17)."
    )

    def handle(self, *args, **options):
        with open(WORLD_CUP_DATA) as f:
            raw_matches = json.load(f)["matches"]

        self.stdout.write(f"Found {len(raw_matches)} matches to load.")

        batch_size = 5
        created = 0
        for i in range(0, len(raw_matches), batch_size):
            batch = raw_matches[i : i + batch_size]
            Match.objects.bulk_create([Match(**to_match_kwargs(m)) for m in batch])
            created += len(batch)
            self.stdout.write(f"Loaded {created}/{len(raw_matches)} matches...")

        self.stdout.write(self.style.SUCCESS(f"Done: {created} matches loaded."))

Next, we load the data by running:
python manage.py load_matches

Once this is successful, we can see the results either by querying the database via the Python shell or via MongoDB Atlas’s Data Explorer. For example, to confirm the data loaded correctly and inspect an embedded Goal array, run:

python manage.py shell

In this shell:

>>> from world_cup.models import Match
>>> Match.objects.count()
100
>>> Match.objects.get(team1="France", team2="Senegal").goals1

Match results queried via Python shell

World Cup match stats after upload in MDB Atlas

Create Views

These views provide three pages: a total goals counter using the Django ORM, a top scorers leaderboard using a raw aggregation pipeline, and an interactive query shell that allows you to run five different query types.

Open the views.py file in your world_cup directory and replace its contents with the following code:

# world_cup/views.py
from django.db import connections
from django.db.models import F, Sum
from django.shortcuts import render

from .models import Match


def tournament_goals(request):
    """Pipeline 1 — built-in aggregate: total goals across completed matches."""
    result = (
        Match.objects.filter(ft_score1__isnull=False)
        .annotate(total_goals=F("ft_score1") + F("ft_score2"))
        .aggregate(tournament_goals=Sum("total_goals"))
    )
    return render(request, "world_cup/goals.html", {
        "total_goals": result["tournament_goals"] or 0,
    })


def top_scorers(request):
    """Pipeline 2 — raw_aggregate: leaderboard via $unwind + $group."""
    pipeline = [
        {"$unwind": "$goals"},
        {"$match": {"goals.own_goal": {"$ne": True}}},
        {"$group": {"_id": "$goals.name", "total_goals": {"$sum": 1}}},
        {"$sort": {"total_goals": -1}},
        {"$limit": 10},
    ]
    results = Match.objects.raw_aggregate(pipeline)
    scorers = [{"name": r.pk, "goals": r.total_goals} for r in results]
    return render(request, "world_cup/scorers.html", {"scorers": scorers})


ALLOWED_QUERIES = {
    "team": {
        "description": "All matches for a team",
        "example": "team France",
    },
    "round": {
        "description": "Matches in a round (e.g. round Quarter-final)",
        "example": "round Quarter-final",
    },
    "top scorers": {
        "description": "Top 10 scorers via $unwind + $group pipeline",
        "example": "top scorers",
    },
    "goals by round": {
        "description": "Goals per round via $group pipeline",
        "example": "goals by round",
    },
    "goals": {
        "description": "Total tournament goals",
        "example": "goals",
    },
}


def _execute_query(query_text):
    """Parse and execute a user query, return result dict."""
    q = query_text.strip().lower()

    if q == "goals":
        result = (
            Match.objects.filter(ft_score1__isnull=False)
            .annotate(total_goals=F("ft_score1") + F("ft_score2"))
            .aggregate(tournament_goals=Sum("total_goals"))
        )
        return {
            "results": [{"tournament_goals": result["tournament_goals"] or 0}],
        }

    if q in ("top scorers", "scorers", "top"):
        pipeline = [
            {"$unwind": "$goals"},
            {"$match": {"goals.own_goal": {"$ne": True}}},
            {"$group": {"_id": "$goals.name", "total_goals": {"$sum": 1}}},
            {"$sort": {"total_goals": -1}},
            {"$limit": 10},
        ]
        results = Match.objects.raw_aggregate(pipeline)
        return {
            "results": [{"scorer": r.pk, "goals": r.total_goals} for r in results],
        }

    if q.startswith("team "):
        team = query_text.strip()[5:].strip()
        from django.db.models import Q
        matches = Match.objects.filter(Q(team1__iexact=team) | Q(team2__iexact=team)).order_by("date")
        return {
            "query": f'db.world_cup_match.aggregate([{{$match: {{$or: [{{team1: {{$regex: "^{team}$", $options: "i"}}}}, {{team2: {{$regex: "^{team}$", $options: "i"}}}}]}}}}, {{$sort: {{date: 1}}}}])',
            "results": [
                {
                    "date": str(m.date),
                    "round": m.round,
                    "team1": m.team1,
                    "team2": m.team2,
                    "score": f"{m.ft_score1}-{m.ft_score2}" if m.ft_score1 is not None else "TBD",
                }
                for m in matches
            ],
        }

    if q.startswith("round "):
        round_name = query_text.strip()[6:].strip()
        matches = Match.objects.filter(round__icontains=round_name).order_by("date")
        return {
            "query": f'db.world_cup_match.aggregate([{{$match: {{round: {{$regex: "{round_name}", $options: "i"}}}}}}, {{$sort: {{date: 1}}}}])',
            "results": [
                {
                    "date": str(m.date),
                    "team1": m.team1,
                    "team2": m.team2,
                    "score": f"{m.ft_score1}-{m.ft_score2}" if m.ft_score1 is not None else "TBD",
                }
                for m in matches
            ],
        }

    if q in ("goals by round", "goals per round"):
        pipeline = [
            {"$match": {"ft_score1": {"$ne": None}}},
            {"$group": {
                "_id": "$round",
                "total_goals": {"$sum": {"$add": ["$ft_score1", "$ft_score2"]}},
                "matches": {"$sum": 1},
            }},
            {"$sort": {"total_goals": -1}},
        ]
        results = Match.objects.raw_aggregate(pipeline)
        return {
            "results": [{"round": r.pk, "goals": r.total_goals, "matches": r.matches} for r in results],
        }

    return None


def query_shell(request):
    """Interactive query shell — form POST triggers full page reload for MQL panel."""
    context: dict = {"queries": ALLOWED_QUERIES}

    if request.method == "POST":
        query_text = request.POST.get("query", "").strip()
        context["last_query"] = query_text

        if query_text:
            result = _execute_query(query_text)
            if result is None:
                context["error"] = f"Unknown query. Try: {', '.join(ALLOWED_QUERIES.keys())}"
            else:
                context["mongo_query"] = result.get("query", "")
                context["results"] = result.get("results", [])

    return render(request, "world_cup/shell.html", context)

Configure URLs for your views

Create a new file called urls.py file in your world_cup directory. To map the views defined in the preceding step to URLs, paste the following code into urls.py:

from django.urls import path

from . import views

urlpatterns = [
    path("goals/total/", views.tournament_goals, name="tournament_goals"),
    path("goals/top-scorers/", views.top_scorers, name="top_scorers"),
    path("shell/", views.query_shell, name="query_shell"),
]
`

Then, navigate to the config/urls.py file and replace its contents with the following code:
`
from django.conf import settings
from django.shortcuts import render
from django.urls import include, path


def landing(request):
    return render(request, "world_cup/landing.html")


urlpatterns = [
    path("", landing, name="landing"),
    path("world_cup/", include("world_cup.urls")),
]

if settings.DEBUG:
    urlpatterns += [path("__debug__/", include("debug_toolbar.urls"))]

Create Templates

In your world_cup directory, create a subdirectory called templates.

Under templates, create five HTML files to display the base page, goals page(showing total goals by aggregation), landing page, scorers page(top scorers), and shell page(interactive shell to run queries and aggregation pipelines interactively).

base.html: This is the shared layout (nav, styles) that the other four templates extend.

#world_cup/templates/base.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{% block title %}World Cup 2026{% endblock %}</title>
    <style>
        :root {
            --nav-bg: #1C2D38;
            --page-bg: #f0f2f5;
            --card-bg: #ffffff;
            --text-primary: #1C2D38;
            --text-secondary: #5c6970;
            --border: #e2e5e9;
            --accent: #1a6b4b;
            --accent-light: #e8f5ef;
            --white: #ffffff;
        }

        * { margin: 0; padding: 0; box-sizing: border-box; }

        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            background: var(--page-bg);
            color: var(--text-primary);
            min-height: 100vh;
        }

        nav {
            background: var(--nav-bg);
            padding: 0.9rem 2rem;
            display: flex;
            align-items: center;
            justify-content: space-between;
            border-bottom: 3px solid var(--accent);
        }

        nav .brand {
            color: var(--white);
            font-size: 1.1rem;
            font-weight: 700;
            text-decoration: none;
        }

        nav .nav-links a {
            color: rgba(255,255,255,0.85);
            text-decoration: none;
            margin-left: 2rem;
            font-size: 0.9rem;
        }

        nav .nav-links a:hover {
            color: var(--white);
        }

        .container {
            max-width: 900px;
            margin: 2rem auto;
            padding: 0 1.5rem;
        }

        header {
            margin-bottom: 1.5rem;
        }

        header h1 {
            font-size: 1.6rem;
            font-weight: 700;
            color: var(--text-primary);
        }

        header p {
            color: var(--text-secondary);
            font-size: 0.9rem;
            margin-top: 0.25rem;
        }

        .card {
            background: var(--card-bg);
            border-radius: 8px;
            padding: 1.5rem;
            margin-bottom: 1rem;
            border: 1px solid var(--border);
        }

        .card:hover {
            border-color: var(--accent);
        }

        .card a {
            text-decoration: none;
            color: var(--text-primary);
            display: block;
        }

        .card h3 {
            font-size: 1rem;
            font-weight: 600;
            margin-bottom: 0.3rem;
        }

        .card p {
            color: var(--text-secondary);
            font-size: 0.85rem;
        }

        .badge {
            display: inline-block;
            background: var(--accent);
            color: var(--white);
            font-size: 0.7rem;
            font-weight: 600;
            padding: 0.2rem 0.6rem;
            border-radius: 4px;
            margin-bottom: 0.5rem;
            text-transform: uppercase;
        }

        table {
            width: 100%;
            border-collapse: collapse;
            margin-top: 0.5rem;
        }

        th, td {
            text-align: left;
            padding: 0.75rem 1rem;
            border-bottom: 1px solid var(--border);
        }

        th {
            color: var(--text-secondary);
            font-size: 0.75rem;
            font-weight: 600;
            text-transform: uppercase;
            letter-spacing: 0.03em;
        }

        td {
            font-size: 0.9rem;
        }

        .back-link {
            display: inline-block;
            margin-bottom: 1rem;
            color: var(--accent);
            text-decoration: none;
            font-size: 0.85rem;
        }

        .back-link:hover {
            text-decoration: underline;
        }

        .stat-value {
            font-size: 3rem;
            font-weight: 700;
            color: var(--accent);
        }

        .stat-label {
            color: var(--text-secondary);
            font-size: 0.9rem;
            margin-top: 0.25rem;
        }
    </style>
</head>
<body>
    <nav>
        <a href="/" class="brand">World Cup 2026 Stats</a>
        <div class="nav-links">
            <a href="{% url 'tournament_goals' %}">Goals</a>
            <a href="{% url 'top_scorers' %}">Scorers</a>
            <a href="{% url 'query_shell' %}">Shell</a>
        </div>
    </nav>
    <div class="container">
        {% block content %}{% endblock %}
    </div>
</body>
</html>

landing.html: This is the app's home page, linking out to the goals, scorers, and shell pages.
Endpoint: http://127.0.0.1:8000/

#world_cup/templates/landing.html
{% extends "world_cup/base.html" %}

{% block title %}World Cup 2026 — Home{% endblock %}

{% block content %}
<header>
    <h1>⚽ World Cup 2026 Stats</h1>
</header>

<div class="card">
    <a href="{% url 'tournament_goals' %}">
        <span class="badge">Aggregation</span>
        <h3>Total Goals</h3>
        <p>Sum of all goals scored — view the MQL query in the Debug Toolbar</p>
    </a>
</div>

<div class="card">
    <a href="{% url 'top_scorers' %}">
        <span class="badge">Pipeline</span>
        <h3>Top Scorers</h3>
        <p>$unwind + $group pipeline — view execution time in the MQL panel</p>
    </a>
</div>

<div class="card">
    <a href="{% url 'query_shell' %}">
        <span class="badge">Interactive</span>
        <h3>Query Shell</h3>
        <p>Run find queries and aggregation pipelines </p>
    </a>
</div>
{% endblock %}

goals.html: This displays the total goals count from the tournament_goals view's aggregation.
Endpoint: http://127.0.0.1:8000/world_cup/goals/total/

#world_cup/templates/goals.html
{% extends "world_cup/base.html" %}

{% block title %}Total Goals — World Cup 2026{% endblock %}

{% block content %}
<a href="/" class="back-link">← Back to Home</a>
<header>
    <h1>Tournament Goals</h1>
    <p>Total goals across all completed matches</p>
</header>

<div class="card" style="text-align: center; padding: 3rem;">
    <div class="stat-value">{{ total_goals }}</div>
    <div class="stat-label">goals scored</div>
</div>
{% endblock %}

scorers.html: This displays the top scorers leaderboard from the top_scorers view's raw pipeline.
Endpoint: http://127.0.0.1:8000/world_cup/goals/top-scorers/

#world_cup/templates/scorers.html
{% extends "world_cup/base.html" %}

{% block title %}Top Scorers — World Cup 2026{% endblock %}

{% block content %}
<a href="/" class="back-link">← Back to Home</a>
<header>
    <h1>Top Scorers</h1>
    <p>Leading goal scorers in the tournament</p>
</header>

<div class="card">
    <table>
        <thead>
            <tr>
                <th>#</th>
                <th>Player</th>
                <th>Goals</th>
            </tr>
        </thead>
        <tbody>
            {% for scorer in scorers %}
            <tr>
                <td>{{ forloop.counter }}</td>
                <td>{{ scorer.name }}</td>
                <td>{{ scorer.goals }}</td>
            </tr>
            {% empty %}
            <tr><td colspan="3">No scoring data available yet.</td></tr>
            {% endfor %}
        </tbody>
    </table>
</div>
{% endblock %}

shell.html: This is the interactive query shell which takes an input form plus a results table, for running any of the commands from ALLOWED_QUERIES and compares them in the MQL panel.

Endpoint: http://127.0.0.1:8000/world_cup/shell/

#/templates/shell.html
{% extends "world_cup/base.html" %}

{% block title %}Query Shell — World Cup 2026{% endblock %}

{% block content %}
<a href="/" class="back-link">← Back to Home</a>
<header>
    <h1>Query Shell</h1>
    <p>Each query reloads the page — check the MQL panel in the Debug Toolbar</p>
</header>

<div class="shell">
    <div class="shell-output" id="output">
        {% if not last_query %}
        <div class="shell-line system">Click an example or type a query:</div>
        <div class="shell-line system"></div>
        <div class="shell-line system" style="color: var(--mdb-gray); opacity: 0.6;">— Queries (find) —</div>
        <div class="shell-line example" data-query="team France">team France</div>
        <div class="shell-line example" data-query="team England">team England</div>
        <div class="shell-line example" data-query="round Quarter-final">round Quarter-final</div>
        <div class="shell-line system"></div>
        <div class="shell-line system" style="color: var(--mdb-gray); opacity: 0.6;">— Aggregation Pipelines —</div>
        <div class="shell-line example" data-query="top scorers">top scorers</div>
        <div class="shell-line example" data-query="goals by round">goals by round</div>
        <div class="shell-line example" data-query="goals">goals</div>
        {% endif %}

        {% if last_query %}
        <div class="shell-line query">{{ last_query }}</div>
        {% endif %}

        {% if error %}
        <div class="shell-line error">{{ error }}</div>
        {% endif %}

        {% if mongo_query %}
        <div class="shell-line mongo-query">{{ mongo_query }}</div>
        {% endif %}

        {% if results %}
        <div class="shell-line result">
            <table class="result-table">
                <thead>
                    <tr>
                        {% for key in results.0.keys %}
                        <th>{{ key }}</th>
                        {% endfor %}
                    </tr>
                </thead>
                <tbody>
                    {% for row in results %}
                    <tr>
                        {% for val in row.values %}
                        <td>{{ val|default:"—" }}</td>
                        {% endfor %}
                    </tr>
                    {% endfor %}
                </tbody>
            </table>
        </div>
        {% endif %}
    </div>

    <form method="post" action="{% url 'query_shell' %}" class="shell-input-row">
        {% csrf_token %}
        <span class="prompt">▶</span>
        <input type="text" name="query" id="query-input" value="" placeholder="e.g. team France, top scorers, round Quarter-final" autofocus>
    </form>
</div>

<style>
    .shell {
        background: var(--card-bg);
        border: 1px solid var(--border);
        border-radius: 8px;
        overflow: hidden;
        font-family: 'SF Mono', 'Fira Code', 'JetBrains Mono', monospace;
        font-size: 0.85rem;
    }

    .shell-output {
        padding: 1.5rem;
        max-height: 500px;
        overflow-y: auto;
    }

    .shell-line {
        margin-bottom: 0.4rem;
        line-height: 1.5;
    }

    .shell-line.system {
        color: var(--text-secondary);
    }

    .shell-line.query {
        color: var(--accent);
        font-weight: 600;
    }

    .shell-line.query::before {
        content: "▶ ";
        opacity: 0.5;
    }

    .shell-line.mongo-query {
        color: var(--text-secondary);
        font-size: 0.78rem;
        padding-left: 1rem;
        background: var(--page-bg);
        padding: 0.5rem 1rem;
        border-radius: 4px;
        margin: 0.3rem 0;
        overflow-x: auto;
    }

    .shell-line.result {
        color: var(--text-primary);
        padding-left: 0;
    }

    .shell-line.error {
        color: #c0392b;
    }

    .shell-line.example {
        color: var(--accent);
        cursor: pointer;
        padding-left: 1rem;
        opacity: 0.8;
    }

    .shell-line.example::before {
        content: "▶ ";
        opacity: 0.4;
    }

    .shell-line.example:hover {
        opacity: 1;
        text-decoration: underline;
    }

    .shell-input-row {
        display: flex;
        align-items: center;
        border-top: 1px solid var(--border);
        padding: 0.75rem 1.5rem;
        background: var(--page-bg);
    }

    .prompt {
        color: var(--accent);
        margin-right: 0.75rem;
        font-size: 0.8rem;
    }

    .shell-input-row input {
        flex: 1;
        background: transparent;
        border: none;
        outline: none;
        color: var(--text-primary);
        font-family: inherit;
        font-size: inherit;
    }

    .shell-input-row input::placeholder {
        color: var(--text-secondary);
        opacity: 0.5;
    }

    .result-table {
        width: 100%;
        border-collapse: collapse;
        margin: 0.5rem 0;
    }

    .result-table th {
        color: var(--text-secondary);
        font-size: 0.7rem;
        text-transform: uppercase;
        text-align: left;
        padding: 0.3rem 0.75rem;
        border-bottom: 1px solid var(--border);
    }

    .result-table td {
        padding: 0.3rem 0.75rem;
        font-size: 0.8rem;
        color: var(--text-primary);
    }
</style>

<script>
document.querySelectorAll('.shell-line.example').forEach(el => {
    el.addEventListener('click', () => {
        document.getElementById('query-input').value = el.dataset.query;
        el.closest('.shell').querySelector('form').submit();
    });
});
</script>
{% endblock %}

Build an Aggregation Pipeline

The tournament_goals view uses the Django ORM's aggregate() and Sum() to total up goals, and the MQL panel captures that query automatically. For more advanced analysis, like ranking top scorers, you can use MongoDB's aggregation pipelines. The top_scorers view in views.py does exactly this: it uses $concatArrays to merge embedded goal arrays, $unwind to flatten them into individual documents, and $group to count goals per player.

The top_scorers view uses raw_aggregate(), a method which accepts a raw MongoDB aggregation pipeline directly, including stages like $unwind, and returns Django model instances. See the QuerySet API reference for more details.

When you navigate to the /world_cup/goals/top-scorers/ and open the MQL panel in the Django Debug Toolbar. You'll see the full aggregation pipeline that was executed, along with its timing. The MQL panel captures both ORM-generated queries and raw pipelines, so you can inspect and optimize either approach from the same interface.

Verify the MQL panel

Start your development server by running the following command:
python manage.py runserver

Navigate to any page in your application that queries MongoDB. Open the Django Debug Toolbar and select the MQL panel to view the MongoDB queries executed during the request, including their execution times and explain plans.

View worldcup.goals query information

Now, navigate to http://127.0.0.1:8000/world_cup/goals/total/ to view MongoDB queries executed during the request.
The Django Debug Toolbar appears on the right side of the page. Select the MQL label to view the MongoDB query used to calculate the total goals, which resembles the following code:

After, you can explore the query information by clicking on the following buttons:
Select the + button to the left of the query to view the call stack, which resembles the following call trace:

Next, select the Query button to the top-right of the query, in the ACTION column, to view the pretty-printed MQL. This MQL resembles the following code:

Now, select the Explain button to the right of the query, in the ACTION column, to view the explain plan for the query. This plan resembles the following code:

View the top scorers aggregation pipeline

Next, navigate to http://127.0.0.1:8000/world_cup/goals/top-scorers/ to see the aggregation pipeline in the MQL panel. We see that this page runs a raw multi-stage pipeline ($concatArrays, $unwind, $group, $sort, $limit). Select the MQL panel to view the pipeline stages, execution time, and explain plans.

View query shell queries

Finally, access the endpoint http://127.0.0.1:8000/world_cup/shell/ and submit a query such as team France. The page reloads with the results, and the MQL panel shows the aggregation pipeline that was executed. Even though the view uses the Django ORM's filter() and order_by(), the MongoDB backend translates these into an aggregation pipeline.

Next Steps

Congratulations on getting this far! You now have a Django application that uses Django MongoDB Extensions to view and analyze MongoDB queries in the Django Debug Toolbar.

Here are some debugging exercises you can experiment with:

Run the "round" search in the query shell (e.g., round Group A) and check its query plan in the MQL panel. You'll see a COLLSCAN which is a full collection scan because round__icontains compiles to an unanchored regex, which can't use an index no matter what you add.
Compare it against round__iexact on the same field, and the panel shows IXSCAN instead. It is similar code but different queries underneath, and that is exactly what the Django Debug Toolbar makes evident.

To learn more about the Django MongoDB Extensions package, see django-mongodb-extensions and the django-mongodb-extensions repository on GitHub.
To learn how to query your data, see the Specify a Query guide.

Link to this GitHub Project: Django MongoDB World Cup project

Link to the Data: Open Football Dataset

What Is MongoDB Atlas Vector Search

MongoDB Guests — Tue, 28 Jul 2026 10:01:53 +0000

This article was written by Moses Anumadu.

Traditional search relies on keywords and tags to recommend search results. This system works and is in use across multiple platforms. However, it has a major limitation that has become more apparent in recent years due to increased AI adoption. The major limitation of traditional search is that it returns search results based solely on keyword matches. Traditional searches, as we have them today, do not consider semantic meaning. For example:

Imagine that we built a movie website using traditional search. Now, if a user wants to find The Matrix, but they can't remember the name. They type in "dystopian AI reality simulation." A traditional keyword database will return zero results because those exact words are not in the movie title or description. This is the major challenge for traditional search. It returns results strictly from keywords, in this case, either in the movie name or description. So, if a user does not type the exact keywords stored in your database, the correct or intended movie does not show up, even though it is in the database. The platform simply does not know that it was the intended movie. This can be limiting and produce search results that do not accurately match the users' intent.

A better approach for this use case is to have the search not rely on keywords to recommend movies. It should recommend movies based on semantic similarities. This is a very good example of when vector search should be used over traditional search.

In this tutorial, we will explore what vector search is, its importance, what MongoDB Vector Search is, and why you should consider it for your next vector search implementation. With that said, let's get started.

Prerequisites

To follow along with this article, you should have a basic understanding of the following concepts:

MongoDB Atlas
Database and collection
Can perform CRUD operations
Basic understanding of web development technologies

What Is Vector Search?

Vector search is a search technology that uses vectors to identify semantic similarity and recommend results that are accurate in terms of meaning and not keywords.

With vector search, text, images, and other media file types are stored as embeddings. Embeddings are numerical values generated by machine learning models that capture the context, intent, and semantic similarity of the stored data. Items with similar meanings have embeddings (numeric values) that are closer.

When a search is done, the vector search identifies similar values by comparing the closeness of the content embeddings. The closer the embeddings, the more similar the contents. This returns a more accurate search result that relies on meaning over a keyword search that relies on keywords.

The major difference to note here is that keyword searches rely on keyword matches to recommend results, while vector searches rely on meaning by comparing embeddings to recommend results.

Keyword Search vs. Vector Search

Keyword Search	Vector Search
Search relies on exact keyword matching to return results.	Search relies on a semantic understanding of search terms.
Results are not generated based on users' intentions. They rely on keyword accuracy.	Generates results with users' intent in consideration.
The use of synonyms in keyword searches does not often return the best search results. Eg, car and vehicle won't return the same result.	Synonyms in vector search generate far more accurate results. It factors in the actual meaning of the words to generate results.
Keyword search queries are not flexible to things like typos and long search queries.	Search keywords or phrases can be sentences. It can be flexible with misspelled words and still return accurate results.

How Embeddings Enable Vector Search

What Is an Embedding?

Think of embeddings as the foundation of vector searches. Embeddings are numerical values generated by artificial intelligence. These numeric values represent the meaning of text and media files, so vector search can compare them and return more accurate, similar results.

In a keyword search query, a traditional database does not treat words as symbols with meaning; it sees them as independent flat characters that don't have links to the sentence's meaning. So it only returns results that match exactly. An example can be a search keyword of "CAT" would return a CAT. Not because it understands it, but because the keywords match. But a search keyword of VEHICLE would not return a result of CAR.

How AI generates these similarities

Let's take a moment to examine how an AI embedding model generates the numbers in an embedding. Imagine you need to describe an apple using a scale of 1-10. Is an apple sweet? Yes. On a scale of 1 - 10, how sweet is an apple? Say 8. Is an apple crunchy? Yes. On a scale of 1 - 10, how crunchy is an apple? Say 6. Is an apple red in color? Yes. On a scale of 1 to 10, how red is an apple? Say 9. This would give us an embedding of [8, 6, 9]. A fruit like a banana can be [9, 1, 0].

The AI embedding model does something very similar to the example above; when it processes a sentence, it outputs a long list of numbers (called a vector). This list serves as a precise map coordinate for that specific piece of text in a giant, digital "map of meaning."
This results in words with similar meaning having vectors that are closely related or similar.

Why Embeddings Matter

Embeddings are like the building blocks of vectors. With them, vectors are generated, and similarity in terms of meaning can be measured in a search query.

How MongoDB Vector Search Works

The Vector Search Workflow

In a MongoDB vector search implementation, data is stored together with its generated vector in the same collection. This simplifies the implementation when compared to the steps required to implement this using different technologies. Let's examine the workflow for both storing a document and retrieving it during a search query.

Storing document

Storing record

This process starts with storing our normal documents in a MongoDB collection. A document can be in text or media format.

Embeddings are generated

After storing this document, embeddings are generated using any of the AI models that have this compatibility. Some popular examples are VoyageAI, OpenAI, Cohere, and Hugging Face.

Documents are updated to contain vectors.

The data collection in Atlas is updated to contain the generated vectors. This saves the vector as a field in the collection. Keeping both the data and its embeddings in one collection.

A vector search index is created

The final step in this flow is creating the vector search index. This boosts performance during searches.

The image below provides a visual explanation of the flow;

Search workflow

The MongoDB vector search workflow consists of a few steps; it starts with a user query. The query is converted into embeddings using an AI embedding model (for best results, use the same embedding model as the one used to embed the documents in the database is advised).

After the vectors are generated, MongoDB vector search calculates the semantic proximity between the search query vector and the vector of the documents stored in the collection. It then returns the results, which are semantically matching items to the user search query. The image below provides a more visual explanation of the process.

Common Use Cases

There is no doubt about the importance of vector searches. However, this does not make it the right tool for every search implementation. Vector search implementations require AI models to generate vectors. This can make the search implementation a bit more complex and costly. With that in mind, it is important to explore some real-world use cases where it can be a good fit and also where it is not. But in general, vector searches are a great solution for search results that want semantic similarity. Some examples include:

Semantic document search
AI knowledge bases
Product recommendation systems
Similar content discovery
FAQ search
AI assistants using business data

Benefits and Considerations

Benefits

Some of the key benefits include:

More relevant search results

Using vectors to measure similarity enables vector searches to return more relevant results. Unlike keyword searches, vector search can provide relevant results even if the search query contains misspelled or slang words.

Better user experience

Vector search implementation can improve the user experience. Vector search is less rigid; it provides some flexibility for users when typing their search. This improves the users' experience of the application.

Natural language querying

Vector search implementation allows users to type search queries in natural language, rather than having to target keywords, often explaining the expected result rather than targeting the keywords.

Native integration within MongoDB

Vector Search is part of the core features of MongoDB. This means that it is already integrated with your database and collections. If you have an already existing collection in MongoDB, you can easily use your existing data to implement vector searching.

Reduced need for a dedicated vector database

With MongoDB, you do not need a separate vector database. Data can be stored alongside its vector embeddings in the MongoDB collection.

Considerations

While vector search can provide more accurate results, it is worth noting that it is not a complete replacement for traditional searches. The following key points are worth noting before deciding to implement a vector search in an application:

The need for embedding models:

Vector search implementation requires the use of AI models to generate embeddings. These models can be expensive and provide an additional configuration layer.

Additional storage requirements for vectors

Vectors can be large in size. The vector for a sentence can have up to 8,192 dimensions. Imagine when you have a hundred blog posts. This can take up a huge amount of space and can lead to higher cloud bills.

Choosing an appropriate embedding model

There are several embedding models that are great for different industries. Choosing the right model for your particular use case is a factor that should be considered. For example, a model that was designed for the fashion industry might not give the best result for a model optimized for medical research.

When keyword search may still be the better choice

Vector search is not a complete replacement for keyword search. Keyword search can still be more effective for exact match searches. An example can be searching for an exact serial number, username, or any other situation that returns an exact keyword result.

When Should You Use MongoDB Vector Search?

A vector search implementation that does not use MongoDB requires data, which can be in the form of text, images, or audio, to be stored in a traditional database; the generated vector for the items will be stored in a different dedicated vector database. This results in repetition because two databases are used, increasing the complexity of keeping the two databases in sync and fragmenting data (text and vectors).

MongoDB vector search bridges that gap. It lets data and their generated vectors be stored in the same collection.

Another major advantage that MongoDB vector search brings is that it keeps data in sync. A very common issue with vector search integrations where one database is used for data and another for storing vectors is that the data is often not in sync. If a record is deleted from the regular database and the vector is not, search results can be recommended that are no longer available in the database. MongoDB vector search stores the record and keeps it in sync. If a record is deleted from its collection, its vector is deleted as well, keeping both the record and its vector in sync.

MongoDB vector search eliminates the need for new infrastructure by storing both records and vectors in the same collection.

Conclusion

In this article, we explored what vector search is, how it works, how AI comes into the picture, and what differentiates it from traditional keyword search. We also took it a step further and explored how MongoDB vector search works and what advantages it has over other vector databases.

By the end of this article, you should have a basic understanding of how:

Vector search retrieves information based on meaning rather than exact keywords.
Embeddings make semantic search possible.
MongoDB provides native vector search capabilities that integrate with your existing data.
Understanding these fundamentals is the first step toward building intelligent search experiences.

For a deeper dive on how to implement vector search with MongoDB, you can check out the MongoDB documentation here. If you prefer a step-by-step tutorial, check out this tutorial here.

Now you have the basics; go build something great. Cheers.

A Proven Application Layer for MongoDB

MongoDB Guests — Mon, 27 Jul 2026 11:48:12 +0000

The successful alternative I used before Atlas Device SDKs. This Article was written by Raschid Jimenez.

Atlas Device SDKs reached end-of-life in September 2025, and it’s easy to understand why so many MongoDB developers liked them: direct client access, authentication, sync, and security, all tied closely to MongoDB Atlas.

Long before Atlas Device SDKs, I had already found a different way to get many of those same benefits. Using Parse Server and Back4app, I built production apps for years without the burden of maintaining custom API layers across every client and language. This article is the recipe I wish more MongoDB developers knew: why this stack works, what it gives you, and why it’s such a strong fit on top of MongoDB.

I will walk you through three things that sold me on Parse Server and Back4app: native client SDKs across every platform, row-level security for multi-tenant apps, and managed schema with index control. Along the way, I'll cover what else comes in the package: authentication, real-time updates via LiveQuery, file storage, auto-generated GraphQL APIs, and offline support. Data never leaves MongoDB Atlas. Back4app is a gateway that translates client requests into operations against your cluster.

            ┌──────────────────────────────────────┐
            │  Client (SDKs / REST / GraphQL)      │
            └────────────────────┬─────────────────┘
                                 │
            ┌────────────────────▼─────────────────┐
            │     Application Layer                │
            │       (Back4app - Stateless Gateway) │ 
            └────────────────────┬─────────────────┘
                                 │
            ┌────────────────────▼─────────────────┐
            │     MongoDB Atlas (your cluster)     │
            └──────────────────────────────────────┘

Back4app Uses MongoDB Atlas as the Datastore

Back4app is a managed backend-as-a-service (BaaS) platform. Sign up, paste in your MongoDB connection string, and you get an application backend running in front of your cluster: APIs, SDKs, authentication, real-time sync, file storage, access control, and a dashboard. No provisioning servers, no configuring authorization, no maintaining the layer yourself.

The connection model is what should land for an Atlas audience: bring your own cluster. Back4app connects to an existing Atlas deployment via a standard MongoDB connection string. No migration, no copy of your data, no proprietary storage format, no lock-in at the storage tier. If you walked away from Back4app tomorrow, your Atlas cluster would still be there, untouched, with every native MongoDB primitive intact.

What Back4app adds is the application backend layer most teams end up building anyway: auto-generated REST and GraphQL APIs, authentication, real-time sync, file storage, ACLs and CLPs, and a visual data browser.

Back4app is a layer in front of Atlas, not a replacement for it.

Parse Server Under the Hood

Under the hood, Back4app runs Parse Server, an open-source backend framework with a mature SDK ecosystem across every major platform. That's where the Parse.Object, Parse.Query, Parse.ACL, and Parse.Schema APIs in the code samples throughout this article come from. They're Parse Server primitives. Back4app is the managed platform that runs Parse Server in production (like Atlas does for MongoDB), plus the pieces around it: hosted infrastructure, the connection-string flow into Atlas, the dashboard, the spreadsheet-like data browser, role-aware visual schema editing, monitoring, scaling, and backups.

The short version: code I write with a Parse.* prefix is Parse Server. The surfaces I interact with through the Back4app dashboard are Back4app.

Client SDKs Across Every Platform

With Atlas Device SDKs gone, the question for most teams is concrete: how do clients perform operations against MongoDB Atlas (CRUD, authentication, file uploads, real-time subscriptions, and access-controlled queries with relations) without building and maintaining a custom REST layer for each?

Back4app offers a set of native SDKs that talk to the gateway, which in turn talks to your Atlas cluster. Supported platforms:

iOS (Swift, Objective-C)
Android (Java, Kotlin)
Web (JavaScript, TypeScript)
React Native, Node.js
Flutter, Dart
PHP, .NET, C#
Edge runtimes

For anything not on that list, Back4app auto-generates REST and GraphQL endpoints from the same schema.

The interesting part isn't the language list. It's that the API shape is the same across all of them. Here are the four CRUD operations in JavaScript:

// CREATE - no REST endpoint, no schema migration, just save.
const order = new Parse.Object("Order");
order.set("total", 149.99);
await order.save();

// READ - ACLs are enforced server side; this user only sees their tenant's orders.
const query = new Parse.Query("Order");
query.greaterThan("total", 100);
query.include("customer"); // hydrate the pointer in one round trip
const orders = await query.find();

// UPDATE - same object, just mutate and save.
order.set("status", "shipped");
await order.save();

// DELETE - single call, ACL-checked at the data layer.
await order.destroy();

That include("customer") line is worth looking at. On raw MongoDB, resolving a reference to fetch the related document means writing an aggregation pipeline:

// Without Parse - manual aggregation pipeline:
db.orders.aggregate([
  { $match: { total: { $gt: 100 } } },
  { $lookup: {
      from: "users",
      localField: "customer",
      foreignField: "_id",
      as: "customer"
  }},
  { $unwind: "$customer" }
]);

// With Parse - one line:
await new Parse.Query("Order")
  .greaterThan("total", 100)
  .include("customer")
  .find();

Same result, one round trip, no pipeline to maintain. The include works identically across REST, GraphQL, and every SDK.

The same read in Swift, using the modern Parse-Swift SDK:

let query = Order.query("total" > 100)
  .include("customer")
let orders = try await query.find()

A note on API symmetry: query.include("customer") reads the same in JavaScript and Swift. The naming follows each language's conventions, but the mental model is identical across platforms. Same query model, same ACL enforcement, same relational include semantics. A team shipping iOS, Android, and web doesn't re-architect the data layer per client. They translate one mental model into three idioms.

If GraphQL is the API you want, the same schema produces a typed GraphQL endpoint automatically. No resolvers to write, and the same ACLs and CLPs that govern the SDKs govern those queries too.

For reactive UIs, LiveQuery lets you subscribe to any query and receive push updates on create, update, and delete over WebSockets. No polling loops, no reconnection logic, no homegrown change-stream plumbing. Subscribe to a dashboard to live order updates, and the dashboard updates itself when an order changes upstream.

Row-Level Security and Multi-Tenancy

Multi-tenant access control is application-layer work by design: the database holds the data, the application decides who sees what. In practice, that means every team building multi-tenant SaaS on Atlas writes the same middleware: tenant filters injected into every query, role checks scattered across controllers, field redaction in serializers. That creates a lot of security-critical logic to maintain.

Back4app moves that enforcement down to the data layer. Four layers of access control work together:

Layer	Granularity	When to use
Application Keys	Per client type	Separate public, client, and master contexts
Class-Level Permissions	Per class (collection)	"Who can create or read Orders at all"
Access Control Lists	Per document	"Who can read this Order"
Protected / Field-level	Per field	isAdmin: only the server can write

Here's what each layer replaces in a hand-rolled implementation:

// Without Parse — middleware you write and never get to delete:
app.get("/api/invoices", auth, async (req, res) => {
  const invoices = await db.collection("invoices").find({
    tenantId: req.user.tenantId,        // remember this on every endpoint
    $or: [
      { ownerId: req.user._id },
      { sharedWith: req.user._id }
    ]
  }).toArray();
  // ...strip fields the role shouldn't see...
  res.json(invoices);
});

// With Parse — write zero filter middleware:
const invoices = await new Parse.Query("Invoice").find();
// ACLs and CLPs enforce the same rules across REST, GraphQL, and every SDK.

Here's how you set those ACLs up for a multi-tenant invoice scoped to a tenant role:

const invoice = new Parse.Object("Invoice");
invoice.set("amount", 1200);

const acl = new Parse.ACL();
acl.setRoleReadAccess("tenant_acme", true);          // every user in this tenant
acl.setRoleWriteAccess("tenant_acme_admins", true);  // only admins can modify
invoice.setACL(acl);

await invoice.save();

Any query from a user outside tenant_acme will not see this document. Enforcement happens server-side at the gateway, not in hopeful client code. The same filter applies whether the request comes from the iOS SDK, the GraphQL endpoint, or an inbound webhook. There is no client-side path that can bypass it.

When per-object rules aren't expressive enough ("users can update their own row, but only during business hours, and only if the invoice isn't locked"), Cloud Code provides server-side functions for custom validation:

// Cloud Code — server side function, runs in Parse Server, ACL-aware.
Parse.Cloud.beforeSave("Invoice", async (req) => {
  if (req.object.get("locked") && !req.master) {
    throw "Locked invoices cannot be modified";
  }
});

Schema and Index Management

With Parse, the schema lives in the database itself. Every client SDK, REST endpoint, and GraphQL type derives from there automatically. One source of truth, propagated to every surface your app talks to.

Parse's ODM defines classes (collections) with typed fields: strings, numbers, dates, files, GeoPoints, pointers, and relations. Parse enforces types at the gateway across REST, GraphQL, and every SDK, so a malformed payload is rejected before it reaches Atlas. The underlying MongoDB collection and the indexes Parse needs are auto-created. Schema changes are tracked through the Parse schema API or the Back4app dashboard, and they propagate to every client without anyone regenerating models by hand.

Document stores don't usually feel relational, but Back4app adds pointers for one-to-one references and relations for many-to-many associations, with include queries that hydrate them in a single round trip:

const query = new Parse.Query("Order");
query.include("customer");   // hydrates the pointer
query.include("products");   // hydrates the relation
const orders = await query.find();
// One round trip. No manual $lookup pipeline.

When you want schemas in version control rather than clicked into a dashboard, schemas can be declared programmatically, and migrations become regular code:

const schema = new Parse.Schema("Invoice");
schema
  .addString("customerEmail")
  .addNumber("amount")
  .addPointer("tenant", "Tenant")
  .addIndex("by_email", { customerEmail: 1 }); // explicit MongoDB index
await schema.save();

Parse exposes MongoDB indexes directly. It creates defaults for ACL fields and pointers, but your hand-tuned indexes stay untouched. Parse only adds the ones it needs for ACL filtering and pointer fields. Your existing indexes for aggregation pipelines, Atlas Search, or hand-tuned queries stay exactly as you set them. The addIndex() call above creates a real MongoDB index. Parse doesn't abstract that away.

If you picked MongoDB for schemaless flexibility: Parse classes can stay flexible (allowAddField: true) during prototyping and tighten as the data model stabilizes. You pick per class. Strict where it matters, flexible where it helps.

Conclusion & Next Steps

Back4app is a stateless gateway in front of your existing MongoDB Atlas cluster. Connect it with a standard MongoDB connection string, and you get the dashboard, the spreadsheet-like data browser, SDKs across every major platform, auto-generated REST and GraphQL endpoints, LiveQuery for real-time UIs, and row-level security via CLPs and ACLs. Native MongoDB primitives (aggregations, transactions, indexes, Atlas Search) remain entirely available to you.

So my advice to you is: go to Back4App and sign up for free, create an app in your preferred language, and run your first operation on your data in under 10 minutes. Back4App offers a free tier (25,000 API requests per month), which is enough to try on a real app rather than a toy. My customers loved having their app backends hosted for free and paying only when they scaled.