Semantic Studio
Semantic Studio
Semantic Studio는 Workspaces 안에서 시맨틱 뷰를 작성하는 환경이에요. 시맨틱 뷰를 YAML 파일로 정의해 라이브 Snowflake 객체로 배포하며, AI 기반 인텔리전트 에이전트인 Snowflake CoCo를 편집 워크플로우에서 바로 사용할 수 있어요. 각 요소를 손으로 구성하는 대신 대화를 통해 시맨틱 뷰를 만들고, 다듬고, 디버깅할 수 있어요.
출처: Snowflake 문서
본문
Semantic Studio는 Workspaces 안의 시맨틱 뷰 작성 환경이에요. 시맨틱 뷰를 YAML 파일로 정의하고 이를 라이브 Snowflake 객체로 배포하며, AI 기반 인텔리전트 에이전트인 Snowflake CoCo를 편집 워크플로우에서 바로 사용할 수 있어요. 각 요소를 손으로 구성하는 대신 대화를 통해 시맨틱 뷰를 만들고 다듬고 디버깅할 수 있어요.
Semantic Studio는 Workspaces 안에서 실행되므로 SQL 파일과 노트북에 사용하는 것과 동일한 파일 기반 워크플로우를 얻을 수 있고, 선택적 Git 통합도 포함돼요. 모니터링 대시보드에는 Semantic Studio의 직접 링크를 통해 언제든 접근할 수 있어요.
시맨틱 뷰와 함께 Cortex Agents를 작성하려면 Create and manage agents를 참고해요.
전제 조건(Prerequisites)
Snowsight의 Workspaces
Snowsight에 로그인하고 내비게이션 메뉴에서 Workspaces에 접근할 수 있는지 확인해요.
작업할 기존 데이터
다음 중 하나를 준비해 두세요:
- 시맨틱 뷰를 만들고 싶은 테이블 — 이 테이블에 읽기 액세스가 있어야 해요.
- 다듬거나 디버깅하고 싶은 기존 시맨틱 뷰
필요한 권한
시맨틱 뷰를 만들려면 다음 권한이 있는 역할을 사용해야 해요:
- 시맨틱 뷰를 만드는 스키마에 대한 CREATE SEMANTIC VIEW
- 시맨틱 뷰를 만드는 데이터베이스와 스키마에 대한 USAGE
- 시맨틱 뷰에서 사용하는 테이블과 뷰에 대한 SELECT
또한 계정에 지원되는 대규모 언어 모델(LLM)이 하나 이상 있어야 해요. 확인하려면 다음 명령을 실행해요:
SHOW MODELS LIKE 'claude-4-sonnet' IN SNOWFLAKE.MODELS;
결과가 없으면 claude-3-7-sonnet, mistral-large2, 또는 openai-gpt-4.1을 확인해 보세요. 최소한 하나는 사용 가능해야 해요.
시맨틱 뷰 열기
기존 시맨틱 뷰는 다음 두 가지 방식으로 열 수 있어요:
- CoCo에게 물어보기. 작업할 뷰 이름을 말하면 CoCo가 열어 줘요.
- 시맨틱 뷰 목록 사용하기. Snowsight에서 AI & ML » Cortex Analyst를 선택해 접근 권한이 있는 시맨틱 뷰를 나열한 다음 열고 싶은 뷰를 선택해요.
뷰는 편집기에서 YAML 파일로 열리고, 워크스페이스 파일 탐색기에 시맨틱 뷰(.sv.yaml)와 프로젝트 파일이 표시돼요.
참고: 워크스페이스에
cortex-project.yaml파일이 자동으로 나타나요. 이것은 프로젝트에 속한 파일과 배포 위치(대상 데이터베이스 및 스키마)를 추적하는 프로젝트 매니페스트예요. 이 파일은 무시해도 돼요. Semantic Studio와 CoCo가 자동으로 관리해요.
시맨틱 뷰 만들기
새 시맨틱 뷰를 만들려면 Add new » Semantic View를 선택해요. 그러면 뷰를 생성해 주는 Semantic View Autopilot 마법사가 열려요. 이 마법사는 시작을 위한 여러 옵션을 제공하며, Snowflake는 대화형으로 뷰 생성 과정을 안내하는 CoCo를 권장해요. SQL 쿼리를 제공하거나 Tableau 파일, Power BI 파일, YAML 사양을 업로드할 수도 있어요.
전체 생성 과정은 Semantic View Autopilot을 참고해요. 뷰가 만들어지면 이 페이지의 나머지 내용을 사용해 다듬어 보세요.
참고: 시맨틱 뷰를 편집하는 것은 사실상 기존 뷰를 교체하는 것이에요. 기존 시맨틱 뷰를 교체하려면 다음 권한이 부여된 역할을 사용해야 해요:
- 시맨틱 뷰를 만드는 스키마에 대한 CREATE SEMANTIC VIEW
- 시맨틱 뷰를 만드는 데이터베이스와 스키마에 대한 USAGE
- 시맨틱 뷰에서 사용하는 테이블과 뷰에 대한 SELECT
이름과 설명 설정하기
시맨틱 뷰의 이름과 설명은 사용자가 뷰의 목적을 발견하고 이해하는 데 도움을 줘요. 둘 다 YAML 파일의 최상위 필드이며, CoCo에게 설정하도록 요청할 수 있어요.
참고: 이 시맨틱 뷰를 Cortex Agents에서 툴로 사용한다면, 뷰 이름이 툴 이름으로 사용되는데 1~64자여야 해요.
팁: 명확하고 상세한 설명을 작성해 다음을 설명하세요:
- 이 뷰가 답할 수 있는 비즈니스 질문
- 포함하는 데이터 소스
- 이 뷰를 사용해야 하는 대상 예시: "제품 및 고객별 수익 분석(전년 대비 추세 포함). 이 뷰를 사용해 지역, 제품 카테고리, 고객 세그먼트별 판매 성과를 분석하세요."
양식으로 이름이나 설명을 수정하려면:
- 시맨틱 뷰 이름 옆의 Edit를 선택해요.
- 이름이나 설명을 변경해요.
- Apply를 선택해요.
논리 테이블 정의하기
논리 테이블은 고객, 주문, 제품 같은 비즈니스 엔티티를 나타내며 물리적 데이터베이스 테이블이나 뷰에 매핑돼요. 각 시맨틱 뷰에는 하나 이상의 논리 테이블이 포함돼요.
각 논리 테이블에 대해 다음을 정의해요:
- 이름(Name): 이 테이블의 비즈니스 친화적인 이름
- 설명(Description): 이 테이블이 무엇을 나타내는지에 대한 설명
- 동의어(Synonyms): 사용자가 이 엔티티에 사용할 수 있는 대체 이름
- 기본 키(Primary key): 행을 고유하게 식별하는 컬럼
CoCo에게 물리적 테이블에서 논리 테이블을 추가하라고 요청하면, 지정한 컬럼의 dimension과 fact를 생성해 줘요. 예: Add ANALYTICS.SALES.CUSTOMERS as a logical table and set the primary key to customer_id.
양식으로 논리 테이블을 추가하려면:
- + Logical Table을 선택해요.
- 마법사의 Select a table 단계에서:
- 시맨틱 뷰에 사용할 데이터가 들어 있는 테이블이나 뷰를 선택해요.
- Next를 선택해요.
- 마법사의 Select columns 단계에서:
- 뷰에 포함할 컬럼을 선택해요.
- 테이블이나 뷰의 모든 컬럼을 선택하려면 해당 테이블이나 뷰를 선택해요.
- Generate logical table을 선택해요.
기존 논리 테이블의 이름, 설명, 동의어, 기본 키를 변경하려면:
- 논리 테이블 이름 옆의 Edit Logical Table을 선택해요.
- 이름, 설명, 동의어, 기본 키를 변경해요.
- 설명이나 동의어를 지정하지 않았다면 Generate fields를 선택해 자동으로 채울 수 있어요.
- Save를 선택해요.
물리적 테이블 대신 SQL 쿼리에서 논리 테이블을 정의하려면 Using an SQL query as a logical table in a semantic view를 참고해요.
fact, dimension, metric 정의하기
각 논리 테이블 안에서 사용자가 쿼리할 수 있는 비즈니스 개념을 정의해요:
- Dimension: 고객 이름, 제품 카테고리, 주문 날짜 같은 컨텍스트를 제공하는 범주형 속성
- Fact: 판매 금액, 수량, 단가 같은 행 수준(row-level) 정량 데이터
- Metric: SUM, AVG, COUNT 같은 함수로 계산된 집계 측정값(예: 총 수익, 평균 주문 가치)
각각은 이름, SQL 표현식, 데이터 타입이 필요해요. 이러한 요소와 그 관계에 대한 전체 설명은 Overview of semantic views와 YAML specification for semantic views를 참고해요.
다음 기능도 사용할 수 있어요:
- 파생 메트릭(Derived metrics): 여러 테이블의 메트릭을 결합하는 뷰 수준 메트릭. 자세한 내용은 Defining derived metrics를 참고해요.
- Private access modifiers: fact나 metric을 private으로 표시해 다른 계산에서 여전히 사용하면서도 쿼리에서는 숨길 수 있어요. 자세한 내용은 Marking a fact or metric as private을 참고해요.
- 메트릭의 선호 조인 경로: 두 논리 테이블 사이에 여러 관계 경로가 있다면 메트릭이 사용할 관계를 선택할 수 있어요.
재사용 가능한 명명된 필터를 정의하려면 Defining filters for logical tables in a semantic view을, 로직 파라미터화는 Using variables in a semantic view을 참고해요.
양식으로 fact, dimension, metric을 추가하려면:
- Fact, Dimension, 또는 Metric을 선택해요.
- 새 fact, dimension, metric에 대한 정보를 입력하고 Add를 선택해요.
fact, dimension, metric을 수정하거나 제거하려면:
- Facts, Dimensions, 또는 Metrics를 선택해 리스트를 표시해요.
- 변경하려는 fact, dimension, metric에 대해:
- 항목을 수정하려면 Edit를 선택해요.
- 항목을 제거하려면 Remove fact, Remove dimension, 또는 Remove metric을 선택해요.
관계(Relationships) 정의하기
관계는 논리 테이블이 어떻게 조인되는지 정의하며, 여러 테이블에 걸친 쿼리를 가능하게 해줘요. 각 관계는 한 테이블의 어떤 컬럼이 다른 테이블의 컬럼을 참조하는지 정의해요:
- 관계의 이름(예:
orders_to_customers) - 왼쪽 테이블(외래 키가 있는 테이블)과 그 조인 컬럼
- 오른쪽 테이블(참조되는 테이블)과 그 조인 컬럼
참고: 시맨틱 뷰에서는 일반적으로 조인 유형(왼쪽 외부, 내부)이나 관계 유형(일대일, 다대일)을 지정할 필요가 없어요. 이들은 쿼리 시 데이터와 기본 키 정의에서 자동으로 유추돼요.
시맨틱 뷰가 충족해야 하는 구조적 및 시맨틱 규칙은 How Snowflake validates semantic views를 참고해요.
양식으로 관계를 추가하려면:
- + Relationship을 선택해요.
- 관계 이름을 입력하고, 관계의 테이블을 선택한 다음, 테이블을 조인하는 데 사용할 컬럼을 선택해요.
- Add를 선택해요.
변경을 마친 후에는 Save를 선택해요.
정확도 향상하기
Cortex Agents가 생성하는 답변의 정확도와 신뢰도를 높이려면 시맨틱 뷰에 컨텍스트와 지침을 추가해요.
검증 쿼리(Verified queries)
Verified Queries 섹션에 샘플 쿼리를 추가해요:
- Cortex Agents가 시맨틱 뷰를 사용하는 방법을 이해하도록 돕는 예시 쿼리예요.
- 데이터의 일반적인 사용 사례를 나타내는 쿼리를 추가해요.
자세한 내용은 Cortex Analyst Verified Query Repository를 참고해요. 실제 사용 이력을 바탕으로 제안된 검증 쿼리를 검토하고 수락하려면 Suggestions for semantic models and views를 참고해요.
동의어(Synonyms)
테이블, fact, dimension, metric에 동의어를 추가해요:
- 사용자가 쿼리에서 사용할 수 있는 대체 용어예요.
- 동의어는 Cortex Agents가 사용자 질문을 올바르게 해석하도록 도와줘요. 예를 들어 사용자가 "customers"를 "clients"나 "accounts"로 부를 수 있어요.
참고: 동의어는 AI로 자동 생성하기보다 수동으로 추가하세요. 내부 용어, 약어, 레거시 이름 같은 도메인 특화 대안에 집중하세요. 자동 생성된 동의어는 시맨틱 뷰 품질을 떨어뜨리는 경우가 많아요.
Custom instructions
SQL 생성과 질문 처리를 조정하기 위해 custom instructions를 추가해요:
- 데이터를 해석해야 하는 방법에 대한 추가 컨텍스트를 제공해요.
- 고려해야 할 비즈니스 규칙이나 제약 조건을 포함해요.
자세한 내용은 Custom instructions in Cortex Analyst를 참고해요. 더 넓은 모델링 안내는 Best practices for modeling semantic views을 참고해요.
배포(Deploy)
Deploy는 로컬 YAML 파일을 라이브 Snowflake 객체로 직접 푸시해요. 이 작업은 Git을 사용하지 않으며, 배포와 Git 커밋은 별개의 작업이에요.
- 상단 바에서 Deploy를 선택해요.
- 배포 대상을 선택해요.
- 로컬 파일과 라이브 객체 사이에서 무엇이 변경됐는지 보여 주는 diff 미리보기를 검토해요.
- 배포를 확인해요.
참고: Deploy는 로컬 파일이 라이브 객체보다 앞서 있는지 뒤처져 있는지 알지 못해요. 다른 사람이 마지막으로 연 이후에 라이브 객체를 업데이트했다면, 배포 시 그들의 변경 사항을 덮어쓰게 돼요. 배포 전에 팀과 협의하거나 Git 워크플로우를 사용해 변경 사항을 관리하세요.
Git으로 버전 관리하기
Semantic Studio는 Workspaces 안에서 실행되므로 워크스페이스를 Git 저장소에 연결할 수 있어요. 이렇게 하면 분기 기반 워크플로우, 커밋 기록, 프로덕션에 반영되기 전에 변경 사항을 검토하는 기능을 얻을 수 있어요. SQL 파일이나 노트북에 사용하는 것과 동일한 패턴이에요.
Git 연결 워크스페이스를 설정하려면:
- Workspaces 메뉴에서 From Git repository를 선택해요.
- 저장소 URL을 붙여넣어요(예:
https://github.com/my-org/my-repo). - API 통합과 인증 방법(OAuth, 개인 액세스 토큰, 공개 저장소)을 선택해요.
연결되면 Workspaces에서 직접 분기를 만들고, 변경 사항을 가져오고, 커밋과 푸시를 하고, 충돌을 해결할 수 있어요. 시맨틱 뷰 YAML 파일은 저장소의 다른 모든 것과 함께 버전 관리돼요.
전체 설정 지침은 Integrate workspaces with a Git repository를 참고해요.
참고: Git 통합은 선택사항이에요. Semantic Studio는 로컬(비-Git) 워크스페이스에서도 동작하며, Git은 나중에 언제든 추가할 수 있어요.
시맨틱 뷰를 자동(CI/CD) 배포를 포함한 데이터 엔지니어링 파이프라인의 일부로 관리하는 방법은 Best practices for developing and deploying semantic views를 참고해요.
실패한 요청 디버깅하기
- 에이전트의 모니터링 탭에서 잘못된 결과를 반환한 요청을 찾고 요청 ID를 복사해요.
- Semantic Studio에서 요청 ID를 CoCo에 붙여넣어요:
This request returned the wrong revenue number. The correct answer is $12M. - 설명을 검토해요. CoCo는 요청을 파이프라인(라우팅, 툴 선택, SQL 생성)을 따라 추적하고 무엇이 잘못됐는지 보고해요.
- 인라인 diff로 나타나는 제안된 수정 사항을 검토하고 수락해요.
시맨틱 뷰를 사용하는 요청을 모니터링하려면 Monitor Cortex Agent requests을 참고해요.
시맨틱 뷰에 액세스 권한 부여하기
다른 사용자나 역할이 시맨틱 뷰를 사용할 수 있게 하려면 적절한 권한을 부여해요. 시맨틱 뷰는 표준 Snowflake 권한 모델을 지원해요:
- SELECT: 시맨틱 뷰를 쿼리하고 내용을 보는 데 필요해요. 이 권한이면 Cortex Agents에서 시맨틱 뷰를 사용하기에 충분해요.
- REFERENCES: 데이터에 대한 액세스를 부여하지 않고 시맨틱 뷰의 구조를 볼 수 있게 해줘요.
- OWNERSHIP: 시맨틱 뷰에 대한 완전한 제어
다른 역할에 시맨틱 뷰를 보고 쿼리할 권한을 부여하려면:
- Share를 선택해요.
- 시맨틱 뷰를 보고 쿼리할 권한을 부여할 역할을 선택해요.
- Done을 선택해요.
이렇게 하면 선택한 역할에 시맨틱 뷰의 SELECT와 REFERENCES 권한이 부여돼요. 미래 권한(future grants)과 더 복잡한 시나리오를 포함해 시맨틱 뷰 권한 부여에 대한 자세한 내용은 Granting privileges on semantic views를 참고해요.
시맨틱 뷰를 다른 계정과 공유하려면 Sharing semantic views를 참고해요.
제한 사항(Limitations)
- 파일 수집(File ingestion). Tableau나 Power BI 모델에서 시맨틱 뷰를 만들려면 Semantic View Autopilot을 사용해요.
- 모니터링 및 평가 패널. Semantic Studio는 모니터링 대시보드를 내장하는 대신 외부 링크로 연결해요.
- 오래된 파일 감지(Stale-file detection). Deploy는 라이브 객체가 마지막으로 연 이후 변경됐는지 확인하지 않고 덮어써요.
- 다중 파일 편집. CoCo는 열린 파일 안에서만 작업하며 시맨틱 뷰와 에이전트 파일을 넘나들며 탐색하지 않아요.