dbload

입력 레코드를 외부 데이터베이스 테이블에 적재합니다. JDBC 프로파일은 사전에 등록되어 있어야 합니다. dbload 명령어는 이전 명령어에서 전달되는 모든 레코드를 SQL 쿼리로 변환하여 외부 데이터베이스에 입력합니다.

명령어 속성

항목	설명
명령어 유형	가공 쿼리
필요 권한	없음
라이선스 사용량	해당 없음
병렬 실행	미지원
분산 실행	분석 노드에서 실행 (reducer)

문법

dbload PROFILE [type={insert|update}] [database=STR] table=STR [batchsize=INT] [rowretry=BOOL] [stoponfail=BOOL] [+]FIELD, ...

옵션

type={insert|update}: 적재 방식 (기본값: insert)

insert: INSERT 쿼리로 데이터를 입력합니다.
update: 키 필드를 기준으로 SELECT 쿼리를 수행하여 데이터 존재 여부를 확인합니다. 데이터가 없으면 INSERT, 데이터가 있으면 UPDATE 쿼리를 수행합니다.

database=STR: 접속 후 전환할 데이터베이스 또는 스키마 이름
table=STR: 데이터를 입력할 대상 테이블 이름
batchsize=INT: 트랜잭션 배치 처리 단위. 단위가 크면 한 번에 많이 커밋되므로 효율적이지만, 트랜잭션이 실패했을 때 롤백되는 양도 늘어납니다. 2000 정도를 권장합니다. 기본값인 1은 매 건마다 자동 커밋하므로 매우 느릴 수 있습니다. (기본값: 1)
rowretry=BOOL: 배치 단위 트랜잭션이 실패했을 때 건 단위로 분해하여 재시도할지 여부. t로 설정하면 배치 트랜잭션 실패 시 해당 배치의 각 레코드를 개별 트랜잭션으로 재시도합니다. 성능이 저하될 수 있으나 데이터 손실을 최소화할 수 있습니다. (기본값: t)
stoponfail=BOOL: 커밋 실패 시 전체 쿼리를 취소할지 여부 (기본값: f)

대상

PROFILE: JDBC 프로파일 이름. 쿼리 매개변수로 지정할 수 있습니다.
[+]FIELD, ...: 적재할 필드 이름을 쉼표(,)로 구분하여 지정합니다. 필드 이름 앞에 +를 붙이면 키 필드로 지정됩니다. type=update인 경우 반드시 1개 이상의 키 필드를 지정해야 합니다.

입력 필드

필드	타입	필수 여부	설명
(지정 필드)	모든 타입	필수	`FIELD` 목록에 지정한 필드의 값을 DB에 적재

출력 필드

없음 (입력 레코드를 변경 없이 전달)

오류 코드

파싱 오류

오류 코드	메시지	설명
12200	유효하지 않은 JDBC 프로파일 이름: [이름]	지정한 JDBC 프로파일이 존재하지 않는 경우
12201	JDBC 프로파일 사용 권한이 없습니다.	현재 사용자에게 해당 JDBC 프로파일 권한이 없는 경우
12202	잘못된 쿼리문입니다.	명령어 문법이 잘못된 경우 (예: 쉼표로 끝나는 경우)
12203	table 옵션을 입력해주십시오.	`table` 옵션이 지정되지 않은 경우
12204	필드를 입력해주십시오.	적재할 필드가 지정되지 않은 경우
12205	update용 key필드를 입력해주십시오.	`type=update`인데 키 필드(`+` 접두사)가 없는 경우

런타임 오류

해당 사항 없음

설명

dbload 명령어는 이전 명령어에서 전달된 레코드를 JDBC 프로파일로 등록된 외부 데이터베이스 테이블에 적재합니다.

type=insert(기본값)인 경우, 지정한 필드 값을 INSERT 쿼리로 변환하여 데이터베이스에 입력합니다.

type=update인 경우, 키 필드(+ 접두사)를 기준으로 먼저 SELECT COUNT(*) 쿼리를 수행하여 해당 레코드의 존재 여부를 확인합니다. 레코드가 없으면 INSERT, 레코드가 있으면 UPDATE 쿼리를 수행합니다.

배치 트랜잭션이 실패하면 rowretry 옵션에 따라 동작이 달라집니다. rowretry=t(기본값)이면 실패한 배치의 각 레코드를 개별적으로 재시도합니다. 개별 레코드 적재가 실패하면 해당 레코드에 _error_msg, _error_code, _sql_state 필드가 추가됩니다. rowretry=f이면 배치 전체를 실패 처리하고, 해당 배치의 모든 레코드에 오류 필드를 추가합니다.

stoponfail=t로 설정하면 배치 커밋이 실패할 때 전체 쿼리를 즉시 취소합니다.

동일 배치 내에서 키 필드 값이 중복되는 레코드는 자동으로 무시됩니다.

분산 환경에서는 분석 노드에서 적재를 수행합니다.

사용 예

이 사용 예에서 조회하는 WEB_APACHE_SAMPLE 테이블을 준비하려면 쿼리 실습용 데이터를 참고하세요.

INSERT 모드로 데이터 적재
```
json "[{'name': 'Alice', 'age': 30}, {'name': 'Bob', 'age': 25}]"
| dbload mydb table=users name, age
```
mydb JDBC 프로파일을 사용하여 users 테이블에 name과 age 필드 값을 INSERT합니다.
배치 크기를 지정한 대량 적재
```
table WEB_APACHE_SAMPLE
| dbload mydb batchsize=2000 table=access_logs src_ip, method, uri, status, bytes
```
배치 크기를 2000으로 설정하여 access_logs 테이블에 대량 데이터를 효율적으로 적재합니다.
UPDATE 모드로 데이터 적재
```
json "[{'id': 1, 'name': 'Alice', 'score': 95}, {'id': 2, 'name': 'Bob', 'score': 88}]"
| dbload mydb type=update table=students +id, name, score
```
id 필드를 키로 사용하여 students 테이블에 데이터가 없으면 INSERT, 있으면 UPDATE를 수행합니다.
데이터베이스 전환 후 적재
```
json "[{'host': '192.0.2.1', 'status': 'up'}]"
| dbload mydb database=monitoring table=host_status host, status
```
monitoring 데이터베이스로 전환한 후 host_status 테이블에 데이터를 적재합니다.
커밋 실패 시 쿼리 중단
```
json "[{'id': 1, 'value': 'test'}]"
| dbload mydb batchsize=1000 stoponfail=t table=critical_data +id, value
```
stoponfail=t 옵션을 지정하여 배치 커밋이 실패하면 전체 쿼리를 즉시 취소합니다.

호환성

dbload 명령어는 소나 4.0 이전 버전부터 제공되었습니다.