Cortex Analyst Verified Query Repository

Cortex Analyst Verified Query Repository(VQR)는 질문과 그 질문에 답하는 SQL 쿼리를 모아 두어 결과의 정확도와 신뢰도를 높이는 데 도움을 줘요. Cortex Analyst는 비슷한 질문에 답할 때 저장소에서 관련 SQL 쿼리를 활용해요. 시맨틱 모델 YAML 파일에서 검증 쿼리를 지정할 수 있어요.

출처: Snowflake 문서

본문

Cortex Analyst Verified Query Repository(VQR)는 질문과 이를 답하기 위한 SQL 쿼리 모음을 제공해 결과의 정확도와 신뢰도를 개선해 줘요. Cortex Analyst는 비슷한 질문에 답할 때 저장소의 관련 SQL 쿼리를 활용해요. 시맨틱 모델 YAML 파일에서 검증 쿼리를 지정할 수 있어요.

중요: 검증된 SQL 쿼리는 기본 데이터셋의 컬럼이 아니라 시맨틱 모델에 정의된 논리 테이블과 컬럼 이름을 사용해야 해요. 자세한 내용은 예시 쿼리와 그 설명을 참고해요.

검증 쿼리는 시맨틱 모델의 verified_queries 섹션에 지정돼요. 예시는 다음과 같아요.

verified_queries:

# Verified Query 1
- name:                         # A descriptive name of the query.
  question:                     # The natural language question that this query answers.
  verified_at:                  # Optional: Time (in seconds since the UNIX epoch, January 1, 1970) when the query was verified.
  verified_by:                  # Optional: Name of the person who verified the query.
  use_as_onboarding_question:   # Optional: Marks this question as an onboarding question for the end user.
  sql:                          # The SQL query for answering the question.

# Verified Query 2
- name:
  question:
  verified_at:
  verified_by:
  use_as_onboarding_question:
  sql:

다음은 검증 쿼리를 포함한 샘플 시맨틱 모델이에요.

name: Sales Data
tables:
- name: sales_data
  base_table:
    database: sales
    schema: public
    table: sd_data

  dimensions:
    - name: state
      description: The state where the sale took place.
      expr: d_state
      data_type: TEXT
        unique: false
        sample_values:
          - "CA"
          - "IL"

    # Time dimension columns in the logical table.
    time_dimensions:
      - name: sale_timestamp
        synonyms:
          - "time_of_sale"
          - "transaction_time"
        description: The time when the sale occurred. In UTC.
        expr: dt
        data_type: TIMESTAMP
        unique: false

    # Measure columns in the logical table.
    measures:
      - name: profit
        synonyms:
          - "earnings"
          - "net income"
        description: The profit generated from a sale.
        expr: amt - cst
        data_type: NUMBER
        default_aggregation: sum

verified_queries:
  - name: "California profit"
    question: "What was the profit from California last month?"
    verified_at: 1714497970
    verified_by: Jane Doe
    use_as_onboarding_question: true
    sql: "
SELECT sum(profit)
FROM __sales_data
WHERE state = 'CA'
    AND sale_timestamp >= DATE_TRUNC('month', DATEADD('month', -1, CURRENT_DATE))
    AND sale_timestamp < DATE_TRUNC('month', CURRENT_DATE)
"

위 예시에서 __sales_data는 모델에 정의된 sales_data 테이블에 대응해요. 이름 충돌을 피하려고 논리 테이블 이름 앞에 두 개의 밑줄이 붙어요. 쿼리에서 사용된 컬럼(state, sale_timestamp, profit)은 모델의 sale_data 테이블에 정의된 논리 컬럼이에요. 기본 컬럼 이름(d_state, dt, amt, cst)은 쿼리에서 직접 사용되지 않아요.

예시에서 볼 수 있듯이 질문은 완전한 문장이거나 실제 질문 형식일 필요는 없지만, 사용자가 물어볼 만한 내용을 반영해야 해요. SQL 쿼리가 구문적으로 올바르고 실제로 제시된 질문에 답하는지 확인하세요. 이것이 "검증 쿼리"의 핵심이에요. 유효하지 않거나 부정확한 쿼리는 Cortex Analyst의 성능과 정확도에 부정적인 영향을 줄 수 있어요.

팁: 다음 섹션에서 설명하는 오픈소스 시맨틱 모델 생성 앱을 사용하면 SQL이나 YAML 구문을 신경 쓰지 않고도 검증 쿼리를 시맨틱 모델에 추가할 수 있어요.

시맨틱 모델 생성기로 검증 쿼리 추가하기

Snowflake는 모델에 검증 쿼리를 추가하는 데 도움이 되는 오픈소스 Streamlit 앱을 제공해요. 이 앱을 설치하고 사용하려면 다음 지침을 따라 해요.

저장소를 클론합니다. 먼저 semantic-model-generator 저장소를 클론해요.
자격 증명을 구성하고 앱을 설치합니다. 저장소의 README에 있는 설정 지침을 따라 Snowflake 자격 증명을 제공하고 Snowflake 또는 로컬에서 앱을 실행해요.
앱을 구성합니다. 앱이 실행되면 시맨틱 모델 YAML 파일의 데이터베이스, 스키마, 스테이지 위치를 제공된 필드에 입력해요. YAML 파일이 창 왼쪽의 대화형 편집기에 나타나요.
쿼리를 생성합니다. 창 오른쪽의 채팅 인터페이스에서 질문을 입력해 SQL 쿼리를 생성해요.
쿼리를 검증하고 저장합니다.
- 생성된 쿼리와 생성 결과를 확인해요. 예상대로 동작한다면 어시스턴트 답변 아래의 Save as verified query 버튼을 선택해 쿼리를 시맨틱 모델에 추가해요.
- 생성된 쿼리가 올바르지 않다면 Edit 버튼을 선택해 쿼리를 수정해요. 수정된 쿼리를 실행해 의도한 결과가 나오는지 확인해요. 쿼리가 원하는 대로 동작할 때까지 편집과 테스트를 반복해요. 그런 다음 Save as verified query를 선택해 시맨틱 모델에 추가해요.
시맨틱 모델을 업데이트합니다. 창 왼쪽 하단의 Save 버튼을 선택해 시맨틱 모델을 업데이트해요. 쿼리를 더 추가하려면 이 과정을 반복해요.
새 YAML 파일을 업로드합니다. 추가한 쿼리가 만족스러우면 Upload 버튼을 선택하고 새 YAML 파일 이름을 입력한 다음 Submit Upload를 선택해요.

Snowsight의 스테이지로 돌아가면 검증 쿼리가 포함된 새 시맨틱 모델 YAML 파일을 볼 수 있어요.

제안된 Cortex Analyst Verified Query 항목 추가하기

Cortex Analyst는 Snowsight에서 Verified Query Suggestion 인터페이스도 제공하는데, 사용자 행동을 바탕으로 잠재적인 새 검증 쿼리를 제안해요. 검증 쿼리 추천 추가에 대한 내용은 Suggestions for semantic models and views를 참고해요.

Cortex Analyst 응답에 사용된 검증 쿼리 확인하기

사용자 질문이 Verified Query Repository(VQR)의 쿼리와 비슷하면, Cortex Analyst는 그 쿼리를 사용해 응답의 SQL 쿼리를 생성해요. 어떤 검증 쿼리가 사용됐는지 보려면 API 응답의 confidence 필드를 확인해요.

Cortex Analyst Verified Query Repository