Cortex Analyst REST API¶
この API を使用して、自然言語クエリでデータに関する質問に回答します。
メッセージの送信¶
POST /api/v2/cortex/analyst/message
リクエストで提供されたセマンティックモデルを使用して、与えられた質問に対する SQL クエリを生成します。以前のクエリを基にしたフォローアップの質問ができるマルチターン会話が可能です。詳細については、 Cortex Analyst におけるマルチターン会話 をご参照ください。
リクエストにはユーザーの質問が含まれ、応答にはユーザーの質問とアナリストの応答が含まれます。応答の各メッセージは、異なるタイプの複数のコンテンツブロックを持つことができます。現在、コンテンツオブジェクトの type
フィールドでサポートされている値は、 text
、 suggestions
および sql
の3つです。
リクエストヘッダー¶
ヘッダー |
説明 |
---|---|
|
(必須)認証トークン詳細については、 サーバーへの認証 をご参照ください。 |
|
(必須)アプリケーション/JSON |
リクエスト本文¶
リクエスト本文は、スピーカーのロール(user
である必要があります)、ユーザーの質問、セマンティックモデル YAML ファイルへのパスを含みます。ユーザーの質問は、 type
と text
の2つのフィールドを持つ content
オブジェクトに含まれています。 text
はまた、 type
フィールドの唯一の許容値です。
フィールド |
説明 |
---|---|
|
(必須)メッセージを作成するエンティティのロール。Snowflakeは現在、 型: string:enum 例: |
|
(必須)メッセージの一部であるコンテンツオブジェクト。 型: オブジェクト
|
|
(必須)コンテンツタイプ。現在のところ、 型: string:enum 例: |
|
(必須)ユーザーの質問。 型: 文字列 例: |
|
セマンティックモデル YAML ファイルへのパス。データベースとスキーマを含む、完全修飾されたステージ 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"
}
応答¶
この操作は、以下にリストされている応答コードを返すことができます。応答は常に次のような構造になっています。現在、応答には text
、 suggestion
、 sql
の3つのコンテンツタイプがサポートされています。コンテンツタイプ suggestion
と sql
は相互に排他的であるため、応答に sql
コンテンツタイプが含まれる場合、 suggestion
コンテンツタイプは含まれません。 suggestion
コンテンツタイプは、ユーザーの質問があいまいで、 Cortex Analyst がそのクエリに対する SQL ステートメントを返せなかった場合にのみ、応答に含まれます。
前方互換性を確保するために、実装がコンテンツタイプを考慮し、タイプを処理することを確認してください。
コード |
説明 |
---|---|
200 |
ステートメントは正常に実行されました。 応答の本文には、以下のフィールドを含むメッセージオブジェクトが含まれます。
{
"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"
}
]
}
|
フィードバックを送信¶
POST /api/v2/cortex/analyst/feedback
質的なエンドユーザーフィードバックを提供します。 Snowsight 内で、フィードバックは Monitoring にある Semantic Model Admins に表示されます。
リクエストヘッダー¶
ヘッダー |
説明 |
---|---|
|
(必須)認証トークン詳細については、 サーバーへの認証 をご参照ください。 |
|
(必須)アプリケーション/JSON |
リクエスト本文¶
フィールド |
説明 |
---|---|
|
(必須)メッセージを送信するために行ったリクエストのID。 型: 文字列 例: |
|
(必須)フィードバックが肯定的か否定的か。肯定的または「サムズアップ」の場合は 型: ブール値 例:
|
|
(オプション)ユーザーからのフィードバックメッセージ。 例: |
応答¶
ステータスコード200の空の応答本文。
アクセス制御の要件¶
必要な権限の情報については、 アクセス制御の要件 をご参照ください。
API への認証コードの詳細については、 Snowflakeでの Snowflake REST APIs 認証 をご参照ください。