Forem: aasawari sahasrabuddhe

Exploring the Advanced Search Capabilities With MongoDB Atlas Search-Part 3

aasawari sahasrabuddhe — Sat, 14 Feb 2026 06:14:33 +0000

If you've been following along with the first two parts of our Atlas Search with Spring Boot series, you should already understand Atlas Search concepts and how to craft queries using them. In this article, we'll get into some more advanced topics and features of Atlas Search, enhancing your ability to query data effectively.

For those who still need to explore the earlier parts of the series, I strongly recommend doing so to build a foundational understanding. You can access the previous articles here: Getting Started With MongoDB Atlas Search and Java and Exploring Search Capabilities With Atlas Search.

In this article, we'll explore advanced topics such as creating custom analyzers, utilizing language-specific analyzers, working with GeoJSON data, and performing searches in combination with other aggregation stages like $lookup.

Let's get into it!

Prerequisites

Sign up for a MongoDB free tier Atlas account. You can start by following Register to Free Tier to build your Atlas cluster.
Use Import and Export Data to add the data to the Atlas cluster. The sample data is available in the GitHub repository at productDetails.json and productReviews.json.
Install Java version 17 or above.

Exploring the advanced search capabilities

Case 1: Searching with language analyzers

In the previous tutorial, we learned the use of English language analyzers. However, Atlas Search offers a wide range of language analyzers beyond just English. For comprehensive details, you can refer to the official Language Analyzers documentation.

After loading the data into your Atlas cluster from productDetails.json, you'll need to create a search index. You can do this using any of the methods outlined in Part 1 of our series, Getting Started With MongoDB Atlas Search and Java.

To create your search index, you can make use of the below JSON and create an index using the JSON editor on the Atlas UI.

{
 "analyzer": "lucene.spanish",
 "searchAnalyzer": "lucene.spanish",
 "mappings": {
   "dynamic": true,
   "fields": {
     "productNameSpanish": {
       "analyzer": "lucene.spanish",
       "searchAnalyzer": "lucene.spanish",
       "type": "string"
     }
   }
 }
}

Once the index is created, you can make use of the below Java code:

public List<Document> searchWithSpanish(String query, String sampleProducts) {
   MongoCollection<Document> collection;
   MongoDatabase database = mongoTemplate.getDb();
   collection = database.getCollection(sampleProducts);
   List<Document> pipeline = Arrays.asList(new Document("$search",
           new Document("index", "index01")
                   .append("text",
                           new Document("query", query)
                                   .append("path", "productNameSpanish"))),
           new Document("$limit", 3));

   ArrayList<Document> results = new ArrayList<>();
   collection.aggregate(pipeline).into(results);
   return results;
}

In this tutorial, since we use two different collections, we pass them as parameters in the search methods.

To run this, you can run the API call as:

GET http://localhost:8080/search/withSpanish?query={Raton Inalambrico}

and it would give you the output as

[
  {
    "_id": {
      "timestamp": 1723024731,
      "date": "2024-08-07T09:58:51.000+00:00"
    },
    "productID": "ELEC-00123",
    "productName": "Wireless Mouse",
    "productNameSpanish": "Ratón Inalámbrico",
    "category": "Electronics",
    "price": 25.99,
    "availability": "In Stock",
    "productLink": "https://www.amazon.com/dp/B08J2T6P7Q",
    "location": {
      "city": "Shenzhen",
      "coordinates": [
        114.0579,
        22.5431
      ]
    }
  },
  {
    "_id": { 
      "timestamp": 1723024731,
      "date": "2024-08-07T09:58:51.000+00:00"
    },
    "productID": "CHRG-11111",
    "productName": "Wireless Charger",
    "productNameSpanish": "Cargador Inalámbrico",
    "category": "Accessories",
    "price": 24.99,
    "availability": "In Stock",
    "productLink": "https://www.target.com/p/wireless-charger/-/A-87654321",
    "location": {
      "city": "Shenzhen",
      "coordinates": [
        114.0579,
        22.5431
      ]
    }
  }
]

Case 2: Building custom analyzers

In previous tutorials, we explored Atlas's pre-defined analyzers and their use cases. In addition to these, Atlas Search also allows you to create custom analyzers, which can be particularly useful when you need to search for data like product IDs containing alphanumeric characters and hyphens or email addresses.

In this tutorial, we'll build custom analyzers for two different fields and demonstrate how to perform searches using the indexes we create.

For example, in the sample data you've imported, the productDetails field contains a productID with a value like ELEC-00123. To effectively search within this field, we would configure the index as follows:

{
 "mappings": {
   "dynamic": true
 },
 "analyzers": [
   {
     "name": "productIDAnalyzer",
     "tokenFilters": [
       {
         "type": "lowercase"
       }
     ],
     "tokenizer": {
       "pattern": "[-.]+",
       "type": "regexSplit"
     }
   },
   {
     "name": "productLinkAnalyzer",
     "tokenFilters": [
       {
         "type": "lowercase"
       },
       {
         "originalTokens": "include",
         "type": "asciiFolding"
       }
     ],
     "tokenizer": {
       "pattern": "\\W+",
       "type": "regexSplit"
     }
   }
 ]
}

To search for the productID, we can specify only the numeric or the alphabets to perform the search. The Spring Boot method to perform the search would look like this:

public List<Document> withCustomAnalyzersOnProductID(String query, String sampleProducts) {
   MongoCollection<Document> collection;
   MongoDatabase database = mongoTemplate.getDb();
   collection = database.getCollection(sampleProducts);
   List<Document> pipeline = Arrays.asList(new Document("$search",
                   new Document("index", "index02")
                           .append("text",
                                   new Document("query", query)
                                           .append("path", "productID"))),
           new Document("$project",
                   new Document("_id", 0L)
                           .append("productID", 1L)
                           .append("productName", 1L)),
           new Document("$limit", 3));

   ArrayList<Document> results = new ArrayList<>();
   collection.aggregate(pipeline).into(results);
   return results;
   }

The REST call would look like this:

GET http://localhost:8080/search/withCustomAnalyzersOnProductID?query={05050}

and it would give you results as:

[
  {
    "productID": "WEAR-05050",
    "productName": "Smartwatch"
  }
]

In the above index, we also have an analyzer created on the productLink field which uses the regex on the links being used. This regex would remove the "//" from the text and allow you to search without using these special characters.

For example, if you wish to search for all products listed on www.amazon.com, the custom analyzer would help you search for the products.

For instance, if we have the search function as:

public List<Document> withCustomAnalyzersOnProductLink(String query, String sampleProducts) {
   MongoCollection<Document> collection;
   MongoDatabase database = mongoTemplate.getDb();
   collection = database.getCollection(sampleProducts);
   List<Document> pipeline = Arrays.asList(new Document("$search",
                   new Document("index", "index02")
                           .append("text",
                                   new Document("query", query)
                                           .append("path", "productLink"))),
           new Document("$project",
                   new Document("_id", 0L)
                           .append("productID", 1L)
                           .append("productName", 1L)
                           .append("productLink", 1L)),
           new Document("$limit", 3));

   ArrayList<Document> results = new ArrayList<>();
   collection.aggregate(pipeline).into(results);
   return results;
}

We can use the REST call as:

GET http://localhost:8080/search/withCustomAnalyzerOnProductLink?query={www.amazon.com}

and it would result as:

[
  {
    "productID": "ELEC-00123",
    "productName": "Wireless Mouse",
    "productLink": "https://www.amazon.com/dp/B08J2T6P7Q"
  },
  {
    "productID": "MONI-03030",
    "productName": "4K Monitor",
    "productLink": "https://www.amazon.com/dp/B09ABCDEFG"
  },
  {
    "productID": "ACC-08080",
    "productName": "Smartphone Stand",
    "productLink": "https://www.amazon.com/dp/B08ABC1234"
  }
]

Case 3: Performing a search with lookups

While using the $search operator, it is always expected to use it as the first stage in the pipeline. But if you get into a situation where you need to perform join first and then search, what would you do? Well, this case covers the concept!

When you imported the data into the Atlas cluster, you would also have imported the productReviews.json which contains reviews for the products.

To understand further, let's create a simple index on the productReviews collection:

{
 "mappings": {
   "dynamic": true
 }
}

And let's suppose you wish to get all the product information from both collections which have reviews as _excellent. _

The method would look like:

public List<Document> searchWithLookups(String query, String productReviews) {
   MongoCollection<Document> collection;
   MongoDatabase database = mongoTemplate.getDb();
   collection = database.getCollection(productReviews);
   List<Document> pipeline = Arrays.asList(new Document("$lookup",
                   new Document("from", productReviews)
                           .append("localField", "productID")
                           .append("foreignField", "productID")
                           .append("as", "result")
                           .append("pipeline", Arrays.asList(new Document("$search",
                                   new Document("index", "index03")
                                           .append("text",
                                                   new Document("query", query)
                                                           .append("path", "review")))))),
           new Document("$match",
                   new Document("result",
                           new Document("$ne", Arrays.asList()))),
           new Document("$limit", 3));

   ArrayList<Document> results = new ArrayList<>();
   collection.aggregate(pipeline).into(results);
   return results;
}

The REST API call would look like:

GET http://localhost:8080/search/withLookups?query={excellent}

and it would result in

[
{
   "_id": {
     "timestamp": 2008237403,
     "date": "2033-08-21T11:43:23.000+00:00"
   },
   "productID": "ELEC-00123",
   "review": "The Wireless Mouse is excellent with a long-lasting battery, perfect for daily use.",
   "rating": 4.5,
   "reviewer": "Alice Walker",
   "reviewDate": "2024-08-01T10:00:00.000+00:00",
   "result": [
     {
       "_id": {
         "timestamp": 2008237403,
         "date": "2033-08-21T11:43:23.000+00:00"
       },
       "productID": "ELEC-00123",
       "review": "The Wireless Mouse is excellent with a long-lasting battery, perfect for daily use.",
       "rating": 4.5,
       "reviewer": "Alice Walker",
       "reviewDate": "2024-08-01T10:00:00.000+00:00"
     }
   ]
 },
 {
   "_id": {
     "timestamp": 2008237403,
     "date": "2033-08-21T11:43:23.000+00:00"
   },
   "productID": "HEAD-07070",
   "review": "Noise Cancelling Headphones offer excellent sound isolation, though availability is limited.",
   "rating": 4.5,
   "reviewer": "Jack Taylor",
   "reviewDate": "2024-08-10T19:00:00.000+00:00",
   "result": [
     {
      "_id": {
         "timestamp": 2008237403,
         "date": "2033-08-21T11:43:23.000+00:00"
       },
       "productID": "HEAD-07070",
       "review": "Noise Cancelling Headphones offer excellent sound isolation, though availability is limited.",
       "rating": 4.5,
       "reviewer": "Jack Taylor",
       "reviewDate": "2024-08-10T19:00:00.000+00:00"
     }
   ]
 },
 {
   "_id": {
     "timestamp": 2008237403,
     "date": "2033-08-21T11:43:23.000+00:00"
   },
   "productID": "MONI-03030",
   "review": "The 4K Monitor delivers stunning visuals with excellent clarity, though it is on the pricier side.",
   "rating": 4.7,
   "reviewer": "Frank Harris",
   "reviewDate": "2024-08-06T11:20:00.000+00:00",
   "result": [
     {
       "_id": {
         "timestamp": 2008237403,
         "date": "2033-08-21T11:43:23.000+00:00"
       },
       "productID": "MONI-03030",
       "review": "The 4K Monitor delivers stunning visuals with excellent clarity, though it is on the pricier side.",
       "rating": 4.7,
       "reviewer": "Frank Harris",
       "reviewDate": "2024-08-06T11:20:00.000+00:00"
     }
   ]
 }
]

This would give all product information with excellent keywords in the reviews.

Conclusion

In this final part of our Atlas Search with Spring Boot series, we've learned more advanced features that Atlas Search offers, such as custom analyzers and language-specific search capabilities. By exploring these topics, we have expanded the ability to design powerful and efficient search queries that cater to complex data retrieval needs.

We discussed custom analyzers to fine-tune search results and perform searches combined with other MongoDB aggregation stages, such as $lookup, to enrich your queries with related data from multiple collections. These techniques will help you create more nuanced and effective search solutions tailored to your specific application requirements.

If you have any questions about the articles, please follow the community forum thread below for questions and discussion. Also, keep exploring other tutorials on our MongoDB Developer Center.

Happy coding!

Exploring Search Capabilities With Atlas Search-Part 2

aasawari sahasrabuddhe — Sat, 14 Feb 2026 06:07:19 +0000

Welcome to the second part of our series on leveraging MongoDB Atlas Search with Spring Boot. In Part 1, we learned how to create Atlas Search indexes using various methods: the MongoDB CLI, the Atlas UI, and programmatically within a Spring Boot application. We explored the fundamental steps required to set up these indexes, providing a solid foundation for implementing powerful search capabilities.

In this part, we will build upon that foundation by diving deeper into the practical application of these indexes. This article will focus on crafting and executing search queries using Spring Boot, illustrating how to harness the full potential of Atlas Search in your applications.

We will also explain key concepts and terminologies associated with Atlas Search, ensuring you have a comprehensive understanding of how it operates.

Whether you are a seasoned developer or new to MongoDB and Spring Boot, this series aims to equip you with the knowledge and tools needed to implement efficient and effective search functionality in your applications.

Pre-requisites

A dedicated Atlas cluster to create indexes programmatically
Java Version 22
Sample data loaded in your atlas cluster

Querying with Atlas Search indexes

Before we get into writing search queries using the indexes we've created, we highly recommend familiarizing yourself with the foundational concepts of MongoDB Atlas Search. A great resource for this is Part 1 of the series "Getting Started With MongoDB Atlas Search and Java.".

This tutorial will provide you with an understanding of the key principles behind Atlas Search and demonstrate how to create different types of indexes tailored to various use cases. By gaining this background knowledge, you'll be better equipped to effectively implement and leverage search functionalities in your Spring Boot applications.

In each of the sections below, we will cover the terminology and understand real-life examples where the indexes would be helpful.

The search queries mentioned will be used on the movies collection of the sample_mflix database

Case 1: Setting dynamic properties to true

If you have an application where the schema changes frequently, setting up dynamic property to true will automatically create the indexes on the supported data type fields. For example, the testIndex01 has the dynamic mapping to true, which indexes all fields with supported data types.

The below function makes use of testIndex01 to query all the string index fields.

public ArrayList<Document> searchMovies(String query) {
        List<Document> pipeline = Arrays.asList(new Document("$search",
                        new Document("index", "testIndex01")
                                .append("text",
                                        new Document("query", "cartoon")
                                                .append("path", Arrays.asList("title", "plot", "fullplot")))),
                        new Document("$project",
                        new Document("_id", 0L)
                                .append("title", 1L)
                                .append("plot", 1L)
                                .append("fullplot", 1L)),
                        new Document("$limit", 3L));

ArrayList<Document> results = new ArrayList<>();
collection.aggregate(pipeline).into(results);
return results;
    }

Using the above function, you can find movies that mention the keyword mentioned in the _query _on the title, plot, and fullplot fields defined in the path. _For example…

curl -X GET "http://localhost:8080/search?query=cartoon" | jq

…will give all movies with the keyword "cartoon" as shown below:

