Cortex Analyst 의미 체계 모델 사양¶

의미 체계 계층 개념¶

논리적 의미 계층을 정의하는 구조와 개념은 물리적 데이터베이스 계층을 정의하는 구조와 개념과 유사합니다. 다음은 의미 체계 계층의 개념 유형입니다.

• 논리적 테이블 수준

• 모델 수준

• 추가 컨텍스트

논리적 테이블 수준 개념¶

논리적 테이블 은 Snowflake의 의미 체계 모델의 기본 개념입니다. 실제 데이터베이스 테이블 또는 뷰를 나타냅니다. 일반적으로 비즈니스 엔터티(예: 고객, 주문, 공급업체) 또는 차원(예: 위치 또는 시간)에 해당합니다. 논리적 테이블의 각 행은 일반적으로 고객 ID 같은 엔터티의 고유한 인스턴스를 나타냅니다.

논리 테이블에는 다음과 같은 종류의 열이 포함됩니다.

• 팩트(비즈니스 이벤트에 대한 정량적 데이터)

• 차원(누가, 무엇을, 어디서, 어떻게)

• 시간(이벤트가 발생한 시간)

• 논리적 테이블과 연결된 필터를 사용하여 쿼리 결과를 특정 데이터 하위 집합으로 제한할 수 있습니다.

집계 또는 다른 논리적 오브젝트의 조합을 사용하여 메트릭을 정의할 수 있습니다.

다음 예제에서는 LINEITEM 팩트 테이블을 포함하는 TPC-H 스키마 를 사용합니다. 전체 YAML 구현을 보려면 snow_tpch 파일을 다운로드하십시오.

다음 논리 테이블 수준의 예제는 모두 order_lineitems 논리 테이블에 속합니다.

tables:
  - name: order_lineitems
    description: >
      The order line items table contains detailed information about each item within an
      order, including quantities, pricing, and dates.

    base_table:
      database: SNOWFLAKE_SAMPLE_DATA
      schema: TPCH_SF1
      table: LINEITEM
    primary_key:
      columns:
        - order_key
        - order_lineitem_number

Copy

차원 은 제품, 고객 또는 위치 정보와 같이 팩트에 대한 컨텍스트를 제공하는 범주형 데이터를 나타냅니다. 차원에는 일반적으로 제품 이름이나 고객 주소와 같은 설명 텍스트 값이 포함됩니다. 분석 및 보고서에서 팩트을 필터링하고, 그룹화하고, 레이블을 지정하는 데 사용됩니다.

시간 차원 은 여러 기간에 걸쳐 팩트을 분석할 수 있는 시간적 맥락을 제공합니다. 특정 시간 간격(날짜, 월, 년)에 걸쳐 메트릭을 추적할 수 있으며 추세 식별 및 기간 간 비교와 같은 분석을 지원합니다.

time_dimensions:
  - name: shipment_duration
    synonyms:
      - "shipping time"
      - "shipment time"
    description: The time it takes for items to be shipped.

    expr: DATEDIFF(day, lineitem.L_SHIPDATE, lineitem.L_RECEIPTDATE)
    data_type: NUMBER
    unique: false

Copy

팩트 는 분석에 대한 컨텍스트를 제공하는 측정 가능한 정량적 데이터입니다. 팩트는 매출, 비용 또는 수량과 같은 비즈니스 프로세스와 관련된 숫자 값을 나타냅니다. 팩트는 집계되지 않은 행 수준의 개념입니다.

# Fact columns in the logical table.
facts:
  - name: net_revenue
    synonyms:
      - "revenue after discount"
      - "net sales"
    description: Net revenue after applying discounts.

    expr: lineitem.L_EXTENDEDPRICE * (1 - lineitem.L_DISCOUNT)
    data_type: NUMBER

Copy

필터 는 기간, 위치 또는 카테고리와 같은 기준에 따라 쿼리 결과를 특정 데이터 하위 집합으로 제한하는 조건입니다.

- name: north_america
  synonyms:
    - "NA"
    - "North America region"
  description: >
    Filter to restrict data to orders from North America.
  comments: Used for analysis focusing on North American customers.
  expr: nation.N_NAME IN ('Canada', 'Mexico', 'United States')

Copy

