Cortex Analyst REST API

この API を使用して、自然言語クエリでデータに関する質問に回答します。

メッセージの送信

POST /api/v2/cortex/analyst/message

リクエストで提供されたセマンティックモデルを使用して、与えられた質問に対する SQL クエリを生成します。以前のクエリを基にしたフォローアップの質問ができるマルチターン会話が可能です。詳細については、 Cortex Analyst におけるマルチターン会話 をご参照ください。

リクエストにはユーザーの質問が含まれ、応答にはユーザーの質問とアナリストの応答が含まれます。応答の各メッセージは、異なるタイプの複数のコンテンツブロックを持つことができます。現在、コンテンツオブジェクトの type フィールドでサポートされている値は、 text、 suggestions および sql の3つです。

リクエストヘッダー

ヘッダー

説明

Authorization

（必須）認証トークン詳細については、 サーバーへの認証 をご参照ください。

Content-Type

（必須）アプリケーション/JSON

リクエスト本文

リクエスト本文は、スピーカーのロール（user である必要があります）、ユーザーの質問、セマンティックモデル YAML ファイルへのパスを含みます。ユーザーの質問は、 type と text の2つのフィールドを持つ content オブジェクトに含まれています。 text はまた、 type フィールドの唯一の許容値です。

フィールド

説明

messages[].role

（必須）メッセージを作成するエンティティのロール。Snowflakeは現在、 user のみをサポートしています。

型: string:enum

例: user

messages[].content[]

（必須）メッセージの一部であるコンテンツオブジェクト。

型: オブジェクト

例:

{
  "type": "text",
  "text":  "Which company had the most revenue?"
}
Copy

messages[].content[].type

（必須）コンテンツタイプ。現在のところ、 text のみサポートされています。

型: string:enum

例: text

messages[].content[].text

（必須）ユーザーの質問。

型: 文字列

例: Which company had the most revenue?

semantic_model_file

セマンティックモデル YAML ファイルへのパス。データベースとスキーマを含む、完全修飾されたステージ URL でなければなりません。その代わりに、 semantic_model フィールドに完全なセマンティックモデル YAML を提供することができます。

型: 文字列

例: @my_db.my_schema.my_stage/my_semantic_model.yaml

semantic_model

セマンティックモデル YAML 全体を含む文字列。その代わりに、 semantic_model_file フィールドに URL を指定することで、セマンティックモデル YAML をステージングされたファイルとして渡すことができます。

型: 文字列

重要

リクエスト本文には、 semantic_model_file または semantic_model のどちらかを指定しなければなりません。

例

{
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "which company had the most revenue?"
                }
            ]
        }
    ],
    "semantic_model_file": "@my_stage/my_semantic_model.yaml"
}
Copy

応答

この操作は、以下にリストされている応答コードを返すことができます。応答は常に次のような構造になっています。現在、応答には text、 suggestion、 sql の3つのコンテンツタイプがサポートされています。コンテンツタイプ suggestion と sql は相互に排他的であるため、応答に sql コンテンツタイプが含まれる場合、 suggestion コンテンツタイプは含まれません。 suggestion コンテンツタイプは、ユーザーの質問があいまいで、 Cortex Analyst がそのクエリに対する SQL ステートメントを返せなかった場合にのみ、応答に含まれます。

前方互換性を確保するために、実装がコンテンツタイプを考慮し、タイプを処理することを確認してください。

コード

説明

200

ステートメントは正常に実行されました。