[
  {
    "plot": "Follow Garfield behind the scenes in Cartoon World where he grows bored with his life as a comic strip star.",
    "title": "Garfield Gets Real",
    "fullplot": "Follow Garfield behind the scenes in Cartoon World where he grows bored with his life as a comic strip star."
  },
  {
    "plot": "A high-profiled documentary about Hergè and his major cartoon success, Tintin, based in part on previously unreleased archive tape footage.",
    "title": "Tintin and I",
    "fullplot": "A high-profiled documentary about Hergè and his major cartoon success, Tintin, based in part on previously unreleased archive tape footage."
  },
  {
    "plot": "Bugs Bunny reflects on his past cartoon exploits.",
    "title": "The Bugs Bunny/Road-Runner Movie",
    "fullplot": "The Bugs Bunny/Road Runner Movie is basically a collection of Warner Bros. short cartoon features, \"starring\" the likes of Daffy Duck, Porky Pig and Wile.E.Coyote. These animations are interspersed by Bugs Bunny reminiscing on past events and providing links between the individual animations which are otherwise unconnected. The Road Runner feature at the end consists of sketches from various RR separates (well it does in the 78-minute version anyway)."
  }
]

Case 2: Using analyzers in search indexes

In this case, we will be utilising the testIndex02 created with field mapping. Field mapping means static mapping has been used and not all fields are indexes. Only fields that are mentioned are indexed.

In our case, the field _genre _has been indexed and can be used with the below method:

public ArrayList<Document> searchMoviesWithGenre(String keyword){
        List<Document> pipeline = Arrays.asList(new Document("$search",
                new Document("index", "testIndex02")
                        .append("text",
                                new Document("query", keyword)
                                        .append("path", "genres"))),
                new Document("$project",
                new Document("_id", 0L)
                        .append("title", 1L)
                        .append("genres", 1L)),
                new Document("$limit", 5L));
ArrayList<Document> results = new ArrayList<>();
collection.aggregate(pipeline).into(results);
return results;
    }

For example, if you wish to list all the movies whose genre is action, you can make the REST call as:

curl -X GET "localhost:8080/searchMoviesWithGenre?query=action" | jq

This will give the output as:

[
  {
    "genres": [
      "Action"
    ],
    "title": "The Perils of Pauline"
  },
  {
    "genres": [
      "Action"
    ],
    "title": "Legacy of Rage"
  },
  {
    "genres": [
      "Action"
    ],
    "title": "Batman Returns"
  },
  {
    "genres": [
      "Action"
    ],
    "title": "Dragon Inn"
  },
  {
    "genres": [
      "Action"
    ],
    "title": "Dikiy vostok"
  }
]

Case 3: Using facets to categorise the data

From the above example, we will be using the facets used by the searchMoviesAndCategorise method to perform a search on genres and categorise the data based on genres. Later, the testIndex02 also has numberFacet created on the year field, which will bucket all the movies released every 10 years and return the count for all movies.

public ArrayList<Document> searchMoviesAndCategorise(){
        List<Document> pipeline = Arrays.asList(new Document("$searchMeta",
                new Document("index", "testIndex02")
                        .append("facet",
                new Document("operator",new Document("text",
                new Document("query", "movie").append("path", "title")))
                        .append("facets",new Document("genresFacet",
                new Document("type", "string").append("path", "genres"))
                        .append("yearFacet",new Document("type", "number")
                        .append("path", "year")
                        .append("boundaries", Arrays.asList(1990L, 2000L, 2010L, 2020L)))))));
ArrayList<Document> results = new ArrayList<>();
collection.aggregate(pipeline).into(results);
return results;
}

For example, when you use the below API call, it will categorise the data based on genres first and then categorise on the number of movies released every 10 years to date.

curl -X GET "http://localhost:8080/searchMoviesAndCategorise" | jq

It will give the output as:

{
  "count": {
    "lowerBound": 125
  },
  "facet": {
    "genresFacet": {
      "buckets": [
        {
          "_id": "Comedy",
          "count": 71
        },
        {
          "_id": "Animation",
          "count": 42
        },
        {
          "_id": "Adventure",
          "count": 40
        },
        {
          "_id": "Family",
          "count": 29
        },
        {
          "_id": "Drama",
          "count": 19
        },
        {
          "_id": "Action",
          "count": 18
        },
        {
          "_id": "Documentary",
          "count": 16
        },
        {
          "_id": "Horror",
          "count": 9
        },
        {
          "_id": "Fantasy",
          "count": 6
        },
        {
          "_id": "Crime",
          "count": 5
        }
      ]
    },
    "yearFacet": {
      "buckets": [
        {
          "_id": 1990,
          "count": 19
        },
        {
          "_id": 2000,
          "count": 62
        },
        {
          "_id": 2010,
          "count": 27
        }
      ]
    }
  }
}

Case 4: Search text using incomplete spellings

The autocomplete feature helps you search using keywords that are spelt incompletely. This feature is helpful when a user wants to look for a book with an incomplete name on the e-commerce website. In this case, we will be making use of testIndex03 and outlook for movies where incomplete keywords for the fullplot fields have been mentioned.

The search function can be written as:

public ArrayList<Document> searchWithIncompleteKeyword(String keyword){
      List<Document> pipeline = Arrays.asList(new Document("$search",
                      new Document("index", "testIndex03")
                              .append("autocomplete",
                                      new Document("query", keyword)
                                              .append("path", "fullplot"))
                              .append("highlight",
                                      new Document("path", "fullplot"))),
                      new Document("$project",
                      new Document("_id", 0L)
                              .append("fullplot", 1L)
                              .append("highlights",
                      new Document("$meta", "searchHighlights"))),
                      new Document("$limit", 1L));
ArrayList<Document> results = new ArrayList<>();
collection.aggregate(pipeline).into(results);
return results;
    }

For example, if the fullplot field mentions Spa and Cow as incomplete keywords for Spain, Space, cowboys, etc. to test, you can search using the following API.

curl -X GET "http://localhost:8080/searchMoviesWithAutocomplete?query=spa%20cow" | jq

It will give a response as:

[
  {
    "fullplot": "Julièn Torralba is a former movie stuntman in Almeria, Spain. He and several of his colleagues, who once made a living in American Westerns shot in Spain, now are reduced to doing stunt shows for minuscule audiences on the decaying set built for those old Westerns. Julièn wrestles with dark memories of the death of his son, also a stuntman, and with estrangement from his daughter-in-law Laura and her son Carlos. Carlos, a young boy, becomes intrigued with his late father's life and runs away to join Julièn and his band of has-beens. There Carlos is initiated into the rambunctious life of these hard-drinking faux cowboys. But when Laura, a powerful executive looking for a new site for a tourist resort, learns that Carlos has joined the hated Julièn, she moves to destroy even this remnant of Julièn's once-proud career. Julièn and the cowboys decide to fight back the only way they know how.",
    "highlights": [
      {
        "score": 2.126451015472412,
        "path": "fullplot",
        "texts": [
          {
            "value": "Julièn Torralba is a former movie stuntman in Almeria, ",
            "type": "text"
          },
          {
            "value": "Spain. He and",
            "type": "hit"
          }
        ]
      },
      {
        "score": 1.518623948097229,
        "path": "fullplot",
        "texts": [
          {
            "value": "He and several of his colleagues, who once made a living in American Westerns shot in ",
            "type": "text"
          },
          {
            "value": "Spain, now are",
            "type": "hit"
          },
          {
            "value": " reduced to doing stunt shows for minuscule audiences on the decaying set built for those old Westerns. ",
            "type": "text"
          }
        ]
      },
      {
        "score": 1.869809865951538,
        "path": "fullplot",
        "texts": [
          {
            "value": "There Carlos is initiated into the rambunctious life of these hard-drinking faux ",
            "type": "text"
          },
          {
            "value": "cowboys. But when",
            "type": "hit"
          }
        ]
      },
      {
        "score": 1.9461908340454102,
        "path": "fullplot",
        "texts": [
          {
            "value": "Julièn and the ",
            "type": "text"
          },
          {
            "value": "cowboys decide to",
            "type": "hit"
          },
          {
            "value": " fight back the only way they know how.",
            "type": "text"
          }
        ]
      }
    ]
  }
]

Case 5: Searching using incorrect spelling

Sometimes, we search for items/products on websites using the wrong spelling due to autocorrect or unawareness of the right spelling, but the application still gives us the right results. This is possible because of the fuzzy search feature.

MongoDB's Atlas Search also allows you to search through the text with the incorrect spelling.

The testIndex03 created in the previous part of the series will be used here in the below function:

public ArrayList<Document> searchWithMisspelledTitle(String keyword){
        List<Document> result = Arrays.asList(new Document("$search",
                         new Document("index", "testIndex03")
                                .append("text",
                         new Document("query", keyword)
                                                .append("path", "title")
                                                .append("fuzzy",
                         new Document("maxEdits", 2L)
                                .append("maxExpansions", 100L)))),
                         new Document("$project",
                         new Document("title", 1L)
                                .append("cast", 1L)),
                         new Document("$limit", 3L));
return collection.aggregate(result).into(new ArrayList<>());
    }

In this case, you can search for the movie with a misspelled title, and the right movie name will appear in the results.

For example, if you search for the movie with the below REST call…

curl -X GET "localhost:8080/searchMoviesWithIncorrectSpelling?query=Gerti%20the%20Dinosor" | jq

…where the word Dinosour is wrongly spelt as Dinosor, it will give the results as:

[
  {
    "_id": {
      "timestamp": 1463423888,
      "date": "2016-05-16T18:38:08.000+00:00"
    },
    "cast": [
      "Winsor McCay",
      "George McManus",
      "Roy L. McCardell"
    ],
    "title": "Gertie the Dinosaur"
  },
  {
    "_id": {
      "timestamp": 1463423899,
      "date": "2016-05-16T18:38:19.000+00:00"
    },
    "title": "Dinosaur",
    "cast": [
      "D.B. Sweeney",
      "Alfre Woodard",
      "Ossie Davis",
      "Max Casella"
    ]
  },
  {
    "_id": {
      "timestamp": 1463423974,
      "date": "2016-05-16T18:39:34.000+00:00"
    },
    "cast": [
      "Stan Adelstein",
      "Lanice Archer",
      "Robert Bakker",
      "Philip Currie"
    ],
    "title": "Dinosaur 13"
  }
]

Case 6: Search with synonym keywords

Similar to the case mentioned above, MongoDB Atlas Search also allows searching with synonym keywords — i.e., words that have the same or nearly the same meaning.

To explore this feature, we utilise the testIndex04 to write the search query.

When we create the search index, we specify the collection as Synonyms Source Collection, from where the synonyms will be mapped. The testIndex04 mentions the collection name as test_synonyms, which is the source collection.

The search query is written as:

public ArrayList<Document> searchWithSynonyms(String keyword){
        List<Document> result = Arrays.asList(new Document("$search",
                        new Document("index", "testIndex04")
                                .append("text",
                                        new Document("path", "fullplot")
                                                .append("query", keyword)
                                                .append("synonyms", "synonymName"))),
                        new Document("$limit", 10L),
                        new Document("$project",
                        new Document("_id", 0L)
                                .append("title", 1L)
                                .append("fullplot", 1L)
                                .append("score",
                                        new Document("$meta", "searchScore"))),
                       new Document("$limit", 3L));
        return collection.aggregate(result).into(new ArrayList<>());
    }

The $meta used in the query with searchScore will determine how close the document is to the searched keyword. Before we do the rest call to test the query, we need to create the mapping for the synonyms in a different collection.

Insert the data below into the test_synonyms collection.

[
  {
    mappingType: 'explicit',
    input: [ 'love', 'romance' ],
    synonyms: [ 'love', 'romance' ]
  },
  {
    mappingType: 'equivalent',
    synonyms: [ 'car', 'vehicle', 'automobile' ]
  }
]

To test the above query, you can use the REST call as:

curl -X GET "localhost:8080/searchMoviesWithSynonyms?query=love" | jq

This will give results based on the mapping created, as shown below.

[
  {
    "title": "Oh, Woe Is Me",
    "fullplot": "Romance about Simon Donnadieu and his decision to leave his ever-loving wife Rachel.",
    "score": 3.9741177558898926
  },
  {
    "title": "27 Missing Kisses",
    "fullplot": "The summerly adventures of teen Sybilla, who falls in love with a middle-aged father, while being romanced by the his teen son.",
    "score": 3.8209657669067383
  },
  {
    "title": "The End of the Affair",
    "fullplot": "In wartorn London Maurice Bendrix falls in love with neighbor Sarah Miles. They begin an illicit romance behind Sarah's husband's back. While war does not last forever, neither does love in this existentialist tale.",
    "score": 3.753319263458252
  }
]

The complete code for the application using all the cases mentioned above is available in the GitHub repository.

Clean up the indexes

After you have utilised all the indexes created, you can use the below method to delete all the search indexes that have been created through the application.

public void deleteSearchIndexes(String dbName, String collectionName) {
        MongoDatabase database = mongoClient.getDatabase(dbName);
        MongoCollection<Document> collection = database.getCollection(collectionName);

        List<String> indexNames = new ArrayList<>();
        for (Document indexInfo : collection.listSearchIndexes()) {
            String indexName = indexInfo.getString("name");
            if (!"_id_".equals(indexName)) {
                indexNames.add(indexName);
            }
        }
        // Drop each index using its name from the array
        for (String indexName : indexNames) {
            collection.dropSearchIndex(indexName);
        }
        System.out.println("Deleted all indexes created");
    }

And call the API with the below command

curl -X DELETE "localhost:8080/deleteSearchIndexes?dbName=<dbName>&collectionName=<collectionName>"

Conclusion

In this second part of our series on exploring MongoDB Atlas Search with Spring Boot, we have delved into the practical applications of the search indexes we created in Part 1. By demonstrating various search scenarios, we highlighted the versatility and power of Atlas Search in handling different types of queries and data structures.

In this part, we have covered some use cases like autocomplete, fuzzy, field mapping, etc. If you wish to learn about more cases, we also have other articles — MongoDB Atlas Search Using the Java Driver and Spring Data and How to Build a Search Service in Java — where you can explore more use cases.

If you have any questions or suggestions, please feel free to reach out on the MongoDB community forum and also explore more fun tutorials through our MongoDB Developer Center.

Getting started with MongoDB Atlas Search and Java-Part 1

aasawari sahasrabuddhe — Sat, 14 Feb 2026 06:02:41 +0000

Creating Atlas Search Indexes: A Comprehensive Guide

MongoDB's Atlas Search is an embedded full-text search available in MongoDB Atlas, providing a seamlessly scalable experience for building relevance-based app features. Built on Apache Lucene, the Atlas Search feature supports a wide scope of search functionalities without the need for additional applications to handle searching capabilities.

In this tutorial series, we will delve into the concepts of Atlas Search in detail and build a sample application using Spring Boot. These articles will guide you through the process of creating search indexes and implementing search functionalities on documents using advanced features like fuzzy searches, autocomplete, and more.

In the first part of this series, we will cover how to create search indexes using various methods:

Atlas UI: A user-friendly interface for managing search indexes
Atlas CLI: Command line interface for more direct control
Spring Boot application: Programmatically managing indexes within your application

