Cortex Analyst のカスタム手順

カスタム手順により、 SQL の生成をより自由にコントロールできます。自然言語を使用することで、 Cortex Analyst にセマンティックモデル YAML ファイル内から SQL クエリを生成する方法を正確に伝えることができます。例えば、カスタム手順を使用して、 パフォーマンス または 会計年度 の意味を Cortex Analyst に伝えます。このように、カスタムロジックや追加要素を組み込むことで、生成される SQL の精度を向上させることができます。

より細かく制御するために、 SQL 生成パイプラインの個々のモジュールにカスタム命令を指定することもできます。詳細については、 モジュールのカスタム指示 をご参照ください。

カスタム手順の仕組み

Cortex Analyst は、 custom_instructions フィールドをセマンティックモデルの YAML ファイルに導入します。このフィールドでは、 SQL クエリの生成に定義変更や追加を適用できます。

セマンティックモデルの構文についての詳細は、 Cortex Analyst セマンティックモデル仕様 をご参照ください。

例

カスタム手順で可能なユースケースを探るために、以下の例を考えてみましょう。

データ出力のフォーマット

出力のすべての数値が10進数で四捨五入されていることを確認してください。

セマンティックモデルの YAML ファイルの custom_instructions フィールド

custom_instructions: "Ensure that all numeric columns are rounded to 2 decimal points in the output."
Copy

生成された SQL クエリ

SELECT
  ROUND(column_name, 2) AS column_name,
  ...
FROM
  your_table;
Copy

パーセンテージの調整

一貫性を保つために、パーセンテージやレートの計算に自動的に100を掛けます。

セマンティックモデルの YAML ファイルの custom_instructions フィールド

custom_instructions: "For any percentage or rate calculation, multiply the result by 100."
Copy

生成された SQL クエリ

SELECT
  (column_a / column_b) * 100 AS percentage_rate,
  ...
FROM
  your_table;
Copy

デフォルトフィルターの追加

ユーザーがフィルターを指定しない場合、フィルターを適用します（例えば、デフォルトを直近の年にします）。

セマンティックモデルの YAML ファイルの custom_instructions フィールド

custom_instructions: "If no date filter is provided, apply a filter for the last year."
Copy

生成された SQL クエリ

SELECT
  ...
FROM
  your_table
WHERE
  date_column >= DATEADD(YEAR, -1, CURRENT_DATE);
Copy

列フィルターのリンク

ユーザー入力に基づいて、関連列に追加のフィルターを適用します。

セマンティックモデルの YAML ファイルの custom_instructions フィールド

custom_instructions: "If a filter is applied on column X, ensure that the same filter is applied to dimension Y."
Copy

生成された SQL クエリ

SELECT
  ...
FROM
  your_table
WHERE
  column_x = 'filter_value' AND
  dimension_y = 'filter_value';
Copy

モジュールのカスタム指示

SQL 生成パイプラインの特定のコンポーネントにカスタム命令を定義するために、セマンティックモデルのトップレベルに module_custom_instructions キーをセットします。この機能は、以下のような場合に便利です。

  • SQL が生成される前に、ユーザーの質問がどのように解釈されるかを左右するロジックを定義します。

  • アナリストのワークフローのさまざまな部分について、より構造化された個別の指示を維持します。

  • 使用量の増加に伴い、既存の custom_instructions からよりモジュール化された形式へ移行。

現在、 module_custom_instructions は以下のコンポーネントをサポートしています。

  • question_categorization: Cortex Analyst がユーザーの質問をどのように分類するかを定義します (たとえば、特定のトピックをブロックしたり、ユーザーの動作を誘導したりします)。

  • sql_generation: SQL の生成方法（データの形式やフィルターなど）を指定します。

これらのコンポーネントのどちらか、または両方の指示は、 module_custom_instructions キーの下にセットできます。

重要

次の例に示すように、既存の custom_instructions を sql_generation コンポーネントに移行します。

既存のカスタム命令の移行

モデルにすでに custom_instructions フィールドがある場合、その内容を module_custom_instructions の sql_generation フィールドに移行してください。

前:

custom_instructions: "Ensure that all numeric columns are rounded to 2 decimal points."
Copy

後:

module_custom_instructions:
  sql_generation: |
     "Ensure that all numeric columns are rounded to 2 decimal points."
Copy

特定のトピックに関する質問のブロック

question_categorization コンポーネントを使用して、特定のトピックに関する質問をブロックすることができます。例えば、ユーザーに関する質問をブロックしたい場合、次のようにセットします。 Cortex Analyst は、管理者に連絡するようにというメッセージとともに、ユーザーに関する質問を拒否します。

module_custom_instructions:
  question_categorization: |
     Reject all questions asking about users. Ask users to contact their admin.
Copy

また、質問分類の指示を使って、不足している詳細を尋ねることもできます。次の例では、 Cortex Analyst は、ユーザーについて質問され、製品タイプを指定しなかった場合、ユーザーに製品タイプの提供を求めています。

module_custom_instructions:
  question_categorization: |
    - If the question asks for users without providing a product_type, consider this question UNCLEAR and ask the user to specify product_type.
Copy

ベストプラクティス

具体的に説明する。

例えば、「列に42の固定値を追加」または「列Xの合計計算を含める」など、変更をはっきりと説明してください。

小さく始める。

より複雑なシナリオに移動する前に、統計列やデフォルトフィルターを追加するなど、簡単な変更から始めます。

生成された SQL クエリをプレビューする。

手順が意図したとおりに適用され、生成された SQL クエリが正しいことを確認してください。

徐々に繰り返す。

機能に慣れるにつれて、より複雑なユースケースで実験します。

言語: 日本語