algolia-data-modeling

Algolia のデータモデリング

このスキルは、コードで Algolia にレコードを書き込む前にデータを整えるために使用します。関連性の高い検索は通常、ソースデータベースのスキーマではなく、ユーザーの利用経路に合ったレコードから始まります。

顧客向け標準

• レコードの形について判断を示す前に、サンプルレコードとエッジケースを確認します。
• ソースデータが不足している場合は、前提を明確に述べます。
• 学習内容との整合性を確認するには公開されている academy.algolia.com を、最新の実装ガイダンスが必要な場合は公開されている algolia.com/doc を使用します。
• Academy のメタデータ参照パックが利用可能な場合は、構成のために title、url、course、module、learning_objectives、updated_at の各フィールドのみを使用します。情報が古い場合や該当するものがない場合は、最新の Academy／ドキュメントを検索します。キャッシュされたメタデータをコースの内容や実装の根拠として扱わないでください。
• Academy／ドキュメントへの特別なアクセスは求めないでください。顧客が提供するソースは、任意のコンテキストとしてのみ使用します。
• ライブの Algolia データ、分析、インデックスの調査、設定変更、またはアカウント操作が必要な場合は、ライブ操作に Algolia MCP、Algolia CLI、または公式の Algolia スキルを使用してから、このスキルを適用して結果を解釈し、顧客に提示できる実装手順を検証します。
• インデックス作成の契約、検証クエリ、担当者への引き継ぎ、再インデックス／更新の手順を提示します。
• E コマースカタログでは、マーチャンダイジングや UI の動作について説明する前に、バリアント単位、バリエーショングループ単位、商品単位のどのレコードモデルを採用するかを明確に選択します。

公式の関連スキル

• ライブのサンプルレコード、既存のインデックス構造、オブジェクト数、インポート、エクスポートを調査する必要がある場合は、公式の algolia-mcp または algolia-cli を使用します。
• 公式ツールの呼び出し後にこのスキルを使用し、調査結果を顧客向けのインデックス作成契約、バリアント戦略、検証計画にまとめます。

情報源に関するルール

• データベースのテーブルだけから最終的なレコードモデルを推測しないでください。サンプルレコード、UI の期待動作、イベント要件、更新の担当者を確認します。
• ライブ操作を公式の algolia-cli、algolia-mcp、または最新のドキュメントを通さずに、具体的な Algolia の設定、API コマンド、移行手順を指示しないでください。
• 安定した ID、バリアントの所有者、タイムスタンプの所有者、在庫戦略、イベント識別子が定まっていないスキーマは、暫定的なものとして扱います。
• レコードのインデックス作成や UI の実装を開始する前に、可能な場合はインデックス契約を作成または更新します。簡易なプロトタイプが必要な場合は、最低限の暫定契約で進め、見直しが必要な前提を列挙します。
• マーチャンダイジングルールを、マーチャンダイジングデータの不足を補う代わりとして扱わないでください。新しさ、セール状況、ブランドの所有権、在庫、ベストセラー状況、利益率、人気度は、明示的なフィールドにするか、上流で計算する方法を文書化する必要があります。

インデックス契約の判断ポイント

インデックス作成や UI の作業を始める前に、可能な場合は algolia/index-contract.md または同等の成果物を作成します。完全な契約がないまま進める場合は、どの判断が暫定的なのかを明示します。

• インデックス名。
• レコードモデル：バリアント単位、バリエーショングループ単位、商品単位、または E コマース以外の同等モデル。
• レコードの粒度。
• objectID の戦略。
• 検索可能な属性。
• 表示する属性。
• ファセット対象の属性。
• ランキングシグナル。
• ランキング指標の粒度、順序、方向、精度、バケットのロジック。
• マーチャンダイジングのフィールド。
• 在庫フィールド。
• イベント帰属フィールド。
• 更新の担当者と頻度。
• 検証クエリ。

デモやプロトタイプでは、1 段落のデータ契約、3 つの検証クエリ、本番環境向けに先送りする懸念事項を明示します。

ワークフロー

