Spring Boot MongoDB: Document Modeling, Aggregation Pipelines & High-Performance Practices

Relational vs Document Modeling: Think About Read Patterns First

Traditional relational modeling (ER diagrams, normalization, foreign keys) becomes awkward in internet-scale scenarios, especially after sharding where cross-table JOINs are either banned or perform poorly. MongoDB flips this approach: it encourages aggregating a business entity into a single document so that all related data resides physically together and can be read in one operation without joins.

Take an e-commerce order as an example. A relational design splits data across order, order_item, product, and customer tables, requiring three-table JOINs that become painful at scale. In MongoDB, a single order document embeds everything: product snapshots, quantities, prices, and totals in a nested structure:

{
  "_id": "order_1001",
  "userId": "user_888",
  "createdAt": "2024-06-01T10:30:00Z",
  "items": [
    { "productId": "p_1", "name": "iPhone 15", "price": 6999, "qty": 1 },
    { "productId": "p_2", "name": "AirPods Pro", "price": 1899, "qty": 2 }
  ],
  "totalAmount": 10797
}

This modeling does not pursue normalization; it only cares about what the business needs at read time. When an order is loaded, all relevant data is already in the document, and it naturally supports sharding.

Relational databases excel at strict schemas, complex transactions, and multi-table analytical queries; MongoDB excels at flexibility, fast iteration, and high-concurrency reads/writes. Neither universally dominates — the choice depends on business shape. If entities have strong relationships and require complex SQL, relational remains reliable; if business objects are highly cohesive and schemas change frequently, MongoDB saves significant effort.

Embed vs Reference: One Rule — Look at How You Read

The most common MongoDB modeling question has a simple principle: if you always need the child data when reading the parent, the child set is bounded, and children don't change independently, embed; if children are queried separately, can grow unbounded, or are shared by multiple parents, reference.

Embedding provides locality: one I/O fetches the entire object tree. It suits order items, user addresses, product attributes — "one parent with a few children." But embedding cannot be abused: unbounded arrays like comments, logs, or messages quickly hit the 16 MB document limit, and every update rewrites the whole document at high cost.

Referencing stores only an _id and performs a second query at runtime. It fits articles and comments, users and roles, products and inventory. Inventory is a classic case: high-frequency updates and independent transactions; embedding it in the product document would cause frequent rewrites and write amplification.

Concrete example: a social platform post. The post embeds author info { userId: "u_1", nickname: "Alice" } but references comments via commentsRef: ["c_1", "c_2"]. Author info is a snapshot; if the user changes their nickname, old posts showing the old nickname is acceptable — no need to sync-update all posts. This intentional redundancy is far simpler than JOINs.

Spring Data MongoDB: Repository vs MongoTemplate

Spring Boot integration is straightforward: add the starter dependency and configure the connection URI (including replica set and connection pool parameters).

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

spring:
  data:
    mongodb:
      uri: mongodb://user:pass@host1:27017,host2:27018,host3:27019/dbname?replicaSet=rs0
      auto-index-creation: true

Entity definition uses @Document and @Id:

@Document(collection = "orders")
public class Order {
  @Id
  private String orderId;
  private String userId;
  private List<OrderItem> items;
  private BigDecimal totalAmount;
  private Instant createdAt;
  // getters/setters
}

public class OrderItem {
  private String productId;
  private String productName;
  private BigDecimal price;
  private Integer qty;
}

For simple semantic queries, MongoRepository is sufficient:

public interface OrderRepository extends MongoRepository<Order, String> {
  List<Order> findByUserId(String userId);
  Page<Order> findByCreatedAtBetween(Instant start, Instant end, Pageable pageable);
}

For complex queries, aggregation pipelines, dynamic conditions, or bulk updates, use MongoTemplate directly:

@Service
public class OrderQueryService {
  @Autowired
  private MongoTemplate mongoTemplate;

  public List<Order> findRecentOrders(int limit) {
    Query query = new Query();
    query.with(Sort.by(Sort.Direction.DESC, "createdAt"));
    query.limit(limit);
    return mongoTemplate.find(query, Order.class);
  }
}