메트릭 은 일반적으로 여러 행에 걸쳐 팩트을 집계하여 계산되는 비즈니스 성능의 정량화 가능한 측정값입니다. 메트릭을 SUM() 또는 AVG()와 같이 여러 논리적 오브젝트와 집계 함수를 결합할 수 있는 SQL 수식으로 식을 지정합니다. 보고서 및 대시보드에서 메트릭을 핵심 성과 지표(KPIs)로 사용할 수 있습니다. 가장 세분화된 수준에서 메트릭을 정의하여 상위 수준에서 집계할 수 있습니다. 예를 들어, 고객, 공급업체 또는 리전별로 집계할 수 있도록 라인항목 수준에서 total_revenue를 정의합니다.

  metrics:

# Simple metric referencing objects from the same logical table
- name: total_revenue
  expr: SUM(lineitem.l_extendedprice * (1 - lineitem.l_discount))

# Complex metric referencing objects from multiple logical tables.
# The relationships between tables have been defined below.
- name: total_profit_margin
  description: >
              The profit margin from orders. This metric is not additive
              and should always be calculated directly from the base tables.
  expr: (SUM(order_lineitems.net_revenue) -
        SUM(part_suppliers.part_supplier_cost * order_lineitems.lineitem_quantity))
        / SUM(order_lineitems.net_revenue)

Copy

허용된 참조¶

차원, 팩트, 메트릭 또는 필터에 대한 식을 참조할 수 있습니다.

• 자체 기본 테이블의 물리적 열

• 동일한 논리 테이블 내의 논리 열

• 의미 체계적 모델의 다른 논리 테이블의 논리 열

참고

식은 다른 물리적 테이블의 물리적 열을 참조할 수 없습니다.

모델 수준 개념¶

관계는 공유 키에 대한 조인을 통해 논리적 테이블을 연결합니다. 예를 들어, customer_id 열에 대한 조인을 통해 고객과 주문 테이블 간에 관계가 있을 수 있습니다. 조인을 사용하여 고객 특성이 있는 주문 데이터를 분석할 수 있습니다.

relationships:

  # Relationship between orders and lineitems
  - name: order_lineitems_to_orders
    left_table: order_lineitems
    right_table: orders
    relationship_columns:
      - left_column: order_key
        right_column: order_key
    join_type: left_outer
    relationship_type: many_to_one

  # Relationship between lineitems and partsuppliers
  - name: order_lineitems_to_part_suppliers
    left_table: order_lineitems
    right_table: part_suppliers
    # The relationship requires equality of multiple columns from each table
    relationship_columns:
      - left_column: part_key
        right_column: part_key
      - left_column: supplier_key
        right_column: supplier_key
    join_type: left_outer
    relationship_type: many_to_one

검증된 쿼리 리포지토리 (VQR)는 올바른 것으로 확인된 질문 및 해당 SQL 쿼리의 모음입니다. 이 쿼리를 사용하여 Cortex Analyst 의 결과 정확도를 개선할 수 있습니다.

Cortex Analyst 의 사용자 지정 지침 을 사용하여 Cortex Analyst 의 SQL 쿼리 생성을 보다 강력하게 제어할 수 있습니다. 사용자 지정 지침 내에서 비즈니스의 고유한 컨텍스트를 LLM 에 제공합니다.

Cortex Analyst 의미 체계 모델은 YAML 에 지정되어 있습니다. 이 모델은 자연어 질문에 높은 정확도로 답변하기 위해 필요한 의미 체계적 정보를 제공합니다.

YAML 형식¶

YAML 은 사람의 가독성과 정확성 사이에서 균형을 맞춥니다. 비즈니스 사용자는 이를 이해할 수 있고 데이터 엔지니어와 분석가는 기술 개념을 명확하게 정의할 수 있습니다.

Cortex Analyst 의미 체계 모델의 일반적인 구문은 다음과 같습니다.

# Name and description of the semantic model.
name: <name>
description: <string>
comments: <string>

# Logical table-level concepts

# A semantic model can contain one or more logical tables.
tables:

  # A logical table on top of a base table.
  - name: <name>
    description: <string>


    # The fully qualified name of the base table.
    base_table:
      database: <database>
      schema: <schema>
      table: <base table name>

    # Dimension columns in the logical table.
    dimensions:
      - name: <name>
        synonyms: <array of strings>
        description: <string>

        expr: <SQL expression>
        data_type: <data type>
        unique: <boolean>
        cortex_search_service:
          service: <string>
          literal_column: <string>
          database: <string>
          schema: <string>
        is_enum: <boolean>


    # Time dimension columns in the logical table.
    time_dimensions:
      - name: <name>
        synonyms:  <array of strings>
        description: <string>

        expr: <SQL expression>
        data_type: <data type>
        unique: <boolean>

    # Fact columns in the logical table.
    facts:
      - name: <name>
        synonyms: <array of strings>
        description: <string>

        expr: <SQL expression>
        data_type: <data type>


    # Business metrics across logical objects
    metrics:
      - name: <name>
        synonyms: <array of strings>
        description: <string>

        expr: <SQL expression>


    # Commonly used filters over the logical table.
    filters:
      - name: <name>
        synonyms: <array of strings>
        description: <string>

        expr: <SQL expression>



