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

access_modifier 필드를 ``private_access``로 설정하여 팩트를 비공개로 설정할 수 있습니다(의미 체계 모델에서는 액세스할 수 있지만, 최종 사용자는 액세스할 수 없음). 기본적으로, 팩트는 공개입니다(사용자가 액세스 가능).

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

- 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

*메트릭*은 SQL 수식으로 표현되는 비즈니스 성과의 정량화 가능한 척도입니다. 보고서 및 대시보드에서 메트릭을 핵심 성과 지표(KPIs)로 사용할 수 있습니다. 다음 두 가지 종류의 메트릭을 계산할 수 있습니다.

• **일반 메트릭**은 SUM 또는 AVG와 같은 함수를 사용하여 팩트 열에 대해 값을 집계합니다.

• **파생 메트릭**은 더하기 또는 나누기와 같은 산술 연산을 사용하여 기존 메트릭에서 계산됩니다.

더 높은 수준에서 집계하기 위해 가장 세분화된 수준에서 메트릭을 정의합니다. 예를 들어, 품목 수준에서 ``total_revenue``를 정의하여 고객, 공급자 또는 리전별로 집계할 수 있습니다.

다음 예에서는 간단한 메트릭 계산과 더 복잡한 메트릭 계산을 통해 두 가지 일반 메트릭 계산을 보여줍니다. 이들은 table 정의 내부에 정의되어 있으므로 해당 논리 테이블로 범위가 지정됩니다.

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

팁

access_modifier 필드를 ``private_access``로 설정하여 메트릭을 비공개로 설정할 수 있습니다(의미 체계 모델에서는 액세스할 수 있지만, 최종 사용자는 액세스할 수 없음). 기본적으로, 메트릭은 공개입니다(사용자가 액세스 가능).

허용된 참조¶

Expressions for dimensions, facts, filters, or regular table-scoped metrics can reference:

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

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

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

모델 범위가 지정된 파생 메트릭은 의미 체계 모델의 논리 테이블에 정의된 메트릭 또는 기타 파생 메트릭을 참조할 수 있습니다.

참고

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

모델 수준 개념¶

관계는 공유 키에 대한 조인을 통해 논리적 테이블을 연결합니다. 예를 들어, 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>
        access_modifier: < public_access | private_access >  # Default is public_access

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


    # Regular metrics scoped to the logical table.
    metrics:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        access_modifier: < public_access | private_access >  # Default is public_access

        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 >

# Derived metrics scoped to the semantic model
metrics:
  - name: <name>
    synonyms: <array of strings>
    description: <string>
    access_modifier: < public_access | private_access >  # Default is public_access

    expr: <SQL expression>


# Additional context concepts

#  Verified queries with example questions and queries that answer them
verified_queries:
  - 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

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

is_enum

부울 값입니다. True 인 경우 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 replaces the cortex_search_service_name field, which could only specify the name. cortex_search_service_name has been deprecated.

시간 차원¶

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

필수 사항

name

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

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

expr

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

data_type

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

선택 사항

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

synonyms

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

description

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

unique:

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

sample_values:

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

팩트¶

A fact describes numerical values, such as revenue, impressions, and salary. Facts used to be called measures in earlier releases of Cortex Analyst. Facts are backward compatible with measures. Facts have the following fields:

필수 사항

name

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

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

expr

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

data_type

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

선택 사항

The following fields are not required, but should be included whenever possible.

synonyms

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

description

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

unique

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

sample_values

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

다음 필드는 선택 사항입니다. 포함되지 않은 경우, 기본값은 ``public_access``입니다.

access_modifier

public_access 또는 private_access 입니다. ``private_access``인 경우, 팩트는 의미 체계 모델에서 액세스할 수 있지만, 최종 사용자는 액세스할 수 없습니다.

필터¶

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

필수 사항

name

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

expr

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

선택 사항

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

synonyms

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

description

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

메트릭¶

A metric describes quantifiable measures of business performance, such as total revenue, average order value, or customer count. Metrics can be regular metrics or derived metrics.

• **일반 메트릭**은 논리 테이블로 범위가 지정되며 동일 논리 테이블 내의 논리 열(팩트, 차원 또는 시간 차원) 또는 의미 체계 모델의 다른 논리 테이블의 논리 열을 참조할 수 있습니다. 의미 체계 모델에서 metric 요소는 table 요소 내부에 있습니다. 일반 메트릭은 집계 및 윈도우 함수를 사용하여 테이블의 전체 값을 계산합니다.

• **파생 메트릭**은 의미 체계 모델로 범위가 지정되며 다른 메트릭을 결합하는 방법을 제공합니다. 의미 체계 모델에서 metric 요소는 semantic_model 요소 내부에 있습니다. 메트릭의 표현식에서 다른 메트릭(다른 파생 메트릭 포함)만 참조할 수 있습니다.

Metrics have the following fields.

필수 사항

name

A descriptive name for this metric. This name deterines whether it is a regular metric.

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

expr

이 열의 SQL 식입니다. 표현식의 형식은 메트릭이 일반 메트릭인지 파생 메트릭인지에 따라 다릅니다.

• Regular metrics, which are scoped to a table, reference a logical column (fact, dimension, or time dimension) in the same logical table or a logical column from another logical table in the semantic model and use aggregate or window functions to calculate overall values.

• 파생 메트릭은 일반 메트릭 또는 기타 파생 메트릭을 참조할 수 있는 스칼라 표현식입니다.

선택 사항

The following fields are not required, but should be included whenever possible.

synonyms

A list of other terms/phrases used to refer to this metric. Each synonym must be unique across all synonyms in the semantic model.

description

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

sample_values

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

다음 필드는 선택 사항입니다. 포함되지 않은 경우, 기본값은 ``public_access``입니다.

access_modifier

public_access 또는 private_access 입니다. ``private_access``인 경우, 메트릭은 의미 체계 모델에서 액세스할 수 있지만, 최종 사용자는 액세스할 수 없습니다.

기본 테이블¶

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

필수 사항

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 섹션을 참조하십시오.

사용자 지정 지침¶

For information about custom instructions, see Cortex Analyst 의 사용자 지정 지침.