vtex-io-masterdata-strategy

マスターデータ戦略

このスキルを使用する場面

VTEX IO アプリのカスタムデータに Master Data v2 が適切な仕組みかどうかを判断するときに、このスキルを使用します。

• レビュー、ウィッシュリスト、フォーム、カスタムアプリレコードのモデリング
• エンティティ境界の選定
• スキーマのインデックス作成とライフサイクルの計画
• 長期的な Master Data 設計のレビュー

以下には、このスキルを使用しないでください。

• 低レベルのクライアント使用方法の詳細
• ランタイムやルートの構造
• アプリ設定スキーマ
• フロントエンドの UI 動作

判断ルール

• Master Data が有力なストレージ候補になった時点で、このスキルを使用します。Master Data、VBase、VTEX コア API、外部ストアのより広範な選択には、vtex-io-data-access-patterns を使用します。
• 検証、インデックス作成、クエリのサポートが必要な構造化カスタムデータには、Master Data を使用します。
• このアプリで新しいビジネスエンティティを導入し、データモデルを所有し、アプリの契約の一部としてスキーマを作成・バージョン管理する場合は、masterdata ビルダーを使用します。
• エンティティとスキーマがすでに存在し、共有または一元管理されている場合、このアプリがスキーマ自体を再定義せずにレコードの読み取りや書き込みのみを行うのであれば、Master Data クライアントのみを使用することを優先します。
• アプリが所有する安定したスキーマについて、アプリのバージョンごとに再作成または更新すべきでない場合は、スキーマ定義をコード内に保持し、必要な場合にのみ制御されたセットアップ手順で Master Data クライアントを使用してスキーマを作成または更新します。
• Master Data エンティティはアカウント単位であることを忘れないでください。共有エンティティやスキーマを変更すると、そのアカウントでそれに依存するすべてのアプリに影響するため、スキーマが一元管理されている場合はクライアントのみで利用することを優先します。
• エンティティ境界は意図的に設け、保存するビジネス概念に沿わせます。
• 実際にフィルタリングや検索に使用するフィールドにインデックスを作成します。
• スキーマの乱立を避けるため、スキーマのライフサイクルを明確に計画します。
• 最初からデータ量と保持期間を考慮します。データセットが際限なく増加し、保持またはアーカイブ戦略がない場合、Master Data は適切なストレージの仕組みではない可能性が高いです。
• Master Data を、任意のペイロードを無制限に放り込む場所として扱わないでください。
• 大量の追記専用データに対する、無制限のログやイベントストアとして Master Data を使用しないでください。構造化クエリよりも生の履歴が主な要件である場合は、専用のログ記録またはストレージの仕組みを優先します。
• シークレット、認証情報、グローバルなアプリ設定を Master Data に保存しないでください。代わりにアプリ設定または設定アプリを使用します。
• アカウント、ワークスペース、機能フラグごとにエンティティやスキーマを作成しないでください。エンティティ名は安定させ、必要に応じてレコードのフィールドでテナントや環境を区別します。
• masterdata ビルダーを通じてスキーマの進化をアプリのバージョン管理に直接結び付ける場合は注意してください。アプリのリリースに伴う頻繁なスキーマ変更は、過剰なスキーマ更新やインデックス変更、長期的なスキーマの乱立につながる可能性があります。

masterdata ビルダーと Master Data クライアントの使い分け

VTEX IO アプリが Master Data を扱う方法は、主に 3 つあります。

• masterdata ビルダーを使ってスキーマを管理する：

  • アプリはリポジトリ内の masterdata/ にエンティティとスキーマを宣言します。
  • スキーマのフィールド、検証、インデックスはアプリのコードとともに進化します。
  • アプリがデータモデルの主な管理者であり、スキーマ変更の頻度が比較的低く、アプリのコントラクトの一部としてスキーマを展開する必要がある場合に使用します。

• Master Data クライアントのみを使って既存のスキーマを利用する：

  • アプリは Master Data クライアントを使用しますが、masterdata ビルダーを通じてエンティティやスキーマを宣言しません。
  • アプリは別の場所で管理されている安定したスキーマを前提とし、そのコントラクトに沿ったレコードの読み取りまたは書き込みのみを行います。
  • エンティティが複数のアプリで共有されている、または一元管理されており、このアプリが環境ごとにスキーマを再定義したり分割したりすべきでない場合に使用します。

• 安定したスキーマ定義をコードで管理し、クライアントを通じて適用する：

  • アプリは masterdata/ ビルダーファイルではなく、安定したスキーマ定義をコード内に保持します。
  • 管理されたセットアップ手順でスキーマの有無を確認し、必要な場合にのみ作成または更新します。
  • アプリが実際にスキーマを管理するものの、スキーマの展開をアプリのすべてのバージョンやリリースパイプラインの各ステップに結び付けるべきでない場合に使用します。

厳守すべき制約

制約：Master Data のエンティティには明確なスキーマ境界が必要です

各エンティティは明確なビジネス上の概念を表し、想定される用途に合ったスキーマを持つ必要があります。

重要な理由

エンティティの境界が曖昧だと、クエリが分かりにくくなり、適切でないインデックスが選択され、スキーマのずれが生じます。

検出方法

1 つのエンティティに無関係な概念が混在している、または無関係なレコード形式を多数格納している場合は、作業を停止して設計を分割してください。

正しい例

{
  "title": "review-schema-v1",
  "type": "object",
  "properties": {
    "productId": { "type": "string" },
    "userId": { "type": "string" },
    "rating": { "type": "number" },
    "approved": { "type": "boolean" }
  },
  "required": ["productId", "userId", "rating"],
  "v-indexed": ["productId", "userId", "approved"]
}

誤った例

{
  "title": "everything-schema",
  "type": "object"
}

制約：インデックス付きフィールドは実際のクエリ動作に合わせる必要があります

フィルターや検索に使うフィールドには、意図的にインデックスを設定する必要があります。

重要な理由

インデックスがないと、クエリの動作が悪化し、不必要な運用リスクが生じます。

検出方法

インデックス戦略に含まれていないフィールドにクエリが依存している場合は、作業を停止してスキーマとアクセスパターンを一致させてください。

正しい例

{
  "v-indexed": ["productId", "approved"]
}

誤った例

{
  "v-indexed": []
}

制約：スキーマのライフサイクルを明示的に管理する必要があります

Master Data のスキーマ変更は、クリーンアップとバージョン管理を考慮して計画する必要があります。

重要な理由

管理されていないスキーマの増加は、長期的な運用上の負担を生み、プラットフォームの上限に達する可能性があります。

検出方法

ライフサイクルやクリーンアップの計画なしにスキーマバージョンを追加している場合は、作業を停止して計画を策定してください。

正しい例

review-schema-v1 -> review-schema-v2 with cleanup plan

誤った例

review-schema-v1, v2, v3, v4, v5 with no cleanup strategy

インデックス付きフィールドやフィールドの型を変更すると、既存のドキュメントのインデックス作成方法やクエリ方法に影響する可能性があることを忘れないでください。スキーマの変更を頻繁なアプリのバージョン変更に結び付けると、このリスクは高まります。

制約：エンティティ名とスキーマ名は環境間で安定させる必要があります

エンティティ名とスキーマ識別子は、アカウント、ワークスペース、環境をまたいで安定させる必要があります。アカウント名、ワークスペース、ロールアウトフラグをエンティティ名やスキーマ名自体に含めないでください。

重要な理由

アカウントやワークスペースごとにスキーマ名を付けると、スキーマが乱立し、ライフサイクル管理が難しくなり、後から解消しにくい運用上の制限が生じます。

検出方法

ワークスペース、アカウント、環境ごとにエンティティやスキーマを作成する設計になっている場合は、作業を停止し、スコープ付きフィールドやレコードを使った安定した名前を中心とする設計に見直してください。

正しい例

review-schema-v1
RV

誤った例

review-schema-brazil-master
RV_US_MASTER