# Model-level concepts

# Relationships between logical tables
relationships:
  - name: <string>

    left_table: <table>
    right_table: <table>
    relationship_columns:
      - left_column: <column>
        right_column: <column>
      - left_column: <column>
        right_column: <column>
    join_type: <left_outer | inner>
    relationship_type: < one_to_one | many_to_one>


# Additional context concepts

#  Verified queries with example questions and queries that answer them
verified_queries:
# Verified Query (1 of n)
  - 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

예제 사양은 snow_tpch.yaml 파일을 참조하십시오.

의미 체계 모델¶

의미 체계 모델은 테이블의 모음을 나타냅니다. 모델에는 테이블에 대한 설명이 포함되어 있으며, 각 테이블에는 테이블의 특정 측면에 대한 설명이 포함되어 있습니다. 모델에 설명된 각 테이블은 Snowflake의 물리적 기본 테이블에 매핑됩니다.

다음과 같은 필드가 있습니다.

필수 사항

name

이 의미 체계 모델에 대한 설명적 이름입니다.

고유해야 하며 따옴표로 묶지 않은 식별자 요구 사항 을 따라야 합니다. 또한 Snowflake 예약 키워드 와 충돌할 수 없습니다.

선택 사항

이러한 필드는 필수가 아니지만, 가능하면 반드시 포함해야 합니다.

description

이 의미 체계 모델에 대한 설명과 이 모델이 어떤 종류의 분석에 유용한지에 대한 세부 정보입니다.

tables

이 의미 체계 모델의 논리적 테이블 목록입니다.

relationships

논리적 테이블 간의 조인 목록입니다.

논리 테이블¶

논리적 테이블은 물리적 데이터베이스 테이블 또는 뷰에 대한 뷰로 생각할 수 있습니다. 다음과 같은 필드가 있습니다.

필수 사항

name

이 테이블에 대한 설명적 이름입니다.

고유해야 하며 따옴표로 묶지 않은 식별자 요구 사항 을 따라야 합니다. 또한 Snowflake 예약 키워드 와 충돌할 수 없습니다.

base_table

데이터베이스의 기본 테이블의 정규화된 이름입니다.

선택 사항

이러한 필드는 필수가 아니지만, 가능하면 반드시 포함해야 합니다.

synonyms

이 테이블을 참조하는 데 사용된 다른 용어/구문 목록입니다. 논리 테이블 내의 모든 동의어에서 고유해야 합니다.

description

이 테이블의 설명.

primary_key

이 테이블의 기본 키 열입니다. 관계를 정의하는 경우 필수입니다.

dimensions

이 테이블의 차원 열 목록입니다.

time_dimensions

이 테이블의 시간 차원 열 목록입니다.

facts

이 테이블의 팩트 열 목록입니다.

metrics

이 테이블의 메트릭 목록입니다.

filters

있는 경우, 이 테이블의 미리 정의된 필터.

차원¶

차원은 상태, 사용자 유형, 플랫폼 등과 같은 범주형 값을 설명합니다. 다음과 같은 필드가 있습니다.

필수 사항

name

이 차원에 대한 설명적 이름입니다.

고유해야 하며 따옴표로 묶지 않은 식별자 요구 사항 을 따라야 합니다. 또한 Snowflake 예약 키워드 와 충돌할 수 없습니다.

expr

이 차원에 대한 SQL 식입니다. 이는 물리적 열에 대한 참조이거나 기본 테이블의 열을 하나 이상 포함하는 SQL 식일 수 있습니다.

data_type

이 차원의 데이터 타입입니다. Snowflake의 모든 데이터 타입에 대한 개요는 SQL 데이터 타입 참조 섹션을 참조하십시오. 참고로 VARIANT, OBJECT, GEOGRAPHY, ARRAY 는 현재 지원되지 않습니다.

선택 사항

이러한 필드는 필수가 아니지만, 가능하면 반드시 포함해야 합니다.

synonyms

이 차원을 지칭하는 데 사용되는 다른 용어/구문 목록입니다. 이 의미 체계 모델의 모든 동의어에서 고유해야 합니다.

description

이 차원에 대한 간략한 설명과 해당 차원이 가지고 있는 데이터를 포함합니다.

unique

