DESCRIBE SEMANTIC VIEW
DESCRIBE SEMANTIC VIEW
시맨틱 뷰(Semantic View)를 구성하는 논리 테이블, 차원(Dimension), 사실(Fact), 메트릭(Metric)의 속성을 설명하는 명령어입니다. DESCRIBE는 DESC로 줄여서 쓸 수 있어요.
출처: 문서
본문
DESCRIBE SEMANTIC VIEW는 시맨틱 뷰를 구성하는 논리 테이블, 차원, 사실, 메트릭의 속성을 설명합니다. 관련 명령어로 CREATE SEMANTIC VIEW, ALTER SEMANTIC VIEW, DROP SEMANTIC VIEW, SHOW SEMANTIC VIEWS, SHOW SEMANTIC DIMENSIONS, SHOW SEMANTIC DIMENSIONS FOR METRIC, SHOW SEMANTIC FACTS, SHOW SEMANTIC METRICS가 있어요.
구문 (Syntax)
{ DESCRIBE | DESC } SEMANTIC VIEW <name>
파라미터 (Parameters)
- name — 설명할 시맨틱 뷰의 식별자를 지정합니다. 식별자에 공백이나 특수 문자가 포함된 경우 전체 문자열을 큰따옴표로 감싸야 합니다. 큰따옴표로 감싼 식별자는 대소문자를 구분해요. 자세한 내용은 Identifier requirements를 참고하세요.
출력 (Output)
명령어 출력은 논리 테이블, 관계, 사실, 차원, 메트릭과 시맨틱 뷰 자체에 대한 속성과 메타데이터를 제공합니다.
뷰의 각 행은 다음 중 하나의 속성을 나타냅니다.
- 논리 테이블
- 관계(Relationship)
- 사실(Fact)
- 차원(Dimension)
- 메트릭(Metric)
- 검증된 쿼리(Verified query)
- 커스텀 지침(Custom instructions)
- 시맨틱 뷰 자체
다음은 이 명령어 출력의 예입니다.
+--------------+------------------------------+---------------+--------------------------+----------------------------------------+
| object_kind | object_name | parent_entity | property | property_value |
|--------------+------------------------------+---------------+--------------------------+----------------------------------------|
| NULL | NULL | NULL | COMMENT | Comment about the semantic view |
| TABLE | CUSTOMERS | NULL | BASE_TABLE_DATABASE_NAME | SNOWFLAKE_SAMPLE_DATA |
| ... | ... | ... | ... | ... |
| DIMENSION | CUSTOMER_NAME | CUSTOMERS | TABLE | CUSTOMERS |
| ... | ... | ... | ... | ... |
| RELATIONSHIP | LINE_ITEM_TO_ORDERS | LINE_ITEMS | TABLE | LINE_ITEMS |
| ... | ... | ... | ... | ... |
| FACT | DISCOUNTED_PRICE | LINE_ITEMS | TABLE | LINE_ITEMS |
| ... | ... | ... | ... | ... |
| METRIC | AVERAGE_LINE_ITEMS_PER_ORDER | ORDERS | TABLE | ORDERS |
| ... | ... | ... | ... | ... |
+--------------+------------------------------+---------------+--------------------------+----------------------------------------+
위에 표시된 대로 각 행은 논리 테이블, 차원, 관계, 메트릭 또는 사실의 속성을 나타냅니다. 예를 들어:
- 첫 번째 행은 시맨틱 뷰 자체의 주석 속성 값입니다.
- 두 번째 행은 customers라는 논리 테이블의
base_table_database_name속성 값입니다.
뷰에는 다음 컬럼이 포함됩니다.
| 컬럼 | 설명 |
|---|---|
| object_kind | 이 행에 대한 속성을 가진 객체의 유형입니다. 값은 다음 중 하나일 수 있습니다: TABLE(뷰의 논리 테이블), RELATIONSHIP, DIMENSION, FACT, METRIC, DERIVED_METRIC(파생 메트릭용), CUSTOM_INSTRUCTIONS(커스텀 지침용), AI_VERIFIED_QUERY(검증된 쿼리용), NULL(주석과 같은 시맨틱 뷰 자체에 적용되는 속성). |
| object_name | 이 행에 대한 속성을 가진 차원, 사실, 메트릭, 논리 테이블, 관계 또는 검증된 쿼리의 이름입니다. 시맨틱 뷰 자체의 속성이나 커스텀 지침을 나타내는 행에서는 이 값이 NULL입니다. |
| parent_entity | 차원, 사실, 메트릭 또는 관계의 상위 엔티티 이름입니다. 시맨틱 뷰 자체, 논리 테이블 속성, 파생 메트릭 속성, 커스텀 지침 속성, 검증된 쿼리 속성을 나타내는 행에서는 NULL입니다. |
| property | 논리 테이블, 제약 조건, 관계, 차원, 사실, 메트릭, 커스텀 지침 또는 시맨틱 뷰의 속성 이름입니다. 이 값은 객체 유형(object_kind)에 따라 달라집니다. |
| property_value | 논리 테이블, 관계, 차원, 사실, 메트릭, 커스텀 지침 또는 시맨틱 뷰의 속성 값입니다. |
논리 테이블의 속성 (Properties for logical tables)
object_kind 컬럼이 TABLE이면 property 컬럼은 다음 값을 포함할 수 있습니다.
| 속성 이름 | 설명 |
|---|---|
| BASE_TABLE_DATABASE_NAME | 논리 테이블을 포함하는 데이터베이스의 이름입니다. 논리 테이블이 SQL 쿼리로 정의된 경우에는 없습니다. |
| BASE_TABLE_SCHEMA_NAME | 논리 테이블을 포함하는 스키마의 이름입니다. 논리 테이블이 SQL 쿼리로 정의된 경우에는 없습니다. |
| BASE_TABLE_NAME | 논리 테이블의 이름입니다. 논리 테이블이 SQL 쿼리로 정의된 경우에는 없습니다. |
| DEFINITION | 논리 테이블을 정의하는 SQL 쿼리입니다. 논리 테이블이 물리 테이블이 아니라 SQL 쿼리로 정의된 경우에만 있습니다. |
| SYNONYMS | 논리 테이블의 동의어를 나타내는 VARCHAR 값 배열입니다. |
| PRIMARY_KEY | 논리 테이블의 기본 키를 구성하는 컬럼 이름을 지정하는 VARCHAR 값 배열입니다. |
제약 조건의 속성 (Properties for constraints)
object_kind 컬럼이 CONSTRAINT이면 해당 행은 범위 조인(range join)에 사용되는 제약 조건을 나타냅니다. property 컬럼은 다음 값을 포함할 수 있습니다.
| 속성 이름 | 설명 |
|---|---|
| CONSTRAINT_TYPE | 값은 DISTINCT_RANGE입니다. |
| START_COLUMN | 범위의 시작을 나타내는 컬럼의 이름입니다. |
| END_COLUMN | 범위의 끝을 나타내는 컬럼의 이름입니다. |
관계의 속성 (Properties for relationships)
object_kind 컬럼이 RELATIONSHIP이면 property 컬럼은 다음 값을 포함할 수 있습니다.
| 속성 이름 | 설명 |
|---|---|
| TABLE | 관계에 있는 논리 테이블 중 하나의 이름입니다. |
| FOREIGN_KEY | 관계에서 사용되는 해당 논리 테이블의 컬럼 이름입니다. |
| REF_TABLE | 관계에 있는 다른 논리 테이블의 이름입니다. |
| REF_KEY | 다음 값 중 하나입니다: 범위 조인을 나타내는 관계의 경우 start_column, end_column, type(=RANGE) 키를 가진 객체에 대한 JSON 형식 문자열을 포함하는 배열. ASOF 조인을 나타내는 관계의 경우 첫 번째 테이블의 컬럼 이름과 두 번째 테이블의 컬럼(column) 및 유형(type=ASOF)을 가진 JSON 객체를 포함하는 배열. 다른 유형의 관계에서는 관계에 있는 다른 논리 테이블의 컬럼 이름. |
사실, 차원, 메트릭의 속성 (Properties for facts, dimensions, and metrics)
object_kind 컬럼이 FACT, DIMENSION 또는 METRIC이면 property 컬럼은 다음 값을 포함할 수 있습니다.
| 속성 이름 | 설명 |
|---|---|
| TABLE | 차원, 사실 또는 메트릭을 정의하는 데 사용되는 논리 테이블의 이름입니다. |
| EXPRESSION | 차원, 사실 또는 메트릭에 대한 SQL 표현식입니다. |
| DATA_TYPE | 평가된 SQL 표현식의 SQL 데이터 유형입니다. |
| ACCESS_MODIFIER | 비공개 사실과 메트릭은 PRIVATE, 그 외에는 PUBLIC입니다. |
참고: 파생 메트릭(derived metric)의 경우
TABLE속성이 없습니다.
또한 해당 행이 Cortex Search Service를 사용하는 차원을 나타내는 경우 property 컬럼은 다음 값을 포함할 수 있습니다.
| 속성 이름 | 설명 |
|---|---|
| CORTEX_SEARCH_SERVICE_COLUMN_NAME | Cortex Search Service에서 검색할 수 있는 컬럼의 이름입니다. |
| CORTEX_SEARCH_SERVICE_DATABASE_NAME | Cortex Search Service를 포함하는 데이터베이스의 이름입니다. |
| CORTEX_SEARCH_SERVICE_SCHEMA_NAME | Cortex Search Service를 포함하는 스키마의 이름입니다. |
| CORTEX_SEARCH_SERVICE_NAME | Cortex Search Service의 이름입니다. |
커스텀 지침의 속성 (Properties for custom instructions)
object_kind 컬럼이 CUSTOM_INSTRUCTIONS이면 해당 행은 커스텀 지침의 속성을 나타냅니다. property 컬럼은 다음 값을 포함할 수 있습니다.
| 속성 이름 | 설명 |
|---|---|
| AI_QUESTION_CATEGORIZATION | 질문을 분류하는 방법을 설명하는 Cortex Analyst용 커스텀 지침입니다. |
| AI_SQL_GENERATION | SQL 문 생성 방법을 설명하는 Cortex Analyst용 커스텀 지침입니다. |
검증된 쿼리의 속성 (Properties for verified queries)
object_kind 컬럼이 AI_VERIFIED_QUERY이면 해당 행은 검증된 쿼리의 속성을 나타냅니다. property 컬럼은 다음 값을 포함할 수 있습니다.
| 속성 이름 | 설명 |
|---|---|
| QUESTION | 예상 쿼리를 생성해야 하는 질문입니다. |
| VERIFIED_AT | 쿼리가 검증된 시점의 타임스탬프(Unix epoch 이후의 초)입니다. |
| ONBOARDING_QUESTION | TRUE이면 온보딩 질문입니다(대안으로 Cortex Analyst로 구동되는 앱과 상호작용하는 사용자에게 제안되는 질문). |
| VERIFIED_BY | 쿼리가 질문에 답하는지 검증한 연락처의 목적과 이름입니다. |
| SQL | 질문에 답하는 쿼리의 SQL 문입니다. |
시맨틱 뷰의 속성 (Properties for semantic views)
object_kind 컬럼이 NULL이면 property 컬럼은 다음 값을 포함할 수 있습니다.
| 속성 이름 | 설명 |
|---|---|
| COMMENT | 시맨틱 뷰에 대한 주석입니다. |
접근 제어 요구 사항 (Access control requirements)
이 작업을 실행하는 역할은 최소한 ANY 권한(객체: Semantic view)이 있어야 합니다.
스키마 안의 객체를 조작하려면 상위 데이터베이스에 대한 권한이 1개 이상, 상위 스키마에 대한 권한이 1개 이상 필요합니다. 지정된 권한 집합으로 커스텀 역할을 만드는 방법은 Creating custom roles을, securable 객체에 대한 역할과 권한 부여에 관한 일반 정보는 Overview of Access Control을 참고하세요.
사용 참고 사항 (Usage notes)
- 이 명령어의 출력을 후처리하려면 파이프 연산자(
->>)나RESULT_SCAN함수를 사용할 수 있어요. 두 방식 모두 출력을 조회 가능한 결과 집합으로 취급합니다. 예를 들어 SHOW 명령어 출력에서 원하는 컬럼만 선택하거나 행을 필터링할 수 있어요. - 출력 컬럼을 참조할 때는 컬럼 이름을 큰따옴표 식별자로 사용하세요. 예를 들어 출력 컬럼
type을 선택하려면SELECT "type"처럼 지정합니다. SHOW 명령어의 출력 컬럼 이름은 소문자이므로 큰따옴표 식별자를 반드시 사용해야 해요.
예제 (Examples)
다음은 tpch_rev_analysis라는 시맨틱 뷰를 설명하는 예제입니다.
DESC SEMANTIC VIEW tpch_rev_analysis;
+--------------+------------------------------+---------------+--------------------------+----------------------------------------+
| object_kind | object_name | parent_entity | property | property_value |
|--------------+------------------------------+---------------+--------------------------+----------------------------------------|
| NULL | NULL | NULL | COMMENT | Comment about the semantic view |
| TABLE | CUSTOMERS | NULL | BASE_TABLE_DATABASE_NAME | SNOWFLAKE_SAMPLE_DATA |
| TABLE | CUSTOMERS | NULL | BASE_TABLE_SCHEMA_NAME | TPCH_SF1 |
| TABLE | CUSTOMERS | NULL | BASE_TABLE_NAME | CUSTOMER |
| TABLE | CUSTOMERS | NULL | PRIMARY_KEY | ["C_CUSTKEY"] |
| TABLE | CUSTOMERS | NULL | COMMENT | Main table for customer data |
| DIMENSION | CUSTOMER_NAME | CUSTOMERS | TABLE | CUSTOMERS |
| DIMENSION | CUSTOMER_NAME | CUSTOMERS | EXPRESSION | customers.c_name |
| DIMENSION | CUSTOMER_NAME | CUSTOMERS | DATA_TYPE | VARCHAR(25) |
| DIMENSION | CUSTOMER_NAME | CUSTOMERS | SYNONYMS | ["customer name"] |
| DIMENSION | CUSTOMER_NAME | CUSTOMERS | COMMENT | Name of the customer |
| TABLE | LINE_ITEMS | NULL | BASE_TABLE_DATABASE_NAME | SNOWFLAKE_SAMPLE_DATA |
| TABLE | LINE_ITEMS | NULL | BASE_TABLE_SCHEMA_NAME | TPCH_SF1 |
| TABLE | LINE_ITEMS | NULL | BASE_TABLE_NAME | LINEITEM |
| TABLE | LINE_ITEMS | NULL | PRIMARY_KEY | ["L_ORDERKEY","L_LINENUMBER"] |
| TABLE | LINE_ITEMS | NULL | COMMENT | Line items in orders |
| RELATIONSHIP | LINE_ITEM_TO_ORDERS | LINE_ITEMS | TABLE | LINE_ITEMS |
| RELATIONSHIP | LINE_ITEM_TO_ORDERS | LINE_ITEMS | REF_TABLE | ORDERS |
| RELATIONSHIP | LINE_ITEM_TO_ORDERS | LINE_ITEMS | FOREIGN_KEY | ["L_ORDERKEY"] |
| RELATIONSHIP | LINE_ITEM_TO_ORDERS | LINE_ITEMS | REF_KEY | ["O_ORDERKEY"] |
| FACT | DISCOUNTED_PRICE | LINE_ITEMS | TABLE | LINE_ITEMS |
| FACT | DISCOUNTED_PRICE | LINE_ITEMS | EXPRESSION | l_extendedprice * (1 - l_discount) |
| FACT | DISCOUNTED_PRICE | LINE_ITEMS | DATA_TYPE | NUMBER(25,4) |
| FACT | DISCOUNTED_PRICE | LINE_ITEMS | COMMENT | Extended price after discount |
| FACT | LINE_ITEM_ID | LINE_ITEMS | TABLE | LINE_ITEMS |
| FACT | LINE_ITEM_ID | LINE_ITEMS | EXPRESSION | CONCAT(l_orderkey, '-', l_linenumber) |
| FACT | LINE_ITEM_ID | LINE_ITEMS | DATA_TYPE | VARCHAR(134217728) |
| TABLE | ORDERS | NULL | BASE_TABLE_DATABASE_NAME | SNOWFLAKE_SAMPLE_DATA |
| TABLE | ORDERS | NULL | BASE_TABLE_SCHEMA_NAME | TPCH_SF1 |
| TABLE | ORDERS | NULL | BASE_TABLE_NAME | ORDERS |
| TABLE | ORDERS | NULL | SYNONYMS | ["sales orders"] |
| TABLE | ORDERS | NULL | PRIMARY_KEY | ["O_ORDERKEY"] |
| TABLE | ORDERS | NULL | COMMENT | All orders table for the sales domain |
| RELATIONSHIP | ORDERS_TO_CUSTOMERS | ORDERS | TABLE | ORDERS |
| RELATIONSHIP | ORDERS_TO_CUSTOMERS | ORDERS | REF_TABLE | CUSTOMERS |
| RELATIONSHIP | ORDERS_TO_CUSTOMERS | ORDERS | FOREIGN_KEY | ["O_CUSTKEY"] |
| RELATIONSHIP | ORDERS_TO_CUSTOMERS | ORDERS | REF_KEY | ["C_CUSTKEY"] |
| METRIC | AVERAGE_LINE_ITEMS_PER_ORDER | ORDERS | TABLE | ORDERS |
| METRIC | AVERAGE_LINE_ITEMS_PER_ORDER | ORDERS | EXPRESSION | AVG(orders.count_line_items) |
| METRIC | AVERAGE_LINE_ITEMS_PER_ORDER | ORDERS | DATA_TYPE | NUMBER(36,6) |
| METRIC | AVERAGE_LINE_ITEMS_PER_ORDER | ORDERS | COMMENT | Average number of line items per order |
| FACT | COUNT_LINE_ITEMS | ORDERS | TABLE | ORDERS |
| FACT | COUNT_LINE_ITEMS | ORDERS | EXPRESSION | COUNT(line_items.line_item_id) |
| FACT | COUNT_LINE_ITEMS | ORDERS | DATA_TYPE | NUMBER(18,0) |
| METRIC | ORDER_AVERAGE_VALUE | ORDERS | TABLE | ORDERS |
| METRIC | ORDER_AVERAGE_VALUE | ORDERS | EXPRESSION | AVG(orders.o_totalprice) |
| METRIC | ORDER_AVERAGE_VALUE | ORDERS | DATA_TYPE | NUMBER(30,8) |
| METRIC | ORDER_AVERAGE_VALUE | ORDERS | COMMENT | Average order value across all orders |
| DIMENSION | ORDER_DATE | ORDERS | TABLE | ORDERS |
| DIMENSION | ORDER_DATE | ORDERS | EXPRESSION | o_orderdate |
| DIMENSION | ORDER_DATE | ORDERS | DATA_TYPE | DATE |
| DIMENSION | ORDER_DATE | ORDERS | COMMENT | Date when the order was placed |
| DIMENSION | ORDER_YEAR | ORDERS | TABLE | ORDERS |
| DIMENSION | ORDER_YEAR | ORDERS | EXPRESSION | YEAR(o_orderdate) |
| DIMENSION | ORDER_YEAR | ORDERS | DATA_TYPE | NUMBER(4,0) |
| DIMENSION | ORDER_YEAR | ORDERS | COMMENT | Year when the order was placed |
+--------------+------------------------------+---------------+--------------------------+----------------------------------------+