データエージェントクエリ生成を改善するためのベストプラクティス

データエージェントは、利用可能なデータに関する焦点を絞った正確なコンテキストを持つことで、より良いクエリを生成します。 オブジェクト名やスキーマメタデータは出発点を提供しますが、ビジネスの意味、期待値、関係性、あるいは質問に答えるために必要なクエリロジックを説明できない場合があります。

必要なコンテキストに最も合った構成を使いましょう:

これらの設定の概要については、 データエージェント構成を参照してください。

明確なスキーマ名を使いましょう

スキーマを制御する際には、データソース、テーブル、カラムに記述的な名前を使いましょう。 CustomerOrders、order_submission_date、product_unit_priceなどの名前は、Table1、date1、valueのような名前よりもエージェントに有用な信号を与えます。

名前だけに頼らないでください。 明確な技術名であっても、そのオブジェクトのビジネス上の意味、詳細のレベル、単位、有効な価値を伝えられないことがあります。 説明やデータソースの指示を使ってその文脈を与えましょう。

選択したスキーマを制限する

データエージェントが答えるべき質問に必要なテーブル、列、ビュー、関数のみを選択します。 無関係なオブジェクトは曖昧さを増し、クエリ生成ツールに考慮すべき経路を増やすことができます。

例えば、ユーザーが現在の顧客注文について尋ねた場合、アーカイブされたステージングテーブルや無関係な財務テーブルは含めないでください。 選ばれた2つのオブジェクトに類似したデータが含まれている場合は、どちらが権威的か、そしてそれぞれの使用タイミングを説明してください。

スキーマオブジェクトを記述する(プレビュー)

大規模または曖昧なSQLスキーマの場合は、 スキーマオブジェクトの記述 を使って個々のテーブル、カラム、その他のスキーマ要素が何を表しているかを説明してください。 スキーマオブジェクトの記述は、データエージェントが プレビューランタイムを使用している場合にのみ利用可能です。

説明は以下の場合に役立ちます:

• オブジェクト名は略称、汎用、または類似しています。
• テーブルの穀物や用途は名前からは明らかではありません。
• 列にはコード、フラグ、単位、または解釈が必要なカテゴリ値が含まれます。
• 日付列は、注文の提出など特定のビジネスイベントを表し、履行時ではありません。
• スキーマが大きすぎて、データソースの命令ですべてのオブジェクトを明確に説明できません。

その情報がクエリ生成に影響を与える場合の意味と期待値を記述してください。 例えば次が挙げられます。

推論が難しいオブジェクトの記述を優先してください。 ビジネスの文脈を加えずに、わかりやすい名前を繰り返さないようにしましょう。

オブジェクト間のルールにはデータソースの指示を使う

データソース命令 は、特定のデータソースに対するクエリ生成の指針を提供します。 複数のスキーマオブジェクトにまたがるコンテキストや、クエリの構成方法を定義するために、以下のようなものを活用してください。

• 特定分野の信頼性の高い表。
• 結合キーと必要な結合パス。
• テーブルの粒度と重複排除ルール。
• デフォルトフィルター、例えば現在またはアクティブなレコードのみを使用するなど。
• 日付の論理、会計カレンダー、タイムゾーンの仮定。
• 必要な計算や出力列。

エージェントが何をすべきかを明確に指示してください。 例えば、「従業員テーブルを誤って結合しないでください」ではなく、「EmployeeStatusFactをEmployeeIDでEmployeeDimに結合する」を使用します。

指示に集中します。 各テーブルや列の用語集として限られた命令空間を使うのではなく、スキーマオブジェクトの記述にオブジェクト固有の定義を入れましょう。

ビジネス用語と期待値を定義する

ユーザーが質問に含めてもスキーマに直接対応しない用語を定義してください。 例としては、「MAU」のような頭字語、「アクティブ顧客」の組織固有の意味、会計年度と暦年といった区別があります。

また、エージェントがフィルターを正しく構築するために必要な値を文書化してください:

• 状態列で "CA" と "California" のどちらを使用するか。
• ブール値が 1 と 0、 Y と N、あるいはテキストとして保存されるか。
• 通貨の値がドル単位で保存されるか、セント単位で保存されるか。
• どのステータス値が完了済み、キャンセル済み、またはアクティブなレコードを表しているか。
• null、ゼロ、または番兵日付が特別な意味を持つかどうか。

定義は1つのオブジェクトに適用される場合は、スキーマオブジェクトの説明に配置してください。 データソース全体に適用される場合やマルチオブジェクトクエリロジックに影響を与える場合は、データソース命令に配置してください。

関係性とテーブルグレインの説明

正確な結合は、列名の一致だけでなく、それ以上の要素に依存します。 重要なテーブルの粒状、有効な関係パス、メタデータからは明らかでないキーを特定しましょう。

例えば、売上テーブルに注文ごと、注文明細ごと、または商品の日次合計ごとに1行含まれるかどうかを説明してください。 2つのファクトテーブルを結合すると行が重複する場合は、エージェントに各テーブルを結合する前に集約するか、適切な次元テーブルを使用するよう指示してください。

以下のような関係のアドバイスを含めてください:

- Join `OrderItems` to `Orders` on `OrderID`.
- Join `Orders` to `Customers` on `CustomerID`.
- Aggregate `OrderItems` to one row per `OrderID` before joining to order-level payment totals.

複雑な論理のための例クエリを活用してください

ロジックを文章で説明するよりも、クエリを示したほうが明確な場合は、サンプル クエリ を使用します。 良い例としては、代表的な自然言語の質問と、期待されるパターンを示す有効なクエリを組み合わせます。

以下を示す例を優先して挙げましょう:

• マルチテーブル結合や事前アグリゲーションの要求。
• ビジネス固有の計算です。
• 相対的な日付、会計期間、またはスナップショットロジック。
• ユーザーの用語を保存された値にマッピングするフィルター。
• ランキング、ウィンドウ関数、またはその他の複雑なクエリパターン。

各例は1つの再利用可能なパターンに焦点を当ててください。 重複や矛盾する例を避け、すべての例が現在のスキーマに一致しているか確認してください。

コンテキストをテストし、洗練する

代表的な質問をテストし、生成されたクエリを検証し、欠けている文脈や誤解を特定しましょう。 問題に最も近い設定を更新してください:

• スキーマ選択で無関係なオブジェクトを削除したり、欠けているオブジェクトを追加したりします。
• あるオブジェクトのスキーマ記述における意味や期待値を明確にすること。
• データソース命令にクロスオブジェクトのビジネスロジックやジョインロジックを追加してください。
• エージェントが特定のクエリパターンを学ぶ必要がある場合に例のクエリを追加します。

このプロセスを繰り返し、スキーマやユーザーの質問が進化するにつれて繰り返します。 構造化テストのワークフローについては、「 反復的プロセスを使ってデータエージェントを開発する」を参照してください。

次のステップ

• データ エージェントの構成
• データエージェントにスキーマオブジェクトの記述を追加する
• Fabric データ エージェント ランタイム
• サンプル クエリ
• データソースの追加と設定