dblookup

입력 레코드의 필드 값을 SQL 플레이스홀더에 바인딩하여 외부 데이터베이스를 조회하고, 조회 결과의 첫 번째 레코드를 필드로 추가합니다.

명령어 속성

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

문법

dblookup PROFILE [bypass=EXPR] SELECT_SQL

옵션

bypass=EXPR: 바이패스 조건식. 조건식이 참으로 평가되면 SQL 쿼리를 실행하지 않고 입력 레코드를 그대로 출력합니다. 일반적으로 SQL 조건에 사용할 필드 값이 null인 경우를 검사하는 용도로 사용합니다.

대상

PROFILE: JDBC 프로파일 이름. 쿼리 매개변수로 지정할 수 있습니다. JDBC 프로파일은 사전에 등록되어 있어야 합니다.
SELECT_SQL: SELECT로 시작하는 SQL 쿼리. 콜론(:)으로 시작하는 플레이스홀더를 사용하여 입력 레코드의 필드 값을 바인딩할 수 있습니다. 예를 들어 :src_ip는 입력 레코드의 src_ip 필드 값으로 대체됩니다.

입력 필드

필드	타입	필수 여부	설명
(플레이스홀더)	모든 타입	조건부	SQL 문장의 `:필드명` 플레이스홀더에 대응하는 입력 필드. 필드 값이 SQL 조건에 바인딩됩니다.

출력 필드

없음 (SQL 쿼리 결과의 컬럼에 따라 동적으로 결정)

SQL 조회 결과의 첫 번째 레코드의 모든 컬럼이 입력 레코드에 추가됩니다. 출력 필드 이름과 타입은 SQL 쿼리에 지정한 컬럼 이름과 데이터베이스 컬럼 타입에 따라 결정됩니다.

오류 코드

파싱 오류

오류 코드	메시지	설명
12000	유효하지 않은 JDBC 프로파일 이름: [이름]	지정한 JDBC 프로파일이 존재하지 않는 경우
12001	JDBC 프로파일 사용 권한이 없습니다.	현재 사용자에게 해당 JDBC 프로파일 권한이 없는 경우
12108	잘못된 쿼리문입니다.	SELECT로 시작하는 SQL 문장이 아닌 경우
12109	잘못된 bypass 조건식입니다.	`bypass` 옵션의 조건식이 올바르지 않은 경우

런타임 오류

해당 사항 없음

설명

dblookup 명령어는 각 입력 레코드마다 SQL 쿼리를 실행하여 외부 데이터베이스에서 데이터를 조회합니다. SQL 쿼리에 포함된 플레이스홀더(:필드명)가 입력 레코드의 해당 필드 값으로 바인딩됩니다. 조회 결과의 첫 번째 레코드만 가져오며, 해당 레코드의 모든 컬럼을 입력 레코드의 필드로 추가합니다.

dbquery 명령어와 달리 dblookup은 입력 레코드 단위로 SQL 쿼리를 실행하므로, 대량의 입력에 대해 개별적으로 외부 데이터베이스를 조회해야 하는 경우에 적합합니다.

bypass 옵션을 사용하면 특정 조건에서 SQL 쿼리 실행을 건너뛸 수 있습니다. 예를 들어, 조건에 사용할 필드 값이 null인 레코드에 대해 불필요한 데이터베이스 조회를 방지할 수 있습니다.

SQL 쿼리 실행 중 오류가 발생하면 해당 레코드는 조회 결과 없이 그대로 출력됩니다.

분산 환경에서는 수집 노드에서 개별적으로 외부 데이터베이스를 조회합니다.

사용 예

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

입력 레코드의 필드 값으로 데이터베이스 조회
```
json "[{'src_ip': '192.0.2.1'}, {'src_ip': '192.0.2.2'}]"
| dblookup mydb SELECT hostname, location FROM asset_info WHERE ip = :src_ip
```
각 입력 레코드의 src_ip 필드 값을 SQL 쿼리의 :src_ip 플레이스홀더에 바인딩하여 asset_info 테이블을 조회합니다. 조회 결과의 hostname과 location 컬럼이 입력 레코드에 필드로 추가됩니다.
bypass 옵션으로 null 값 건너뛰기
```
json "[{'user_id': 'admin'}, {'user_id': null}]"
| dblookup mydb bypass="isnull(user_id)" SELECT name, dept FROM users WHERE id = :user_id
```
user_id가 null인 레코드는 SQL 쿼리를 실행하지 않고 그대로 출력합니다. user_id가 존재하는 레코드만 users 테이블에서 name과 dept를 조회하여 필드로 추가합니다.
여러 플레이스홀더를 사용한 조건 조회
```
json "[{'src_ip': '192.0.2.1', 'dst_port': 443}]"
| dblookup mydb SELECT service_name FROM service_map WHERE ip = :src_ip AND port = :dst_port
```
입력 레코드의 src_ip와 dst_port 필드 값을 각각 플레이스홀더에 바인딩하여 service_map 테이블을 조회합니다.
테이블 데이터에 대해 외부 데이터베이스 조회
```
table WEB_APACHE_SAMPLE
| dblookup mydb bypass="isnull(src_ip)" SELECT country, city FROM geoip WHERE ip = :src_ip
```
WEB_APACHE_SAMPLE 테이블 데이터를 조회하면서, 각 레코드의 src_ip를 기준으로 geoip 테이블에서 country와 city 정보를 추가합니다.

호환성

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