CSV 로딩

CSV 로딩

CSV 로딩, 즉 CSV 파일을 데이터베이스로 가져오는 작업은 아주 흔하면서도 의외로 까다로운 일이에요. CSV는 겉보기에 단순해 보이지만, 실제 파일들을 보면 일관되지 않은 부분이 많아서 로딩이 어려운 경우가 많죠. CSV 파일은 아주 다양한 형태로 존재하고, 종종 손상되어 있기도 하며, 스키마도 없습니다. CSV reader는 이런 모든 상황을 감당할 수 있어야 해요.

DuckDB의 CSV reader는 CSV sniffer를 이용해 CSV 파일을 분석한 뒤 어떤 설정 값(플래그)을 써야 할지 자동으로 추론합니다. 대부분의 상황에서 이 방식이 정확하게 동작하므로, 먼저 시도해 봐야 할 방법이에요. 드물게 CSV reader가 올바른 설정을 알아내지 못하는 상황에서는 설정을 직접 지정해서 CSV 파일을 제대로 파싱하도록 할 수 있습니다. 자세한 내용은 자동 감지 페이지를 참고하세요.

예시

다음 예시들은 flights.csv 파일을 사용합니다.

디스크에 있는 CSV 파일을 읽고, 옵션을 자동으로 추론할 때:

SELECT * FROM 'flights.csv';

read_csv 함수를 쓰고 옵션을 직접 지정할 때:

SELECT *
FROM read_csv('flights.csv',
    delim = '|',
    header = true,
    columns = {
        'FlightDate': 'DATE',
        'UniqueCarrier': 'VARCHAR',
        'OriginCityName': 'VARCHAR',
        'DestCityName': 'VARCHAR'
    });

표준 입력(stdin)에서 CSV를 읽고 옵션을 자동으로 추론할 때:

cat flights.csv | duckdb -c "SELECT * FROM read_csv('/dev/stdin')"

CSV 파일을 테이블로 읽어 들일 때:

CREATE TABLE ontime (
    FlightDate DATE,
    UniqueCarrier VARCHAR,
    OriginCityName VARCHAR,
    DestCityName VARCHAR
);
COPY ontime FROM 'flights.csv';

아니면 스키마를 직접 지정하지 않고 CREATE TABLE ... AS SELECT 문으로 테이블을 만들 수도 있어요:

CREATE TABLE ontime AS
    SELECT * FROM 'flights.csv';

FROM-first 문법을 쓰면 SELECT *를 생략할 수 있어요.

CREATE TABLE ontime AS
    FROM 'flights.csv';

파라미터

아래는 read_csv 함수에 넘길 수 있는 파라미터 목록입니다. 의미상 적용 가능한 곳에서는 이 파라미터들을 COPY 문에도 넘길 수 있어요.

팁 DuckDB의 CSV reader는 UTF-8(기본값), UTF-16, Latin-1 인코딩을 지원해요. 다른 인코딩의 경우 encodings 확장을 사용하거나, 예를 들어 iconv 커맨드라인 도구로 변환할 수 있어요:

iconv -f ISO-8859-2 -t UTF-8 input.csv > input-utf-8.csv

auto_type_candidates 상세

auto_type_candidates 옵션은 CSV reader가 컬럼 데이터 타입 감지에서 고려해야 할 데이터 타입을 지정하게 해 줍니다. 사용 예시:

SELECT * FROM read_csv('csv_file.csv', auto_type_candidates = ['BIGINT', 'DATE']);

auto_type_candidates 옵션의 기본값은 ['NULL', 'BOOLEAN', 'BIGINT', 'DOUBLE', 'TIME', 'DATE', 'TIMESTAMP', 'VARCHAR']입니다.

CSV 함수

read_csv는 CSV 스니퍼를 이용해 CSV reader의 올바른 설정을 자동으로 알아내고, 컬럼 타입도 자동으로 추론합니다. CSV 파일에 헤더가 있으면 그 헤더의 이름으로 컬럼 이름을 짓고, 헤더가 없다면 컬럼 이름이 column0, column1, column2, ...로 지정돼요. flights.csv 파일을 쓰는 예시를 볼게요:

SELECT * FROM read_csv('flights.csv');

경로는 현재 작업 디렉터리를 기준으로 한 상대 경로거나 절대 경로일 수 있어요.

read_csv로 영속 테이블을 만들 수도 있습니다:

CREATE TABLE ontime AS
    SELECT * FROM read_csv('flights.csv');
DESCRIBE ontime;

SELECT * FROM read_csv('flights.csv', sample_size = 20_000);

delim/sep, quote, escape, header를 직접 지정하면 해당 파라미터의 자동 감지를 건너뛸 수 있어요:

SELECT * FROM read_csv('flights.csv', header = true);

glob이나 파일 목록을 제공하면 여러 파일을 한 번에 읽을 수 있습니다. 자세한 내용은 multiple files 섹션을 참고하세요.

COPY 문으로 쓰기

COPY 문으로 CSV 파일에서 테이블로 데이터를 불러올 수 있습니다. 이 문의 문법은 PostgreSQL에서 쓰는 것과 동일해요. COPY 문으로 데이터를 불러오려면 먼저 올바른 스키마(CSV 파일의 컬럼 순서와 일치하고, CSV 파일에 있는 값에 맞는 타입을 쓰는 스키마)를 가진 테이블을 만들어야 합니다. COPY는 CSV의 설정 옵션을 자동으로 감지해요.

CREATE TABLE ontime (
    flightdate DATE,
    uniquecarrier VARCHAR,
    origincityname VARCHAR,
    destcityname VARCHAR
);
COPY ontime FROM 'flights.csv';
SELECT * FROM ontime;

CSV 형식을 직접 지정하고 싶다면 COPY의 설정 옵션으로 지정할 수 있어요.

CREATE TABLE ontime (flightdate DATE, uniquecarrier VARCHAR, origincityname VARCHAR, destcityname VARCHAR);
COPY ontime FROM 'flights.csv' (DELIMITER '|', HEADER);
SELECT * FROM ontime;

오류 있는 CSV 파일 읽기

DuckDB는 오류가 있는 CSV 파일도 읽을 수 있습니다. 자세한 내용은 Reading Faulty CSV Files 페이지를 참고하세요.

순서 보존

CSV reader는 preserve_insertion_order 설정 옵션에 따라 삽입 순서를 보존합니다. true(기본값)이면 CSV reader가 반환하는 결과 집합의 행 순서가 파일에서 읽은 해당 줄의 순서와 같아요. false면 순서가 보존된다는 보장이 없어요.

CSV 파일 쓰기

DuckDB는 COPY ... TO 문으로 CSV 파일을 쓸 수 있습니다.