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 의 세 가지 내용 유형이 지원됩니다. 내용 유형 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 이벤트는 한 글자부터 전체 응답까지 포함할 수 있으며, 길이가 다를 수 있습니다. 토큰이 생성될 때 토큰을 받게 되며, 이를 최종 응답으로 조합하는 것은 사용자의 몫입니다.

{
    "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

오류

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:
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의 빈 응답 본문입니다.