using-document-databases

ドキュメントデータベースの実装

Python、TypeScript、Rust、Go で、柔軟なスキーマを持つアプリケーション向けに NoSQL ドキュメントデータベースを選定し、実装するためのガイドです。

このスキルを使用するタイミング

次のような要件があるアプリケーションでは、ドキュメントデータベースを使用してください。

• 柔軟なスキーマ - マイグレーションなしでデータモデルを迅速に進化させられます
• ネストされた構造 - JSON のような階層データを扱えます
• 水平スケーリング - シャーディングとレプリケーションが組み込まれています
• 開発の迅速化 - ORM の複雑さを伴わずに、オブジェクトをデータベースへマッピングできます

データベースの選定

選定の簡易フレームワーク

DEPLOYMENT ENVIRONMENT?
├── AWS-Native Application → DynamoDB
│   ✓ Serverless, auto-scaling, single-digit ms latency
│   ✗ Limited query flexibility
│
├── Firebase/GCP Ecosystem → Firestore
│   ✓ Real-time sync, offline support, mobile-first
│   ✗ More expensive for heavy reads
│
└── General-Purpose/Complex Queries → MongoDB
    ✓ Rich aggregation, full-text search, vector search
    ✓ ACID transactions, self-hosted or managed

データベースの比較

データベース	最適な用途	レイテンシ	最大アイテムサイズ	クエリ言語
MongoDB	汎用、複雑なクエリ	1-5ms	16MB	MQL（豊富）
DynamoDB	AWS サーバーレス、予測可能なパフォーマンス	<10ms	400KB	PartiQL（限定的）
Firestore	リアルタイムアプリ、モバイルファースト	50-200ms	1MB	Firebase クエリ

MongoDB の詳細は references/mongodb.md を参照してください DynamoDB のシングルテーブル設計は references/dynamodb.md を参照してください Firestore のリアルタイムパターンは references/firestore.md を参照してください

スキーマ設計パターン

埋め込みと参照

判断マトリックスは references/schema-design-patterns.md を使用してください

簡易ガイド：

関係	パターン	例
1対少数	埋め込み	ユーザーの住所（最大2～3件）
1対多	ハイブリッド	ブログ記事 → コメント
1対数百万	参照	ユーザー → イベント（ログ記録）
多対多	参照	商品 ↔ カテゴリ

埋め込みの例（MongoDB）

// User with embedded addresses
{
  _id: ObjectId("..."),
  email: "[email protected]",
  name: "Jane Doe",
  addresses: [
    {
      type: "home",
      street: "123 Main St",
      city: "Boston",
      default: true
    }
  ],
  preferences: {
    theme: "dark",
    notifications: { email: true, sms: false }
  }
}

参照の例（Eコマース）

// Orders reference products
{
  _id: ObjectId("..."),
  userId: ObjectId("..."),
  items: [
    {
      productId: ObjectId("..."),      // Reference
      priceAtPurchase: 49.99,          // Denormalize (historical)
      quantity: 2
    }
  ],
  totalAmount: 99.98
}

非正規化するタイミング：

• 頻繁に一緒に読み取られるデータ
• 履歴スナップショット（価格、名前）
• 読み取り負荷の高いワークロード

インデックス戦略

MongoDB のインデックスタイプ

// 1. Single field (unique email)
db.users.createIndex({ email: 1 }, { unique: true })

// 2. Compound index (ORDER MATTERS!)
db.orders.createIndex({ status: 1, createdAt: -1 })

// 3. Partial index (index subset)
db.orders.createIndex(
  { userId: 1 },
  { partialFilterExpression: { status: { $eq: "pending" }}}
)

// 4. TTL index (auto-delete after 30 days)
db.sessions.createIndex(
  { createdAt: 1 },
  { expireAfterSeconds: 2592000 }
)

// 5. Text index (full-text search)
db.articles.createIndex({
  title: "text",
  content: "text"
})

インデックスのベストプラクティス：

• すべてのクエリフィルターにインデックスを追加します
• 複合インデックスの順序：等価条件 → 範囲条件 → ソート
• カバリングインデックスを使用します（クエリとプロジェクションをインデックスに含めます）
• explain() を使用してインデックスの利用を確認します
• Performance Advisor（Atlas）で監視します

スクリプトでインデックスを検証します：

python scripts/validate_indexes.py

完全なガイドは references/indexing-strategies.md を参照してください。

MongoDB 集約パイプライン

主な演算子： $match（フィルター）、$group（集約）、$lookup（結合）、$unwind（配列）、$project（再構成）