1. データ形状を決定する前に、references/data-modeling-guide.mdを読んでください。
2. 顧客向けのインデックス契約を作成するとき、または適切な出力例を示すときは、references/example-output.mdを読んでください。
3. レコードの粒度、ビジネス目標、または絞り込み要件が不明な場合は、コンテキストを尋ねてください。
4. まずインデックス契約を設計します。インデックス名、環境、objectID 戦略、レコード形状、検索可能属性、ファセット属性、ランキングシグナル、更新の責任範囲を決めます。
5. コードを書く前に、バリアント戦略を選択します。商品レコード、バリアントレコード、バリアントのグループ化、またはロケール、地域、テナント、チャネル、価格表、権限セットごとに分けたレコードのいずれかを選びます。
6. インデックス作成前に、マーチャンダイジング関連のデータギャップを確認します。スキーマの明確さ、タイムスタンプ／新しさ、プロモーション属性、在庫区分、ベストセラー区分、利益率／人気度の指標、指標の精度、上流システムの責任範囲を確認してください。
7. 非正規化された、検索に適したレコードを優先してください。クエリ時に重要なランキング／絞り込みフィールドを結合したり推測したりするよう、UI に強いることは避けてください。
8. カスタムランキングの入力値は、生のデータベースダンプではなく、ビジネス上のタイブレーカーとして設計してください。どの指標を優先するか、値が大きいほうと小さいほうのどちらがよいか、後続のランキング属性が同点時にも影響できるよう値を丸めるか区分化するかを決めます。
9. objectID、レコードの粒度、または関連性に影響する設定を変更する場合は、移行と再インデックスの計画を含めてください。
10. 多くのマーチャンダイジング上の問題は、まずデータ準備の問題であることをビジネスユーザーに説明してください。新商品、セール品、自社ブランド、高在庫、高利益率、人気商品、ベストセラーを示す情報がインデックス済みレコードに含まれていなければ、ルールやブーストでそれらを確実に上位表示することはできません。

確認する質問

役立つ最小限の質問を選んでください。

• 通常のレコードを5件、エッジケースを5件共有してもらえますか。バリアント、購入不可の商品、アクセス制限のあるコンテンツ、地域差、検索結果の品質が低くなりやすいレコードを含めてください。
• 検索結果の単位とすべきエンティティは何ですか。商品、バリアント、SKU、記事、所在地、アカウント、または別の単位ですか。
• バリアントは個別のヒットとして表示しますか、商品ごとに1件表示しますか、色など共通のバリエーションごとに1件表示しますか、1件のヒット内に選択肢をまとめますか、それとも在庫状況、チャネル、地域、アカウント、権限に基づいて表示せずに絞り込みますか。
• ユーザーが検索、絞り込み、並べ替え、表示、またはランキングに使用する必要がある属性は何ですか。
• 商品のプロモーションまたは表示抑制に、マーチャンダイジングで使用する必要がある属性は何ですか。新しさ、評価、売上、人気度、利益率、セール中かどうか、自社ブランド、高在庫、ベストセラー、季節性、キャンペーン、編集上の優先度などです。
• カテゴリーごとに、ビジネスでは「新しい」「高在庫」「ベストセラー」をどのように定義していますか。また、インデックス作成前に、それらの区分はどこで計算されますか。
• テキストの関連性が同点の場合、カスタムランキング指標はどの順序で優先しますか。売上、利益率、評価、人気度、新しさ、在庫、編集上の優先度などです。
• ランキング指標の精度が高すぎて有効なタイブレークができない場合、sales_30d_bucket、margin_band、freshness_bucketのように丸めるか区分化する必要がありますか。
• 安定した識別子と、変動しやすい表示フィールドまたはランキングフィールドは、それぞれどれですか。
• ユーザー、アカウント、地域、チャネルによって非表示にする、表示を遅らせる、またはアクセスを制限する必要があるレコードは何ですか。
• レコードはどのくらいの頻度で変更されますか。また、その変更の責任を持つシステムはどれですか。
• 同じコンテンツについて、ロケール、地域、テナント、環境、またはユーザーセグメントごとに別々のインデックスが必要ですか。

実装基準

