레거시 스테이지 API에서 시맨틱 뷰로 마이그레이션하기

시맨틱 뷰가 도입되기 전에는 Cortex Analyst의 비즈니스 시맨틱을 정의하는 유일한 방법이 YAML 파일을 Snowflake 스테이지에 업로드하는 것("스테이지 API")이었어요. 시맨틱 뷰는 이 워크플로우를 대체하는 네이티브 스키마 수준 객체예요.

출처: Snowflake 문서

본문

시맨틱 뷰가 도입되기 전에는 Cortex Analyst의 비즈니스 시맨틱을 정의하는 유일한 방법이 YAML 파일을 Snowflake 스테이지에 업로드하는 것(스테이지 API)이었어요. 시맨틱 뷰는 이 워크플로우를 대체하는 네이티브 스키마 수준 객체예요.

중요: Snowflake는 모든 새 구현에 시맨틱 뷰를 사용할 것을 권장해요. 레거시 스테이지 API와 함께 사용해 온 스테이지의 기존 YAML 파일이 있다면 이 파일들은 Cortex Analyst에서 계속 동작해요. 다만 직접 SQL 쿼리 인터페이스, 네이티브 공유, 그리고 시맨틱 뷰에서 사용할 수 있는 기타 기능은 지원하지 않아요.

레거시 스테이지 API와의 주요 차이점

시맨틱 뷰(DDL 또는 YAML로 작성됐든)는 레거시 스테이지 방식에서 제공하지 못한 다음 기능을 제공해요:

직접 SQL 쿼리: SELECT … FROM SEMANTIC_VIEW(…)로 비즈니스 메트릭을 직접 쿼리할 수 있어요. 레거시 스테이지 API는 Cortex Analyst가 SQL을 생성하기 위한 컨텍스트로만 동작해요.
네이티브 Snowflake 통합: 시맨틱 뷰는 표준 SQL 명령(SHOW, DESCRIBE, GRANT, REVOKE)으로 관리되는 스키마 수준 객체예요. 스테이지 기반 YAML 파일은 스테이지에 대한 읽기와 쓰기가 필요해요.
세밀한 보안: 시맨틱 뷰는 역할 기반 액세스 제어(RBAC)를 사용해요. 레거시 방식은 스테이지 권한을 통한 거친(coarse-grained) 액세스만 제공해요.
공유와 Marketplace: 시맨틱 뷰는 Snowflake 공유, Snowflake Marketplace, 리스팅(listings)을 통해 네이티브하게 공유할 수 있어요.
거버넌스와 관찰 가능성: 시맨틱 뷰는 Information Schema와 Account Usage 뷰에 나타나 사용 추적과 감사(audit)를 제공해요.

스테이지 기반 YAML에서 마이그레이션하기

스테이지에 기존 YAML 파일이 있다면 SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML 저장 프로시저를 사용해 이를 시맨틱 뷰로 변환할 수 있어요. 시맨틱 뷰를 YAML 형식으로 다시 내보내려면 SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW 함수를 사용해요.

스테이지 기반 YAML 파일을 시맨틱 뷰로 변환할 때:

뷰 수준 계산에는 파생 메트릭(derived metrics) 사용을 고려해요.
비공개로 만들려는 fact와 metric에 access_modifier를 추가해요.
YAML 파일의 custom instructions를 시맨틱 뷰의 AI_SQL_GENERATION과 AI_QUESTION_CATEGORIZATION 파라미터로 옮겨요.

참고: 저장 프로시저로 YAML 파일을 한 번에 하나씩 변환해야 해요. 대량 변환이나 CI/CD 파이프라인 통합이 필요하다면 변환을 순차적으로 실행하도록 스크립트를 만들 수 있어요.

시맨틱 뷰의 역할, 권한, 배포 파이프라인 설정 안내는 Best practices for developing and deploying semantic views를 참고해요.

레거시 스테이지 API에서 시맨틱 뷰로 마이그레이션하기