dbt rpc 명령어

dbt rpc 명령어

dbt-rpc 플러그인은 Remote Procedure Call(rpc) dbt 서버를 실행하는 데 사용해요. 이 서버는 dbt 프로젝트 컨텍스트에서 쿼리를 컴파일·실행하고, 실행 중인 프로세스를 나열·종료하는 메서드를 제공해요. (현재는 폐기 예정 상태예요.)

출처: 문서

본문

dbt-rpc 플러그인은 폐기 예정

dbt Labs는 dbt-core v1.5까지의 호환성을 위해 dbt-rpc를 적극적으로 유지 관리했어요. dbt-core v1.6(2023년 7월 출시)부터 dbt-rpc는 지속적인 호환성에 대해 더 이상 지원되지 않아요. 그동안 dbt Labs는 마지막 호환 버전의 dbt-core가 공식 지원이 종료될 때까지 dbt-rpc에 대해 핵심 유지 관리만 수행해요. 그 시점에 dbt Labs는 이 저장소를 읽기 전용으로 아카이브할 거예요.

개요

dbt-rpc 플러그인으로 Remote Procedure Call(rpc) dbt 서버를 실행할 수 있어요. 이 서버는 dbt 프로젝트 컨텍스트에서 쿼리를 컴파일·실행해요. 또한 RPC 서버는 실행 중인 프로세스를 나열·종료하는 메서드를 제공해요. dbt 프로젝트가 있는 디렉터리에서 rpc 서버를 실행하는 것을 권장해요. 서버는 프로젝트를 메모리로 컴파일한 다음, 해당 프로젝트의 dbt 컨텍스트에 대해 작업하라는 요청을 받아들여요.

Windows에서 실행 신뢰성 문제 때문에 Windows에서 rpc 서버를 실행하는 것은 권장하지 않아요. 필요하면 Docker 컨테이너가 유용한 해결책이 될 수 있어요.

자세한 내용은 dbt-rpc 저장소 소스 코드를 참고하세요.

서버 실행:

$ dbt-rpc serve
Running with dbt=1.5.0

16:34:31 | Concurrency: 8 threads (target='dev')
16:34:31 |
16:34:31 | Done.
Serving RPC server at 0.0.0.0:8580
Send requests to http://localhost:8580/jsonrpc

서버 설정

• --host: 수신할 호스트 지정(기본값=0.0.0.0)
• --port: 수신할 포트 지정(기본값=8580)

서버에 쿼리 제출: rpc 서버는 다음 형식의 요청을 기대해요:

rpc-spec.json

{
    "jsonrpc": "2.0",
    "method": "{ a valid rpc server command }",
    "id": "{ a unique identifier for this query }",
    "params": {
        "timeout": { timeout for the query in seconds, optional },
    }
}

내장 메서드

status

status 메서드는 rpc 서버의 상태를 반환해요. 이 메서드 응답에는 ready, compiling, error 같은 상위 수준 상태와, 프로젝트 초기 컴파일 중 축적된 로그 집합이 포함돼요. rpc 서버가 compiling 또는 error 상태일 때는 RPC 서버의 내장 메서드만 허용돼요.

예시 요청

{
    "jsonrpc": "2.0",
    "method": "status",
    "id": "2db9a2fe-9a39-41ef-828c-25e04dd6b07d"
}

예시 응답

{
    "result": {
        "status": "ready",
        "error": null,
        "logs": [..],
        "timestamp": "2019-10-07T16:30:09.875534Z",
        "pid": 76715
    },
    "id": "2db9a2fe-9a39-41ef-828c-25e04dd6b07d",
    "jsonrpc": "2.0"
}

poll

poll 엔드포인트는 실행 중이거나 완료된 작업의 상태, 로그, 결과(사용 가능한 경우)를 반환해요. poll 메서드는 응답을 폴링할 작업을 나타내는 request_token 매개변수가 필요해요. request_token은 compile, run, test 같은 dbt 작업의 응답에서 반환돼요.

매개변수:

• request_token: 응답을 폴링할 토큰
• logs: 응답에 로그를 포함할지 여부(기본값=false)
• logs_start: 로그를 가져올 시작 지점(0-인덱스, 기본값=0)

예시 요청

{
    "jsonrpc": "2.0",
    "method": "poll",
    "id": "2db9a2fe-9a39-41ef-828c-25e04dd6b07d",
    "params": {
        "request_token": "f86926fa-6535-4891-8d24-2cfc65d2a347",
        "logs": true,
        "logs_start": 0
    }
}

예시 응답

{
    "result": {
        "results": [],
        "generated_at": "2019-10-11T18:25:22.477203Z",
        "elapsed_time": 0.8381369113922119,
        "logs": [],
        "tags": {
            "command": "run --select my_model",
            "branch": "abc123"
        },
        "status": "success"
    },
    "id": "2db9a2fe-9a39-41ef-828c-25e04dd6b07d",
    "jsonrpc": "2.0"
}

ps

ps 메서드는 RPC 서버가 실행한 실행 중·완료된 프로세스를 나열해요.

매개변수

• completed: true면 완료된 작업도 반환(기본값=false)

예시 요청:

{
    "jsonrpc": "2.0",
    "method": "ps",
    "id": "2db9a2fe-9a39-41ef-828c-25e04dd6b07d",
    "params": {
        "completed": true
    }
}

예시 응답:

{
    "result": {
        "rows": [
            {
                "task_id": "561d4a02-18a9-40d1-9f01-cd875c3ec56d",
                "request_id": "3db9a2fe-9a39-41ef-828c-25e04dd6b07d",
                "request_source": "127.0.0.1",
                "method": "run",
                "state": "success",
                "start": "2019-10-07T17:09:49.865976Z",
                "end": null,
                "elapsed": 1.107261,
                "timeout": null,
                "tags": {
                    "command": "run --select my_model",
                    "branch": "feature/add-models"
                }
            }
        ]
    },
    "id": "2db9a2fe-9a39-41ef-828c-25e04dd6b07d",
    "jsonrpc": "2.0"
}

kill

kill 메서드는 실행 중인 작업을 종료해요. 실행 중인 작업의 task_id는 해당 작업을 호출한 원래 응답이나 ps 메서드의 결과에서 찾을 수 있어요.

예시 요청

{
    "jsonrpc": "2.0",
    "method": "kill",
    "id": "2db9a2fe-9a39-41ef-828c-25e04dd6b07d",
    "params": {
        "task_id": "{ the task id to terminate }"
    }
}

dbt 프로젝트 실행

다음 메서드로 RPC 서버를 통해 dbt 프로젝트를 실행할 수 있어요.

공통 매개변수

모든 RPC 요청은 나열된 매개변수 외에 다음을 받아들여요:

• timeout: 요청을 취소하기 전에 기다릴 최대 시간.
• task_tags: 이 작업에 첨부할 임의의 키/값 쌍. 이 태그는 poll과 ps 메서드 출력에 반환돼요(선택).

CLI 문법으로 작업 실행

매개변수:

• cli: 실행할 dbt 명령어(예: run --select abc+ --exclude +def) (필수)

{
    "jsonrpc": "2.0",
    "method": "cli_args",
    "id": "<request id>",
    "params": {
        "cli": "run --select abc+ --exclude +def",
        "task_tags": {
            "branch": "feature/my-branch",
            "commit": "c0ff33b01"
        }
    }
}

다음 요청 유형 중 몇 가지는 추가 매개변수를 받아들여요:

• threads: 컴파일 시 사용할 스레드 수(선택)
• select: 실행할 리소스 집합(공백으로 구분, 선택). (models는 하위 호환성을 위해 일부 요청 유형에서 지원돼요.)
• selector: 실행할 리소스 집합을 정의하는 사전 정의된 YAML 선택자의 이름(선택)
• exclude: 컴파일·실행·테스트·시드·스냅샷에서 제외할 리소스 집합(공백으로 구분, 선택)
• state: 상태를 설정할 때 사용할 아티팩트의 파일 경로(선택)

프로젝트 컴파일 (docs)

{
	"jsonrpc": "2.0",
	"method": "compile",
	"id": "<request id>",
	"params": {
            "threads": "<int> (optional)",
            "select": "<str> (optional)",
            "exclude": "<str> (optional)",
            "selector": "<str> (optional)",
            "state": "<str> (optional)"
        }
}

모델 실행 (docs)

추가 매개변수:

• defer: 업스트림의 선택되지 않은 리소스에 대한 참조를 defer할지 여부(선택, state 필요)

{
	"jsonrpc": "2.0",
	"method": "run",
	"id": "<request id>",
	"params": {
            "threads": "<int> (optional)",
            "select": "<str> (optional)",
            "exclude": "<str> (optional)",
            "selector": "<str> (optional)",
            "state": "<str> (optional)",
            "defer": "<bool> (optional)"
        }
}

테스트 실행 (docs)

추가 매개변수:

• data: true면 데이터 테스트 실행(선택, 기본값=true)
• schema: true면 스키마 테스트 실행(선택, 기본값=true)

{
	"jsonrpc": "2.0",
	"method": "test",
	"id": "<request id>",
	"params": {
            "threads": "<int> (optional)",
            "select": "<str> (optional)",
            "exclude": "<str> (optional)",
            "selector": "<str> (optional)",
            "state": "<str> (optional)",
            "data": "<bool> (optional)",
            "schema": "<bool> (optional)"
        }
}

시드 실행 (docs)

매개변수:

• show: true면 응답에 시드 데이터 샘플을 표시(선택, 기본값=false)

{
	"jsonrpc": "2.0",
	"method": "seed",
	"id": "<request id>",
	"params": {
            "threads": "<int> (optional)",
            "select": "<str> (optional)",
            "exclude": "<str> (optional)",
            "selector": "<str> (optional)",
            "show": "<bool> (optional)",
            "state": "<str> (optional)"
        }
}

스냅샷 실행 (docs)

{
	"jsonrpc": "2.0",
	"method": "snapshot",
	"id": "<request id>",
	"params": {
            "threads": "<int> (optional)",
            "select": "<str> (optional)",
            "exclude": "<str> (optional)",
            "selector": "<str> (optional)",
            "state": "<str> (optional)"
        }
}

빌드 (docs)

{
	"jsonrpc": "2.0",
	"method": "build",
	"id": "<request id>",
	"params": {
            "threads": "<int> (optional)",
            "select": "<str> (optional)",
            "exclude": "<str> (optional)",
            "selector": "<str> (optional)",
            "state": "<str> (optional)",
            "defer": "<str> (optional)"
        }
}

프로젝트 리소스 나열 (docs)

추가 매개변수:

• resource_types: 선택된 리소스를 유형별로 필터링
• output_keys: 출력에 포함할 노드 속성 지정

{
	"jsonrpc": "2.0",
	"method": "ls",
	"id": "<request id>",
	"params": {
        "select": "<str> (optional)",
        "exclude": "<str> (optional)",
        "selector": "<str> (optional)",
        "resource_types": ["<list> (optional)"],
        "output_keys": ["<list> (optional)"],
    }
}

문서 생성 (docs)

추가 매개변수:

• compile: true면 카탈로그를 생성하기 전에 프로젝트를 컴파일(선택, 기본값=false)

{
	"jsonrpc": "2.0",
	"method": "docs.generate",
	"id": "<request id>",
	"params": {
            "compile": "<bool> (optional)",
            "state": "<str> (optional)"
        }
}

SQL 문장 컴파일·실행

쿼리 컴파일

이 쿼리는 rpc 서버에 대해 SQL select {{ 1 + 1 }} as id(base64 인코딩)를 컴파일해요:

rpc-spec.json

{
    "jsonrpc": "2.0",
    "method": "compile_sql",
    "id": "2db9a2fe-9a39-41ef-828c-25e04dd6b07d",
    "params": {
        "timeout": 60,
        "sql": "c2VsZWN0IHt7IDEgKyAxIH19IGFzIGlk",
        "name": "my_first_query"
    }
}

결과 응답에는 값이 'select 2'인 compiled_sql이라는 키가 포함돼요.

쿼리 실행

이 쿼리는 rpc 서버에 대해 SQL select {{ 1 + 1 }} as id(base64 인코딩)를 실행해요:

rpc-run.json

{
    "jsonrpc": "2.0",
    "method": "run_sql",
    "id": "2db9a2fe-9a39-41ef-828c-25e04dd6b07d",
    "params": {
        "timeout": 60,
        "sql": "c2VsZWN0IHt7IDEgKyAxIH19IGFzIGlk",
        "name": "my_first_query"
    }
}

결과 응답에는 값이 {'column_names': ['?column?'], 'rows': [[2.0]]}인 table이라는 키가 포함돼요.

RPC 서버 다시 로드

dbt RPC 서버가 시작되면 시작 시점에 디스크에 있는 파일을 사용해 dbt 프로젝트를 메모리로 로드해요. dbt 프로젝트의 파일이 바뀌면(개발 중이든 배포에서든) 서버 프로세스를 재순환하지 않고 dbt RPC 서버를 실시간으로 업데이트할 수 있어요. 디스크에 있는 파일을 다시 로드하려면 실행 중인 프로세스의 Process ID(pid)를 사용해 "hangup" 신호를 실행 중인 서버 프로세스로 보내세요.

서버 PID 찾기

서버 PID를 찾으려면 서버의 status 메서드 응답에서 .result.pid 값을 가져오거나 ps를 사용하세요:

# Find the server PID using `ps`:
ps aux | grep 'dbt-rpc serve' | grep -v grep

프로세스의 PID(예: 12345)를 찾은 후 kill 명령어로 신호를 실행 중인 서버로 보내세요:

kill -HUP 12345

서버가 HUP(hangup) 신호를 받으면 디스크의 파일을 다시 파싱하고 후속 요청을 처리할 때 업데이트된 프로젝트 코드를 사용해요.

더 알아보기 (Learn more)

• dbt-rpc 저장소
• dbt 아티팩트