開発用と本番用に、それぞれ適切に管理されたスキーマを 1 つずつ使用する方法は、両者を同期させる明確な計画がある場合に適切です。ワークスペース、アカウント、フィーチャーフラグごとにスキーマ名を生成するのは避けてください。

推奨パターン

構造化されたカスタムレコードには Master Data を使用し、クエリ対象のフィールドだけにインデックスを設定し、スキーマの進化を計画的に進めます。

例：masterdata ビルダーでスキーマを管理するアプリ

• masterdata/review-schema-v1.json で、RV エンティティのスキーマとインデックスを宣言します。
• アプリは専用の Master Data クライアントを使用して、RV ドキュメントを作成し、クエリします。

{
  "title": "review-schema-v1",
  "v-entity": "RV",
  "type": "object",
  "properties": {
    "productId": { "type": "string" },
    "userId": { "type": "string" },
    "rating": { "type": "number" },
    "approved": { "type": "boolean" }
  },
  "required": ["productId", "userId", "rating"],
  "v-indexed": ["productId", "userId", "approved"]
}

例：クライアントのみを使用して既存のスキーマを利用するアプリ

• このアプリでは masterdata ビルダーファイルを宣言しません。
• 別の場所で管理されている、既存の安定した RV エンティティに対して Master Data クライアントを使用します。

await ctx.clients.masterdata.createDocument({
  dataEntity: 'RV',
  fields: {
    productId,
    userId,
    rating,
    approved: false,
  },
})

例：安定したスキーマをコードで管理し、クライアントを通じて確実に存在させるアプリ

• アプリでは、安定したスキーマ定義をコード内に保持します。
• すべてのロールアウトで masterdata ビルダーに依存するのではなく、管理されたセットアップ手順によってスキーマの存在を確保します。

const schema = {
  title: 'review-schema-v1',
  'v-entity': 'RV',
}

const existing = await ctx.clients.masterdata.getSchema('review-schema-v1')

if (!existing) {
  await ctx.clients.masterdata.createOrUpdateSchema('review-schema-v1', schema)
}

よくある失敗パターン

• 範囲が広すぎるエンティティを作成する。
• インデックスが設定されていないフィールドでクエリする。
• ライフサイクル計画なしに、スキーマのバージョンを増やし続ける。
• 保持やアーカイブの戦略なしに、大量のログやイベントの格納先として Master Data を使用する。
• 設定固有の仕組みを使わず、構成、シークレット、アプリ間で共有する設定を Master Data に保存する。
• RV_storeA_master のようなアカウントごとまたはワークスペースごとのエンティティを生成するのではなく、スコープ付きレコードフィールドを持つ RV のような安定したエンティティを使用します。
• アプリのバージョンごとに頻繁なスキーマ変更を masterdata ビルダーに依存させ、時間の経過とともに過剰なスキーマ更新やインデックス設定の副作用を引き起こす。

レビューチェックリスト

• このユースケースに Master Data は適切なストレージ機構ですか？
• このアプリは masterdata ビルダーでスキーマを管理するべきですか。それとも、クライアントを通じて既存の安定したスキーマを利用するだけでよいですか？
• スキーマのロールアウトをすべてのアプリバージョンに連動させるより、コード内の安定したスキーマと管理されたセットアップ手順を組み合わせるほうが安全ですか？
• 各エンティティは明確なビジネス概念を表していますか？
• エンティティ名とスキーマ名は、ワークスペースやアカウントをまたいで安定していますか？
• フィルター対象のフィールドには、意図的にインデックスが設定されていますか？
• スキーマのライフサイクル計画はありますか？
• 開発と本番で異なるスキーマを使用する場合、スキーマが増えすぎないようにしながら同期を保つ明確な計画はありますか？

関連スキル

• vtex-io-data-access-patterns - 特定のデータセットに対して Master Data、VBase、VTEX コア API、外部ストアのどれを使うか判断する場合に使用します。

リファレンス

• Master Data - プラットフォームのデータストレージに関する情報