By the end of this tutorial, you'll have a solid understanding of how to leverage MongoDB's Atlas Search to enhance your application's search capabilities.

Let's get started!

Prerequisites

Below are the prerequisites you need to get started.

An M0 cluster — you can create one by registering for a free Atlas account
Java version 17+

Note: The free tier or M0 allows only three Atlas search indexes to be created at once. To create more than three at a time, you must upgrade to M2/M5 or higher. Also, if you wish to create an index using CLI and drivers, make sure to upgrade the cluster to M10 or higher.

What are Atlas Search indexes?

Traditional database indexes, such as B-trees or hash indexes in MongoDB, improve query performance by allowing the database to locate data quickly without scanning every document. They are typically used for exact match queries, range queries, and sorting operations.

On the other hand, the Atlas Search indexes are designed for full-text search, supporting advanced text queries, relevancy scoring, and text analysis. It is a specialised data structure that organises data to make it easily searchable. It maps terms to the documents containing those terms, enabling quicker retrieval of documents based on specific identifiers. To query data in your Atlas cluster using Atlas Search, you need to configure an Atlas Search index.

The search indexes can be created on a single field or multiple document fields. The indexes on these fields could be created with different mechanisms which we will discuss.

Learn more about analysers, tokenisers, and field mappings.

Creating Atlas Search indexes

Case 1: Creating an index with dynamic mapping set to true

Using Atlas UI

Log in to your Atlas cluster and switch to the "Atlas Search" section on the screen.
Click on "Create Search Index."

Click on "Next" and select the index name and collection on which you wish to create the search index.

The index build will start and after a few minutes, you will see the screen below:

Using Atlas CLI

To create and manage Atlas Search indexes using the Atlas CLI, your Atlas cluster must run MongoDB 6.0+ or 7.0+.

You can't use the mongosh command to create and manage Atlas Search indexes on M0, M2, or M5 Atlas clusters. You will have to upgrade to M10+ to use this method. The index will be created using the below command:

atlas clusters search indexes create --clusterName <clusterName> --file index.json

The index.json file should contain the following information:

{
  "name": "testIndex01",
  "database": "sample_mflix",
  "collectionName": "movies",
  "mappings": {
    "dynamic": true
  }
}

It will give you the following output as:

Index testIndex01 created.

Using Spring Boot application

To create an index using Spring Boot application, you will have to use the code example below:

try (MongoClient mongoClient = MongoClients.create(uri)) {
MongoDatabase database = mongoClient.getDatabase("sample_mflix");
MongoCollection<Document> collection = database.getCollection("movies");
SearchIndexModel indexOne = new SearchIndexModel("indexOne",
                                new Document("mappings",
                         new Document("dynamic", true)));
collection.createSearchIndexes(Collections.singletonList(indexOne));

Case 2: Creating an index with field mapping

Using Atlas UI

As mentioned in the first step to create the index, select the Visual Editor and select the database and collection name as sample_mflix and movies respectively.

Once you select it click "Next" and then on the "Refine Your Index" tab. Click on "Add Field Mapping" and you will see the below screen pop up:

Select the field name and data type that you would like to recognise the field name as. For example, the below screenshot represents the field mapping added for the genres and year fields.

Click on "Save Changes" and the index creation will start.

Using Atlas CLI

Update the index.json file as:

{
  "name": "testIndex02",
  "database": "sample_mflix",
  "collectionName": "movies",
  "mappings": {
    "dynamic": true,
    "fields": {
      "genre": [
        {
          "type": "string"
        },
        {
          "type": "stringFacet"
        }
      ],
      "year": [
        {
          "type": "numberFacet"
        },
        {
          "type": "number"
        }
      ]
    }
  }
}

Now to create the index, use the same command as mentioned in Case 1 above.

Using Spring Boot application

If you wish to create the above index using the Spring Boot application, you can try using the below code:

try (MongoClient mongoClient = MongoClients.create(uri)) {
MongoDatabase database = mongoClient.getDatabase("sample_mflix");
MongoCollection<Document> collection = database.getCollection("movies");
SearchIndexModel indexTwo = new SearchIndexModel("testIndex02",
                new Document("mappings",
                        new Document("dynamic", true).append("fields", new Document().append("genres", Arrays.asList(
               new Document().append("type", "stringFacet"),
               new Document().append("type", "string")))
.append("year",Arrays.asList(
                       new Document().append("type", "numberFacet"),
               new Document().append("type", "number"))))));
collection.createSearchIndexes(Collections.singletonList(indexTwo));
}

Case 3: Creating an index to test the autocomplete capability

The autocomplete feature of Atlas Search allows you to text with incomplete words and sentences. The fields that you intend to query with the autocomplete operator must be indexed with the autocomplete data type in the collection's index definition. To learn more about the feature, you can follow the documentation for autocomplete in Atlas Search.

Using Atlas UI

After following the same steps to create field mapping with data type as autocomplete for fullplot, specify the details as below and create the index.

Using Atlas CLI

To create the same index with Atlas CLI, update the index.json file as:

{
  "name": "testIndex03",
  "database": "sample_mflix",
  "collectionName": "movies",
  "mappings": {
    "dynamic": true,
    "fields": {
      "fullplot": {
        "foldDiacritics": false,
        "maxGrams": 7,
        "minGrams": 3,
        "tokenization": "nGram",
        "type": "autocomplete"
      }
    }
  }
}

As mentioned in the above screenshot, to have autocomplete tokenisation set for Atlas Search, you will have to see certain parameters to create the tokens.

For example, in the above JSON, the foldDiacritics set to false returns only results that match the strings with or without diacritics in the query. For instance, a search for cafè returns results only with the characters in the word cafè.

The maxGrams and minGrams are attributes for nGram tokenisers which determine the number of characters to include in the longest and shortest tokens created respectively.

Use the same command as above to create the index.

Using Spring Boot application

Use the code snippet below to create the same index programmatically in Spring.

try (MongoClient mongoClient = MongoClients.create(uri)) {
MongoDatabase database = mongoClient.getDatabase("sample_mflix");
MongoCollection<Document> collection = database.getCollection("movies");
SearchIndexModel indexThree = new SearchIndexModel("testIndex03",
                    new Document("mappings",
                    new Document("dynamic",false).append("fields",
                    new Document().append("fullplot",
Arrays.asList(new Document().append("type", "stringFacet"),
        new Document().append("type", "string"),
        new Document().append("type", "autocomplete")
        .append("tokenization", "nGram")
           .append("minGrams", 3)
        .append("maxGrams", 7)
        .append("foldDiacritics", false)))
             .append("title", new Document().append("type", "string")))));
collection.createSearchIndexes(Collections.singletonList(indexThree));
}

Case 4: Creating a search index to make use of analyzers

Atlas Search allows you to create analyzers to control how it turns a string field's contents into searchable terms.

The methods below will help you understand how to create indexes for using these analyzers.

Using Atlas UI

Follow the same steps that you have been following in the above cases. The below screenshot will help you understand how you can add analyzers using the UI.

Once done, create the index.

Using Atlas CLI

Update the index.json as below:

{
  "name": "testIndex04",
  "database": "sample_mflix",
  "collectionName": "movies",
  "analyzer": "lucene.english",
  "searchAnalyzer": "lucene.english",
  "mappings": {
    "dynamic": true,
    "fields": {
      "fullplot": {
        "type": "string"
      }
    }
  },
  "synonyms": [
    {
      "analyzer": "lucene.english",
      "name": "synonymName",
      "source": {
        "collection": "test_synonyms"
      }
    }
  ]
}

And later, use the same command to create the index.

atlas clusters search indexes create --clusterName <clusterName> --file index.json

Using Spring Boot application

To create the above index, use the below code in your Spring application.

try (MongoClient mongoClient = MongoClients.create(uri)) {
MongoDatabase database = mongoClient.getDatabase("sample_mflix");
MongoCollection<Document> collection = database.getCollection("movies");
SearchIndexModel indexFlour = new SearchIndexModel("testIndex04",
                new Document("mappings", new Document()
                    .append("dynamic", true)
                    .append("fields", new Document()
                    .append("fullplot", new Document()
                    .append("analyzer", "lucene.english")
                    .append("type", "string"))))
                    .append("synonyms", List.of(new Document()
                    .append("analyzer", "lucene.english")
                            .append("name", "synonymName")
                            .append("source", new Document()
                            .append("collection", "test_synonyms")))));
collection.createSearchIndexes(Collections.singletonList(indexThree));
}

The code for creating all the indexes programmatically is available at the GitHub repository.

Deleting the search indexes

After the indexes are created, and you wish to drop those indexes, make sure you drop the indexes using one of the following methods:

Using UI: Click on the index on the UI and select "Delete Index" from the list.

Using Atlas CLI: Follow the steps below to create all the indexes and index IDs and use the command to delete the index.

atlas clusters search indexes list --clusterName <clusterName> --db sample_mflix --collection movies
atlas clusters search indexes delete <index ID> --clusterName <clusterName>

Using Spring Boot application: Use the below command to delete all the indexes created.

collection.dropSearchIndex("<indexName>");

Conclusion

Creating Atlas Search indexes using the Atlas UI, CLI, and Spring Boot application provides a comprehensive understanding of how to leverage MongoDB's powerful search capabilities. The Atlas UI offers an intuitive and visual approach, perfect for those who prefer a graphical interface. The CLI gives more control and scripting capabilities, making it ideal for automation and integration into development workflows. Integrating search index creation in a Spring Boot application showcases the seamless integration of MongoDB Atlas with Java-based applications, enabling developers to build robust and scalable search functionalities.

By mastering these methods, you can enhance your applications with advanced search features, ensuring a better user experience and improved data retrieval performance. Whether you are a beginner or an experienced developer, combining UI, CLI, and programmatic approaches provides a flexible and comprehensive toolkit for managing search indexes in MongoDB Atlas.

If you have any questions or need further assistance, please reach out to the MongoDB Community Forums and refer to the official documentation and MongoDB University tutorials for more in-depth information and guidance.

Building REST APIs with API Platform, Symfony, and MongoDB

aasawari sahasrabuddhe — Sat, 14 Feb 2026 05:12:21 +0000

Today's web applications rely on large datasets and require real-time database interaction. Developers often face the challenge of efficiently managing and scaling CRUD (Create, Read, Update, Delete) operations while maintaining flexibility, performance, and security. However, building a standard API often comes with significant challenges: documenting endpoints, mapping them to the database, handling data transformation, and ensuring validation—all while maintaining performance, scalability, and security.

Building an application with API Platform provides a robust, flexible, and user-friendly solution for creating modern APIs. When seamlessly integrated with MongoDB, it empowers developers to efficiently handle CRUD operations while maintaining scalability and ease of use.

In this tutorial, we will use API Platform with Symfony to build REST APIs that perform CRUD operations on the MongoDB database. To connect the application with MongoDB, we will use MongoDB Atlas.

Prerequisites

A free Atlas cluster—register to create your first free cluster
Docker installed

Creating a Symfony project

To start with the Symfony project using API Platform, follow the steps outlined below:

Create the template project, which generates all the necessary files for you. To do so, generate a GitHub repository with your choice of name using the api-platform repository template. You can refer to the screenshot below to fill in the entries.

Once the repository is created, you can clone it using the command below.

git clone <URL to your repository>

Once you have the code on your local machine, we will edit the application to connect with MongoDB.

To learn more, you can follow the steps mentioned in the Getting Started with API Platform documentation for Symfony.

In the next section, we'll understand how to connect your application to the MongoDB Atlas cluster and perform the CRUD operations on the collections inside the cluster.

Connecting your application with MongoDB Atlas

After you have your sample application running correctly, the next step is to connect with MongoDB Atlas. To do so, we will first need to create a free Atlas cluster and get the connection string.

To get the connection string, click on Connect and then select the appropriate driver with the correct version. You will see a screen like the one below; copy the connection string and keep it safe with you.

Once you have the connection string, the next step is to update the Dockerfile and install the PHP extensions. The Dockerfile to install the extensions is available inside the api/ folder.

Update the file with the code below to install PHP extensions.

Add the below code changes to the Dockerfile you will need to update:

RUN apt-get update && apt-get install --no-install-recommends -y \
    libcurl4-openssl-dev \
    libssl-dev \
    && pecl install mongodb \
    && docker-php-ext-enable mongodb

After the update, run the command from the root folder of the project to install the extensions. In this case, go to .

docker compose build --no-cache

Update the .env file with the connection string and database name.

MONGODB_URL=<Atlas URI>
MONGODB_DB=Test

Update the compose.yaml file with the connection string as:

services:
  php:
    image: ${IMAGES_PREFIX:-}app-php
    depends_on:
      - pwa
    environment:
      MONGODB_URL: <Atlas URI>

After the extensions are installed, we need to start the containers and install the ODM bundle.

docker compose up --wait

Once the containers are up and ready, execute the below commands to install the ODM bundle.

docker compose exec php \
 composer require doctrine/mongodb-odm-bundle api-platform/doctrine-odm

The mongodb-odm-bundle is a bundle (a modular package of code) that integrates MongoDB ODM into Symfony. This library provides a PHP object mapping functionality for MongoDB.

Performing CRUD operations

Once you are all set with making the MongoDB Atlas connections, the next step is to create REST APIs to perform CRUD operations.

In this tutorial, we are using a simple collection named Restaurants, which will have the following field values:

{
    "name": "The Gourmet Spot",
    "address": {
      "building": "123",
      "street": "Elm Street",
      "zipcode": "12345"
      },
    "borough": "Manhattan",
    "cuisine": "Italian"
}

Once the document structure is decided, the next step is to create the Document and the Controller class.

The Document class is created at api/src/Document/Restaurant.php.

Copy the below code in the Restaurant.php class. This class has all the field values with all the getter and setter methods.

<?php

namespace App\Document;

use ApiPlatform\Metadata\ApiResource;
use App\Repository\RestaurantRepository;
use Doctrine\ODM\MongoDB\Mapping\Annotations\Document;
use Doctrine\ODM\MongoDB\Mapping\Annotations\Field;
use Doctrine\ODM\MongoDB\Mapping\Annotations\Id;

#[ApiResource]
#[Document(collection: 'restaurants')]
class Restaurant
{
    #[Id]
    public string $id;

    #[Field]
    public string $name;

    #[Field]
    public array $address;

    #[Field]
    public string $borough;

    #[Field]
    public string $cuisine;
}

The Address.php will look like:

<?php

namespace App\Document;

use Doctrine\ODM\MongoDB\Mapping\Annotations\EmbeddedDocument;
use Doctrine\ODM\MongoDB\Mapping\Annotations\Field;

#[EmbeddedDocument]
class Address
{
    #[Field]
    public string $building;

    #[Field]
    public string $street;

    #[Field]
    public string $zipcode;
}

Once the code is all set, run the below command to run the complete application.

HTTP_PORT=8080 HTTPS_PORT=8443 docker-compose up

Testing the CRUD operations

The next step is to access the access APIs that have been created. The below URI takes you to the swagger of the API platform to test the REST API calls.

https://localhost:8443/docs

API Platform natively supports the Open API (formerly Swagger) API documentation format. It also integrates a customized version of Swagger UI, a nice tool to display the API documentation in a user-friendly way.

This page at the below URI will look like the following:

Let's test these REST APIs.

Create

To test the CREATE API, go to the POST method and place the JSON as:

{
    "name": "The Gourmet Spot",
    "address": {
      "building": "123",
      "street": "Elm Street",
      "zipcode": "12345"
      },
   "borough": "Manhattan",
   "cuisine": "Italian"
}

Click on "Try it out" and you will see the below document has been inserted into the collection:

To verify, navigate to the Atlas cluster and check if the data has been inserted in the test.Restaurants collection. The screenshot below shows that the data has been inserted into the database.

Read

To get all the documents from the collection, you can simply use the GET API to get all the documents. To get a specific document from the collection, run the GET API as specified.

Update

There are two operations to update an existing document. PUT replaces the full document and PATCH will update only the properties that are sent. Usually, only PATCH is used, which is why the PUT operation is disabled by default. For more information, you can look into the documentation for API Platform Operations.

To test this API, we have updated the above JSON document as:

{
    "name": "The Gourmet Spot",
    "address": {
      "building": "123",
      "street": "Elm Street",
      "zipcode": "12345"
      },
    "borough": "New York",
    "cuisine": "Spanish"
}

The API results in:

The document is also updated in the Atlas cluster.

Delete

Finally, to delete specific restaurant information with an _id, we run the API call as:

The above tests cover the basic CRUD operations: Create, Read, Update, Delete. But the API platform goes way beyond that. It has a ton of features that let you build more powerful and dynamic APIs with minimal work.

Let's see each of these in detail in the next section.

Beyond CRUD with API Platform

The API platform simplifies creating and enforcing validations so your data integrity rules are applied consistently without having to write a lot of custom code. And it's great at advanced search too, so you can execute complex queries with ease. It also allows you to apply filters, perform regex validations, and much more.

Performing validations on the field

If you wish to put validations on the field to be required values, we set the field values as #[Assert\NotBlank] before the field values. For example, in the code below, we have marked the name, borough, and cuisine as the required values.

class Restaurant
{
    #[Id]
    public string $id;

    #[Field]
    #[Assert\NotBlank]
    #[Assert\Length(max: 255)]
    public string $name;

    #[EmbedOne(targetDocument: Address::class)]
    #[Assert\Valid]
    public ?Address $address;

    #[Field]
    #[Assert\NotBlank]
    public string $borough;

    #[Field]
    #[Assert\NotBlank]
    public string $cuisine;
}

As a result, if a request is sent with any of the missing values, an HTTP error will be returned. The screenshot below shows an example of a name missing from the POST request.

We need to add the code to the Validators to add this validation. This code should be available inside the api/src/Validator/Constraints/ folder.

<?php

namespace App\Validator\Constraints;

use Symfony\Component\Validator\Constraint;
use Symfony\Component\Validator\ConstraintValidator;

final class MinimalPropertiesValidator extends ConstraintValidator
{
    public function validate($value, Constraint $constraint): void
    {
        if (array_diff(['name', 'cuisine', 'bourough'], $value)) {
            $this->context->buildViolation($constraint->message)->addViolation();
        }
    }
}

And:

<?php

namespace App\Validator\Constraints;

use Symfony\Component\Validator\Constraint;

#[Attribute]
class MinimalProperties extends Constraint
{
    public $message = 'The product must have the minimal properties required ("name", "cuisine", "bourough")';
}

This code defines a custom validation logic in Symfony. The MinimalPropertiesValidator class is responsible for validating that an array contains the required keys: name, cuisine, and borough.

The validate method checks if any of these keys are missing using array_diff, and if the validation fails, it triggers a violation with an error message.

The MinimalProperties class acts as the custom constraint, with its message property holding the error text displayed upon failure.

Similarly, if you wish to add the validator for the ZIP Code provided in the Address field values, add the below code in the api/src/Validator/Constraints/ folder as:

<?php

namespace App\Validator\Constraints;

use Symfony\Component\Validator\Constraint;
use Symfony\Component\Validator\ConstraintValidator;

final class ValidZipcodeValidator extends ConstraintValidator
{
    public function validate($value, Constraint $constraint): void
{
        if (!$constraint instanceof ValidZipCode) {
            throw new InvalidArgumentException(sprintf('Expected instance of %s, got %s.', ValidZipCode::class, get_class($constraint)));}

        if (!preg_match('/^[0-9]{5}$/', $value)) {
            $this->context->buildViolation($constraint->message)
                ->setParameter('{{ value }}', $value)
                ->addViolation();}
    }
}

And:

<?php

namespace App\Validator\Constraints;

use Symfony\Component\Validator\Constraint;

#[Attribute]
class ValidZipCode extends Constraint
{
    public $message = 'The zipcode "{{ value }}" is not valid. It must be exactly 5 digits.';
}

In the above code, ValidZipcodeValidator creates the validation that the ZIP Code can only be numeric and only five characters will be allowed. For any other ZIP Code, it should throw the error as mentioned in the ValidZipCode class.

You also need to declare the function in the Address.php as:

#[Field]
#[ValidZipCode]
public string $zipcode;

To test this, we can send the POST request as:

{
    "name": "Dim Sum Express",
    "address": {
      "building": "404",
      "street": "Chinatown Blvd",
      "zipcode": "abcnn"
    },
    "borough": "Manhattan",
    "cuisine": "Chinese"
}

The above request should result in an HTTP error with code 422 and a message saying:

The zipcode \"abcnn\" is not valid. It must be exactly 5 digits

The below screenshot displays the error message with the POST request.

Adding filters using API Platform

The API platform allows you to apply filters and sort criteria on the collections. The search filter supports exact, partial, start, end, and word_start matching strategies. You can read more about filters from the API platform documentation on search filters.

In our case, we will apply search filters to the name and the cuisine fields using the below code inside the Document class.

#[ApiFilter(
    SearchFilter::class,
    properties: [
        'name' => 'ipartial',  // The "ipartial" strategy will use a case-insensitive partial match
        'cuisine' => 'exact',  // The "exact" strategy will use an exact match
    ])
]

