spring-data-mongodb

Spring Data MongoDB - Quick Reference

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: spring-data-mongodb for comprehensive documentation.

Setup

Dependencies (Maven)

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-mongodb</artifactId> </dependency>

Configuration

spring: data: mongodb: uri: mongodb://localhost:27017/mydb # Or explicit host: localhost port: 27017 database: mydb username: user password: secret authentication-database: admin

Entity Mapping

Basic Document

@Document(collection = "products") public class Product { @Id private String id;

@Field("product_name")
private String name;

@Indexed
private String category;

private BigDecimal price;

@CreatedDate
private LocalDateTime createdAt;

@LastModifiedDate
private LocalDateTime updatedAt;

}

Embedded Documents

@Document(collection = "orders") public class Order { @Id private String id;

private Customer customer;           // Embedded
private List&#x3C;OrderItem> items;       // Embedded list
private Address shippingAddress;     // Embedded

}

// No @Document - embedded class public class OrderItem { private String productId; private String productName; private int quantity; private BigDecimal price; }

References

@Document(collection = "posts") public class Post { @Id private String id; private String title;

@DBRef
private User author;                 // Lazy loaded reference

// Manual reference (preferred for performance)
private String authorId;

}

Repository Pattern

Basic Repository

public interface ProductRepository extends MongoRepository<Product, String> {

// Derived queries
List&#x3C;Product> findByCategory(String category);
List&#x3C;Product> findByPriceLessThan(BigDecimal price);
List&#x3C;Product> findByCategoryAndPriceBetween(
    String category, BigDecimal min, BigDecimal max);

// Sorting
List&#x3C;Product> findByCategoryOrderByPriceDesc(String category);

// Limiting
List&#x3C;Product> findTop5ByCategoryOrderByPriceAsc(String category);

// Exists/Count
boolean existsByName(String name);
long countByCategory(String category);

}

@Query Annotation

public interface ProductRepository extends MongoRepository<Product, String> {

@Query("{ 'category': ?0, 'price': { $lte: ?1 } }")
List&#x3C;Product> findByCategoryWithMaxPrice(String category, BigDecimal maxPrice);

@Query("{ 'tags': { $in: ?0 } }")
List&#x3C;Product> findByAnyTag(List&#x3C;String> tags);

@Query("{ 'name': { $regex: ?0, $options: 'i' } }")
List&#x3C;Product> searchByName(String keyword);

// Projection
@Query(value = "{ 'category': ?0 }", fields = "{ 'name': 1, 'price': 1 }")
List&#x3C;Product> findNameAndPriceByCategory(String category);

}

Aggregation in Repository

@Aggregation(pipeline = { "{ $match: { status: 'COMPLETED' } }", "{ $group: { _id: '$customerId', total: { $sum: '$amount' } } }", "{ $sort: { total: -1 } }", "{ $limit: 10 }" }) List<CustomerTotal> findTopCustomers();

MongoTemplate

CRUD Operations

@Service @RequiredArgsConstructor public class ProductService { private final MongoTemplate mongoTemplate;

// Create
public Product save(Product product) {
    return mongoTemplate.save(product);
}

// Insert (fails if exists)
public Product insert(Product product) {
    return mongoTemplate.insert(product);
}

// Read
public Product findById(String id) {
    return mongoTemplate.findById(id, Product.class);
}

public List&#x3C;Product> findByCategory(String category) {
    Query query = Query.query(Criteria.where("category").is(category));
    return mongoTemplate.find(query, Product.class);
}

// Update
public UpdateResult updatePrice(String id, BigDecimal price) {
    Query query = Query.query(Criteria.where("id").is(id));
    Update update = Update.update("price", price);
    return mongoTemplate.updateFirst(query, update, Product.class);
}

// Delete
public DeleteResult delete(String id) {
    Query query = Query.query(Criteria.where("id").is(id));
    return mongoTemplate.remove(query, Product.class);
}

}

Complex Queries

public List<Product> search(ProductFilter filter) { Query query = new Query();

// Multiple criteria
if (filter.getCategory() != null) {
    query.addCriteria(Criteria.where("category").is(filter.getCategory()));
}

if (filter.getMinPrice() != null &#x26;&#x26; filter.getMaxPrice() != null) {
    query.addCriteria(Criteria.where("price")
        .gte(filter.getMinPrice())
        .lte(filter.getMaxPrice()));
}

// OR condition
if (filter.getKeywords() != null) {
    query.addCriteria(new Criteria().orOperator(
        Criteria.where("name").regex(filter.getKeywords(), "i"),
        Criteria.where("description").regex(filter.getKeywords(), "i")
    ));
}

// Pagination
query.with(PageRequest.of(filter.getPage(), filter.getSize()));

// Sorting
query.with(Sort.by(Sort.Direction.DESC, "createdAt"));

// Projection
query.fields().include("name", "price", "category");

return mongoTemplate.find(query, Product.class);

}