이 차원이 고유한 값을 가지고 있음을 나타내는 부울 값입니다.

sample_values

이 열의 샘플 값(있는 경우)입니다. 사용자 질문에 참조될 가능성이 있는 모든 값을 추가합니다.

cortex_search_service

이 차원에 사용할 Cortex Search Service를 지정합니다. 다음과 같은 필드가 있습니다.

• service: Cortex Search Service의 이름입니다.

• literal_column: (선택 사항) Cortex Search Service의 리터럴 값을 포함하는 열입니다.

• database: (선택 사항) Cortex Search Service가 위치한 데이터베이스입니다. 기본값은 base_table 의 데이터베이스입니다.

• schema: (선택 사항) Cortex Search Service가 위치한 스키마입니다. 기본값은 base_table 의 스키마입니다.

이 필드는 이름만 지정할 수 있는 cortex_search_service_name 필드를 대체합니다. cortex_search_service_name 은 더 이상 사용되지 않습니다.

is_enum

부울 값입니다. True 인 경우 sample_values 필드의 값은 가능한 값의 전체 목록으로 간주되며 모델은 해당 열에서 필터링할 때 해당 값 중에서만 선택합니다.

시간 차원¶

시간 차원은 판매일, 생성일, 연도와 같은 시간 값을 설명합니다. 다음과 같은 필드가 있습니다.

필수 사항

name

이 시간 차원에 대한 설명적 이름입니다.

고유해야 하며 따옴표로 묶지 않은 식별자 요구 사항 을 따라야 합니다. 또한 Snowflake 예약 키워드 와 충돌할 수 없습니다.

expr

이 열의 SQL 식입니다. 이는 물리적 열에 대한 참조이거나 기본 테이블의 열을 하나 이상 포함하는 SQL 식일 수 있습니다.

data_type

이 시간 차원의 데이터 타입입니다. Snowflake의 모든 데이터 타입에 대한 개요는 SQL 데이터 타입 참조 섹션을 참조하십시오. 참고로 VARIANT, OBJECT, GEOGRAPHY, ARRAY 는 현재 지원되지 않습니다.

선택 사항

이러한 필드는 필수가 아니지만, 가능하면 반드시 포함해야 합니다.

synonyms

이 시간 차원을 지칭하는 데 사용되는 다른 용어/구문 목록입니다. 이 의미 체계 모델의 모든 동의어에서 고유해야 합니다.

description

이 차원에 대한 간략한 설명과 해당 차원이 가지고 있는 데이터를 포함합니다. 이 테이블을 사용하여 쿼리를 작성하는 데 도움이 되는 정보를 제공합니다. 예를 들어, DATETIME 열의 경우 데이터의 표준 시간대를 지정합니다.

unique:

이 열에 고유한 값이 있음을 나타내는 부울 값입니다.

sample_values:

이 열의 샘플 값(있는 경우)입니다. 사용자 질문에서 참조될 가능성이 있는 모든 값을 추가합니다. 이 필드는 선택 사항입니다.

팩트¶

팩트는 매출, 노출 수, 급여와 같은 숫자를 설명합니다. 이전 Cortex Analyst 릴리스에서는 팩트를 측정값이라고 불렀습니다. 팩트는 측정값과 역호환됩니다. 다음과 같은 필드가 있습니다.

필수 사항

name

이 팩트에 대한 설명적인 이름입니다.

고유해야 하며 따옴표로 묶지 않은 식별자 요구 사항 을 따라야 합니다. 또한 Snowflake 예약 키워드 와 충돌할 수 없습니다.

expr

이 SQL 식은 동일한 논리 테이블의 기본 물리적 테이블에 있는 물리적 열 또는 해당 논리 테이블 내의 논리적 열(팩트, 차원 또는 시간 차원)을 참조할 수 있습니다.

data_type

이 팩트의 데이터 타입입니다. Snowflake의 모든 데이터 타입에 대한 개요는 SQL 데이터 타입 참조 섹션을 참조하십시오. 참고로 VARIANT, OBJECT, GEOGRAPHY, ARRAY 는 현재 지원되지 않습니다.

선택 사항)

이러한 필드는 필수가 아니지만, 가능하면 반드시 포함해야 합니다.

synonyms

이 측정값을 지칭하는 데 사용되는 다른 용어/구문 목록입니다. 이 의미 체계 모델의 모든 동의어에서 고유해야 합니다.

description

이 열에 어떤 데이터가 있는지 등 이 측정값에 대한 간략한 설명입니다.

unique

이 열에 고유한 값이 있음을 나타내는 부울 값입니다.

