Cortex Analyst REST API¶

リクエストヘッダー¶

リクエスト本文¶

リクエスト本文で：

• 最後の messages[].role フィールドにスピーカーのロールをセットします。 user でなければなりません。

• ユーザーの質問を content オブジェクトに含めます。このオブジェクトの中に：

  • type を text に設定します。

  • ユーザーの質問に text をセットします。

• 以下のいずれかを含めてください：

  • YAML における意味モデル仕様。

  • 意味モデル仕様を含む YAML ファイルへのパス。このファイルはステージ上になければなりません。

  • セマンティックビューの名前。

以下のテーブルは、リクエスト本文にセットできるフィールドを説明しています。

{
  /* ... */
  "semantic_view": "MY_DB.MY_SCHEMA.SEMANTIC_VIEW"
  /* ... */
}

{
  /* ... */
  "semantic_view": "\"my-database\".\"my-schema\".\"\"my-semantic-view\"\""
  /* ... */
}

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

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "which company had the most revenue?"
        }
      ]
    }
  ],
  "semantic_view": "MY_DB.MY_SCH.MY_SEMANTIC_VIEW"
}

ストリーム以外での対応¶

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

リクエストが semantic_models フィールドを含むとき、レスポンスはリクエストにどのセマンティックモデルが 選択されたかを示す semantic_model_selection フィールドを含みます。

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

デフォルトでは、 Cortex Analyst がユーザーの質問を完全に処理した後、レスポンスが一度に返されます。ストリーミングモードの応答形式については、 ストリーミング対応 をご参照ください。

{
    "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"
        }
    ],
    "response_metadata": {
        "model_names": [
            "claude-3-5-sonnet"
        ],
        "cortex_search_retrieval": [
            {
                "service": "my_db.my_schema.my_search_service",
                "response_body": {
                    "results": [
                        {
                            "CUST_NAME": "customer1"
                        }
                    ],
                    "request_id": "request1"
                },
                "query": "'customer1'"
            }
        ],
        "question_category": "CLEAR_SQL"
    }
}

Copy

ストリーミング対応¶

ストリーミング・モードでは、クライアントはレスポンス全体が生成されるのを待つのではなく、 Cortex Analyst によって生成されたレスポンスを受け取ることができます。これにより、アプリケーションの応答性が向上し、特に実行時間の長いクエリでは、ユーザーがより早く出力を確認できるようになります。また、ストリーミングレスポンスでは、 Cortex Analyst がレスポンスを生成するプロセスのどの段階にあるのかを理解するのに役立つステータス情報や、 Cortex Analyst が期待通りに動作しない場合に何が問題だったのかを理解するのに役立つ警告も提供されます。

ストリーミング応答を受け取るには、リクエスト本文の stream フィールドを true にセットします。ストリーミング応答は、 サーバーが送信したイベント を使用します。

Cortex Analyst は、ストリーム応答で5つの異なるタイプのイベントを送信します。

• status: SQL の生成プロセスに関するステータスを表示します。

• message.content.delta: レスポンスの一部が含まれています。このイベントは複数回送信されます。

• error: Cortex Analyst がエラーに遭遇し、リクエストの処理を続行できないことを示します。それ以降、 message.content.delta イベントは送信されません。

• warnings: 処理中に発生した警告が含まれています。警告は処理を停止しません。

• response_metadata: リクエスト処理に関するデータを表示するためにレスポンスの最後に送信されます。

• done: 処理が完了し、今後 message.content.delta イベントが送信されないことを示すために送信されます。

このうち、 message.content.delta イベントは、実際のレスポンス内容が含まれているため、理解することが最も重要です。各 delta には、完全なレスポンスのフィールドのトークンが含まれています。それぞれの delta イベントには、1文字から全レスポンスまでのコンテナーが含まれる可能性があり、それらは異なる長さである可能性があります。生成されたトークンを受け取るのはあなたです。最終的なレスポンスに組み立てるのはあなた次第です。

{
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "This is how we interpreted your question and this is how the sql is generated"
            },
            {
                "type": "sql",
                "statement": "SELECT * FROM table"
            }
        ]
    }
}

event: status
data: { status: "interpreting_question" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: "This is how we interpreted your question"
}

event: status
data: { status: "generating_sql" }

event: status
data: { status: "validating_sql" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: " and this is how the sql is generated"
}

event: message.content.delta
data: {
  index: 1,
  type: "sql",
  statement_delta: "SELECT * FROM table"
}

event: status
data: { status: "done" }

{
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "Your question is ambigous, here are some alternatives:"
            },
            {
                "type": "suggestions",
                "suggestions": [
                    "which company had the most revenue?",
                    "which company placed the most orders?"
                ]
            }
        ]
    }
}

event: status
data: { status: "interpreting_question" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: "Your question is ambigous,"
}

event: status
data: { status: "generating_suggestions" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: " here are some alternatives:"
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 0,
    suggestion_delta: "which company had",
  }
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 0,
    suggestion_delta: " the most revenue?",
  }
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 1,
    suggestion_delta: "which company placed",
  }
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 1,
    suggestion_delta: " the most orders?",
  }
}

event: status
data: { status: "done" }

ストリームイベントスキーマ¶

以下は、ストリーミングレスポンスで Cortex Analyst から送信されるイベントの OpenAPI/Swagger スキーマです。

status

message.content.delta

error

StreamingError:
type: object
properties:
  message:
    type: string
    description: A description of the error
  code:
    type: string
    description: The Snowflake error code categorizing the error
  request_id:
    type: string
    description: Unique request ID

Copy

warnings

Warnings:
type: object
description: Warnings found while processing the request
properties:
  warnings:
    type: array
    items:
      $ref: "#/components/schemas/Warning"
Warning:
type: object
title: The warning object
description: Represents a warning within a chat.
properties:
  message:
    type: string
    description: A human-readable message describing the warning

Copy

response_metadata

ResponseMetadata:
type: object
description: Details about request processing

Copy

リクエストヘッダー¶

リクエスト本文¶

応答¶

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