Aggregation Framework

Basic Pipeline

public List<CategoryStats> getCategoryStats() { Aggregation agg = Aggregation.newAggregation( Aggregation.match(Criteria.where("active").is(true)), Aggregation.group("category") .count().as("count") .avg("price").as("avgPrice") .sum("stock").as("totalStock"), Aggregation.sort(Sort.Direction.DESC, "count") );

return mongoTemplate.aggregate(agg, "products", CategoryStats.class)
    .getMappedResults();

}

Lookup (Join)

Aggregation agg = Aggregation.newAggregation( Aggregation.lookup("users", "userId", "_id", "user"), Aggregation.unwind("user"), Aggregation.project() .andInclude("orderNumber", "total") .and("user.name").as("customerName") );

Unwind Arrays

Aggregation agg = Aggregation.newAggregation( Aggregation.unwind("items"), Aggregation.group("items.productId") .sum("items.quantity").as("totalSold") .first("items.productName").as("productName"), Aggregation.sort(Sort.Direction.DESC, "totalSold"), Aggregation.limit(10) );

Indexes

Annotations

@Document(collection = "products") @CompoundIndex(name = "category_price", def = "{'category': 1, 'price': -1}") public class Product {

@Indexed(unique = true)
private String sku;

@Indexed
private String category;

@TextIndexed(weight = 3)
private String name;

@TextIndexed
private String description;

@Indexed(expireAfter = "30d")
private LocalDateTime expiresAt;

}

Programmatic

mongoTemplate.indexOps(Product.class).ensureIndex( new Index() .on("category", Sort.Direction.ASC) .on("price", Sort.Direction.DESC) .named("category_price_idx") );

Update Operations

Update Operators

Update update = new Update() .set("name", "New Name") .inc("viewCount", 1) .push("tags", "new-tag") .addToSet("categories", "electronics") .unset("deprecatedField") .currentDate("lastModified");

mongoTemplate.updateFirst(query, update, Product.class);

Upsert

mongoTemplate.upsert(query, update, Product.class);

Bulk Operations

BulkOperations bulkOps = mongoTemplate.bulkOps(BulkMode.ORDERED, Product.class); products.forEach(p -> bulkOps.insert(p)); bulkOps.execute();

Testing with Testcontainers

@DataMongoTest @Testcontainers class ProductRepositoryTest {

@Container
@ServiceConnection
static MongoDBContainer mongo = new MongoDBContainer("mongo:7.0");

@Autowired
private ProductRepository repository;

@Test
void shouldFindByCategory() {
    repository.save(new Product("Phone", "electronics", BigDecimal.valueOf(999)));

    List&#x3C;Product> found = repository.findByCategory("electronics");

    assertThat(found).hasSize(1);
}

}

Common Query Methods

Method MongoDB Equivalent

findByX(x)

{ x: x }

findByXAndY(x, y)

{ x: x, y: y }

findByXOrY(x, y)

{ $or: [{x: x}, {y: y}] }

findByXBetween(a, b)

{ x: { $gte: a, $lte: b } }

findByXLessThan(x)

{ x: { $lt: x } }

findByXIn(list)

{ x: { $in: list } }

findByXRegex(pattern)

{ x: { $regex: pattern } }

findByXExists(bool)

{ x: { $exists: bool } }

When NOT to Use This Skill

Raw MongoDB driver - Use mongodb skill for driver-level operations
Relational data - Use spring-data-jpa or spring-data-jdbc
Full-text search focus - Consider spring-data-elasticsearch
Graph relationships - Use spring-data-neo4j

Anti-Patterns

Anti-Pattern Problem Solution

Using @DBRef everywhere N+1 queries, slow Embed or manual references

Missing indexes Slow queries Add @Indexed, compound indexes

Fetching full documents Wasted bandwidth Use projections, fields()

Transactions without replica set Transactions fail Configure replica set

Documents > 16MB Insert fails Redesign, use GridFS for large files

Dynamic field types Query issues Use consistent schemas

Quick Troubleshooting

Problem Diagnostic Fix

Connection refused Check MongoDB running Start MongoDB, check URI

Duplicate key error Check @Id or unique index Handle or use upsert

Query returns empty Check field names Verify @Field mapping matches DB

Slow aggregation Check stages Add $match early, use indexes

Transaction fails Check replica set Configure replica set or remove transaction

Reference Documentation

Spring Data MongoDB Reference

spring-data-mongodb

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

cron-scheduling

token-optimization

webrtc