Cortex Analyst REST API

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

메시지 보내기

POST /api/v2/cortex/analyst/message

요청에 제공된 의미 체계 모델을 사용하여 주어진 질문에 대한 SQL 쿼리를 생성합니다. 이전 쿼리를 기반으로 후속 질문을 할 수 있는 멀티턴 대화를 할 수 있습니다. 자세한 내용은 Cortex Analyst 에서의 멀티 턴 대화 섹션을 참조하십시오.

요청에는 사용자 질문이 포함되고, 응답에는 사용자 질문과 분석가의 응답이 포함됩니다. 응답의 각 메시지에는 다양한 유형의 여러 내용 블록이 포함될 수 있습니다. 현재 내용 오브젝트의 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[].confidence (object): 신뢰도 관련 정보를 포함합니다. sql 콘텐츠 유형에 대해서만 반환됩니다.

  • message.content[].confidence.verified_query_used (object): SQL 응답 생성에 사용된 검증된 쿼리 리포지토리에서 검증된 쿼리를 나타냅니다. 확인된 쿼리가 사용되지 않은 경우 필드 값은 null 입니다.

  • message.content[].confidence.verified_query_used.name (string): 사용된 검증된 쿼리의 이름으로, 검증된 쿼리 리포지토리에서 추출한 이름입니다.

  • message.content[].confidence.verified_query_used.question (string): 검증된 쿼리 리포지토리에서 추출한 검증된 쿼리가 답변한 질문입니다.

  • message.content[].confidence.verified_query_used.sql (string): 사용된 검증된 쿼리의 SQL 문으로, 검증된 쿼리 리포지토리에서 추출한 것입니다.

  • message.content[].confidence.verified_query_used.verified_at (정수): 쿼리가 확인될 때의 타임스탬프를 숫자로 표현한 것으로, 확인된 쿼리 리포지토리에서 추출합니다.

  • message.content[].confidence.verified_query_used.verified_by (string): 검증된 쿼리 리포지토리에서 추출한 쿼리를 검증한 사람입니다.

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

  • message.content[].warnings : 사용자의 요청에 대한 분석가의 경고 목록입니다.

  • message.content[].warnings (목록): 사용자 요청 및 의미 체계 모델에 관한 경고 모음을 나타냅니다.

  • message.content[].warnings[].message (string): 하나의 개별 경고에 대한 자세한 설명을 포함합니다.

{
    "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"
        }
    ]
}
Copy

피드백 보내기

POST /api/v2/cortex/analyst/feedback

정성적인 최종 사용자 피드백을 제공합니다. Snowsight 내에서 피드백은 Monitoring 아래의 Semantic Model Admins 에 표시됩니다.

헤더 요청

헤더

설명

Authorization

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

Content-Type

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

요청 본문

필드

설명

request_id

(필수) 메시지를 보내기 위해 요청한 요청의 ID입니다. /api/v2/cortex/analyst/message 의 request_id 필드에 반환됩니다. 자세한 내용은 응답 섹션을 참조하십시오.

유형: 문자열

예: 75d343ee-699c-483f-83a1-e314609fb563

positive

(요구 사항) 피드백이 긍정적인지 부정적인지 여부(긍정 또는 ‘좋아요’의 경우 true, 부정 또는 ‘싫어요’의 경우 false).

유형: 부울

예:

true

feedback_message

(선택 사항) 사용자의 피드백 메시지입니다.

예: This is the best answer I've ever seen!

응답

상태 코드 200의 빈 응답 본문입니다.

액세스 제어 요구 사항

요구 사항에 대한 자세한 내용은 액세스 제어 요구 사항 섹션을 참조하십시오.

API 인증에 대한 자세한 내용은 Snowflake를 사용하여 Snowflake REST APIs 인증하기 섹션을 참조하십시오.

언어: 한국어