graph-schema

dot-skills グラフデータベースのスキーマ設計に関するベストプラクティス

プロパティグラフ（Neo4j、Memgraph、Amazon Neptune など）の包括的なグラフデータベースデータモデリングガイドです。重要度の高いもの（エンティティ分類、リレーションシップ設計）から段階的な改善（規模と進化）まで、モデリングへの影響度に基づいて優先順位付けされた8カテゴリ・46のルールを収録しています。各ルールには詳細な説明、誤ったモデルと適切なモデルを比較する実践的な Cypher の例、具体的な影響の説明が含まれています。

基本方針： まずデータモデリングの正確性を優先し、その次にパフォーマンスを考慮します。構造を選ぶ前に、必ず「ユーザーが達成しようとしていることは何か？」と問いかけてください。

適用する場面

次のような場合に、これらのガイドラインを参照してください。

• ドメイン要件に基づいて新しいグラフデータベースのスキーマを設計するとき
• リレーショナルスキーマをグラフモデルに変換するとき
• ある要素をノード、リレーションシップ、プロパティのどれにするか判断するとき
• 既存のグラフスキーマにモデリング上の誤りがないか確認するとき
• 扱いにくいクエリや遅いクエリを生み出すグラフをリファクタリングするとき
• スキーマの進化とデータの増加に備えるとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響	プレフィックス
1	エンティティ分類	CRITICAL	entity-
2	リレーションシップ設計	CRITICAL	rel-
3	プロパティの配置	HIGH	prop-
4	クエリに基づく改善	HIGH	query-
5	構造パターン	HIGH	pattern-
6	アンチパターン	MEDIUM	anti-
7	制約と整合性	MEDIUM	constraint-
8	規模と進化	LOW-MEDIUM	scale-

クイックリファレンス

1. エンティティ分類（CRITICAL）

• entity-events - 複数の参加者が関わるイベントを第一級ノードとしてモデル化する
• entity-shared-values - 共有されるプロパティ値をノードに昇格させる
• entity-specific-labels - 汎用的なラベルではなく、具体的なラベルを使う
• entity-multi-label - 複数のラベルでエンティティを分類する
• entity-identity-state - 識別情報と変更可能な状態を分離する
• entity-reify-actions - ライフサイクル上のアクションをノードとして実体化する
• entity-avoid-god-nodes - 何でも詰め込んだエンティティノードを避ける

2. リレーションシップ設計（CRITICAL）

• rel-specific-types - 汎用的なものではなく、具体的なリレーションシップタイプを使う
• rel-meaningful-direction - 意味的に適切な方向を選ぶ
• rel-naming-conventions - リレーションシップタイプには UPPER_SNAKE_CASE を使用する
• rel-no-redundant-reverse - 冗長な逆方向のリレーションシップを作成しない
• rel-properties-scope - データが接続を表す場合にのみ、リレーションシップに配置する
• rel-single-semantic - 1つの意味ごとに1種類のリレーションシップタイプを使う
• rel-typed-over-filtered - 汎用タイプとプロパティフィルターの組み合わせより、型付きリレーションシップを優先する

3. プロパティの配置（HIGH）

• prop-no-foreign-keys - 外部キーをプロパティとして埋め込まない
• prop-promote-to-node - 頻繁にクエリされる値をノードに昇格させる
• prop-correct-data-types - プロパティには適切なデータ型を使う
• prop-no-arrays-for-connections - リレーションシップが必要な場合にプロパティ配列を使わない
• prop-relationship-vs-node-data - データをリレーションシップとノードのどちらに配置すべきかを判断する

4. クエリ駆動の改善（HIGH）

• query-critical-traversals - 最も重要なトラバーサルを優先して設計します
• query-shortcut-relationships - 頻繁に行う複数ホップのクエリには、ショートカットとなるリレーションシップを追加します
• query-denormalize-reads - 読み取りが多いパスでは非正規化します
• query-filter-by-rel-props - リレーションシップのプロパティを使用してトラバーサルをフィルタリングします
• query-test-before-deploy - デプロイ前に実際のクエリでモデルをテストします

5. 構造パターン（HIGH）

• pattern-intermediary-nodes - 複数のエンティティ間のリレーションシップには中間ノードを使用します
• pattern-hierarchy - カテゴリノードと深さを表すリレーションシップで階層をモデル化します
• pattern-linked-list - 順序付きシーケンスには連結リストを使用します
• pattern-timeline-tree - 時系列データにはタイムラインツリーを適用します
• pattern-fan-out - イベントストリームやアクティビティフィードにはファンアウトパターンを使用します
• pattern-bipartite - コンテキストを伴う多対多の関係には二部構造を使用します

6. アンチパターン（MEDIUM）

• anti-join-table-nodes - リレーショナルデータベースの結合テーブルをノードとしてモデル化しないでください
• anti-generic-relationships - 汎用的な RELATED_TO や CONNECTED リレーションシップを使用しないでください
• anti-relational-porting - リレーショナルスキーマをそのままグラフに移植しないでください
• anti-over-modeling - すべてをノードにしないでください
• anti-duplicate-data - リレーションシップを作成する代わりにデータを重複させないでください
• anti-string-encoded-structure - 構造化データを区切り文字列としてエンコードしないでください

7. 制約と整合性（MEDIUM）

• constraint-unique-identifiers - 自然識別子に一意性制約を定義します
• constraint-existence - 必須プロパティには存在制約を使用します
• constraint-index-traversals - トラバーサルの開始点となるプロパティにインデックスを作成します
• constraint-no-over-index - インデックスを過剰に作成しないでください。各インデックスには書き込みコストが伴います
• constraint-node-key - 自然な複合識別子には複合ノードキーを使用します

8. スケールと進化（LOW-MEDIUM）

• scale-supernode-mitigation - ファンアウトまたはパーティショニングでスーパーノードを軽減します
• scale-temporal-versioning - 現在の状態と履歴状態を分離します
• scale-schema-migration - ラベルとリレーションシップタイプの変更を計画します
• scale-batch-refactoring - スキーマのリファクタリングには APOC またはバッチクエリを使用します
• scale-dense-node-detection - 新たに発生するスーパーノードを監視、検出します

使用方法

詳しい説明とコード例については、各リファレンスファイルを参照してください。

• セクションの定義 - カテゴリの構造と影響度
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報