As the comment suggests, we have a partial filter that's case-sensitive for the name, and an exact match filter on the cuisine fields.

To test this, we have sample data already being stored inside the collection as:

db.restaurants.find()
[
  {
    _id: ObjectId('6750aa7acda8e992af0c97b4'),
    name: 'The Gourmet Spot',
    address: { building: '123', street: 'Elm Street', zipcode: '12345' },
    borough: 'Manhattan',
    cuisine: 'Italian'
  },
  {
    _id: ObjectId('6750b8406868c9f4fb012be5'),
    name: 'Burger Bliss',
    address: { building: '789', street: 'Main Street', zipcode: '54321' },
    borough: 'Queens',
    cuisine: 'American'
  },
  {
    _id: ObjectId('6750b8516868c9f4fb012be8'),
    name: 'Curry Delight',
    address: { building: '202', street: 'Spice Lane', zipcode: '45678' },
    borough: 'Staten Island',
    cuisine: 'Indian'
  },
  {
    _id: ObjectId('6750b85e6868c9f4fb012beb'),
    name: 'Pasta Paradise',
    address: { building: '303', street: 'Olive Way', zipcode: '11223' },
    borough: 'Manhattan',
    cuisine: 'Italian'
  },
  {
    _id: ObjectId('6750b86e6868c9f4fb012bee'),
    name: 'Pizza Kingdom',
    address: { building: '606', street: 'Pizza Lane', zipcode: '77889' },
    borough: 'Queens',
    cuisine: 'Italian'
  }
]

Now, to apply the search filter, we send the GET request with the cuisine name as Italian and we should see all restaurant with cuisine: 'Italian'.

Similarly, we send a GET request with a partial name as "name": "Pasta...", and we should have a restaurant with the name "Pasta Paradise."

You can create more API calls based on the requirement by extending the code available in the GitHub repository and following the API Platform documentation.

Conclusion

In conclusion, we've seen how API Platform lets you quickly create a REST API to perform CRUD operations on a MongoDB database. This framework also lets you add features to the API, such as data validation and query filters, while keeping the code highly comprehensible and scalable. Developers can work in a local environment using Docker and Atlas.

The tutorial also demonstrates how to establish the connection, configure the environment, and perform basic CRUD operations using a simple example, highlighting the flexibility and ease of working with Symfony's API Platform.

To explore more, consider diving into the advanced features of API Platform, optimizing MongoDB queries, or experimenting with additional CRUD operations to meet your specific application needs. If you wish to learn more, you can visit the documentation for API Platform and MongoDB.

For further questions, please reach out to the MongoDB Community Forum, and to learn more, explore the MongoDB Developer Center for more interesting articles.

Building Quarkus Application with MongoDB and Panache

aasawari sahasrabuddhe — Sat, 14 Feb 2026 04:57:40 +0000

Building applications with frameworks and libraries always makes the job simpler. And who doesn't like a simple life when it comes to building complicated applications? When it comes to Java applications, choosing Spring Data as the framework helps you reduce boilerplate code for setting up the configurations. Similar to Spring, to build Quarkus applications, you can make use of Panache. Panache is a Quarkus-specific library that simplifies the development of your Hibernate-based persistence layer.

Panache in Quarkus simplifies data access by minimizing boilerplate with built-in CRUD operations and type-safe queries. It supports both the Active Record and Repository patterns, allowing flexibility in architecture. Panache is tightly integrated with Quarkus, leveraging fast startup times and a low memory footprint, making it ideal for cloud-native and serverless environments. It also provides easy pagination, supports dynamic and named queries, and works seamlessly with Hibernate ORM and JPA, enhancing productivity while keeping code clean and efficient.

In this tutorial, we will be making a Quarkus application with Panache to perform some basic CRUD with aggregations to show the efficiency of working with Panache. The API allows you to perform basic CRUD operations like adding, updating, finding, and deleting books. It also supports aggregation to the group and counts books by genre.

Prerequisites

A free Atlas cluster. You can create your first Atlas cluster for absolutely free!
Java version 21 and above. Click on Downloads for the latest version.
An IDE of your choice.
Maven or Gradle as per choice.

Setting up the project

Before we get into the actual implementation part of the APIs, let's consider two of the most important things.

You can create your free cluster by following the steps mentioned in the documentation or using an existing cluster.

Create a Quarkus project with Maven using the below command.

mvn io. quarkus:quarkus-maven-plugin:create \
    -DprojectGroupId=io.quarkus.platform \
    -DprojectArtifactId=quarkus-bom \
    -DclassName="com.example.BookResource" \
    -Dpath="/books"

Now, add the below dependencies to the pom.xml.

<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-arc</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-rest</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-rest-client-jackson</artifactId>
        <version>3.16.2</version>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-resteasy-reactive-jackson</artifactId>
        <version>3.15.1</version>
    </dependency>
    <dependency>
        <groupId>io.rest-assured</groupId>
        <artifactId>rest-assured</artifactId>
        <scope>test</scope>
    </dependency>

    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-mongodb-panache</artifactId>
    </dependency>

</dependencies>

Build the complete application and download the dependencies:

mvn clean install

Creating REST API endpoints

Once the project is set up, the next step is to add the API endpoints. In this tutorial, we will use the Book collection from the Atlas cluster. The model class in the Quarkus project will add the fields inside the collection, and the next step will be to perform operations on the collection.

The Book collection in the Atlas collection will look like the following:

{
_id: ..
title: ..
author: ..
genre: ..
year: ..
}

API endpoints

Insert one book

The first step will be to insert the documents inside the collection. To do so, we need to add the function in the resource class in the project. A resource class is a class that implements the PanacheRepository and provides methods to manipulate entities.

Add the below code to the resource class, which injects the repository class to implement the methods, and then create the POST call.

@Inject
BookRepository bookRepository;   
@POST
public Response addBook(Book book) {
    bookRepository.persist(book);
    return Response.status(Response.Status.CREATED).entity(book).build();
}

This would insert a simple document at a time inside the collection.

The BookRepository class with the below code:

import com.quarkusWithPanache.model.Book;
import io.quarkus.mongodb.panache.PanacheMongoRepository;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class BookRepository implements PanacheMongoRepository<Book> {
}

Bulk write

The insert method will insert the documents one by one inside the collection. If there are hundreds or thousands of documents, it will take a long time to insert the documents. To save time and resources with every call, the bulk write will insert all the documents in one go. To do so, add the below code, which will perform the bulk insert.

@POST
@Path("/bulk")
public Response bulkAddBooks(List<Book> books) {
    // Prepare documents for bulk write
    List<Document> documents = new ArrayList<>();
    for (Book book : books) {
        documents.add(new Document("title", book.title)
                .append("author", book.author)
                .append("genre", book.genre)
                .append("year", book.year));
    }
    getCollection().insertMany(documents);

    return Response.status(Response.Status.CREATED).entity(books).build();
}

The getCollection method returns the database and collection name from import com.mongodb.client.MongoCollection package.

Find all books

Once all the books are inserted inside the collection, the next step is to retrieve the documents from the collection. To get all the books, create the below API call as:

@GET
public List<Book> getAllBooks() {
    return bookRepository.listAll();
}

Find one book by ID

To retrieve a specific book from the collection based on the _id, the below API call would fetch a single document that matches the condition.

@GET
@Path("/{id}")
public Book getBookById(@PathParam("id") String id) {
    return bookRepository.findById(new ObjectId(id));
}

Delete book by ID

Similar to retrieving a single document from the collection, the delete one will delete the single document based on the matching _id. To do so, use the below-created API.

@DELETE
@Path("/{id}")
public Response deleteBook(@PathParam("id") String id) {
    boolean deleted = bookRepository.deleteById(new ObjectId(id));
    return deleted ? Response.noContent().build() : Response.status(Response.Status.NOT_FOUND).build();
}

Update a book

Finally, to update the document based on the _id value, use the below code with the updated field values.

@PUT
@Path("/{id}")
public Response updateBook(@PathParam("id") String id, Book book) {
    Book entity = bookRepository.findById(new ObjectId(id));
    if (entity == null) {
        return Response.status(Response.Status.NOT_FOUND).build();
    }
    entity.title = book.title;
    entity.author = book.author;
    entity.genre = book.genre;
    entity.year = book.year;
    bookRepository.update(entity);
    return Response.ok(entity).build();
}

Aggregation (genre count)

Apart from performing basic CRUD operations, if you wish to perform an aggregation operation, you can use the code as below. As an example, this aggregation will perform a genre field and count the genres.

@GET
@Path("/aggregate/genre-count")
public Response countBooksByGenre() {

    List<Document> pipeline = new ArrayList<>();
    pipeline.add(new Document("$group", new Document("_id", "$genre")
            .append("count", new Document("$sum", 1))));

    List<Document> result = getCollection()
            .aggregate(pipeline)
            .into(new ArrayList<>());

    return Response.ok(result).build();
}

Testing the API

To test the API, we can use the following cURL commands to interact with the server. Make sure the application is running on http://localhost:8080 before sending the requests.

Insert one book:

curl -X POST "http://localhost:8080/books" -H "Content-Type: application/json" -d '{                        
  "title": "Quarkus in Action",
  "author": "John Doe",
  "genre": "Programming",
  "year": 2023
}'

Bulk insert