sample_values

이 열의 샘플 값(있는 경우)입니다. 사용자 질문에서 참조될 가능성이 있는 모든 값을 추가합니다.

필터¶

필터는 필터링에 사용되는 SQL 식을 나타냅니다. 다음과 같은 필드가 있습니다.

필수 사항

name

이 필터에 대한 설명적 이름입니다.

expr

이 필터의 SQL 식으로, 논리 열을 참조합니다.

선택 사항

이러한 필드는 필수가 아니지만, 가능하면 반드시 포함해야 합니다.

synonyms

이 필터를 지칭하는 데 사용되는 다른 용어/구문 목록입니다. 이 의미 체계 모델의 모든 동의어에서 고유해야 합니다.

description

이 필터에 대한 간략한 설명으로, 이 필터가 일반적으로 어떤 용도로 사용되는지에 대한 세부 정보도 포함되어 있습니다.

메트릭¶

메트릭은 총 매출, 평균 주문 금액, 고객 수 등 비즈니스 성과를 정량화할 수 있는 측정값을 설명합니다. 다음과 같은 필드가 있습니다.

필수 사항

name

이 메트릭에 대한 설명적인 이름입니다.

고유해야 하며 따옴표로 묶지 않은 식별자 요구 사항 을 따라야 합니다. 또한 Snowflake 예약 키워드 와 충돌할 수 없습니다.

expr

이 열의 SQL 식입니다. 이는 동일한 논리 테이블의 논리 열(팩트, 차원 또는 시간 차원)을 참조하거나 의미 체계적 모델 내의 다른 논리 테이블의 논리 열을 참조할 수 있습니다.

data_type

이 메트릭의 데이터 타입입니다. Snowflake의 모든 데이터 타입에 대한 개요는 SQL 데이터 타입에 대한 참조를 참조하십시오. 참고로 VARIANT, OBJECT, GEOGRAPHY, ARRAY 는 현재 지원되지 않습니다.

선택 사항

이러한 필드는 필수가 아니지만, 가능하면 반드시 포함해야 합니다.

synonyms

이 메트릭을 지칭하는 데 사용되는 기타 용어/문구 목록입니다. 이 의미 체계적 모델의 모든 동의어에서 고유해야 합니다.

description

이 열에 포함된 데이터를 포함하여 이 메트릭에 대한 간략한 설명입니다.

sample_values

이 열의 샘플 값(있는 경우)입니다. 사용자 질문에서 참조될 가능성이 있는 모든 값을 추가합니다.

기본 테이블¶

기본 테이블은 완전히 정규화된 테이블 이름을 나타내는 데 사용됩니다. 이는 논리적 테이블이 매핑되는 물리적 테이블입니다. 다음과 같은 필드가 있습니다.

필수 사항

database

데이터베이스의 이름입니다.

schema

스키마의 이름입니다.

table

테이블의 이름입니다.

기본 키¶

기본 키는 테이블의 각 행을 고유하게 나타내는 열을 나타냅니다. 테이블이 관계에서 사용되는 경우 기본 키는 필수입니다. 다음과 같은 필드가 있습니다.

필수 사항

columns

테이블을 고유하게 나타내는 차원 열 목록입니다.

관계¶

논리적 테이블 간의 조인 관계를 정의합니다. 적절한 조인 기능을 보장하려면 관계에 관련된 테이블에 대해 기본 키를 정의해야 합니다. 다음과 같은 필드가 있습니다.

필수 사항

name

관계의 고유 식별자입니다.

left_table

YAML 파일의 앞부분에 정의된 논리적 테이블 이름입니다. 다대일 관계의 경우 최적의 성능을 위해 왼쪽 테이블이 관계의 다면이 되어야 합니다.

right_table

YAML 파일의 앞부분에 정의된 논리적 테이블 이름입니다. 다대일 관계의 경우 최적의 성능을 위해서는 올바른 테이블이 관계의 한 쪽에 있어야 합니다.

relationship_columns

조인 경로를 나타내는 왼쪽 테이블과 오른쪽 테이블 각각에서 동일한 열 목록입니다.

join_type

left_outer 또는 inner 입니다.

relationship_type

many_to_one 또는 one_to_one 입니다.

유효성 검사된 쿼리¶

YAML 파일의 이 섹션의 목적과 구조에 대한 자세한 내용은 Cortex Analyst Verified Query Repository 섹션을 참조하십시오.

사용자 지정 지침¶

사용자 지정 지침에 대한 자세한 내용은 Cortex Analyst 의 사용자 지정 지침 섹션을 참조하십시오.