• objectID は安定した契約として扱ってください。変更可能な表示フィールドから導出しないでください。
• バリアントのモデル化を明示してください。ユーザーが商品単位の検索結果を期待しているのに、誤って SKU ごとに元データの行をインデックス化しないでください。また、色、サイズ、在庫状況、価格、地域、権限によって検索動作が実質的に変わる場合は、バリアントを統合しないでください。
• レコードサイズは意図的に決めてください。検索、ランキング、ファセット、表示、分析コンテキスト、イベントのアトリビューションに必要なフィールドを含めてください。
• 本番、ステージング、開発のインデックスを分けてください。本番に対する破壊的なインデックス操作をテストしないでください。
• 別のソート順にはレプリカを使用し、適切な場合は関連するソートにバーチャルレプリカを使用してください。
• UI のレスポンスを整形する際は、イベントにおける queryID／objectID／位置の互換性を維持してください。
• レコード契約の一部として、公開レスポンスの許可リストを定義してください。内部のランキング入力（生の値またはバケット化された人気度、販売速度、利益率）はランキングのために存在するものであり、公開レスポンスに含めるものではありません。公開レスポンスに表示用フィールドとイベントのアトリビューション用フィールドのみが含まれるよう、attributesToRetrieve（必要に応じて unretrievableAttributes）を計画し、公開検索キーを使用したライブクエリで検証してください。
• 使用する実効価格属性を 1 つ選び、表示、ソート、フィルタリング、範囲ファセット、レプリカ設定のすべてで一貫して使用してください。セール価格を表示しながら基本価格でソートまたはフィルタリングすると、商品が順不同で表示されたり、フィルタの範囲外に表示されたりするため、ユーザーが気づく不具合であり、スタイル上の選択ではありません。
• 明確な運用上の理由がない限り、マーチャンダイジングのために Algolia で正確な在庫数を必須にしないでください。販売のたびに不要な再インデックスが発生しないよう、in_stock、stock_bucket、high_inventory などの安定したバケットやブール値を優先してください。
• インデックス作成前に、カテゴリごとの鮮度、在庫豊富、セール、自社ブランド、ベストセラーのフラグを計算してください。不完全なレコードから Algolia のルールが不足しているビジネス定義を推測できるとは考えないでください。
• 連続値とバケットの違いを説明してください。正確な販売数、利益率、在庫数、タイムスタンプは有用な場合もありますが、バケットを使うとマーチャンダイジングやカスタムランキングを理解しやすくなり、ノイズも抑えられることがよくあります。
• カスタムランキングは、テキストの関連性に続く優先順位付きのタイブレークとして扱ってください。最初のランキング指標が非常に高精度だと、後続の指標がほとんど影響しない場合があります。ビジネス上 2 番目または 3 番目の指標も反映させたい場合は、精度を下げるか値をバケット化してください。
• E コマースでは、商品 ID、バリエーション ID、SKU ID の違いを維持してください。UI でファミリー単位の検索結果を 1 件だけ表示しつつ、イベントやフィルタにはバリエーション単位の正確な情報が必要な場合は、親 ID と選択中のバリアントのフィールドを使用してください。

アンチパターン

• 購入者が商品ファミリー単位の結果を期待しているのに、デフォルトで SKU ごとに 1 行ずつインデックス化する。
• 在庫状況、価格、権限、色、サイズ、またはイベントのアトリビューションをバリアントごとに変える必要があるのに、バリアントを統合する。
• バケットでビジネスニーズを満たせて更新回数も減らせるのに、正確な在庫数をマーチャンダイジングの入力として使う。
• 信頼できるタイムスタンプや明示的な新しさ属性なしに、「新着」商品を上位表示する。
• 対象期間、カテゴリの範囲、更新担当者を定義せずに「ベストセラー」を上位表示する。
• ビジネス上の順序、方向、対象期間、カテゴリの範囲、精度を決めずに、生の販売数、利益率、評価、人気度でランキングする。
• 後続のビジネス指標で同順位を解消できなくなるほど、最初のカスタムランキング指標の精度を高くする。
• 元のシステムで都合がよいという理由で、表示専用または内部用のフィールドを検索対象テキストに追加する。
• レコード契約を決めた後にイベントを設計し、その結果、後から objectID、index、queryID、またはバリアントの集計に問題が生じる。
• エラーが発生しなかったという理由で、内部のランキング入力（生の人気度、販売速度、利益率、またはそれらのバケット）を公開検索レスポンスに含める。競合他社やスクレイパーはヒットのペイロードを読み取ります。
• UI ではセール価格を表示しながら基本価格でソートまたはフィルタリングする（またはその逆）。実効価格の契約はどこでも 1 つに統一してください。

