HDFS 테이블 엔진

Not supported in ClickHouse Cloud

이 엔진은 ClickHouse를 통해 HDFS 상의 데이터를 관리할 수 있게 함으로써 Apache Hadoop 에코시스템과의 통합을 제공합니다. 이 엔진은 File 및 URL 엔진과 유사하지만, Hadoop에 특화된 기능을 제공합니다.

이 기능은 ClickHouse 엔지니어들이 공식적으로 지원하지 않으며, 품질이 불안정한 것으로 알려져 있습니다. 문제가 발생하는 경우 직접 수정한 후 pull request를 제출하십시오.

사용 방법

ENGINE = HDFS(URI, format)

엔진 매개변수

• URI - HDFS에서 전체 파일의 URI입니다. URI의 경로 부분에는 glob 패턴을 포함할 수 있습니다. 이 경우 테이블은 읽기 전용입니다.
• format - 사용 가능한 파일 포맷 중 하나를 지정합니다. SELECT 쿼리를 수행하려면 입력용 포맷이 지원되어야 하며, INSERT 쿼리를 수행하려면 출력용 포맷이 지원되어야 합니다. 사용 가능한 포맷은 Formats 섹션에 나열되어 있습니다.
• [PARTITION BY expr]

PARTITION BY

PARTITION BY — 선택 사항입니다. 대부분의 경우 파티션 키는 필요하지 않으며, 필요하더라도 일반적으로 월 단위보다 더 세분화된 파티션 키는 필요하지 않습니다. 파티셔닝은 (ORDER BY 표현식과 달리) 쿼리 성능을 향상시키지 않습니다. 지나치게 세분화된 파티셔닝은 절대 사용하면 안 됩니다. 클라이언트 식별자나 이름으로 데이터를 파티셔닝하지 말고, 대신 ORDER BY 표현식에서 클라이언트 식별자나 이름을 첫 번째 컬럼으로 두십시오.

월 단위로 파티셔닝하려면, date_column이 Date 타입의 날짜 컬럼일 때 toYYYYMM(date_column) 표현식을 사용하십시오. 이때 파티션 이름은 "YYYYMM" 형식을 가집니다.

예시:

1. hdfs_engine_table 테이블을 생성합니다:

CREATE TABLE hdfs_engine_table (name String, value UInt32) ENGINE=HDFS('hdfs://hdfs1:9000/other_storage', 'TSV')

2. 파일을 작성합니다:

INSERT INTO hdfs_engine_table VALUES ('one', 1), ('two', 2), ('three', 3)

3. 데이터를 쿼리합니다:

SELECT * FROM hdfs_engine_table LIMIT 2

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

구현 세부사항

• 읽기와 쓰기는 병렬로 수행될 수 있습니다.

• 다음 기능은 지원되지 않습니다:

  • ALTER 및 SELECT...SAMPLE 연산.
  • 인덱스.
  • Zero-copy 복제는 가능하지만, 권장되지 않습니다.
  Zero-copy replication is not ready for production

  Zero-copy 복제는 ClickHouse 22.8 버전 이상에서 기본적으로 비활성화되어 있습니다. 이 기능은 프로덕션 환경에서의 사용이 권장되지 않습니다.

경로의 글롭(glob)

여러 경로 컴포넌트에 글롭을 사용할 수 있습니다. 처리되려면 파일이 존재해야 하며 전체 경로 패턴과 일치해야 합니다. 파일 목록은 SELECT 시점에 결정되며 (CREATE 시점이 아닙니다).

• * — /를 제외한 임의의 문자 0개 이상(빈 문자열 포함)을 대체합니다.
• ? — 임의의 한 문자를 대체합니다.
• {some_string,another_string,yet_another_one} — 문자열 'some_string', 'another_string', 'yet_another_one' 중 어느 하나로 대체합니다.
• {N..M} — N부터 M까지(양 끝 포함) 범위에 있는 임의의 숫자로 대체합니다.