curl -X POST http://localhost:8080/books/bulk \
   -H "Content-Type: application/json" \
   -d '[
        {
            "title": "The Midnight Library",
            "author": "Matt Haig",
            "genre": "Fiction",
            "year": 2020
        },
                {
            "title": "Sapiens: A Brief History of Humankind",
            "author": "Yuval Noah Harari",
            "genre": "Non-Fiction",
            "year": 2011
        },
        .......
    ]'

Find all books:

curl -X GET "http://localhost:8080/books" | jq

Find one book:

curl -X GET "http://localhost:8080/books/672f873b421eaa0c3e4da49f" | jq

Delete one book:

curl -X DELETE "http://localhost:8080/books/673f81b65750de0757a4bbfb" | jq

Update one book:

curl -X PUT "http://localhost:8080/books/672f856f421eaa0c3e4da49e" \
   -H "Content-Type: application/json" \
   -d '{
         "title": "Quarkus in Action",
         "author": "John Doe",
         "genre": "Programming",
         "year": 2021
       }'

Aggregation: Genre count

curl -X GET "http://localhost:8080/books/aggregate/genre-count" | jq

This would give the output for the count of all the genres.

The complete code for the application is available on the GitHub repository.

Conclusion

In this tutorial, we explored how to harness the power of Panache in a Quarkus application to simplify CRUD operations and implement aggregation queries. By leveraging Panache's built-in functionalities, we reduced boilerplate code, making development faster and more efficient. From inserting single and multiple documents to retrieving, updating, and deleting them, we demonstrated how Panache integrates seamlessly with MongoDB to handle data operations. Additionally, we showcased how to perform aggregations, such as counting books by genre, to extract meaningful insights from data.

Panache's ability to work with Hibernate ORM and JPA, combined with Quarkus's low memory footprint and fast startup times, makes it an ideal choice for building cloud-native, serverless, and highly performant applications. With Panache, developers can focus on business logic while maintaining clean and readable code.

If you wish to learn more about MongoDB and its concepts, like vector search, read our tutorial on MongoDB Vector Search with Quarkus on the MongoDB Developer Center, and find more interesting topics. For any questions related to the above or MongoDB, don't forget to pay a visit to the MongoDB community forum and be a part of an interesting discussion.

Building a Quarkus Application to Perform MongoDB Vector Search

aasawari sahasrabuddhe — Sat, 14 Feb 2026 04:52:43 +0000

Traditional keyword-based search methods often fall short of delivering relevant results in a world inundated with data. Vector search is a revolutionary approach that allows applications to understand context and meaning, enabling smarter, more intuitive searches. In this article, we'll explore how to harness the combined power of Quarkus, a lightweight and high-performance Java framework, and MongoDB, a flexible document database, to implement vector search seamlessly.

We will get into the fundamentals of vector search, covering how it differs from traditional search methods and why it's essential for modern applications. We will learn about generating vector embeddings from your data, setting up a robust search engine, and optimising performance—all while leveraging the speed and efficiency of Quarkus.

Whether you're building a recommendation system, improving content discovery, or simply enhancing the user experience, this guide will equip you with the knowledge and tools to unlock the true potential of your search capabilities. Join us on this journey to revolutionize how users find and engage with information!

Understanding vector search

In the past, traditional search methods focused primarily on exact keyword matching or, at best, incorporated fuzzy search techniques. However, the modern digital landscape demands far more than just fuzzy search capabilities. Today's developers are seeking advanced search solutions that offer semantic understanding, full recommendation engines, and AI-driven chatbots through natural language processing (NLP).

The solution to these evolving needs lies in MongoDB's Vector Search capability. This cutting-edge technology goes beyond simple keyword matching, providing a deeper understanding of user intent and context. As the demand for smarter, more intuitive search experiences grows, adopting vector search becomes essential for developers and businesses aiming to elevate user experience and engagement. With MongoDB's vector search, you can build highly responsive and intelligent search systems that keep pace with modern application requirements.

How does vector search work?

MongoDB's vector search works on the concept of vector representations. The vector representation in AI is a method of transforming data into vectors so that machine learning algorithms can process and understand it. These vectors capture semantic relationships; for example, words with similar meanings will be positioned closer together in the vector space.

The vector search performs the similarity measures using techniques like Euclidean, Cosine Similarity, and Dot product calculations to assess how closely related two vectors are.

What is Gemini AI

Gemini AI is a suite of next-generation artificial intelligence models developed by Google DeepMind, intended to compete with advanced AI systems like OpenAI's GPT-4. It focuses on various AI capabilities, including natural language understanding, reasoning, and generating creative outputs.

The Gemini AI models are designed to be used across different Google services and integrated into products like Google Search, Google Workspace, and Google Cloud. They are known for improving interactive AI capabilities, making tasks such as conversation, content generation, and problem-solving more intuitive and human-like.

In this tutorial, we will be utilising the Gemini AI key to generate the embeddings for the fields and also for the query being sent for performing the vector search.

Pre-requisites

Here's what you will need to follow along:

A free-tier Atlas cluster—if you don't have one already, register for a free cluster now
Your sample data pre-loaded into the collection
Java 17 or above
Gemini AI key—create your free Gemini key

Building a Quarkus project

Quarkus, known for its lightweight framework and robust extensions, is an excellent choice for building high-performance applications. When paired with MongoDB, a scalable document-oriented database, it enables the creation of advanced search solutions that surpass traditional keyword-based methods, offering a more context-aware and intuitive search experience.

In this tutorial, we will work with the listings collection from the AirbnB database to explore generating embeddings and conducting vector searches.

Specifically, we'll cover two main functionalities:

Generating vector embeddings for the "description" field in each document within the collection.
Creating a vector index to perform efficient vector searches across the dataset.

The complete code for the project is available on the GitHub repository. You can start by cloning the project and adding your details to the application.properties file to run the application.*

Generating the vector embeddings using the Gemini API key

The first step is to generate the vector embeddings for a specific field, which contains large texts and is also in different languages. To create these embeddings, we have the ListingResource.java file, which has the REST call to generate embeddings.

We are using a simple embedding model as text-embedding-004. The "text-embedding-004" model is one of the embedding models provided by Gemini AI, which is designed to handle various AI tasks, such as text embedding for semantic search, recommendation systems, and natural language processing.

The number of embeddings generated by the text-embedding-004 model in Gemini AI depends on the length of the input text and how the model is configured to handle it. Typically, embeddings are produced for each token (words or subwords) in the text. The embedding model will generate a fixed-length numerical vector for each token or sequence of tokens. In this example, the total number of embeddings generated is 768.

As mentioned in the ListingResource.java class:

@POST  
@Path("/generate-embeddings")  
public Response generateEmbeddings() {  
   listingService.generateAndStoreEmbeddings();  
   return Response.ok("Embeddings generated and stored").build();  
}

The ListingService.java class is where the embeddings are being performed in batches. This is to avoid making repetitive calls to the Gemini API to generate embeddings for each document.

The batch process is followed by BulkWrite, which first generates all description fields and then makes the API call to Gemini AI.

public void generateAndStoreEmbeddings() {  
   MongoCollection<Document> listingsCollection = mongoClient.getDatabase("sample_airbnb").getCollection("listingsAndReviews");
   int processedDocuments = 0;  
   long totalDocuments = listingsCollection.countDocuments();
   while (processedDocuments < totalDocuments) {  
       List<Document> documents = listingsCollection.find()  
               .skip(processedDocuments)  
               .limit(BATCH_SIZE)  
               .into(new ArrayList<>());  
       List<UpdateOneModel<Document>> bulkUpdates = new ArrayList<>();
       for (Document document : documents) {  
           String description = document.getString("description");  
           List<Double> embeddings = geminiClient.getEmbedding(description);
           if (embeddings != null) {  
               UpdateOneModel<Document> updateModel = new UpdateOneModel<>(  
                       Filters.eq("_id", document.getString("_id")),  
                       Updates.set("embeddings", embeddings)  
               );  
               bulkUpdates.add(updateModel);  
           }  
       }  
       if (!bulkUpdates.isEmpty()) {  
           listingsCollection.bulkWrite(bulkUpdates, new BulkWriteOptions().ordered(false));  
       }
       processedDocuments += documents.size();  
       System.out.println("Processed " + processedDocuments + " out of " + totalDocuments + " documents.");  
   }
   System.out.println("Embedding generation complete for all documents.");  
}

The next step of generating the embedding is creating the Gemini request and returning the list of embeddings. This is carried through the GeminiAIGatewayImpl.java class.

package com.example.vectorsearch.gateway;
import com.example.vectorsearch.config.GeminiConfig;  
import com.example.vectorsearch.request.GeminiRequest;  
import com.fasterxml.jackson.core.JsonProcessingException;  
import com.fasterxml.jackson.databind.ObjectMapper;  
import io.quarkus.rest.client.reactive.QuarkusRestClientBuilder;  
import jakarta.enterprise.context.ApplicationScoped;  
import jakarta.inject.Inject;  
import jakarta.ws.rs.WebApplicationException;  
import org.slf4j.Logger;  
import org.slf4j.LoggerFactory;
import java.net.URI;  
import java.util.List;
@ApplicationScoped  
public class GeminiAIGatewayImpl implements GeminiAIGateway {
   @Inject  
   GeminiConfig geminiAIConfig;
   private static final Logger LOGGER = LoggerFactory.getLogger(GeminiAIGatewayImpl.class);
   @Override  
   public List<Double> getEmbedding(String input) {  
       ObjectMapper objectMapper = new ObjectMapper();
       var geminiAIGateway = QuarkusRestClientBuilder.newBuilder()  
               .baseUri(URI.create*(geminiAIConfig.getGeminiAIUrl() + "?key=" + geminiAIConfig.getApiKey()))  
               .build(GeminiClient.class);
       GeminiRequest request = new GeminiRequest(  
               geminiAIConfig.getModel(),  
               new GeminiRequest.Content(List.of(new GeminiRequest.Part(input)))  
       );  
       try {  
           String jsonRequest = objectMapper.writeValueAsString(request);  
           var embedding = geminiAIGateway.embedding(jsonRequest);
           return embedding.getEmbedding().getValues();  
       } catch (WebApplicationException e) {  
           LOGGER.error("Error from Gemini AI: {}", e.getResponse().readEntity(String.class));  
           throw e;  
       } catch (JsonProcessingException e) {  
           throw new RuntimeException(e);  
       }  
   }  
}

To run this API method, run the below command and wait until all the embeddings are generated in the collection for the field.

curl -X POST http://localhost:8080/api/listings/generate-embeddings

Note: The generated embedding will take time to generate and store inside the collection. In the above method, the processing happens in batches.

Creating the vector search index

After the embeddings have been generated and stored inside the collection, the next step is to create the vector index. To create this index, you can go to the created Atlas cluster and then click on Atlas Search and perform the steps below:

Step 1: Click on the Search Indexes tab of the Atlas UI screen as shown below:

Step 2: Click on Create Vector Search Index on the screen.

Step 3: Click on JSON Editor under the Atlas Vector Search section and click Next.

Step 4: Select the database and collection name and create the vector index with the following JSON.

{  
 "fields": [  
   {  
     "numDimensions": 768,  
     "path": "embeddings",  
     "similarity": "euclidean",  
     "type": "vector"  
   }  
 ]  
}

Performing the vector search

After generating the embedding for the desired field and creating the vector search index, the last step is to perform the semantic search. For example, you might wish to look for:

Hotels that are recommended for a romantic stay.
Places that have beachside views.
Places that one would enjoy with kids.

To perform the searches with such an example, you need to perform the vector search.

The first step to do this is creating an embedding for the text being sent as a part of the request.

To do so, we will use the same embedding technique mentioned in the ListingService.java class.

public void performVectorSearch(String query) {  
   MongoCollection<Document> collection = mongoClient.getDatabase("sample_airbnb").getCollection("listingsAndReviews");
   List<Double> queryEmbeddings = geminiClient.getEmbedding(query);  
   String indexName = "vector_index";  
   int numCandidates = 150;  
   int limit = 10;
   List<Document> pipeline = Arrays.asList(  
           new Document("$vectorSearch",  
                   new Document("index", indexName)  
                           .append("path", "embeddings")  
                           .append("queryVector", queryEmbeddings)  
                           .append("numCandidates", numCandidates)  
                           .append("limit", limit)  
           ),  
           new Document("$project",  
                   new Document("_id", 0)  
                           .append("name", 1)  
                           .append("listing_url", 1)  
                           .append("description", 1)  
                           .append("price", 1)  
           ),  
           new Document("$limit", 5));
   collection.aggregate(pipeline)  
           .forEach(doc -> System.out.println(doc.toJson()));  
}

The next step is to use the $vectorsearch aggregation stage. This stage performs the semantic search on the data. It searches a vector index (a specialized index that stores vector embeddings) for the closest matching vectors based on a given query vector.

For this example, we are projecting only a few details of the hotel and limiting the response to five.

To run the API, use the below command:

curl -X GET "http://localhost:8080/api/listings/perform-vector-search?query=Hotels%20that%20are%20recommended%20for%20romantic%20stay" | jq

Note: " | jq" has been used in the cURL command to display the results in the JSON format. It is recommended to download jq before using the above cURL command.

This will give you the following response:

[
  {
    "listing_url": "https://www.airbnb.com/rooms/15266254",
    "name": "The Manhattan Club in the heart of midtown!!!!",
    "description": "My place is good for couples, solo adventurers, and business travelers.",
    "price": 305.00
  },
  {
    "listing_url": "https://www.airbnb.com/rooms/14261122",
    "name": "Cute Condo in Mile-End, sleeps 2",
    "description": "You'll love my place because of the location. My place is good for couples, solo adventurers, and business travellers.",
    "price": 70.00
  },
  {
    "listing_url": "https://www.airbnb.com/rooms/13609188",
    "name": "Habitacion al lado de Sagrada Familia",
    "description": "Lugares de interés: La Paradeta Sagarada Familia, FCB Official Point, Basílica de la Sagrada Família, Starbucks, . Mi alojamiento es bueno para parejas y aventureros.",
    "price": 45.00
  },
  {
    "listing_url": "https://www.airbnb.com/rooms/13748059",
    "name": "Studio for the 2016 Olympics",
    "description": "My space is good for couples, business travelers and individual adventures.",
    "price": 298.00
  },
  {
    "listing_url": "https://www.airbnb.com/rooms/11130156",
    "name": "Double Room",
    "description": "Literally just across the street is the world famous Cagaloglu Hammam featured in 1,000 Places to See Before You Die by Patricia Schultz. The hotel is tucked away on a quiet street and is just a few minutes walk to some of the world's famous sites,",
    "price": 359.00
  }
]

Another example that we can try is, "Stays that the kids would enjoy."

curl -X GET "http://localhost:8080/api/listings/perform-vector-search?query=Stays%20that%20the%20kids%20would%20enjoy" | jq

This would give the response:

