Cortex Analyst REST API

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

メッセージの送信

POST /api/v2/cortex/analyst/message

リクエストで提供されたセマンティックモデルを使用して、与えられた質問に対する SQL クエリを生成します。API はステートレスなので、シングルターンの会話しかサポートされていないことに注意してください。

リクエストにはユーザーの質問が含まれ、応答にはユーザーの質問とアナリストの応答が含まれます。応答の各メッセージは、異なるタイプの複数のコンテンツブロックを持つことができます。現在、コンテンツオブジェクトの 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[].suggestions （string）: SQL を生成できない場合、セマンティックモデルが SQL を生成できる質問のリスト。コンテンツタイプ suggestion に対してのみ返されます。

{
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "We interpreted your question as ..."
            },
            {
                "type": "sql",
                "statement": "SELECT * FROM table"
            }
        ]
    }
}
Copy
言語: 日本語