# Mongodb Schema Design

MongoDB schema design patterns and anti-patterns.

- Repository: https://github.com/fcakyon/claude-codex-settings (1195 stars)
- Category: Design
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add fcakyon/claude-codex-settings --skill mongodb-schema-design -g -a claude-code -y`
Codex: `npx skills add fcakyon/claude-codex-settings --skill mongodb-schema-design -g -a codex -y`
Cursor: `npx skills add fcakyon/claude-codex-settings --skill mongodb-schema-design -g -a cursor -y`
Gemini CLI: `npx skills add fcakyon/claude-codex-settings --skill mongodb-schema-design -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add fcakyon/claude-codex-settings`

## Description

MongoDB schema design patterns and anti-patterns. Use when designing data models, reviewing schemas, migrating from SQL, or troubleshooting performance issues caused by schema problems. Triggers on "design schema", "embed vs reference", "MongoDB data model", "schema review", "unbounded arrays", "one-to-many", "tree structure", "16MB limit", "schema validation", "JSON Schema", "time series", "schema migration", "polymorphic", "TTL", "data lifecycle", "archive", "index explosion", "unnecessary indexes", "approximation pattern", "document versioning".

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# MongoDB Schema Design

Data modeling patterns and anti-patterns for MongoDB, maintained by MongoDB. Bad schema is the root cause of most MongoDB performance and cost issues, queries and indexes cannot fix a fundamentally wrong model.

## When to Apply

Reference these guidelines when:
- Designing a new MongoDB schema from scratch
- Migrating from SQL/relational databases to MongoDB
- Reviewing existing data models for performance issues
- Troubleshooting slow queries or growing document sizes
- Deciding between embedding and referencing
- Modeling relationships (one-to-one, one-to-many, many-to-many)
- Implementing tree/hierarchical structures
- Seeing Atlas Schema Suggestions or Performance Advisor warnings
- Hitting the 16MB document limit
- Adding schema validation to existing collections

## Quick Reference

### 1. Schema Anti-Patterns - 3 rules

- [antipattern-unnecessary-collections](references/antipattern-unnecessary-collections.md) - Splitting homogeneous data into multiple collections is often an anti-pattern; consult this reference to validate whether this is the case.
- [antipattern-excessive-lookups](references/antipattern-excessive-lookups.md) - When encountering overly normalized collections that reference each other or frequent and possibly slow $lookup operations, consult this reference to validate whether this is problematic and how to fix it.
- [antipattern-unnecessary-indexes](references/antipattern-unnecessary-indexes.md) - Consult this reference when indexes overlap or are not used by queries, to identify and remove unnecessary indexes that add overhead without benefit.

### 2. Schema Fundamentals - 4 rules

The rest: https://github.com/fcakyon/claude-codex-settings/blob/HEAD/plugins/mongodb-skills/skills/mongodb-schema-design/SKILL.md