[
  {
    "listing_url": "https://www.airbnb.com/rooms/13997910",
    "name": "Apartamento de luxo em Copacabana - 4 quartos",
    "description": "Meu espaço é bom para casais, viajantes de negócios e famílias (com crianças).",
    "price": 11190.00
  },
  {
    "listing_url": "https://www.airbnb.com/rooms/14571224",
    "name": "Alugo Quarto Para Temporada de Olimpiadas",
    "description": "Meu espaço é bom para casais, viajantes de negócios e famílias (com crianças).",
    "price": 798.00
  },
  {
    "listing_url": "https://www.airbnb.com/rooms/13927230",
    "name": "Casa completa p olimpíadas com serviços incluído",
    "description": "Você vai amar meu espaço por causa de a área externa, da piscina, o bairro com vários bares e diversões, o condomínio seguro com porteiro, a iluminação, a cama confortável e a cozinha grande. Meu espaço é bom para famílias (com crianças) e grandes grupos. Podendo se contratar junto também serviços de cozinheira, garçons e bartender. Podendo se contratar também com alimentação. Tudo para se sentir em casa e não se preocupar com nada. Consultar valores extras.",
    "price": 601.00
  },
  {
    "listing_url": "https://www.airbnb.com/rooms/13617872",
    "name": "Amor do Rio",
    "description": "Você vai amar meu espaço por causa de o aconchego e a localização. Meu espaço é bom para casais, aventuras individuais, viajantes de negócios, famílias (com crianças) e grandes grupos.",
    "price": 116.00
  },
  {
    "listing_url": "https://www.airbnb.com/rooms/13993059",
    "name": "Ventanas Nature Resort  ambiente familiar",
    "description": "Meu espaço é perto de transporte público, restaurantes e refeições, atividades para famílias, , praia. Você vai amar meu espaço por causa de a localização, as pessoas, o ambiente e o bairro. Meu espaço é bom para casais, famílias (com crianças), grandes grupos e amigos peludos (animais de estimação).",
    "price": 899.00
  }
]

There are several additional examples you can explore by adjusting the query to perform a vector search tailored to your needs.

Conclusion

Integrating vector search with MongoDB and Quarkus provides a powerful, scalable, and efficient solution for modern search needs. By leveraging Quarkus's lightweight framework and MongoDB's advanced search capabilities, developers can easily implement vector search to provide more context-aware and meaningful search experiences. With the ability to process natural language queries and return semantically relevant results, vector search opens new possibilities for building intelligent applications—whether for recommendation engines, content discovery, or personalized user interactions. This approach not only enhances performance but also significantly improves user satisfaction by making search results more intuitive and aligned with their true intent.

If you have further questions, please reach out to the MongoDB Community Forums and visit the content on the Developer Center to learn about more such cool concepts.

Why Unstructured Data is a Good Fit for Java

aasawari sahasrabuddhe — Sat, 14 Feb 2026 04:46:32 +0000

As Java developers of the legacy application you have worked on, most of you must have spent a large part of the application development mastering relational databases, building schemas, and perfecting SQL queries. During those days, the data was limited and was easily mapped to the strict schema structures. But with the changing era, where data is valued as gold, it is growing exponentially and getting more unstructured.

Unstructured data refers to information that does not follow a predefined pattern or is not organised in a strict pattern. As said above, the unstructured data mostly has data in varied formats like multimedia data, CSVs, and many more. Storage of these in relational databases has been difficult because of the diverse formats. Therefore, we store them as JSONs, XMLs, etc. Learn more about unstructured data.

Why should you care as a Java developer? The enterprise applications built today have more unstructured data like texts for customer reviews, product images, and shipping details, and these are all within a single platform. Relational databases require complex designs to handle this, while MongoDB thrives in this scenario, making it easier for Java developers to work with such diverse data types.

How does MongoDB prove to be helpful with unstructured data?

In today's fast-paced world of agile development, where application requirements are constantly evolving, the challenge of managing rapidly growing unstructured data becomes significantly more manageable. This is largely because unstructured data doesn't need to conform to a rigid schema model, offering flexibility that is particularly beneficial when working with non-relational databases like MongoDB.

MongoDB's schemaless architecture allows developers to introduce new fields to documents or collections on the fly, without the need to overhaul an entire schema. This not only minimizes downtime but also speeds up the development process, enabling teams to adapt quickly to changing requirements.

In contrast, a strict schema model can demand substantial effort when continuous changes are required. By managing data in an unstructured format, MongoDB significantly reduces the overhead associated with these changes. Its dynamic schema is particularly well-suited for handling diverse data types such as images, tags, and metadata, making it an ideal choice for modern applications that handle a wide variety of content.

Moreover, MongoDB's built-in horizontal scalability allows developers to effortlessly scale out their applications as data volumes increase, ensuring that performance remains consistent even as the amount of unstructured data grows. For Java developers, this means they can handle large datasets efficiently while maintaining the agility needed to meet evolving business needs.

How do you work with unstructured data in Java?

Now, let's get back to the main objective of the article: Why should you as a Java developer use MongoDB as the database for your growing unstructured data?

When we talk about unstructured data, it is mostly stored in the JSON format, and so is data stored in MongoDB. It stores the data in a JSON-like format known as BSON, or Binary JSON, which is highly compatible with Java's POJO model.

This compatibility makes the mapping simpler. For example, let's say you have a customer class in your Java application that stores details for a specific customer.

public class Customer {
    private String id;
    private String name;
    private String email;
    // Constructors, getters, and setters
}

With the MongoDB Java driver, you can map the Customer class to a MongoDB document. Below is the example, where this mapping would be useful in inserting a new document.

public class CustomerRepository {
    private MongoCollection<Document> collection;
    public CustomerRepository() {
        MongoClient mongoClient = MongoClients.create("mongodb://localhost:27017");
        this.collection = mongoClient.getDatabase("mydatabase").getCollection("customers");
    }
    public void addCustomer(Customer customer) {
        Document doc = new Document("id", customer.getId())
                            .append("name", customer.getName())
                            .append("email", customer.getEmail());
        collection.insertOne(doc);
    }
}

And similarly, querying and updating the data will become simpler. By using the MongoDB Java driver, you can work directly with BSON documents in a way that naturally fits Java's POJO model.

The example above shows that MongoDB operations can be intuitive and simple even without using frameworks. Hence, this unstructured data is a good option for Java applications.

This mapping also proves to be helpful when operating on the subdocuments being created. For example, if the Customer also has details about their Orders it will be stored as:

public class Customer {
    private String id;
    private String name;
    private String email;
    private List<String> Orders;
    // Constructors, getters, and setters
}

Here, to fetch the orders, you do not need to perform complicated joins on multiple tables. MongoDB allows you to retrieve nested or related data directly from a document. To do so, you could use:

Customer customer = customerCollection.find(Filters.eq("_id", "customerId")).first();
if (customer != null) {
    List<Order> orders = orderCollection.find(Filters.in("_id", customer.getOrders())).into(new ArrayList<>());
    orders.forEach(order -> System.out.println(order.getProductName()));
} else {
    System.out.println("Customer not found");
}

MongoDB's aggregation framework also allows you to perform complex queries on large volumes of unstructured data. These operations are optimised and efficiently reduce the complex calculations of several joins.

MongoDB's Java driver provides builders to perform data manipulation and perform queries on the data. These builders simplify the process of creating complex MongoDB queries in Java by offering a clear, chainable API that resembles natural language, making the code easier to read and write.

Querying unstructured data in MongoDB with Java

In this section, we will provide practical examples of how MongoDB's Java driver helps you work with unstructured data, while also discussing how to utilise POJOs and builders. There are certain prerequisites you need to follow along, including the necessary setup and knowledge required for working with MongoDB and Java.

Pre-requisites

If you don't already have an Atlas cluster, get started for free.
Use the import mechanism to load the data given as productDetails.json into your Atlas cluster.
Update your MongoDB Java driver to version 5.1 or above.
Use Java version 17 or above.

How does unstructured data in MongoDB help in mapping POJOs?

Once you load the data into your Atlas cluster, your data should see the following structure, which is stored in BSON (Binary JSON) format:

{
  "_id": {"$oid": "66cc68309ff045b1b411b6ba"},
  "productName": "Wireless Mouse",
  "category": "Electronics",
  "price": 29.99,
  "stock": 150,
  "description": "Ergonomic wireless mouse with adjustable DPI settings.",
  "brand": "TechBrand",
  "images": [
    {
      "url": "https://example.com/images/wireless_mouse_1.jpg",
      "altText": "Wireless Mouse Top View"
    },
    {
      "url": "https://example.com/images/wireless_mouse_2.jpg",
      "altText": "Wireless Mouse Side View"
    }
  ],
  "features": "2.4 GHz wireless connectivity, Adjustable DPI from 800 to 1600, Compatible with Windows and macOS",
  "reviews": [
    {
      "customerId": {"$oid": "66cc67443921db64869bcf3d"},
     "rating": 4.5,
      "comment": "Great mouse, very comfortable to use!",
      "date": "2023-03-01T08:45:00Z"
    }
  ]
}

Since MongoDB stores data in a JSON-like format, POJOs are particularly useful. They align closely with MongoDB's document-oriented data model, allowing for a more natural and efficient development process.

For our example, we have a POJOs class created for Product, Image, and Reviews using model classes as Product.java, Image.java, and Reviews.java class respectively.

Having the fields mapped inside the POJOs makes the operations on this easy and efficient.

For example, in Main.java, the basic CRUD operations become simpler.

In the code below, we first try to make the connection with the MongoDB Atlas URI by placing the connection string in the environment variable. You can follow the documentation to get your connection string.

In the last part of the code, we perform some simple operations, like CRUD (Create, Read, Update, Delete), to operate on the database.

The complete code is given as:

public static void main(String[] args) {
   ConnectionString connectionString = new ConnectionString(System.getenv("mongodb.uri"));
   CodecRegistry pojoCodecRegistry = fromProviders(PojoCodecProvider.builder().automatic(true).build());
   CodecRegistry codecRegistry = fromRegistries(MongoClientSettings.getDefaultCodecRegistry(), pojoCodecRegistry);
   MongoClientSettings clientSettings = MongoClientSettings.builder()
           .applyConnectionString(connectionString)
           .codecRegistry(codecRegistry)
           .build();
   try (MongoClient mongoClient = MongoClients.create(clientSettings)) {
       MongoDatabase database = mongoClient.getDatabase("ecommerce");
       MongoCollection<Product> collection = database.getCollection("productDetails", Product.class);

       Product newProduct = new Product();
       newProduct.setId(new ObjectId());
       newProduct.setProductName("Wireless Mouse");
       newProduct.setCategory("Electronics");
       newProduct.setPrice(29.99);
       newProduct.setStock(150);
       newProduct.setDescription("Ergonomic wireless mouse with adjustable DPI settings.");
       newProduct.setBrand("TechBrand");
       newProduct.setFeatures("2.4 GHz wireless connectivity, Adjustable DPI from 800 to 1600, Compatible with Windows and macOS");

       List<Image> images = new ArrayList<>();
       images.add(new Image("https://example.com/images/wireless_mouse_1.jpg", "Wireless Mouse Top View"));
       images.add(new Image("https://example.com/images/wireless_mouse_2.jpg", "Wireless Mouse Side View"));
       newProduct.setImages(images);

       List<Reviews> reviews = new ArrayList<>();
       reviews.add(new Reviews(new ObjectId("66cc67443921db64869bcf3d"), 4.5, "Great mouse, very comfortable to use!", "2024-08-18T19:00:00Z"));
       newProduct.setReviews(reviews);

       collection.insertOne(newProduct);
       System.out.println("Inserted product: " + newProduct);

       Product foundProduct = collection.find(Filters.eq("productName", "Wireless Mouse")).first();
       System.out.println("Found product: " + foundProduct);

       collection.updateOne(Filters.eq("_id", newProduct.getId()), Updates.set("stock", 140));
       Product updatedProduct = collection.find(Filters.eq("_id", newProduct.getId())).first();
       System.out.println("Updated product stock: " + updatedProduct.getStock());

       collection.deleteOne(Filters.eq("_id", newProduct.getId()));
       System.out.println("Deleted product: " + newProduct.getProductName());
   }
}

Using Builders in MongoDB

Builders, provided by the MongoDB Java driver, simplify the operations for basic CRUD and also for writing complex aggregations. These are the utility classes which allow you to create complex operations in a readable and type-safe manner, making the code more expressive and easier to maintain.

Let us understand the usage of builders through a code example.

Aggregation builders are built using the aggregate class which provides the method to create pipeline stages in the Java code.

The example given below from the AggregationBuilder.java class shows how you can create a simple aggregation pipeline using builder methods.

The below aggregation is an instance to show product details for the top three highest-reviewed products.

private static void runAverageRatingPipeline(MongoCollection<Product> collection) {
   AggregateIterable<Product> result = collection.aggregate(Arrays.asList(
           unwind("$reviews"),
           group("$_id",
                   avg("averageRating", "$reviews.rating"),
                   first("productName", "$productName"),
                   first("category", "$category"),
                   first("price", "$price"),
                   first("brand", "$brand"),
                   first("stock", "$stock")
           ),
           match(gte("averageRating", 4.5)),
           sort(Sorts.descending("averageRating")),
           project(fields(
                   excludeId(),
                   include("productName", "category", "price", "brand", "stock")
           )),
           limit(3)
           )
   );

   System.out.println("High-Rated Products:");
   for (Product doc : result) {
       System.out.println(doc.toProductDetails());
   }
}

Similarly, the code snippet below uses update builders to update the collection records.

private static void updateLowStockProducts(MongoCollection<Product> collection) {
   collection.updateMany(
           lt("stock", 50),
           Updates.inc("stock", 20)
   );

   System.out.println("Update: Increased stock for products with less than 50 units.");
}

This is how builders make your life simpler and more efficient. You can visit the complete code in the GitHub repository.

Conclusion

To sum it all up, the truth is data is growing at an unprecedented rate and becoming increasingly diverse and unstructured, and traditional relational databases might need to be revised. For Java developers accustomed to the rigidity of SQL schemas, MongoDB offers a refreshing alternative with its schemaless architecture and natural integration with Java's POJO model.

Moreover, MongoDB's dynamic schema and powerful aggregation framework allow for agile development and complex querying without the overhead of rigid schemas.

Incorporating MongoDB into your Java applications not only streamlines data management but also empowers you to adapt swiftly to changing requirements and scale with ease. As the data landscape evolves, MongoDB's capabilities position you to deal with the challenges of unstructured data and ensure your applications remain robust and responsive in a data-driven world.

If you wish to learn more about building applications in Java and frameworks like Spring Boot and Quarkus, visit the MongoDB Developer Center for more interesting tutorials.

Streamlining Java Application Development With MongoDB: A Comprehensive Guide to Using Testcontainers

aasawari sahasrabuddhe — Sat, 14 Feb 2026 04:42:41 +0000

The world of software development is a continuous cycle. We build, test, deploy, and iterate – striving to deliver high-quality applications. Within this software development lifecycle (SDLC), testing is crucial in ensuring our code functions as intended. There are two main types of tests we encounter:

Unit testing: In this part, the intent is to check if the business logic for the code is working well and if no unexpected results are formed.

Integration testing: In this part of testing, the developer assesses how different parts of the system interact with each other. They simulate real-world scenarios by integrating with external dependencies. While providing a more holistic view of application behavior, traditional integration tests can be cumbersome to set up and maintain due to the need for external resources like databases.

Testcontainers is an open-source framework for Java that leverages the power of Docker containers to streamline integration testing, by spinning up lightweight, throwaway instances of real dependencies within Docker containers for the duration of your test.