インデックス作成前のチェックポイント

レコードをインデックスに登録する前に、次の項目が準備完了、暫定、または保留のいずれであるかを明記してください。

• objectID の安定性。
• UI で使用するファセットと、その正規化方法。
• ランキングフィールドと、それらが重要な理由。
• ランキング指標の精度：生データ、丸め処理、バケット化、またはキュレーション済み。
• 取得可能な表示フィールド。
• 公開レスポンスの許可リスト：内部ランキングフィールドは取得可能なペイロードから除外します。
• 表示、ソート、フィルター、範囲ファセットに使用する実効価格属性を 1 つ選びます。
• 画像、URL、タイトル、価格、在庫状況、その他 UI で必要なフィールド。
• イベントのアトリビューションフィールド。
• UI で必要となる在庫、在庫状況、または権限のフィールド。
• 変動の大きいフィールドの更新担当者と更新頻度。

E コマースのレコードモデル戦略

次のいずれかのパターンを選択し、トレードオフを明記してください。

• バリアントレベルのレコード：1 件のレコードが、色やサイズの SKU など、販売可能な特定のバリエーションを表します。ユーザーがバリアント単位で検索、絞り込み、比較、価格確認、または購入を行う場合、色、サイズ、在庫状況、画像を正確にする必要がある場合、または詳細な更新が重要な場合に使用します。UI で商品ファミリーを表示する必要がある場合は、グループ化または distinct の動作を計画してください。
• バリエーショングループレベルのレコード：1 件のレコードが、色などの主要属性を共有するバリアントをグループ化します。UI とマーチャンダイジングが通常、商品または色の単位で運用される一方で、マスター商品レコードよりも精度の高いフィルターと画像が必要な場合に使用します。
• 商品レベルまたはマスター商品レコード：1 件のレコードが基本商品を表し、すべてのバリアントを含みます。マーチャンダイジング、分析、AI の動作を商品単位で行い、ユーザーが商品ごとに 1 件の検索結果を期待する場合に使用します。フィルター適用後に適切なバリアントを表示するために必要なフロントエンド作業を記録してください。
• ロケール、地域、チャネル、またはアカウントごとのバリアント：テキスト、価格、在庫状況、権限、またはイベントの違いが検索動作に影響するほど大きい場合は、別々のレコードまたはインデックスに分けます。
• セキュリティ保護されたバリアント：UI で非表示にするだけに頼らないでください。権限の影響を受けるバリアントには、セキュリティ保護されたフィルター、別々のインデックス、またはレコードレベルのアクセス戦略が必要です。

各モデルについて、テキストの関連性、ファセットの精度、マーチャンダイジングの制御、AI／パーソナライズの動作、分析の集計、更新コスト、レコード数、UI の複雑さへの影響を明記してください。

Academy と顧客向け教育の連携

ソースに基づくガイダンスが必要な場合は、インデックス作成とデータ準備の学習目標について公開されている Academy の情報を検索し、レコード、objectID、ファセット、レプリカ、現在の実装詳細について公開されている Algolia ドキュメントを検索してください。顧客が、初級の実装、本番環境への対応、最適化、AI 対応のどの段階にあるかを特定します。ソースの文脈を判断や質問に活用し、コースやドキュメントの長い抜粋を貼り付けないでください。

成熟度に応じた対応

• 初級の実装：最もシンプルで正確なレコード仕様を作成し、サンプルレコード、データソースの担当者、objectID の候補、必須フィルター、主要なランキング目標についてのみ質問します。
• 本番環境への対応：環境名、更新の担当者、セキュリティ保護対象フィールド、ロールバック／再インデックス計画、検証クエリを追加します。
• 最適化：ランキングシグナル、クエリ分析、レプリカ戦略、管理された関連性テストを追加します。
• AI 対応：セマンティックフィールド、イベントのアトリビューションフィールド、権限、ノイズの多い属性、NeuralSearch または Agent Studio の前提条件を満たしているかを検証します。

成果物

設計作業では、サンプルレコード、レコードモデル戦略、マーチャンダイジングのデータ不足レポート、カスタムランキング指標の対応表、検証クエリを含む簡潔なインデックス仕様を返します。コード作業では、その仕様を実装し、再インデックス／更新の手順と検証コマンドまたはテストを含めます。