outputcsv

지정한 파일 시스템 경로에 입력 레코드의 필드 값을 CSV 형식으로 기록합니다. 첫 번째 행에 필드 이름을 헤더로 기록하고, 이후 각 레코드의 필드 값을 쉼표로 구분하여 기록합니다.

명령어 속성

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

문법

outputcsv [overwrite=BOOL] [append=BOOL] [encoding=STR] [bom=BOOL] [tab=BOOL] [partition=BOOL] [tmp=STR] [emptyfile=BOOL] [flush=INT{s|m|h|d}] FILE_PATH FIELD, ...

옵션

overwrite=BOOL
t로 설정하면 대상 파일이 이미 존재하더라도 덮어씁니다. 미설정 시 파일이 존재하면 쿼리가 실패합니다. append 옵션과 동시에 사용할 수 없습니다. (기본값: f)
append=BOOL
t로 설정하면 대상 파일이 이미 존재할 때 파일 끝에 이어서 기록합니다. overwrite 옵션과 동시에 사용할 수 없습니다. (기본값: f)
encoding=STR
출력 파일의 문자 인코딩을 지정합니다. (기본값: utf-8)
bom=BOOL
t로 설정하면 파일 시작 부분에 UTF-8 바이트 오더 마크(BOM)를 기록합니다. 마이크로소프트 엑셀에서 CSV 파일을 열 때 한글이 깨지는 경우 이 옵션을 사용합니다. (기본값: f)
tab=BOOL
t로 설정하면 쉼표 대신 탭 문자를 구분자로 사용합니다. (기본값: f)
partition=BOOL
t로 설정하면 파일 경로에 시간 기반 매크로를 사용하여 파티션별로 파일을 분리하여 기록합니다. 로그 시각 기준의 logtime 매크로와 현재 시각 기준의 now 매크로를 사용할 수 있습니다. (기본값: f)
tmp=STR
임시 파일 경로를 지정합니다. 설정 시 해당 경로에 임시로 기록한 후 쿼리가 종료되면 최종 파일 경로로 이동합니다.
emptyfile=BOOL
t로 설정하면 입력 레코드가 없더라도 빈 파일을 생성합니다. (기본값: f)
flush=INT{s|m|h|d}
주기적으로 버퍼를 플러시하는 간격을 지정합니다. 예를 들어 flush=10s는 10초마다 버퍼를 플러시합니다.

대상

FILE_PATH
CSV 파일을 기록할 파일 시스템 경로. partition=t 옵션과 함께 사용할 때는 {logtime:yyyy}, {logtime:MM}, {logtime:dd}, {now:yyyy} 등의 시간 매크로를 경로에 포함할 수 있습니다.
FIELD, ...
CSV 파일에 기록할 필드 이름. 쉼표(,)로 구분하여 여러 필드를 지정합니다.

입력 필드

없음

출력 필드

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

오류 코드

파싱 오류
오류 코드메시지설명
30200outputcsv 명령어 쿼리가 잘못되었습니다.명령어 문자열이 쉼표로 끝나는 경우
30201outputcsv 명령어로 내보낼 파일 경로에 매크로를 지정한 경우 파티션(partition) 옵션이 필요합니다.파일 경로에 시간 매크로가 포함되어 있으나 partition=t가 없는 경우
30202outputcsv 명령어로 내보낼 필드명을 입력하십시오.출력할 필드가 지정되지 않은 경우
30204[encoding]은 outputcsv 명령어에서 지원하지 않는 인코딩입니다.지원하지 않는 인코딩을 지정한 경우
30205outputcsv 명령어의 overwrite와 append 옵션은 동시에 사용할 수 없습니다.overwrite=t와 append=t를 동시에 지정한 경우
30206outputcsv 명령어로 내보낼 임시 파일 경로 tmp_path로의 접근이 거부되었습니다.임시 파일 경로에 대한 접근 권한이 없는 경우
30207outputcsv 명령어로 내보낼 파일 경로 csv_path로의 접근이 거부되었습니다.CSV 파일 경로에 대한 접근 권한이 없는 경우
런타임 오류
오류 코드메시지설명후처리 동작
30203outputcsv 명령어를 실행하는 중 IO 오류가 발생했습니다: [msg].파일 쓰기 중 입출력 오류가 발생한 경우파일 핸들을 닫고 쿼리를 취소함
30207outputcsv 명령어로 내보낼 파일 경로 csv_path로의 접근이 거부되었습니다.파티션 모드에서 해석된 파일 경로에 접근할 수 없는 경우쿼리를 취소함