Best practice: use Repository for simple semantic queries, MongoTemplate for complex aggregations and dynamic conditions — they can be mixed freely.

Aggregation Pipeline: Do Complex Statistics in the Database

The aggregation framework is a powerful pipeline model for filtering, grouping, projecting, unwinding arrays, sorting, and computing. Spring Data's Aggregation DSL lets you write pipelines in Java without hand-crafting JSON.

Common stages: $match: filter $group: group and aggregate $project: project and compute $unwind: unwind arrays $lookup: left join across collections

Example: sum sales by category. Each order document has an items array with category and amount fields.

public Map<String, BigDecimal> sumSalesByCategory() {
  Aggregation agg = Aggregation.newAggregation(
    Aggregation.unwind("items"),
    Aggregation.group("items.category")
      .sum("items.amount").as("totalAmount"),
    Aggregation.sort(Sort.by(Sort.Direction.DESC, "totalAmount"))
  );
  AggregationResults<CategorySales> results =
    mongoTemplate.aggregate(agg, "orders", CategorySales.class);
  return results.getMappedResults().stream()
    .collect(Collectors.toMap(CategorySales::getCategory, CategorySales::getTotalAmount));
}

Another example: UV by month and region. Since the aggregation framework doesn't support nested $group, first project year and month, then combine them in a single group:

Aggregation agg = Aggregation.newAggregation(
  Aggregation.project("region", "userId")
    .andExpression("year(createdAt)").as("year")
    .andExpression("month(createdAt)").as("month"),
  Aggregation.group("region", "year", "month")
    .addToSet("userId").as("uvSet"),
  Aggregation.project("region", "year", "month")
    .and("uvSet").size().as("uv")
);

addToSet

naturally deduplicates; size yields the UV count.

Top-N ranking: $match + $unwind + $group + $sort + $limit:

Aggregation agg = Aggregation.newAggregation(
  Aggregation.match(Criteria.where("status").is("PAID")),
  Aggregation.unwind("items"),
  Aggregation.group("items.productId")
    .sum("items.qty").as("totalQty")
    .avg("items.price").as("avgPrice"),
  Aggregation.sort(Sort.by(Sort.Direction.DESC, "totalQty")),
  Aggregation.limit(5)
);

The aggregation engine pushes down pipeline stages where possible; combined with indexes, million-row datasets return in milliseconds.

Multi-Document Transactions: Available but Not a Silver Bullet

MongoDB 4.0 introduced replica-set multi-document ACID transactions; 4.2 extended them to sharded clusters. Spring Data MongoDB 2.x supports @Transactional with JPA-like usage:

@Transactional
public void placeOrder(Order order, String userId, Product product, int qty) {
  orderRepository.save(order);
  productRepository.decreaseStock(product.getProductId(), qty);
  paymentRepository.insert(new Payment(...));
}

Prerequisites: replica set or sharded cluster (standalone not supported), WiredTiger storage engine (default). Cross-shard transactions in sharded clusters have additional constraints.

Transactions carry overhead: timestamp coordination, lock conflicts, snapshots, and per-document intent locks. Don't treat them as a cure-all. Strong-consistency scenarios like inventory deduction + order creation + payment require transactions; but async steps like sending SMS or updating analytics after order creation don't — use message queues for eventual consistency.

Techniques to avoid transactions:

Redesign document boundaries. Combine inventory, order, and payment into one document and use $inc atomic updates. Single-document operations are naturally atomic.

State machine pattern. Transition order status from "pending" to "paid" using conditional findAndModify + $set to ensure only valid state transitions.

Compensation mechanism. If a later step fails, run compensating tasks to roll back earlier successes, achieving eventual consistency.

Indexes: No Index Means Full Scan — Sooner or Later It Bites

Query performance depends entirely on indexes, just like relational databases. Spring Data can auto-create indexes via annotations, but production environments should manage them manually.

Composite index design principle: equality fields first, then sort fields, then range fields. For frequent queries by userId (equality) + createdAt (descending):

@Document(collection = "orders")
@CompoundIndex(def = "{'userId': 1, 'createdAt': -1}")
public class Order { ... }