This tutorial will explore using Testcontainers with Java and Spring Boot, leveraging MongoDB as our database. We'll show you how to set up Testcontainers, integrate it into your project, and effectively use it to streamline your integration tests.

Let's get started.

Pre-requisites

Java version 22 — download and install the latest JDK from the official Oracle website
Maven version 3.9.6 — Download and install the latest version from the Maven official website
Docker version 26.0.0 — Download and install Docker Desktop for your operating system from the official website

Getting started with Testcontainers

Why Testcontainers?

As a software developer, you navigate through every phase of the software development lifecycle during application development. Once the development phase is complete, the next critical stage involves writing test cases to verify the business logic of the application.

Whether your application is developed using vanilla Java or Spring Boot, you will typically write JUnit tests to ensure that the business logic functions correctly and meets the specified requirements. These tests are essential for validating the application's functionality and maintaining high-quality standards.

To test the complete functionality of your application, you are also required to perform integration testing. Integration testing is particularly important as it focuses on the interactions between different modules of the software. It detects interface issues and validates the functional relationships and data flow between combined units, ensuring they work together seamlessly. This is crucial for systems with multiple interconnected components, as it improves the overall reliability and stability of the application by ensuring that all parts integrate correctly and function as a unified whole.

Now, let's suppose your Java application uses MongoDB as its database. While writing your JUnits tests, what would you prefer?

Testing your services with in-memory databases that may also be utilized by another module of the application?
Testing the application with the database created locally only for the business logic to be tested?

As a part of the database optimization, you would choose the second option from the above.

Now, this is where Testcontainers would help achieve the second option.

Let us understand the concept of Testcontainers in the next section.

Introduction to Testcontainers

As quoted in the documentation for testcontainers:

Testcontainers for Java is a Java library that supports JUnit tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container.

These containers are managed during test execution, ensuring a clean, isolated environment for each test or test suite. By leveraging Docker, Testcontainers allows developers to automate the setup and teardown of test dependencies, significantly simplifying the integration testing process.

As we have already discussed above, using Testcontainers gives you the advantage of using the database locally, reducing the load on the actual database used by the services.

Along with this, Testcontainers also helps in providing:

Consistency: It ensures that the tests run in a consistent environment, regardless of the underlying infrastructure.
Isolation: Each test can run in an isolated environment with its own set of dependencies.
Up-to-date environments: This allows you to easily switch to different versions of dependencies by using different Docker images, which is particularly useful for testing compatibility with various versions of a database or service.

Working with Testcontainers

By now, you should have the theoretical knowledge about what Testcontainers is and why we should use it.

In this section of the article, we will discuss how Testcontainers can be used in Java and Spring Boot.

This will be divided into two sections:

Testcontainers with Java
Testcontainers with Spring Boot

The concept of Testcontainers remains the same irrespective of the framework being used, but these two sections will help you understand the application in both scenarios.

To begin using Testcontainers, you need to load the below dependency in your pom.xml file.

<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongodb-driver-sync</artifactId>
    <version>5.1.0</version>
</dependency>
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-api</artifactId>
    <version>5.10.2</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-engine</artifactId>
    <version>5.10.2</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-core</artifactId>
    <version>5.12.0</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers</artifactId>
    <version>1.19.8</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>1.19.8</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>mongodb</artifactId>
    <version>1.19.8</version>
    <scope>test</scope>
</dependency>

Testcontainers with vanilla Java

The test cases written in JUnits tests are executed in three stages with Testcontainers.

Before tests: In this stage, the container is created, the database will be loaded, and collections will be created.
During tests: This is the stage where the actual business logic of the application is tested.
After tests: At this stage, the containers created in the first stage are destroyed and the resources are set free.

The code on how to use Testcontainers with Java is available in the GitHub repository.

In this code example, the JUnits test case is written to test a simple query to find five movie names that have IMDb ratings greater than seven.

The JUnits tests are written in the TestcontainerClass.java class and the below description will help you understand the code:

If you look at the code, it is divided in four parts:

Creating container: This will pull the mongo:7.0.0 docker image from Docker Hub and create the container. The @Container annotation will start and stop the container when the tests are finished.

@Container
private static final MongoDBContainer mongoDBContainer = new MongoDBContainer("mongo:7.0.0");

Setup: The container is started and the example documents are inserted inside testCollection.

@BeforeAll
public void setup() {
    String uri = mongoDBContainer.getConnectionString();
    mongoClient = MongoClients.create(uri);
    database = mongoClient.getDatabase("testdb");
    collection = database.getCollection("testCollection");

    // Insert sample data
    Document doc1 = new Document("title", "Inception").append("imdb", new Document("rating", 8.8));
    Document doc2 = new Document("title", "The Room").append("imdb", new Document("rating", 3.7));
    Document doc3 = new Document("title", "The Dark Knight").append("imdb", new Document("rating", 9.0));

    collection.insertMany(List.of(doc1, doc2, doc3));
}

Actual tests: The actual test case for the business logic is implemented.

@Test
void testMoviesWithHighRating() {
    List<Document> resultDocuments = new ArrayList<>();
    try (MongoCursor<Document> cursor = collection.find(Filters.gt("imdb.rating", 7))
            .projection(new Document("title", 1).append("_id", 0))
            .limit(5)
            .iterator()) {
        while (cursor.hasNext()) {
            Document doc = cursor.next();
            System.out.println(doc.toJson());
            resultDocuments.add(doc);
        }
    }

    assertEquals(2, resultDocuments.size());
    for (Document doc : resultDocuments) {
        assertTrue(doc.containsKey("title"));
        assertFalse(doc.containsKey("_id"));
    }
}

In the above code example, when the sample data is loaded, the resultDocuments will contain an empty list.

Next, in the try-catch section of the code, the cursor iterates through the results, adding each document to the resultDocuments list after printing it in JSON format to the console. After the iteration, the test asserts that exactly two documents were retrieved by checking the size of the resultDocuments list.

Additionally, for each document in the list, the test asserts that the title field is present and the _id field is absent. These assertions ensure that the query behaves as expected, retrieving the correct number of documents with the appropriate fields.

It is often confusing that the tests are created on the production database. But the advantage of using Testcontainers is that when you run the test class, the Docker image is loaded, the sample document is created, and the test cases are run all on this container. After the tests are completed, the container and connection are closed.

Now, let us try to understand how this logic can be implemented in the Spring Boot framework.

Testcontainers with Spring Boot

To write JUnits tests in a Spring Boot application, we will utilize an old GitHub repository that explains advanced aggregations using Spring Boot.

In this repository, you will see different REST APIs created that work on the sample_supplies.sales collection.

For this example, we will just utilize it to write test cases for the findAll() API.

The JUnits tests are similarly written in MongoDBSalesRepositoryTest.java.

Set up the container:

@Container
public static MongoDBContainer mongoDBContainer = new MongoDBContainer(DockerImageName.parse("mongo:7.0.0"));

Insert data into the container:

@DynamicPropertySource
static void setProperties(DynamicPropertyRegistry registry) {
    registry.add("spring.data.mongodb.uri", mongoDBContainer::getReplicaSetUrl);
    registry.add("spring.data.mongodb.database", () -> "testdb");
}

@BeforeAll
public static void setUpAll() {
    String mongoUri = mongoDBContainer.getConnectionString();
    mongoClient = MongoClients.create(mongoUri);
}

@BeforeEach
public void setUp() {
    salesRepository.save(createMockSales());
}

private Sales createMockSales() {
    Item item1 = new Item("Item1", Arrays.asList("Tag1", "Tag2"), new BigDecimal("19.99"), 2);
    Item item2 = new Item("Item2", Arrays.asList("Tag3", "Tag4"), new BigDecimal("29.99"), 1);
    List<Item> items = Arrays.asList(item1, item2);

    Customer customer = new Customer("Male", 30, "customer@example.com", 5);

    return new Sales(new ObjectId(), new Date(), items, "Store1", customer, true, "Online");
}

Actual tests:

@Test
public void testFindAll() {
    List<Sales> salesList = salesRepository.findAll();
    assertThat(salesList).isNotEmpty();
    assertThat(salesList.size()).isEqualTo(1);
    Sales sales = salesList.get(0);
    assertThat(sales.getStoreLocation()).isEqualTo("Store1");
    assertThat(sales.getCustomer().getEmail()).isEqualTo("customer@example.com");
    assertThat(sales.getItems()).hasSize(2);
}

The testFindAll method validates the findAll function of SalesRepository. It checks if at least one sales record is returned if there's exactly one record, and if its attributes match expected values like store location, customer email, and the number of items purchased. This test ensures the correctness of the repository's retrieval function.

Conclusion

Throughout this tutorial, we've demonstrated how to set up and use Testcontainers for integration testing with MongoDB in both a vanilla Java application and a Spring Boot application. We started by adding the necessary dependencies to our project, setting up the MongoDB container, and writing test cases to validate our business logic. Following these steps can achieve a more robust and maintainable testing setup.

If you liked this article and wish to practice more such content, we encourage you to visit the MongoDB Developer Centre. You can also visit our community forums for meaningful discussions and documentation for more learning.

MongoDB Advanced Aggregations With Spring Boot and Amazon Corretto

aasawari sahasrabuddhe — Sat, 14 Feb 2026 03:51:30 +0000

Introduction

In this tutorial, we'll get into the understanding of aggregations and explore how to construct aggregation pipelines within your Spring Boot applications.

If you're new to Spring Boot, it's advisable to understand the fundamentals by acquainting yourself with the example template provided for performing Create, Read, Update, Delete (CRUD) operations with Spring Boot and MongoDB before delving into advanced aggregation concepts.

This tutorial serves as a complement to the example code template accessible in the GitHub repository. The code utilises sample data, which will be introduced later in the tutorial.

As indicated in the tutorial title, we'll compile the Java code using Amazon Corretto.

We recommend following the tutorial meticulously, progressing through each stage of the aggregation pipeline creation process.

Let's dive in!

Prerequisites

This tutorial follows a few specifications mentioned below. Before you start practicing it, please make sure you have all the necessary downloads and uploads in your environment.

Amazon Corretto 21 JDK
A free Atlas tier, also known as an M0 cluster
Sample Data loaded in the cluster
Spring Data Version 4.2.2
MongoDB version 6.0.3
MongoDB Java Driver version 4.11.1

Let’s understand each of these in detail.

Understanding and installing Corretto

Corretto comes with the ability to be a no-cost, multiplatform, production-ready open JDK. It also provides the ability to work across multiple distributions of Linux, Windows, and macOS.

You can read more about Amazon Corretto in Introduction to Amazon Corretto: A No-Cost Distribution of OpenJDK.

We will begin the tutorial with the first step of installing the Amazon Corretto 21 JDK and setting up your IDE with the correct JDK.

Step 1

Install Amazon Corretto 21 from the official website based on the operating system specifications.

Step 2

If you are on macOS, you will need to set the JAVA_HOME variable with the path for the Corretto. To do this, go to the system terminal and set the variable JAVA_HOME as:

export JAVA_HOME=/Library/Java/JavaVirtualMachines/amazon-corretto-21.jdk/Contents/Home

Once the variable is set, you should check if the installation is done correctly using:

java --version
openjdk 21.0.2 2024-01-16 LTS
OpenJDK Runtime Environment Corretto-21.0.2.13.1 (build 21.0.2+13-LTS)
OpenJDK 64-Bit Server VM Corretto-21.0.2.13.1 (build 21.0.2+13-LTS, mixed mode, sharing)

For any other operating system, you will need to follow the steps mentioned in the official documentation from Java on how to set or change the PATH system variable and check if the version has been set.

Once the JDK is installed on the system, you can set up your IDE of choice to use Amazon Corretto to compile the code.

At this point, you have all the necessary environment components ready to kickstart your application.

Creating the Spring Boot application

In this part of the tutorial, we're going to explore how to write aggregation queries for a Spring Boot application.

Aggregations in MongoDB are like super-powered tools for doing complex calculations on your data and getting meaningful results back. They work by applying different operations to your data and then giving you the results in a structured way.

But before we get into the details, let's first understand what an aggregation pipeline is and how it operates in MongoDB.

Think of an aggregation pipeline as a series of steps or stages that MongoDB follows to process your data. Each stage in the pipeline performs a specific task, like filtering or grouping your data in a certain way. And just like a real pipeline, data flows through each stage, with the output of one stage becoming the input for the next. This allows you to build up complex operations step by step to get the results you need.

By now, you should have the sample data loaded in your Atlas cluster. In this tutorial, we will be using the sample_supplies.sales collection for our aggregation queries.

The next step is cloning the repository from the link to test the aggregations. You can start by cloning the repository using the below command:

git clone https://github.com/mongodb-developer/spring-boot-mongodb-aggregations.git

Once the above step is complete, upon forking and cloning the repository to your local environment, it's essential to update the connection string in the designated placeholder within the application.properties file. This modification enables seamless connectivity to your cluster during project execution.

README

After cloning the repository and changing the URI in the environment variables, you can try running the REST APIs in your Postman application.

All the extra information and commands you need to get this project going are in the README.md file which you can read on GitHub.

Writing aggregation queries in Spring

The Aggregation Framework support in Spring Data MongoDB is based on the following key abstractions:

Aggregation
AggregationDefinition
AggregationResults

The Aggregation Framework support in Spring Data MongoDB is based on the following key abstractions: Aggregation, AggregationDefinition, and AggregationResults.

While writing the aggregation queries, the first step is to generate the pipelines to perform the computations using the operations supported.

The documentation on spring.io explains each step clearly and gives simple examples to help you understand.

For the tutorial, we have the REST APIs defined in the SalesController.java class, and the methods have been mentioned in the SalesRepository.java class.

First aggregation using $match

db.sales.aggregate([{ $match: { "storeLocation": "London"}}])

Spring Boot function:

@Override
public List<SalesDTO> matchOp(String matchValue) {
MatchOperation matchStage = match(new Criteria("storeLocation").is(matchValue));
Aggregation aggregation = newAggregation(matchStage);
AggregationResults<SalesDTO> results = mongoTemplate.aggregate(aggregation, "sales", SalesDTO.class);
return results.getMappedResults();
}

The REST API can be tested using the curl command in the terminal which shows all documents where storeLocation is London.

Group aggregation

@Override
public List<GroupDTO> groupOp(String matchValue) {
MatchOperation matchStage = match(new Criteria("storeLocation").is(matchValue));
GroupOperation groupStage = group("storeLocation").count()
                                                          .as("totalSales")
                                                          .avg("customer.satisfaction")
                                                          .as("averageSatisfaction");
ProjectionOperation projectStage = project("storeLocation", "totalSales", "averageSatisfaction");
Aggregation aggregation = newAggregation(matchStage, groupStage, projectStage);
AggregationResults<GroupDTO> results = mongoTemplate.aggregate(aggregation, "sales", GroupDTO.class);
return results.getMappedResults();
}

REST API:

curl http://localhost:8080/api/sales/aggregation/groupStage/Denver | jq

Total Sales aggregation

@Override
public List<TotalSalesDTO> TotalSales() {
GroupOperation groupStage = group("storeLocation").count().as("totalSales");
SkipOperation skipStage = skip(0);
LimitOperation limitStage = limit(10);
Aggregation aggregation = newAggregation(groupStage, skipStage, limitStage);
AggregationResults<TotalSalesDTO> results = mongoTemplate.aggregate(aggregation, "sales", TotalSalesDTO.class);
return results.getMappedResults();
}

