File 테이블 엔진

File 테이블 엔진

File 테이블 엔진은 데이터를 지원되는 파일 형식(TabSeparated, Native 등) 중 하나로 파일에 보관해요. 주로 ClickHouse에서 파일로 데이터를 내보내거나, 한 형식에서 다른 형식으로 데이터를 변환하거나, 디스크의 파일을 편집하여 ClickHouse의 데이터를 갱신하는 데 사용합니다. 이 엔진은 현재 ClickHouse Cloud에서 사용할 수 없으니, 대신 S3 테이블 함수를 사용하세요.

출처: 문서

본문

File 테이블 엔진은 데이터를 지원되는 파일 형식(TabSeparated, Native 등) 중 하나로 파일에 보관합니다.

사용 시나리오:

  • ClickHouse에서 파일로 데이터 내보내기.
  • 데이터를 한 형식에서 다른 형식으로 변환.
  • 디스크의 파일을 편집하여 ClickHouse의 데이터를 갱신.

이 엔진은 현재 ClickHouse Cloud에서 사용할 수 없으며, 대신 S3 테이블 함수를 사용하세요.

ClickHouse Server에서의 사용 (Usage in ClickHouse Server)

File(Format)

Format 매개변수는 사용 가능한 파일 형식 중 하나를 지정합니다. SELECT 쿼리를 수행하려면 형식이 입력(input)을 지원해야 하고, INSERT 쿼리를 수행하려면 출력(output)을 지원해야 합니다. 사용 가능한 형식은 Formats 섹션에 나열되어 있습니다.

ClickHouse는 File에 대해 파일시스템 경로 지정을 허용하지 않습니다. 서버 구성의 path 설정으로 정의된 폴더를 사용할 거예요.

File(Format)을 사용하여 테이블을 만들면 그 폴더에 빈 하위 디렉토리를 만듭니다. 해당 테이블에 데이터를 쓰면 데이터는 그 하위 디렉토리의 data.Format 파일에 저장됩니다.

이 하위 폴더와 파일을 서버 파일시스템에 수동으로 만들고 일치하는 이름의 테이블 정보에 ATTACH하여 해당 파일의 데이터를 쿼리할 수 있어요.

이 기능을 사용할 때는 주의해야 합니다. ClickHouse는 그러한 파일에 대한 외부 변경을 추적하지 않기 때문입니다. ClickHouse를 통한 쓰기와 ClickHouse 외부의 쓰기가 동시에 일어난 결과는 정의되지 않습니다.

예시 (Example)

  1. file_engine_table 테이블을 설정합니다:
CREATE TABLE file_engine_table (name String, value UInt32) ENGINE=File(TabSeparated)

기본적으로 ClickHouse는 /var/lib/clickhouse/data/default/file_engine_table 폴더를 만듭니다.

  1. /var/lib/clickhouse/data/default/file_engine_table/data.TabSeparated를 수동으로 만들고 다음 내용을 포함시킵니다:
$ cat data.TabSeparated
one 1
two 2
  1. 데이터를 쿼리합니다:
SELECT * FROM file_engine_table

┌─name─┬─value─┐
│ one  │     1 │
│ two  │     2 │
└──────┴───────┘

clickhouse-local에서의 사용 (Usage in ClickHouse-local)

clickhouse-local에서 File 엔진은 Format 외에 파일 경로를 받아들입니다. 기본 입력/출력 스트림은 0 또는 stdin, 1 또는 stdout 같은 숫자 또는 사람이 읽을 수 있는 이름으로 지정할 수 있어요. 추가 엔진 매개변수나 파일 확장자를 기반으로 압축 파일을 읽고 쓸 수 있습니다. 지원되는 값은 none(압축 없음), gzip/gz, deflate, brotli/br, lzma/xz, zstd/zst, lz4, bz2, snappy예요. snappy의 경우 와이어 형식은 snappy_mode 설정에 의해 선택됩니다(기본값은 basic).

예시:

$ echo -e "1,2\n3,4" | clickhouse-local -q "CREATE TABLE table (a Int64, b Int64) ENGINE = File(CSV, stdin); SELECT a, b FROM table; DROP TABLE table"

구현 세부사항 (Details of Implementation)

  • 여러 SELECT 쿼리를 동시에 수행할 수 있지만, INSERT 쿼리는 서로 기다립니다.
  • INSERT 쿼리로 새 파일을 만드는 것을 지원합니다.
  • 파일이 존재하면 INSERT가 새 값을 추가하지만, 추가(append)를 지원하는 형식에만 해당됩니다. Avro, Arrow, JSON, Npy, ORC, Parquet처럼 추가를 지원하지 않는 형식은 비어 있지 않은 파일에 대한 INSERT를 CANNOT_APPEND_TO_FILE로 거부합니다. 일반 파일 경로의 경우 아래에 나열된 engine_file_truncate_on_insert 또는 engine_file_allow_create_multiple_files 설정을 대신 사용하세요. 파일 디스크립터를 통해 쓸 때는 어느 것도 적용되지 않으며, 호출자가 디스크립터를 소유합니다.
  • 지원하지 않음:
    • ALTER
    • SELECT ... SAMPLE
    • 인덱스(Indices)
    • 레플리케이션(Replication)

PARTITION BY

PARTITION BY — 선택 사항. 파티션 키로 데이터를 분할하여 별도의 파일을 만들 수 있어요. 대부분의 경우 파티션 키가 필요하지 않으며, 필요하더라도 일반적으로 월(month)보다 더 세밀한 파티션 키는 필요하지 않습니다. 파티셔닝은 쿼리를 빠르게 만들지 않아요(ORDER BY 표현식과 대조적으로). 너무 세밀한 파티셔닝은 사용해서는 안 됩니다. 클라이언트 식별자나 이름으로 데이터를 파티셔닝하지 마세요(대신 클라이언트 식별자나 이름을 ORDER BY 표현식의 첫 번째 컬럼으로 만드세요).

월별 파티셔닝에는 toYYYYMM(date_column) 표현식을 사용하세요. 여기서 date_column은 Date 타입의 날짜를 가진 컬럼입니다. 여기서 파티션 이름은 "YYYYMM" 형식입니다.

가상 컬럼 (Virtual columns)

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

설정 (Settings)

  • 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. mmap 방법은 clickhouse-server에는 적용되지 않습니다(clickhouse-local용입니다). 기본값: clickhouse-server의 경우 pread, clickhouse-local의 경우 mmap.

더 알아보기 (Learn more)