{}를 사용하는 패턴은 remote 테이블 함수와 유사합니다.

예시

1. HDFS에 다음과 같은 URI를 가진 TSV 형식 파일이 여러 개 있다고 가정합니다:

   • 'hdfs://hdfs1:9000/some_dir/some_file_1'
   • 'hdfs://hdfs1:9000/some_dir/some_file_2'
   • 'hdfs://hdfs1:9000/some_dir/some_file_3'
   • 'hdfs://hdfs1:9000/another_dir/some_file_1'
   • 'hdfs://hdfs1:9000/another_dir/some_file_2'
   • 'hdfs://hdfs1:9000/another_dir/some_file_3'

2. 이 여섯 개 파일 전체로 구성된 테이블을 생성하는 방법은 여러 가지가 있습니다:

CREATE TABLE table_with_range (name String, value UInt32) ENGINE = HDFS('hdfs://hdfs1:9000/{some,another}_dir/some_file_{1..3}', 'TSV')

다른 방식:

CREATE TABLE table_with_question_mark (name String, value UInt32) ENGINE = HDFS('hdfs://hdfs1:9000/{some,another}_dir/some_file_?', 'TSV')

테이블은 두 디렉터리에 있는 모든 파일로 구성됩니다(모든 파일은 쿼리에서 정의한 포맷과 스키마를 만족해야 합니다).

CREATE TABLE table_with_asterisk (name String, value UInt32) ENGINE = HDFS('hdfs://hdfs1:9000/{some,another}_dir/*', 'TSV')

참고

파일 목록에 앞에 0이 붙은 숫자 구간이 포함되어 있는 경우, 각 자릿수마다 별도로 중괄호를 사용하거나 ?를 사용하십시오.

예시

file000, file001, ... , file999와 같이 이름이 지정된 파일들로 테이블을 생성합니다:

CREATE TABLE big_table (name String, value UInt32) ENGINE = HDFS('hdfs://hdfs1:9000/big_dir/file{0..9}{0..9}{0..9}', 'CSV')

구성

GraphiteMergeTree와 마찬가지로 HDFS 엔진은 ClickHouse 설정 파일을 사용하여 확장 구성을 지원합니다. 사용할 수 있는 설정 키는 전역(hdfs)과 사용자 수준(hdfs_*) 두 가지입니다. 전역 설정이 먼저 적용되고, 그 다음에 사용자 수준 설정이 존재하는 경우 사용자 수준 설정이 적용됩니다.

<!-- Global configuration options for HDFS engine type -->
<hdfs>
  <hadoop_kerberos_keytab>/tmp/keytab/clickhouse.keytab</hadoop_kerberos_keytab>
  <hadoop_kerberos_principal>clickuser@TEST.CLICKHOUSE.TECH</hadoop_kerberos_principal>
  <hadoop_security_authentication>kerberos</hadoop_security_authentication>
</hdfs>

<!-- Configuration specific for user "root" -->
<hdfs_root>
  <hadoop_kerberos_principal>root@TEST.CLICKHOUSE.TECH</hadoop_kerberos_principal>
</hdfs_root>

구성 옵션

libhdfs3에서 지원되는 옵션

