CREATE SEMANTIC VIEW

CREATE SEMANTIC VIEW

CREATE SEMANTIC VIEW 명령은 현재/지정된 스키마에 새 시맨틱 뷰(semantic view)를 만드는 명령이에요. 시맨틱 뷰는 Cortex Analyst와 같은 AI 도구가 자연어 질문을 SQL로 변환할 때 사용하는 비즈니스 의미를 정의합니다.

출처: CREATE SEMANTIC VIEW

본문

현재/지정된 스키마에 새 시맨틱 뷰를 만드는 명령입니다. 시맨틱 뷰는 이 검증 규칙을 준수해야 합니다.

지원 변형:

• CREATE OR ALTER SEMANTIC VIEW — 시맨틱 뷰가 없으면 만들고, 있으면 변경해요.

참고: ALTER SEMANTIC VIEW, DESCRIBE SEMANTIC VIEW, DROP SEMANTIC VIEW, SHOW SEMANTIC VIEWS, SHOW SEMANTIC DIMENSIONS, SHOW SEMANTIC DIMENSIONS FOR METRIC, SHOW SEMANTIC FACTS, SHOW SEMANTIC METRICS, SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML

Syntax

CREATE [ OR REPLACE ] SEMANTIC VIEW [ IF NOT EXISTS ] <name>
  TABLES ( logicalTable [ , ... ] )
  [ RELATIONSHIPS ( relationshipDef [ , ... ] ) ]
  [ FACTS ( factExpression [ , ... ] ) ]
  [ DIMENSIONS ( dimensionExpression [ , ... ] ) ]
  [ METRICS ( { metricExpression | windowFunctionMetricExpression } [ , ... ] ) ]
  [ COMMENT = '<comment_about_semantic_view>' ]
  [ MAX_STALENESS = <integer> ]
  [ AI_SQL_GENERATION '<instructions_for_sql_generation>' ]
  [ AI_QUESTION_CATEGORIZATION '<instructions_for_question_categorization>' ]
  [ AI_VERIFIED_QUERIES ( verifiedQuery [ , ... ] ) ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ COPY GRANTS ]

여기서:

• 논리 테이블 파라미터:

  logicalTable ::=
      [ <table_alias> AS ] <table_name>
      [ PRIMARY KEY ( <primary_key_column_name> [ , ... ] ) ]
      [
  UNIQUE ( <unique_column_name> [ , ... ] )
  [ ... ]
      ]
      [
  CONSTRAINT [ <constraint_name> ]
       DISTINCT RANGE BETWEEN <start_column> AND <end_column> EXCLUSIVE
      ]
      [ WITH SYNONYMS [ = ] ( '<synonym>' [ , ... ] ) ]
      [ COMMENT = '<comment_about_table>' ]
      [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  

• 관계(relationships) 파라미터:

  relationshipDef ::=
      [ <relationship_identifier> AS ]
      <table_alias> ( <column_name> [ , ... ] )
      REFERENCES
      <ref_table_alias> [ (
  [ ASOF ] <ref_column_name> [ , ... ] |
  BETWEEN <start_column> AND <end_column> EXCLUSIVE
      ) ]
  

• fact 정의 표현식 파라미터:

  factExpression ::=
      [ { PRIVATE | PUBLIC } ] <table_alias>.<fact>
  [ LABELS = ( FILTER ) ]
  AS <sql_expr>
      [ WITH SYNONYMS [ = ] ( '<synonym>' [ , ... ] ) ]
      [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
      [ COMMENT = '<comment_about_the_fact>' ]
  

• dimension 정의 표현식 파라미터:

  dimensionExpression ::=
      [ PUBLIC ] <table_alias>.<dimension>
  [ LABELS = ( FILTER ) ]
  AS <sql_expr>
      [ WITH SYNONYMS [ = ] ( '<synonym>' [ , ... ] ) ]
      [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
      [ COMMENT = '<comment_about_the_dimension>' ]
      [ WITH CORTEX SEARCH SERVICE <search_service_name> [ USING <search_service_column_name> ] ]
  

• metric 정의 표현식 파라미터:

  metricExpression ::=
      [ { PRIVATE | PUBLIC } ] <table_alias>.<metric>
  [ USING ( <relationship_name> [ , ... ] ) ]
  [
       NON ADDITIVE BY (
         <dimension> [ { ASC | DESC } ] [ NULLS { FIRST | LAST } ]
         [ , ... ]
       )
  ]
  AS <sql_expr>
      [ WITH SYNONYMS [ = ] ( '<synonym>' [ , ... ] ) ]
      [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
      [ COMMENT = '<comment_about_the_metric>' ]
  

• 다음 구문을 사용해 윈도우 함수 메트릭(window function metric)을 정의할 수 있어요:

  windowFunctionMetricExpression ::=
      [ { PRIVATE | PUBLIC } ] <table_alias>.<metric> AS
  <window_function>( <metric> ) OVER (
       [ PARTITION BY { <exprs_using_dimensions_or_metrics> | EXCLUDING <dimensions> } ]
       [ ORDER BY <exprs_using_dimensions_or_metrics> [ ASC | DESC ] [ NULLS { FIRST | LAST } ] [, ...] ]
       [ <windowFrameClause> ]
  )
  

  이 구문에 대한 내용은 Parameters for window function metrics 문서를 참고하세요.

• 검증된 쿼리 파라미터:

  verifiedQuery ::=
      <verified_query_name> AS (
  QUESTION '<question>'
  [ VERIFIED_AT <timestamp> ]
  [ ONBOARDING_QUESTION <boolean> ]
  [ VERIFIED_BY '( <purpose> = <contact> )' ]
  SQL '<verified_query>'
      )
  

참고 절의 순서가 중요해요. 예를 들어 FACTS 절을 DIMENSIONS 절보다 먼저 지정해야 합니다. 나중에 정의되는 시맨틱 표현식을 참조할 수 있어요. 예를 들어 fact_2가 fact_1 이후에 정의되어도 fact_1 정의에서 fact_2를 사용할 수 있습니다.

Required parameters (필수 파라미터)

• name — 시맨틱 뷰의 이름을 지정해요. 시맨틱 뷰가 생성되는 스키마 내에서 고유해야 합니다. 또한 식별자는 알파벳 문자로 시작해야 하고, 전체 식별자 문자열을 큰따옴표로 감싸지 않는 한 공백이나 특수 문자를 포함할 수 없어요 (예: "My object"). 큰따옴표로 감싼 식별자는 대소문자를 구분합니다. 자세한 내용은 Identifier requirements 문서를 참고하세요.

Optional parameters (선택 파라미터)

• COMMENT = '<comment_about_semantic_view>' — 시맨틱 뷰에 대한 주석을 지정해요.
• MAX_STALENESS = <integer> — Snowflake가 자동으로 일시 중지하기 전에 구체화(materialization)가 오래될 수 있는 최대 초 수를 설정해요. 시맨틱 뷰에 구체화를 추가하기 전에 필요합니다. 최소값: 120 (2분). 시맨틱 뷰에 구체화가 존재하는 동안은 해제할 수 없습니다.
• AI_SQL_GENERATION '<instructions_for_sql_generation>' — SQL 문을 생성하는 방법을 설명하는 Cortex Analyst 지침을 지정해요. 자세한 내용은 Providing custom instructions for Cortex Analyst 문서를 참고하세요.
• AI_QUESTION_CATEGORIZATION '<instructions_for_question_categorization>' — 질문을 분류하는 방법을 설명하는 Cortex Analyst 지침을 지정해요.
• TAG ( <tag_name> = '<tag_value>' [ , ... ] ) — 태그 이름과 태그 문자열 값을 지정해요. 태그 값은 항상 문자열이며 최대 문자 수는 256이에요. 태그 지정 방법은 Tag quotas 문서를 참고하세요.
• COPY GRANTS — 기존 시맨틱 뷰를 새 시맨틱 뷰로 교체하기 위해 OR REPLACE를 지정하면, 기존 시맨틱 뷰에 부여된 권한을 새 시맨틱 뷰로 복사하도록 이 파라미터를 설정할 수 있어요. 명령은 기존 시맨틱 뷰에서 OWNERSHIP을 제외한 모든 권한 부여를 새 시맨틱 뷰로 복사합니다. CREATE SEMANTIC VIEW 문을 실행하는 역할이 새 뷰를 소유해요. 새 시맨틱 뷰는 스키마에서 객체 유형에 대해 정의된 미래 권한을 상속하지 않습니다. 권한 복사 작업은 CREATE SEMANTIC VIEW 문과 함께 원자적으로 발생합니다. COPY GRANTS를 생략하면 새 시맨틱 뷰는 기존 시맨틱 뷰에 부여된 명시적 접근 권한을 상속하지 않지만 스키마에서 객체 유형에 대해 정의된 미래 권한은 상속해요.

Parameters for logical tables (논리 테이블 파라미터)

• table_alias AS — 논리 테이블의 선택적 별칭을 지정해요. 별칭을 지정하면 관계, fact, dimension, metric에서 논리 테이블을 참조할 때 그 별칭을 사용해야 합니다. 별칭을 지정하지 않으면 정규화되지 않은 논리 테이블 이름으로 테이블을 참조해요.
• table_name — 논리 테이블의 이름을 지정해요.
• PRIMARY KEY ( <primary_key_column_name> [ , ... ] ) — 테이블의 기본 키 역할을 하는 논리 테이블의 하나 이상의 컬럼 이름을 지정해요.
• UNIQUE ( <unique_column_name> [ , ... ] ) — 고유 값을 포함하는 컬럼의 이름 또는 고유 값 조합을 포함하는 컬럼의 이름을 지정해요. 예를 들어 service_id 컬럼이 고유 값을 포함하면:

  TABLES(
    ...
    product_table UNIQUE (service_id)
  

  product_area_id와 product_id 컬럼의 값 조합이 고유하면:

  TABLES(
    ...
    product_table UNIQUE (product_area_id, product_id)
    ...
  

  주어진 논리 테이블에서 여러 컬럼을 고유로 식별할 수 있어요:

  TABLES(
    ...
    product_table UNIQUE (product_area_id, product_id) UNIQUE (service_id)
    ...
  

  참고 이미 PRIMARY KEY로 컬럼을 식별했다면 그 컬럼에 UNIQUE 절을 추가하지 마세요.

• CONSTRAINT [ <constraint_name> ] DISTINCT RANGE BETWEEN <start_column> AND <end_column> EXCLUSIVE — 범위 조인(range join)에 대한 제약 조건을 지정해요. (Optional name for constraint. 이름을 생략하면 명령이 제약 조건에 시스템 생성 이름을 사용해요.) 각 행에서 start_column과 end_column 사이의 범위가 고유(distinct) 범위임을 지정합니다. Preview Feature — Open — 모든 계정에서 사용할 수 있어요.
• WITH SYNONYMS [ = ] ( '<synonym>' [ , ... ] ) — 논리 테이블의 하나 이상의 동의어를 지정해요. 별칭과 달리 동의어는 정보 제공 목적으로만 사용됩니다. 관계, dimension, metric, fact에서 논리 테이블을 참조하는 데 동의어를 사용하지 않아요.
• COMMENT = '<comment_about_table>' — 논리 테이블에 대한 주석을 지정해요.
• TAG ( ... ) — 태그 이름과 태그 문자열 값을 지정해요. 태그 값은 항상 문자열이며 최대 문자 수는 256이에요.

Parameters for relationships (관계 파라미터)

• <relationship_identifier> — 관계의 선택적 식별자를 지정해요.
• <table_alias> ( <column_name> [ , ... ] ) — 다른 논리 테이블의 컬럼을 참조하는 하나의 논리 테이블과 그 하나 이상의 컬럼을 지정해요.
• <ref_table_alias> — 첫 번째 논리 테이블이 참조하는 다른 논리 테이블을 지정해요. 테이블을 조인하는 방법에 따라 괄호 안에 다음 중 하나를 지정할 수 있어요: 논리 테이블 정의에서 PRIMARY KEY 또는 UNIQUE 제약 조건으로 식별된 컬럼. ASOF 조인의 경우 지원되는 유형 중 하나의 컬럼. 주어진 관계의 정의에서 최대 하나의 ASOF 키워드를 지정할 수 있어요. 범위 조인의 경우 첫 번째 테이블의 가능한 값 범위를 지정하며, 범위의 시작과 끝을 정의하는 컬럼을 지정합니다. column_name은 start_column과 end_column의 데이터 유형으로 강제(coerce)될 수 있는 데이터 유형이어야 해요. Preview Feature — Open — 모든 계정에서 사용할 수 있어요.

Parameters for facts, dimensions, and metrics

시맨틱 뷰에서 최소한 하나의 dimension 또는 metric을 정의해야 하며, 즉 최소한 DIMENSIONS 절 또는 METRICS 절을 지정해야 합니다. 이 파라미터들은 fact, dimension, metric 정의 구문의 일부예요.

• PRIVATE | PUBLIC — fact 또는 metric이 private인지 public인지 지정해요. private로 표시된 fact와 metric은 쿼리하거나 쿼리 조건에 사용할 수 없습니다. dimension은 private로 표시할 수 없으며 항상 public입니다. PRIVATE와 PUBLIC을 모두 생략하면 dimension, fact, metric은 기본적으로 public이에요.
• <table_alias>.<name> — dimension, fact, metric의 이름을 지정해요. metric 정의의 경우 두 논리 테이블 사이에 여러 관계 경로가 존재할 때, 테이블을 조인하고 metric을 계산하는 데 사용해야 하는 관계를 지정해요. 다른 논리 테이블의 여러 metric을 결합하는 파생 metric(derived metric)을 정의하려면 이름에서 table_alias.을 생략하세요. 유효한 시맨틱 뷰를 정의하는 규칙은 How Snowflake validates semantic views 문서를 참고하세요.
• NON ADDITIVE BY ( <dimension> [ { ASC | DESC } ] [ NULLS { FIRST | LAST } ] [ , ... ] ) — metric을 합산할 때 사용하지 않아야 하는 dimension 목록을 지정해요. 대신 쿼리 처리 중 행은 비-가산(non-additive) dimension으로 정렬되고, 정렬 순서의 마지막 행의 값이 집계되어 metric이 계산됩니다. 기본 오름차순(ASC) 정렬 순서에서 마지막 값은 시간 기반 dimension의 최신 값입니다. 내림차순(DESC) 정렬 순서에서 마지막 값은 가장 이른 값이에요. NON ADDITIVE BY 절을 지정하면 metric은 반가산(semi-additive) metric이 됩니다. 자세한 내용은 Identifying the dimensions that should be non-additive for a metric 문서를 참고하세요.
• LABELS = ( FILTER ) — fact 또는 dimension이 쿼리의 WHERE 절에서 필터로도 사용될 수 있음을 지정해요. fact 또는 dimension의 SQL 표현식은 BOOLEAN 값으로 평가되어야 합니다. 이 파라미터는 사실(fact)과 dimension에만 지정할 수 있고 metric에는 지정할 수 없어요.
• AS <sql_expr> — dimension, fact, metric을 계산하는 SQL 표현식을 지정해요. 이 표현식의 검증 규칙은 How Snowflake validates semantic views 문서를 참고하세요.
• WITH SYNONYMS [ = ] ( '<synonym>' [ , ... ] ) — dimension, fact, metric의 선택적 동의어를 하나 이상 지정해요. 동의어는 정보 제공 목적으로만 사용되며, 다른 dimension, fact, metric에서 동의어를 사용해 참조할 수 없습니다.
• TAG ( ... ) — 태그 이름과 태그 문자열 값을 지정해요. 태그 값은 항상 문자열이며 최대 문자 수는 256이에요.
• COMMENT = '<comment...>' — dimension, fact, metric에 대한 선택적 주석을 지정해요.
• WITH CORTEX SEARCH SERVICE <search_service_name> [ USING <search_service_column_name> ] — 이 dimension에 사용할 Cortex Search Service를 지정해요. 이 파라미터는 dimension에만 지정할 수 있고 fact나 metric에는 지정할 수 없습니다.

Usage notes (사용 참고 사항)

• 시맨틱 뷰는 유효해야 하며 How Snowflake validates semantic views에 설명된 규칙을 따라야 해요.
• 메타데이터에 관해: 고객은 Snowflake 서비스를 사용할 때 메타데이터로 개인 데이터(User 객체 제외), 민감 데이터, 수출 통제 데이터, 기타 규제 데이터를 입력하지 않도록 주의해야 해요. 자세한 내용은 Metadata fields in Snowflake 문서를 참고하세요.
• CREATE OR REPLACE <object> 문은 원자적이에요. 객체가 교체되면 이전 객체가 삭제되고 새 객체가 단일 트랜잭션으로 생성됩니다.

Variant syntax

CREATE OR ALTER SEMANTIC VIEW

시맨틱 뷰가 없으면 만들고, 있으면 문의 정의와 일치하도록 변경해요. 지원되는 변경: 테이블, 관계, fact, dimension, metric의 추가·제거·수정, 시맨틱 뷰 주석의 추가·덮어쓰기·제거, AI_SQL_GENERATION과 AI_QUESTION_CATEGORIZATION 지침의 수정, 검증된 쿼리의 추가·제거·수정.

CREATE OR ALTER SEMANTIC VIEW <name>
  TABLES ( logicalTable [ , ... ] )
  [ RELATIONSHIPS ( relationshipDef [ , ... ] ) ]
  [ FACTS ( factExpression [ , ... ] ) ]
  [ DIMENSIONS ( dimensionExpression [ , ... ] ) ]
  [ METRICS ( { metricExpression | windowFunctionMetricExpression } [ , ... ] ) ]
  [ COMMENT = '<comment_about_semantic_view>' ]
  [ MAX_STALENESS = <integer> ]
  [ AI_SQL_GENERATION '<instructions_for_sql_generation>' ]
  [ AI_QUESTION_CATEGORIZATION '<instructions_for_question_categorization>' ]
  [ AI_VERIFIED_QUERIES ( verifiedQuery [ , ... ] ) ]

logicalTable, relationshipDef, factExpression, dimensionExpression, metricExpression, windowFunctionMetricExpression, verifiedQuery의 정의는 CREATE SEMANTIC VIEW 명령의 syntax를 참고하세요.

CREATE OR ALTER SEMANTIC VIEW usage notes

• CREATE OR ALTER 명령의 모든 일반 사용 참고 사항이 적용됩니다.
• 이 명령은 시맨틱 뷰 또는 시맨틱 뷰 내 테이블, fact, dimension, metric의 태그 추가·변경을 지원하지 않습니다. 기존 태그는 보존됩니다.
• 이전에 설정된 속성(예: COMMENT)이 CREATE OR ALTER SEMANTIC VIEW 문에 없으면 그 속성이 해제됩니다.
• 기존 시맨틱 뷰에 대해 CREATE OR ALTER SEMANTIC VIEW 문을 실행하려면 역할이 시맨틱 뷰에 대한 OWNERSHIP 권한을 보유해야 합니다.

Examples (예제)

예제는 Creating a semantic view by using the CREATE SEMANTIC VIEW command 문서를 참고하세요.

더 알아보기 (Learn more)

• ALTER SEMANTIC VIEW
• DESCRIBE SEMANTIC VIEW
• DROP SEMANTIC VIEW
• SHOW SEMANTIC VIEWS
• SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML