Semantic Manifest

Semantic Manifest

semantic_manifest.json은 dbt Semantic Layer가 메트릭 쿼리를 올바르게 빌드·실행하기 위해 MetricFlow가 필요로 하는 아티팩트예요. 프로젝트를 파싱하는 모든 명령어가 이 파일을 생성하며, Semantic Layer의 구조와 상세를 이해하는 데 유용한 참고 자료예요.

출처: 문서

본문

생성 주체: 프로젝트를 파싱하는 모든 명령어. 여기에는 deps, clean, debug, init을 제외한 모든 명령어가 포함돼요.

dbt는 MetricFlow가 dbt Semantic Layer의 메트릭 쿼리를 올바르게 빌드·실행하는 데 필요한 Semantic Manifest(semantic_manifest.json)라는 아티팩트 파일을 생성해요. 이 아티팩트에는 dbt Semantic Layer에 대한 포괄적인 정보가 담겨 있어요. MetricFlow와의 통합 지점 역할을 하는 내부 파일이에요.

dbt가 생성한 semantic manifest를 사용하면 MetricFlow가 데이터 플로우 계획을 인스턴스화하고 Semantic Layer 쿼리 요청에서 SQL을 생성해요. 데이터 모델의 구조와 상세를 이해할 수 있는 귀중한 참고 자료예요.

manifest.json과 마찬가지로 semantic_manifest.json도 dbt 프로젝트의 target 디렉터리에 위치해요. 이 디렉터리에는 프로젝트 실행 중 생성된 다양한 아티팩트(컴파일된 모델·테스트 등)가 저장돼요.

semantic_manifest.json이 manifest.json과 함께 존재하는 이유는 두 가지예요:

• 역직렬화(Deserialization): dbt와 MetricFlow는 데이터 직렬화를 처리하는 라이브러리가 달라요.
• 효율성과 성능(Efficiency and performance): MetricFlow와 dbt Semantic Layer는 manifest의 특정 의미(semantic) 정보가 필요해요. semantic_manifest.json에 출력되는 정보를 줄이면 처리 과정이 더 효율적이 되고, dbt와 MetricFlow 사이의 데이터 처리가 더 빨라져요.

최상위 키(Top-level keys)

(dbt v1.12 이상 적용) semantic manifest의 최상위 키는 다음과 같아요: semantic_models — 엔티티와 차원이 있는 데이터의 시작점으로, dbt 프로젝트의 모델에 해당해요. metrics — 엔티티·차원 등을 결합해 정량적 지표를 정의하는 함수예요. project_configuration — 프로젝트 설정에 관한 정보를 담아요. saved_queries — MetricFlow에서 자주 쓰는 쿼리를 저장해요.

예시 target/semantic_manifest.json

{ "semantic_models": [ { "name": "semantic model name", "defaults": null, "description": "semantic model description", "node_relation": { "alias": "model alias", "schema_name": "model schema", "database": "model db", "relation_name": "Fully qualified relation name" }, "entities": ["entities in the semantic model"], "measures": ["measures in the semantic model"], "dimensions": ["dimensions in the semantic model" ], } ], "metrics": [ { "name": "name of the metric", "description": "metric description", "type": "metric type", "type_params": { "measure": { "name": "name for measure", "filter": "filter for measure", "alias": "alias for measure" }, "numerator": null, "denominator": null, "expr": null, "window": null, "grain_to_date": null, "metrics": ["metrics used in defining the metric. this is used in derived metrics"], "input_measures": [] }, "filter": null, "metadata": null } ], "project_configuration": { "time_spine_table_configurations": [ { "location": "fully qualified table name for timespine", "column_name": "date column", "grain": "day" } ], "metadata": null, "dsi_package_version": {} }, "saved_queries": [ { "name": "name of the saved query", "query_params": { "metrics": [ "metrics used in the saved query" ], "group_by": [ "TimeDimension('model_primary_key__date_column', 'day')", "Dimension('model_primary_key__metric_one')", "Dimension('model__dimension')" ], "where": null }, "description": "Description of the saved query", "metadata": null, "label": null, "exports": [ { "name": "saved_query_name", "config": { "export_as": "view", "schema_name": null, "alias": null } } ] } ]}

(dbt v1.12 이상 적용) Apache Ossie 문서 생성 주체: 프로젝트를 파싱하는 모든 명령어(semantic manifest와 동일).

dbt v1.12부터 dbt는 파싱 시점에 semantic_manifest.json과 함께 osi_document.json 파일을 target/ 디렉터리에 기록해요. 이 파일은 프로젝트의 Semantic Layer를 Apache Ossie 형식(의미 모델·메트릭을 기술하는 벤더 중립 스키마)으로 표현해요.

Ossie 문서는 전체 PydanticSemanticManifest를 Ossie 형식으로 변환해 생성돼요. 모든 dbt semantic layer 구조에 Ossie 대응이 있는 건 아니라서, 변환 중 요소가 버려지거나 저하되면 dbt는 경고(이벤트 코드 I078)를 내보내요:

semantic manifest 검증에 실패하면 dbt는 error 레벨 SemanticValidationFailure를 기록하고, 그 실행에서는 osi_document.json 작성을 건너뛰어요.

더 알아보기 (Learn more)

• Semantic Layer API
• dbt 아티팩트 개요