설명

outputcsv 명령어는 입력으로 받은 레코드를 CSV 형식으로 파일에 기록합니다. 지정한 필드 값만 기록하며, 첫 번째 행에는 필드 이름이 헤더로 포함됩니다. 기록이 완료된 레코드는 다음 명령어로 그대로 전달됩니다.

partition=t 옵션을 사용하면 각 레코드의 _time 필드 값(로그 시각)을 기준으로 파일 경로의 시간 매크로를 해석하여 파티션별로 별도의 파일에 기록합니다.

tmp 옵션을 사용하면 쿼리 실행 중에는 임시 파일 경로에 기록하고, 쿼리가 정상 종료되면 최종 경로로 파일을 이동합니다. 쿼리가 취소된 경우 append 모드가 아니면 임시 파일 또는 출력 파일을 삭제합니다.

분산 환경에서는 분석 노드에서 파일 쓰기를 수행합니다.

이 명령어는 4.0.2511.0 버전부터 클러스터 관리자 권한이 필요하며, 접근 가능한 파일 경로가 제한됩니다. 자세한 내용은 파일 접근 제한을 참고하세요.

사용 예

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

각 사용 예의 파일 경로는 ALLOWED_FILE_SCAN_PATHS 설정에 포함되어 있다고 가정합니다.

  1. CSV 파일로 기록

    table limit=100 WEB_APACHE_SAMPLE
| outputcsv /opt/logpresso/output/access.csv src_ip, method, uri, status, bytes

    src_ip, method, uri, status, bytes 필드를 /opt/logpresso/output/access.csv 파일에 CSV 형식으로 기록합니다.

  2. 기존 파일 덮어쓰기

    table limit=100 WEB_APACHE_SAMPLE
| outputcsv overwrite=t /opt/logpresso/output/access.csv src_ip, method, status

    대상 파일이 이미 존재하더라도 덮어씁니다.

  3. BOM 포함 CSV 파일 기록

    table limit=100 WEB_APACHE_SAMPLE
| outputcsv bom=t /opt/logpresso/output/access_bom.csv src_ip, method, uri, status

    파일 시작 부분에 UTF-8 BOM을 추가하여 기록합니다. 마이크로소프트 엑셀에서 CSV 파일을 열 때 한글이 깨지는 경우 이 옵션을 사용합니다.

  4. 파티션별 파일 분리

    table WEB_APACHE_SAMPLE
| outputcsv partition=t /opt/logpresso/output/{logtime:yyyy}/{logtime:MM}/{logtime:dd}/access.csv src_ip, method, status

    로그 시각을 기준으로 연/월/일 디렉터리를 생성하여 파티션별로 CSV 파일을 기록합니다.

  5. 기존 파일에 이어서 기록

    table limit=100 WEB_APACHE_SAMPLE
| outputcsv append=t /opt/logpresso/output/access.csv src_ip, method, status

    기존 파일 끝에 레코드를 이어서 기록합니다.

  6. 임시 파일을 사용하여 기록

    table WEB_APACHE_SAMPLE
| outputcsv tmp=/opt/logpresso/output/access.tmp /opt/logpresso/output/access.csv src_ip, method, uri, status, bytes

    쿼리 실행 중에는 임시 파일에 기록하고, 쿼리가 정상 종료되면 최종 경로로 파일을 이동합니다.

호환성

outputcsv 명령어는 소나 4.0 이전 버전부터 제공되었습니다. 4.0.2511.0 버전부터 클러스터 관리자 권한이 필요합니다.