file 테이블 함수

file 테이블 함수 (file)

s3 테이블 함수와 비슷하게, 파일에서 SELECT하고 INSERT하는 테이블형 인터페이스를 제공하는 테이블 엔진이에요. 로컬 파일을 다룰 때는 file을, S3, GCS, MinIO 같은 객체 스토리지의 버킷을 다룰 때는 s3를 사용하세요.

file 함수는 파일에서 읽거나 파일에 쓰기 위해 SELECT와 INSERT 쿼리에서 사용할 수 있습니다.

출처: 문서

본문

s3 테이블 함수와 비슷하게 파일에서 SELECT하고 INSERT하기 위한 테이블형 인터페이스를 제공하는 테이블 엔진입니다. 로컬 파일을 다룰 때는 file을, S3, GCS, MinIO 같은 객체 스토리지의 버킷을 다룰 때는 s3를 사용하세요.

file 함수는 파일에서 읽거나 파일로 쓰기 위해 SELECT와 INSERT 쿼리에서 사용할 수 있습니다.

구문

file([path_to_archive ::] path [,format] [,structure] [,compression])

SELECT 쿼리에서는 path가 Array(String)을 반환하는 표현식일 수도 있습니다:

file(['file1.csv', 'file2.csv'], 'CSV', 'column1 UInt32, column2 UInt32')

인자

파라미터	설명
`path`	user_files_path로부터 파일까지의 상대 경로, 또는 `SELECT` 쿼리에서 경로의 `Array(String)`. 읽기 전용 모드에서 다음 globs를 지원합니다: `*`, `?`, `{abc,def}`(`'abc'`와 `'def'`는 문자열) 및 `{N..M}`(`N`과 `M`은 숫자).
`path_to_archive`	zip/tar/7z 아카이브의 상대 경로. `path`와 같은 globs를 지원합니다.
`format`	파일의 포맷.
`structure`	테이블 구조. 형식: `'column1_name column1_type, column2_name column2_type, ...'`.
`compression`	`SELECT` 쿼리에서 사용할 때는 기존 압축 타입, `INSERT` 쿼리에서 사용할 때는 원하는 압축 타입. 지원 값은 `none`(압축 없음), `gzip/gz`, `deflate`, `brotli/br`, `lzma/xz`, `zstd/zst`, `lz4`, `bz2`, `snappy`. `snappy`의 경우 snappy_mode 설정(`basic`이 기본값)으로 와이어 포맷을 선택합니다.

structure 인자를 생략하면 ClickHouse가 포맷 자체에서 스키마를 유추합니다.

포맷별로 기본 컬럼 이름과 타입이 다릅니다. 특정 포맷의 스키마를 보려면 format 테이블 함수와 함께 DESC를 사용하세요. 예:

DESC format(LineAsString, 'Hello\nWorld')

┌─name─┬─type───┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ line │ String │              │                    │         │                  │                │
└──────┴────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

반환 값

파일에서 데이터를 읽거나 쓰기 위한 테이블.

파일에 쓰기 예제

TSV 파일에 쓰기

