Dagster 프로젝트 구조와 Definitions 위치: 왜, 어디에 어떻게 둬야 할까?

Dagster를 이용해 데이터 파이프라인을 구성하다 보면
@asset으로 자산을 만들고, Definitions(...)로 이를 등록하게 됩니다.
그런데 예상과 다르게 Dagit에서 자산이 안 뜨거나,
"no repository found" 같은 에러가 발생할 때가 있죠.

이번 글에서는 그 원인을 설명하고,
올바른 프로젝트 구조와 Definitions 배치 위치에 대해 알아보겠습니다.

 

핵심 개념 요약

 

프로젝트 예시 구조

dagster_project/
├── assets/
│   └── sales_assets.py        # @asset 자산 정의
├── jobs/
│   └── job_defs.py            # Definitions 등록 (Dagit 진입점)
├── workspace.yaml             # Dagit이 읽을 경로
└── dagster_project/
    └── __init__.py

 

 

자산 정의: assets/sales_assets.py

from dagster import asset

@asset
def raw_sales():
    return [100, 200, None]

@asset
def filtered_sales(raw_sales):
    return [x for x in raw_sales if x is not None]

 

Definitions 등록: jobs/job_defs.py

from dagster import Definitions
from assets.sales_assets import raw_sales, filtered_sales

defs = Definitions(
    assets=[raw_sales, filtered_sales]
)

✅ 여기서 중요한 점:
defs = Definitions(...)는 반드시 파일의 최상단, 즉 전역(Global) 스코프에 위치해야 Dagit이 인식합니다.

 

 

잘못된 예시

# Dagit이 감지하지 못하는 경우
def get_defs():
    return Definitions(...)

# 또는 조건문 아래 정의도 인식 불가
if __name__ == "__main__":
    defs = Definitions(...)

 

 

workspace.yaml 설정

load_from:
  - python_file: jobs/job_defs.py

Dagit은 이 설정 파일을 기반으로
job_defs.py에서 이름이 정확히 defs인 변수를 찾아 로딩합니다.

 

왜 폴더를 이렇게 나누는가?

⚠️ jobs/는 @job decorator와 관련 없습니다.
단순히 “실행 정의(Definitions)를 담는 폴더”라는 네이밍일 뿐입니다.

 

 

마무리 정리

• Definitions(...)는 반드시 .py 파일의 전역에서 defs = ...로 선언되어야 함
• Dagit은 workspace.yaml에 지정된 파일에서 defs를 찾음
• 자산은 assets/, 정의는 jobs/ 등으로 모듈화하면 유지보수에 좋음

Dagster는 구조적으로 깨끗한 프로젝트 구성을 권장하는 프레임워크입니다.
작은 습관부터 정리해두면, 더 큰 DAG과 팀 작업에서도 매우 효율적입니다.