Or programmatically:

mongoTemplate.indexOps("orders")
  .ensureIndex(new Index()
    .on("userId", Sort.Direction.ASC)
    .on("createdAt", Sort.Direction.DESC)
    .named("idx_user_created"));

Field order matters: high-cardinality equality fields first to prune data efficiently. Such a composite index also covers single-field userId queries.

In aggregation pipelines, $match and $sort should hit indexes. Filter on status → index status; sort by createdAt → index createdAt. $group doesn't benefit much from indexes; rely on $match early to reduce input volume.

TTL indexes are ideal for auto-expiring data like logs, sessions, verification codes:

@Document(collection = "sessions")
public class UserSession {
  @Id
  private String id;
  private String userId;
  @Indexed(expireAfterSeconds = 3600)
  private Instant lastAccess;
}

MongoDB periodically scans the TTL field and deletes expired documents. The field must be a date type and the index single-field.

Don't over-index: each write maintains indexes, adding overhead. Suggest ≤5 indexes per collection. Low-cardinality fields (e.g., boolean) are nearly useless. When in doubt, run explain() to inspect the query plan — don't guess.

Connection Pool & Cursors: Don't Exhaust Connections or Memory Under High Concurrency

The MongoDB Java driver includes a connection pool configurable via URI parameters:

spring:
  data:
    mongodb:
      uri: mongodb://localhost:27017/db?maxPoolSize=100&minPoolSize=10&maxIdleTimeMS=120000&waitQueueMultiple=5&waitQueueTimeoutMS=10000

Or programmatically:

@Bean
public MongoClientSettings mongoClientSettings() {
  return MongoClientSettings.builder()
    .applyToConnectionPoolSettings(builder -
      builder.maxSize(100)
        .minSize(10)
        .maxConnectionIdleTime(120, TimeUnit.SECONDS)
        .maxConnectionLifeTime(1, TimeUnit.HOURS))
    .build();
}

maxPoolSize

shouldn't be too large (default 100 is usually enough); excessive sizes exhaust file descriptors and memory. maxIdleTimeMS reclaims idle connections to prevent staleness. waitQueueMultiple bounds the wait queue; exceeding it fails fast to avoid thread pile-up.

For huge result sets (hundreds of thousands to millions of rows), loading all into memory causes OOM. Use cursor streaming:

try (CloseableIterator<Order> iterator = mongoTemplate.stream(query, Order.class)) {
  while (iterator.hasNext()) {
    process(iterator.next());
  }
}

Repository can also return a Stream — remember to close it:

try (Stream<Order> stream = orderRepository.findByCreatedAtAfter(start)) {
  stream.forEach(this::process);
}

Cursors hold a connection during iteration, so processing must be fast; avoid slow remote calls inside the loop, or the pool will be exhausted.

For user-facing lists, use proper pagination:

Page<Order> page = orderRepository.findByUserId(userId,
  PageRequest.of(0, 20, Sort.by("createdAt").descending()));

Never use skip(1000000).limit(20) — deeper pages get slower. For massive lists, use cursor-based pagination: query by the last seen _id or sort value:

Query query = new Query();
query.addCriteria(Criteria.where("_id").gt(lastId));
query.limit(20);
query.with(Sort.by(Sort.Direction.ASC, "_id"));

This approach's performance is independent of page depth, making it suitable for large datasets.

Summary

MongoDB doesn't replace relational databases; it solves specific pain points where relational models struggle. Spring Data MongoDB provides comprehensive support from entity mapping to aggregation pipelines, transaction control, and index management. The key is understanding your business:

Model around read patterns — decide embed vs reference to minimize JOINs and associated queries.

Use aggregation pipelines for statistics — don't pull data to the application layer for computation.

Avoid transactions when possible; prefer single-document atomic operations and eventual consistency.

Optimize performance starting with indexes and connection pooling; use cursors and cursor-based pagination for large data volumes.

In today's fast-iterating, ever-growing data landscape, the MongoDB + Spring Boot combination remains highly effective. These practices aim to help you avoid common pitfalls in real projects.