INSERT INTO TABLE FUNCTION
file('test.tsv', 'TSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
VALUES (1, 2, 3), (3, 2, 1), (1, 3, 2)

결과적으로 데이터가 test.tsv 파일에 기록됩니다:

# cat /var/lib/clickhouse/user_files/test.tsv
1    2    3
3    2    1
1    3    2

여러 TSV 파일로 파티션 쓰기

file 타입의 테이블 함수에 데이터를 삽입할 때 PARTITION BY 표현식을 지정하면 각 파티션마다 별도의 파일이 생성됩니다. 데이터를 별도 파일로 나누면 읽기 연산의 성능을 높이는 데 도움이 됩니다.

INSERT INTO TABLE FUNCTION
file('test_{_partition_id}.tsv', 'TSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
PARTITION BY column3
VALUES (1, 2, 3), (3, 2, 1), (1, 3, 2)

결과적으로 데이터가 test_1.tsv, test_2.tsv, test_3.tsv 세 파일에 기록됩니다:

# cat /var/lib/clickhouse/user_files/test_1.tsv
3    2    1

# cat /var/lib/clickhouse/user_files/test_2.tsv
1    3    2

# cat /var/lib/clickhouse/user_files/test_3.tsv
1    2    3

파일에서 읽기 예제

CSV 파일에서 SELECT

먼저 서버 구성에서 user_files_path를 설정하고 test.csv 파일을 준비합니다:

$ grep user_files_path /etc/clickhouse-server/config.xml
    <user_files_path>/var/lib/clickhouse/user_files/</user_files_path>

$ cat /var/lib/clickhouse/user_files/test.csv
    1,2,3
    3,2,1
    78,43,45

그런 다음 test.csv에서 테이블로 데이터를 읽고 첫 두 행을 선택합니다:

SELECT * FROM
file('test.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
LIMIT 2;

┌─column1─┬─column2─┬─column3─┐
│       1 │       2 │       3 │
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘

파일에서 테이블로 데이터 삽입

INSERT INTO FUNCTION
file('test.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
VALUES (1, 2, 3), (3, 2, 1);

SELECT * FROM
file('test.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32');

┌─column1─┬─column2─┬─column3─┐
│       1 │       2 │       3 │
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘

archive1.zip 또는/그리고 archive2.zip에 있는 table.csv에서 데이터 읽기:

SELECT * FROM file('user_files/archives/archive{1..2}.zip :: table.csv');

경로의 Globs

경로는 globbing을 사용할 수 있습니다. 파일은 접미사나 접두사가 아니라 전체 경로 패턴과 일치해야 합니다. 예외 하나: 경로가 기존 디렉터리를 가리키면서 globs를 사용하지 않으면, 디렉터리의 모든 파일이 선택되도록 경로에 *가 암시적으로 추가됩니다.

* — /를 제외한 임의 개수의 문자(빈 문자열 포함)를 나타냅니다.
? — 임의의 단일 문자를 나타냅니다.
{some_string,another_string,yet_another_one} — 'some_string', 'another_string', 'yet_another_one' 문자열 중 하나로 치환합니다. 문자열은 / 기호를 포함할 수 있습니다.
{N..M} — >= N이고 <= M인 임의 숫자를 나타냅니다.
** — 폴더 안의 모든 파일을 재귀적으로 나타냅니다.

{}가 있는 구성은 remote 및 hdfs 테이블 함수와 비슷합니다.

예제

다음과 같은 상대 경로의 파일이 있다고 가정합니다:

some_dir/some_file_1
some_dir/some_file_2
some_dir/some_file_3
another_dir/some_file_1
another_dir/some_file_2
another_dir/some_file_3

모든 파일의 총 행 수 조회:

SELECT count(*) FROM file('{some,another}_dir/some_file_{1..3}', 'TSV', 'name String, value UInt32');

같은 결과를 내는 대체 경로 표현:

SELECT count(*) FROM file('{some,another}_dir/*', 'TSV', 'name String, value UInt32');

암시적 *를 사용해 some_dir의 총 행 수 조회:

SELECT count(*) FROM file('some_dir', 'TSV', 'name String, value UInt32');

파일 목록에 앞자리 0이 있는 숫자 범위가 포함되어 있으면, 각 자릿수에 대해 중괄호 구성을 따로 사용하거나 ?를 사용하세요.

file000, file001, …, file999 파일의 총 행 수 조회:

SELECT count(*) FROM file('big_dir/file{0..9}{0..9}{0..9}', 'CSV', 'name String, value UInt32');

big_dir/ 디렉터리 안의 모든 파일에서 총 행 수를 재귀적으로 조회:

SELECT count(*) FROM file('big_dir/**', 'CSV', 'name String, value UInt32');

big_dir/ 디렉터리의 어떤 폴더든 file002 파일 모두의 총 행 수를 재귀적으로 조회:

SELECT count(*) FROM file('big_dir/**/file002', 'CSV', 'name String, value UInt32');

가상 컬럼

_path — 파일 경로. 타입: LowCardinality(String).
_file — 파일 이름. 타입: LowCardinality(String).
_size — 파일 크기(바이트). 타입: Nullable(UInt64). 파일 크기를 알 수 없으면 NULL.
_time — 파일의 마지막 수정 시간. 타입: Nullable(DateTime). 시간을 알 수 없으면 NULL.

use_hive_partitioning 설정

use_hive_partitioning을 1로 설정하면 ClickHouse가 경로(/name=value/)에서 Hive 스타일 파티셔닝을 감지하고, 파티션 컬럼을 쿼리의 가상 컬럼으로 사용할 수 있게 합니다. 이 가상 컬럼들은 파티션 경로와 같은 이름을 갖습니다.

예제

Hive 스타일 파티셔닝으로 만든 가상 컬럼 사용

SELECT * FROM file('data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;

설정

설정	설명
engine_file_empty_if_not_exists	존재하지 않는 파일에서 빈 데이터를 선택할 수 있게 합니다. 기본 비활성화.
engine_file_truncate_on_insert	삽입하기 전에 파일을 잘라낼 수 있게 합니다. 기본 비활성화.
engine_file_allow_create_multiple_files	포맷에 접미사가 있으면 각 삽입 시 새 파일을 만들 수 있게 합니다. 기본 비활성화.
engine_file_skip_empty_files	읽는 동안 빈 파일을 건너뛸 수 있게 합니다. 기본 비활성화.
storage_file_read_method	스토리지 파일에서 데이터를 읽는 방법. 다음 중 하나: read, pread, mmap(clickhouse-local만). 기본값: clickhouse-server는 `pread`, clickhouse-local은 `mmap`.

file 테이블 함수