Cortex Analyst REST API

자연어 쿼리로 데이터에 대한 질문에 답하려면 이 API를 사용합니다.

메시지 보내기

POST /api/v2/cortex/analyst/message

요청에 제공된 의미 체계 모델을 사용하여 주어진 질문에 대한 SQL 쿼리를 생성합니다. API는 상태 비저장형이므로 단방향 대화만 지원된다는 점에 유의하십시오.

요청에는 사용자 질문이 포함되고, 응답에는 사용자 질문과 분석가의 응답이 포함됩니다. 응답의 각 메시지에는 다양한 유형의 여러 내용 블록이 포함될 수 있습니다. 현재 내용 오브젝트의 text 필드에 지원되는 3개 값은 type, suggestions, sql 입니다.

헤더 요청

헤더

설명

Authorization

(필수) 승인 토큰. 자세한 내용은 서버에 인증하기 섹션을 참조하십시오.

Content-Type

(필수) 애플리케이션/json

요청 본문

요청 본문에는 user 여야 하는 화자의 역할, 사용자의 질문, 의미 체계 모델 YAML 파일의 경로가 포함됩니다. 사용자 질문은 2개의 필드 type 및 text 가 있는 content 오브젝트에 포함되어 있습니다. text 는 type 필드에 허용되는 유일한 값이기도 합니다.

필드

설명

messages[].role

(필수) 메시지를 생성하는 엔터티의 역할. 현재는 user 만 지원합니다.

유형: 문자열:열거형

예: user

messages[].content[]

(필수) 메시지의 일부인 내용 오브젝트.

유형: 오브젝트

예:

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

messages[].content[].type

(필수) 내용 유형. 현재는 text 만 지원됩니다.

유형: 문자열:열거형

예: 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 의 세 가지 내용 유형이 지원됩니다. 내용 유형 suggestion 및 sql 은 상호 배타적이므로 응답에 sql 내용 유형이 포함되어 있으면 suggestion 내용 유형이 포함되지 않습니다. suggestion 내용 유형은 사용자 질문이 모호하고 Cortex Analyst 가 해당 쿼리에 대해 SQL 문을 반환할 수 없는 경우에만 응답에 포함됩니다.

이전 버전과의 호환성을 보장하려면 구현에서 콘텐츠 유형을 고려하고 해당 유형을 처리해야 합니다.

코드

설명

200

문이 성공적으로 실행되었습니다.

응답 본문에는 다음 필드가 포함된 메시지 오브젝트가 포함되어 있습니다.

  • message: 사용자와 분석가 간의 대화 메시지입니다.

  • message (오브젝트): 채팅 내의 메시지를 나타냅니다.

  • message.role (문자열:열거형): 메시지를 생성한 엔터티입니다. user 또는 analyst 중 하나입니다.

  • message.content[] (오브젝트): 메시지의 일부인 내용 오브젝트입니다.

  • message.content[].type (문자열:열거형): 메시지의 내용 유형입니다. text, suggestion 또는 sql 중 하나입니다.

  • message.content[].text (문자열): 내용의 텍스트입니다. 내용 유형 text 에 대해서만 반환됩니다.

  • message.content[].statement (문자열): SQL 문입니다. 내용 유형 sql 에 대해서만 반환됩니다.

  • message.content[].suggestions (문자열): SQL을 생성할 수 없는 경우 의미 체계 모델에서 SQL을 생성할 수 있는 질문 목록입니다. 내용 유형 suggestion 에 대해서만 반환됩니다.

{
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "We interpreted your question as ..."
            },
            {
                "type": "sql",
                "statement": "SELECT * FROM table"
            }
        ]
    }
}
Copy
언어: 한국어