パイプラインの完全なパターンと例は、こちらを参照してください： references/aggregation-patterns.md

DynamoDB のシングルテーブル設計

PK/SK パターンを使用してアクセスパターンを設計します。複合キーを使い、1つのテーブルに複数のエンティティタイプを格納します。

シングルテーブル設計の完全なパターンと GSI 戦略は、こちらを参照してください： references/dynamodb.md

Firestore のリアルタイムパターン

リアルタイムリスナーには onSnapshot() を使用し、アクセス制御には Firestore セキュリティルールを使用します。

リアルタイムパターンとセキュリティルールの詳細は、こちらを参照してください： references/firestore.md

複数言語の例

完全な実装は examples/ ディレクトリにあります：

• examples/mongodb-fastapi/ - Python FastAPI + MongoDB
• examples/mongodb-nextjs/ - TypeScript Next.js + MongoDB
• examples/dynamodb-serverless/ - Python Lambda + DynamoDB
• examples/firestore-react/ - React + Firestore リアルタイム処理

フロントエンドスキルとの連携

• メディアスキル - メタデータとともに大容量ファイルを保存するには、MongoDB GridFS を使用します
• AI チャットスキル - 意味に基づく会話の検索には、MongoDB Atlas Vector Search を使用します
• フィードバックスキル - TTL を使用した高スループットのイベントログ記録には、DynamoDB を使用します

連携例は、こちらを参照してください： references/skill-integrations.md

パフォーマンスの最適化

主な実践方法：

• クエリフィルターには必ずインデックスを使用します（.explain() で確認します）
• コネクションプーリングを使用します（リクエスト間でクライアントを再利用します）
• 本番環境でコレクションスキャンを避けます

最適化の完全なガイドは、こちらを参照してください： references/performance.md

よく使われるパターン

ページネーション： 大規模なデータセットでは、オフセット方式よりも推奨されるカーソルベースのページネーションを使用します。 論理削除： データを削除する代わりに、削除日時を記録して削除済みとしてマークします。 監査ログ： ドキュメント内にバージョン履歴を保存します。

実装の詳細については、次を参照してください： references/common-patterns.md

検証とスクリプト

インデックスのカバレッジを検証する

# Run validation script
python scripts/validate_indexes.py --db myapp --collection orders

# Output:
# ✓ Query { status: "pending" } covered by index status_1
# ✗ Query { userId: "..." } missing index - add: { userId: 1 }

スキーマ分析

# Analyze schema patterns
python scripts/analyze_schema.py --db myapp

# Output:
# Collection: users
# - Average document size: 2.4 KB
# - Embedding ratio: 87% (addresses, preferences)
# - Reference ratio: 13% (orderIds)
# Recommendation: Good balance

避けるべきアンチパターン

上限のない配列： 埋め込み配列のサイズを制限します（大規模なコレクションには参照を使用します）。 過剰なインデックス作成： クエリ対象のフィールドにのみインデックスを作成します（インデックスは書き込みを遅くします）。 DynamoDB のスキャン： 常にパーティションキーを指定して Query を使用し、Scan は避けます。

アンチパターンの詳細については、次を参照してください： references/anti-patterns.md

依存関係

Python

# MongoDB
pip install motor pymongo

# DynamoDB
pip install boto3

# Firestore
pip install firebase-admin

TypeScript

# MongoDB
npm install mongodb

# DynamoDB
npm install @aws-sdk/client-dynamodb @aws-sdk/util-dynamodb

# Firestore
npm install firebase firebase-admin

Rust

# MongoDB
mongodb = "2.8"

# DynamoDB
aws-sdk-dynamodb = "1.0"

Go

# MongoDB
go get go.mongodb.org/mongo-driver

# DynamoDB
go get github.com/aws/aws-sdk-go-v2/service/dynamodb

追加リソース

データベース別ガイド：

• references/mongodb.md - MongoDB の完全なドキュメント
• references/dynamodb.md - DynamoDB の単一テーブルパターン
• references/firestore.md - Firestore のリアルタイムガイド

パターンガイド：

• references/schema-design-patterns.md - 埋め込みと参照の使い分け
• references/indexing-strategies.md - インデックスの最適化
• references/aggregation-patterns.md - MongoDB パイプラインのレシピ集
• references/common-patterns.md - ページネーション、論理削除、監査ログ
• references/anti-patterns.md - 避けるべき間違い
• references/performance.md - クエリの最適化
• references/skill-integrations.md - フロントエンドスキルとの統合

例： examples/mongodb-fastapi/、examples/mongodb-nextjs/、examples/dynamodb-serverless/、examples/firestore-react/