応答の本文には、以下のフィールドを含むメッセージオブジェクトが含まれます。

  • message: ユーザーとアナリストの会話のメッセージ。

  • message （object）: チャット内のメッセージを表します。

  • message.role （string:enum）: メッセージを生成したエンティティ。 user の1つ、または analyst。

  • message.content[] （object）: メッセージの一部であるコンテンツオブジェクト。

  • message.content[].type （string:enum）: メッセージのコンテンツタイプ。 text の1つ、 suggestion、または sql。

  • message.content[].text （string）: コンテンツのテキスト。コンテンツタイプ text に対してのみ返されます。

  • message.content[].statement （string）: SQL ステートメントコンテンツタイプ sql に対してのみ返されます。

  • message.content[].confidence （object）: 信頼性に関連する情報を含みます。 sql コンテンツタイプに対してのみ返されます。

  • message.content[].confidence.verified_query_used （object）: SQL 応答生成で使用される、検証済みクエリリポジトリからの検証済みクエリを表します。検証クエリを使用しない場合、フィールド値は null になります。

  • message.content[].confidence.verified_query_used.name （string）: 検証済みクエリリポジトリから抽出された、使用した検証済みクエリの名前。

  • message.content[].confidence.verified_query_used.question （string）: 検証済みクエリリポジトリから抽出された、検証済みクエリが回答する質問。

  • message.content[].confidence.verified_query_used.sql （string）: 検証済みクエリリポジトリから抽出された、使用された検証済みクエリの SQL ステートメント。

  • message.content[].confidence.verified_query_used.verified_at （integer）: 検証済みクエリリポジトリから抽出された、クエリ検証時のタイムスタンプの数値表現。

  • message.content[].confidence.verified_query_used.verified_by （string）: 検証済みクエリリポジトリから抽出された、クエリの検証者。

  • message.content[].suggestions （string）: SQL を生成できない場合、セマンティックモデルが SQL を生成できる質問のリスト。コンテンツタイプ suggestion に対してのみ返されます。

  • message.content[].warnings: ユーザーのリクエストに関するアナリストからの警告リスト。

  • message.content[].warnings （list）: ユーザーリクエストとセマンティックモデルに関する警告のコレクションを表します。

  • message.content[].warnings[].message （string）: 個々の警告の詳細な説明を含みます。

{
    "request_id": "75d343ee-699c-483f-83a1-e314609fb563",
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "We interpreted your question as ..."
            },
            {
                "type": "sql",
                "statement": "SELECT * FROM table",
                "confidence": {
                    "verified_query_used": {
                        "name": "My verified query",
                        "question": "What was the total revenue?",
                        "sql": "SELECT * FROM table2",
                        "verified_at": 1714497970,
                        "verified_by": "Jane Doe"
                    }
                }
            }
        ]
    },
    "warnings": [
        {
            "message": "Table table1 has (30) columns, which exceeds the recommended maximum of 10"
        },
        {
            "message": "Table table2 has (40) columns, which exceeds the recommended maximum of 10"
        }
    ]
}
Copy

フィードバックを送信

POST /api/v2/cortex/analyst/feedback

質的なエンドユーザーフィードバックを提供します。 Snowsight 内で、フィードバックは Monitoring にある Semantic Model Admins に表示されます。

リクエストヘッダー

ヘッダー

説明

Authorization

（必須）認証トークン詳細については、 サーバーへの認証 をご参照ください。

Content-Type

（必須）アプリケーション/JSON

リクエスト本文

フィールド

説明

request_id

（必須）メッセージを送信するために行ったリクエストのID。 /api/v2/cortex/analyst/message の request_id フィールドに返されます。詳細については、 応答 をご参照ください。

型: 文字列

例: 75d343ee-699c-483f-83a1-e314609fb563

positive

（必須）フィードバックが肯定的か否定的か。肯定的または「サムズアップ」の場合は true、否定的または「サムズダウン」の場合は false。

型: ブール値

例:

true

feedback_message

（オプション）ユーザーからのフィードバックメッセージ。

例: This is the best answer I've ever seen!

応答

ステータスコード200の空の応答本文。

アクセス制御の要件

必要な権限の情報については、 アクセス制御の要件 をご参照ください。

API への認証コードの詳細については、 Snowflakeでの Snowflake REST APIs 認証 をご参照ください。

言語: 日本語