REST API:

curl http://localhost:8080/api/sales/aggregation/TotalSales | jq

Popular items aggregation using $sort and $limit

@Override
public List<PopularDTO> findPopularItems() {
UnwindOperation unwindStage = unwind("items");
GroupOperation groupStage = group("$items.name").sum("items.quantity").as("totalQuantity");
SortOperation sortStage = sort(Sort.Direction.DESC, "totalQuantity");
LimitOperation limitStage = limit(5);
Aggregation aggregation = newAggregation(unwindStage,groupStage, sortStage, limitStage);
return mongoTemplate.aggregate(aggregation, "sales", PopularDTO.class).getMappedResults();
}

curl http://localhost:8080/api/sales/aggregation/PopularItem | jq

Bucket aggregation using $bucket

@Override
public List<BucketsDTO> findTotalSpend(){
ProjectionOperation projectStage = project()
                .and(ArrayOperators.Size.lengthOfArray("items")).as("numItems")
                .and(ArithmeticOperators.Multiply.valueOf("price")
                        .multiplyBy("quantity")).as("totalAmount");

BucketOperation bucketStage = bucket("numItems")
                .withBoundaries(0, 3, 6, 9)
                .withDefaultBucket("Other")
                .andOutputCount().as("count")
                .andOutput("totalAmount").sum().as("totalAmount");

Aggregation aggregation = newAggregation(projectStage, bucketStage);
return mongoTemplate.aggregate(aggregation, "sales", BucketsDTO.class).getMappedResults();
}

curl http://localhost:8080/api/sales/aggregation/buckets | jq

Conclusion

This tutorial provides a comprehensive overview of aggregations in MongoDB and how to implement them in a Spring Boot application. We have learned about the significance of aggregation queries for performing complex calculations on data sets, leveraging MongoDB's aggregation pipeline to streamline this process effectively.

As you continue to experiment and apply these concepts in your applications, feel free to reach out on our MongoDB community forums. Remember to explore further resources in the MongoDB Developer Center and documentation to deepen your understanding and refine your skills in working with MongoDB aggregations.

MongoDB Orchestration With Spring & Atlas Kubernetes Operator

aasawari sahasrabuddhe — Sat, 14 Feb 2026 03:32:21 +0000

In this tutorial, we'll delve into containerisation concepts, focusing on Docker, and explore deploying your Spring Boot application from a previous tutorial. By the tutorial's conclusion, you'll grasp Docker and Kubernetes concepts and gain hands-on experience deploying your application within a cloud infrastructure.

This tutorial is an extension of the previous tutorial where we explained how to write advanced aggregation queries in MongoDB using the Spring Boot framework. We will use the same GitHub repository to create this tutorial's deployment files.

We'll start by learning about containers, like digital packages that hold software. Then, we'll dive into Kubernetes, a system for managing those containers. Finally, we'll use Kubernetes to set up MongoDB and our Spring application, seeing how they work together.

Prerequisites

A Spring Boot application running on your local machine
Elastic Kubernetes Service deployed on AWS using eksctl
A MongoDB Atlas account

Understanding containerisation

Often as a software developer, one comes across an issue where the features of the application work perfectly on the local machine, and many features seem to be broken on the client machine. This is where the concept of containers would come in.

In simple words, a container is just a simple, portable computing environment that contains everything an application needs to run. The process of creating containers for the application to run in any environment is known as containerisation.

Containerisation is a form of virtualisation where an application, along with all its components, is packaged into a single container image. These containers operate in their isolated environment within the shared operating system, allowing for efficient and consistent deployment across different environments.

Advantages of containerising the application

Portability

The idea of “write once and run anywhere” encapsulates the essence of containers, enabling applications to seamlessly transition across diverse environments, thereby enhancing their portability and flexibility.

Efficiency

When configured properly, containers utilise the available resources, and also, isolated containers can perform their operations without interfering with other containers, allowing a single host to perform many functions. This makes the containerised application work efficiently and effectively.

Better security

Because containers are isolated from one another, you can be confident that your applications are running in their self-contained environment. That means that even if the security of one container is compromised, other containers on the same host remain secure.

Comparing containerisation and traditional virtualisation methods

Aspect	Containers	Virtual Machines
Abstraction Level	OS level virtualisation	Hardware-level virtualisation
Resource Overhead	Minimal	Higher
Isolation	Process Level	Stronger
Portability	Highly Portable	Less Portable
Deployment Speed	Fast	Slower
Footprint	Lightweight	Heavier
Startup Time	Almost instant	Longer
Resource Utilisation	Efficient	Less Efficient
Scalability	Easily Scalable	Scalable, but with resource overhead

Understanding Docker

Docker application provides the platform to develop, ship, and run containers. This separates the application from the infrastructure and makes it portable. It packages the application into lightweight containers that can run across without worrying about underlying infrastructures.

Docker containers have minimal overhead compared to traditional virtual machines, as they share the host OS kernel and only include necessary dependencies. Docker facilitates DevOps practices by enabling developers to build, test, and deploy applications in a consistent and automated manner. You can read more about Docker containers and the steps to install them on your local machine from their official documentation.

Understanding Kubernetes

Kubernetes, often called K8s, is an open-source orchestration platform that automates containerised applications' deployment, scaling, and management. It abstracts away the underlying infrastructure complexity, allowing developers to focus on building and running their applications efficiently.

It simplifies the deployment and management of containerised applications at scale. Its architecture, components, and core concepts form the foundation for building resilient, scalable, and efficient cloud-native systems. The Kubernetes architectures have been helpful in typical use cases like microservices architecture, hybrid and multi-cloud deployments, and DevOps where continuous deployments are done.

Kubernetes Components

The K8s environment works in the controller-worker node architecture and therefore, two nodes manage the communication.

Master Node is responsible for controlling the cluster and making decisions for the cluster.
Worker node(s) is responsible for running the application receiving instructions from the Master Node and resorting back to the status.

Other components of the Kubernetes cluster are:

Pods
ReplicaSets
Services
Volumes
Namespaces

Atlas Kubernetes Operator

Consider a use case where a Spring application running locally is connected to a database deployed on the Atlas cluster. Later, your organization introduces you to the Kubernetes environment and plans to deploy all the applications in the cloud infrastructure.

The question of how you will connect your Kubernetes application to the Atlas cluster running on a different environment will arise. This is when the Atlas Kubernetes Operator will come into the picture.

This operator allows you to manage the Atlas resources in the Kubernetes infrastructure.

For this tutorial, we will deploy the operator on the Elastic Kubernetes Service on the AWS infrastructure.

Step 1: Deploy an EKS cluster using eksctl

eksctl create cluster \
--name MongoDB-Atlas-Kubernetes-Operator \
--version 1.29 \
--region ap-south-1 \
--nodegroup-name linux-nodes \
--node-type t2.2xlarge \
--nodes 2

Step 2

kubectl get ns

Example output

NAME                   STATUS        AGE
default                Active        18h
kube-node-lease        Active        18h
kube-public            Active        18h
kube-system            Active        18h

Export Environment Variables

export VERSION=v2.2.0
export ORG_ID=<your-organisations-id>
export PUBLIC_API_KEY=<your-public-key>
export PRIVATE_API_KEY=<your-private-key>

Apply operator:

kubectl apply -f https://raw.githubusercontent.com/mongodb/mongodb-atlas-kubernetes/$VERSION/deploy/all-in-one.yaml

Create secret:

kubectl create secret generic mongodb-atlas-operator-api-key \
--from-literal="orgId=$ORG_ID" \
--from-literal="publicApiKey=$PUBLIC_API_KEY" \
--from-literal="privateApiKey=$PRIVATE_API_KEY" \
-n mongodb-atlas-system

Label secret:

kubectl label secret mongodb-atlas-operator-api-key \
atlas.mongodb.com/type=credentials \
-n mongodb-atlas-system

project.yaml

apiVersion: atlas.mongodb.com/v1
kind: AtlasProject
metadata:
  name: project-ako
spec:
  name: atlas-kubernetes-operator
  projectIpAccessList:
    - cidrBlock: "0.0.0.0/0"
      comment: "Allowing access to database from everywhere (only for Demo!)"

deployment.yaml

apiVersion: atlas.mongodb.com/v1
kind: AtlasDeployment
metadata:
  name: my-atlas-cluster
spec:
  projectRef:
    name: project-ako
  deploymentSpec:
    clusterType: REPLICASET
    name: "cluster0"
    replicationSpecs:
      - zoneName: AP-Zone
        regionConfigs:
          - electableSpecs:
              instanceSize: M10
              nodeCount: 3
            providerName: AWS
            regionName: AP_SOUTH_1
            priority: 7

user.yaml

kubectl create secret generic the-user-password \
--from-literal="password=<password for your user>"
kubectl label secret the-user-password atlas.mongodb.com/type=credentials

apiVersion: atlas.mongodb.com/v1
kind: AtlasDatabaseUser
metadata:
  name: my-database-user
spec:
  roles:
    - roleName: "readWriteAnyDatabase"
      databaseName: "admin"
  projectRef:
    name: project-ako
  username: theuser
  passwordSecretRef:
    name: the-user-password

Apply:

kubectl apply -f project.yaml
kubectl apply -f deployment.yaml
kubectl apply -f user.yaml

Deploying the Spring Boot application in the cluster

Build JAR

mvn clean package

Build Docker image

docker build -t mongodb_spring_tutorial:docker_image . --load

Push image

docker tag mongodb_spring_tutorial:docker_image <your_docker_username>/mongodb_spring_tutorial
docker push <your_docker_username>/mongodb_spring_tutorial

app-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: spring-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: springboot-application
  template:
    metadata:
      labels:
        app: springboot-application
    spec:
      containers:
      - name: spring-app
        image: <your_docker_username>/mongodb_spring_tutorial
        ports:
        - containerPort: 8080
        env:
        - name: SPRING_DATA_MONGODB_URI
          valueFrom:
            secretKeyRef:
              name: atlas-kubernetes-operator-cluster0-theuser
              key: connectionStringStandardSrv
        - name: SPRING_DATA_MONGODB_DATABASE
          value: sample_supplies

service.yaml

apiVersion: v1
kind: Service
metadata:
  name: spring-app-service
spec:
  selector:
    app: spring-app
  ports:
    - protocol: TCP
      port: 8080
      targetPort: 8080
  type: LoadBalancer

Apply:

kubectl apply -f ./*.yaml

Get External IP

kubectl get svc

Or:

EXTERNAL_IP=$(kubectl get svc | grep spring-app-service | awk '{print $4}')
echo $EXTERNAL_IP

Troubleshooting

Check Pods

kubectl describe pods <pod-name> -n <namespace>
kubectl get pods -n <namespace>

Check Nodes

kubectl get nodes

Check Logs

kubectl logs -f <pod-name> -n <namespace>

Check Services

kubectl describe svc <service-name> -n <namespace>

Conclusion

Throughout this tutorial, we've covered essential aspects of modern application deployment, focusing on containerisation, Kubernetes orchestration, and MongoDB management with Atlas Kubernetes Operator.

With this knowledge, you're well-prepared to architect and manage sophisticated cloud-native applications effectively.

A Complete Guide to hire from Canada as US based organisation: Its simpler than you think

aasawari sahasrabuddhe — Fri, 30 Jan 2026 15:11:33 +0000

If you're a US-based organisation and are looking to expand your development team, you might be overlooking a talent pool that's closer than you think: Canada. Employers based out of US assume that hiring across the border involves complex legal hurdles, but the reality is far more straightforward.

The Short Answer: Yes, you can!

As a US employer, you can hire Canadian citizen directly and there's no special permission required. It's a practice that's becoming increasingly common in the tech industry considering they look for talents globally after the work from home flexibility. The key is understanding a few basic requirements.

Why Canada Makes Sense for US Tech Companies

Geographic and Cultural Proximity: Canada shares a close time zones with the US and hence eliminating the coordination challenges of working with teams halfway across the world. You would have the team in your own time zone.

Similar Work Culture: Even though the corporate cultures are globally acceptable these days, Canada offers a similar work culture which makes the global team work efficiently together.

Competitive Costs: While you gain access to highly skilled talent, the cost structure often works in your favour. US salaries are comparatively competitive than the Canadian market.

Strong Talent: Canada has a robust tech ecosystem with excellent engineering schools and a growing startup scene, producing skilled developers in all specialisations.

How can you hire Canadian employees?

Hire as Independent Contractors: This is one of the simplest starting point. Canadian contractors can work with you on a project or ongoing basis. However, if the relationship looks like employment, Canadian authorities may reclassify them as employees, triggering tax and benefit obligations.
Set Up a Canadian Entity: If you're planning significant operations in Canada, establishing a legal entity gives you full control. However, this requires legal setup, ongoing compliance, and administrative overhead.
Use an Employer of Record (EOR): An EOR handles all the legal and administrative aspects payroll, taxes, benefits while you manage the employee's everyday work. This is ideal if you want the commitment of a full-time employee without the complexity of setting up a Canadian entity.

What You Need to Know

Unlike the US federal system, Canada has both federal and provincial employment laws. The rules in Ontario differ from those in British Columbia or Quebec. Your developer's province of residence determines which rules apply for minimum wage, overtime, and benefits.
Canada doesn't recognise at-will employment. You can't terminate employees without cause or notice. When letting someone go without cause, you must provide notice or payment in lieu, based on their tenure and role. Employment contracts should clearly outline these terms.

Benefits for the full time employees

Paid Time Off: After 12 months, employees get a minimum of two weeks annual vacation. This increases with tenure.

Parental Leave: New parents are entitled to 15 weeks of maternity leave plus 35-61 weeks of parental leave (depending on the option chosen), funded through Employment Insurance.

Statutory Holidays: Canada has federal holidays that are paid days off for all employees from day one.

Health Insurance: While Canada has public healthcare, many employers offer supplemental private insurance for dental, vision, and extended coverage to remain competitive.

Payroll and Tax Contributions

Both employers and employees contribute to:

Canada Pension Plan (CPP): 5.95% each on earnings up to $74,600 according to 2026.
Employment Insurance (EI): 1.63% for employees, 2.28% for employers on insurable earnings

These contributions are straightforward and handled through regular payroll.

Common Pitfalls to Avoid

Misclassifying Contractors: If your "contractor" works exclusively for you with set hours and uses your equipment, Canadian authorities may deem them an employee. This triggers backdated tax and benefit obligations.
Ignoring Permanent Establishment: If you have a fixed location in Canada generating revenue, you've created a permanent establishment and must pay Canadian taxes. Remote employees working from home generally don't trigger this, but consult with a tax professional.
Asking Prohibited Questions: Canada's hiring discrimination laws are stricter than US laws. Don't ask about immigration status, age, marital status, religion, or other protected characteristics during interviews.

The Bottom Line

Hiring developers in Canada isn't the bureaucratic nightmare many US companies imagine. The countries' proximity, shared language, and aligned work cultures make it one of the smoothest international hiring experiences available.

Whether you're a startup looking for your first remote developer or an established company expanding your team, Canadian talent offers immediate productivity without the complications of vastly different time zones or work cultures.

The opportunity is there. The talent is ready. And the process? Simpler than you think.