parameter	default value
rpc_client_connect_tcpnodelay	true
dfs_client_read_shortcircuit	true
output_replace-datanode-on-failure	true
input_notretry-another-node	false
input_localread_mappedfile	true
dfs_client_use_legacy_blockreader_local	false
rpc_client_ping_interval	10 * 1000
rpc_client_connect_timeout	600 * 1000
rpc_client_read_timeout	3600 * 1000
rpc_client_write_timeout	3600 * 1000
rpc_client_socket_linger_timeout	-1
rpc_client_connect_retry	10
rpc_client_timeout	3600 * 1000
dfs_default_replica	3
input_connect_timeout	600 * 1000
input_read_timeout	3600 * 1000
input_write_timeout	3600 * 1000
input_localread_default_buffersize	1 * 1024 * 1024
dfs_prefetchsize	10
input_read_getblockinfo_retry	3
input_localread_blockinfo_cachesize	1000
input_read_max_retry	60
output_default_chunksize	512
output_default_packetsize	64 * 1024
output_default_write_retry	10
output_connect_timeout	600 * 1000
output_read_timeout	3600 * 1000
output_write_timeout	3600 * 1000
output_close_timeout	3600 * 1000
output_packetpool_size	1024
output_heartbeat_interval	10 * 1000
dfs_client_failover_max_attempts	15
dfs_client_read_shortcircuit_streams_cache_size	256
dfs_client_socketcache_expiryMsec	3000
dfs_client_socketcache_capacity	16
dfs_default_blocksize	64 * 1024 * 1024
dfs_default_uri	"hdfs://localhost:9000"
hadoop_security_authentication	"simple"
hadoop_security_kerberos_ticket_cache_path	""
dfs_client_log_severity	"INFO"
dfs_domain_socket_path	""

HDFS Configuration Reference에 일부 파라미터에 대한 설명이 있습니다.

ClickHouse 추가 설정

parameter	default value
hadoop_kerberos_keytab	""
hadoop_kerberos_principal	""
libhdfs3_conf	""

제한 사항

• hadoop_security_kerberos_ticket_cache_path 및 libhdfs3_conf는 전역(global) 수준에서만 설정할 수 있으며, 사용자별(user specific) 설정은 지원되지 않습니다.

Kerberos 지원

hadoop_security_authentication 파라미터 값이 kerberos이면 ClickHouse는 Kerberos를 사용하여 인증합니다. 파라미터는 여기에 정리되어 있으며, hadoop_security_kerberos_ticket_cache_path가 도움이 될 수 있습니다. libhdfs3의 제한으로 인해 기존 방식만 지원되며, datanode 통신은 SASL로 보호되지 않습니다 (HADOOP_SECURE_DN_USER는 이러한 보안 방식이 적용되는지에 대한 신뢰할 수 있는 지표입니다). 참고용으로 tests/integration/test_storage_kerberized_hdfs/hdfs_configs/bootstrap.sh를 사용하십시오.

hadoop_kerberos_keytab, hadoop_kerberos_principal 또는 hadoop_security_kerberos_ticket_cache_path가 지정되어 있는 경우 Kerberos 인증이 사용됩니다. 이때 hadoop_kerberos_keytab와 hadoop_kerberos_principal는 필수입니다.

HDFS Namenode HA support

libhdfs3는 HDFS namenode HA를 지원합니다.

• HDFS 노드에서 hdfs-site.xml을 /etc/clickhouse-server/로 복사합니다.
• ClickHouse 설정 파일에 다음 내용을 추가합니다:

  <hdfs>
    <libhdfs3_conf>/etc/clickhouse-server/hdfs-site.xml</libhdfs3_conf>
  </hdfs>

• 그런 다음 HDFS URI에서 namenode 주소로 hdfs-site.xml의 dfs.nameservices 태그 값을 사용합니다. 예를 들어 hdfs://appadmin@192.168.101.11:8020/abc/를 hdfs://appadmin@my_nameservice/abc/로 변경하십시오.

가상 컬럼

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

Storage settings

• hdfs_truncate_on_insert - INSERT 전에 파일을 잘라(truncate) 비울 수 있습니다. 기본적으로 비활성화되어 있습니다.
• hdfs_create_new_file_on_insert - 포맷에 접미사가 있는 경우 각 INSERT마다 새 파일을 생성할 수 있습니다. 기본적으로 비활성화되어 있습니다.
• hdfs_skip_empty_files - 읽을 때 비어 있는 파일을 건너뛸 수 있습니다. 기본적으로 비활성화되어 있습니다.

함께 보기

• Virtual columns