메인 콘텐츠로 건너뛰기
HDFS에 있는 파일에서 테이블을 생성합니다. 이 테이블 함수는 url 및 file 테이블 함수와 유사합니다.

​
구문

hdfs(URI, format, structure)

​
인수

인수설명
URIHDFS에 있는 파일의 상대 URI입니다. 파일 경로에서는 읽기 전용 모드에서 다음 글롭 패턴을 지원합니다: *, ?, {abc,def} 및 {N..M}. 여기서 N, M은 숫자이고 'abc', 'def'는 문자열입니다.
format파일의 포맷입니다.
structure테이블 구조입니다. 포맷은 'column1_name column1_type, column2_name column2_type, ...'입니다.

​
반환 값

지정된 파일에서 데이터를 읽거나 쓰는 데 사용하는, 지정된 구조의 테이블입니다. 예시 hdfs://hdfs1:9000/test의 테이블과 여기서 처음 두 행을 선택하는 예시입니다: 
SELECT *
FROM hdfs('hdfs://hdfs1:9000/test', 'TSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
LIMIT 2

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

​
경로의 글롭 패턴

경로에는 글롭 패턴을 사용할 수 있습니다. 파일은 접미사나 접두사만이 아니라 전체 경로 패턴과 일치해야 합니다.
  • * — 빈 문자열을 포함하되 /를 제외한 임의 개수의 문자를 나타냅니다.
  • ** — 폴더 내부의 모든 파일을 하위 디렉터리까지 포함해 재귀적으로 나타냅니다.
  • ? — 임의의 단일 문자를 나타냅니다.
  • {some_string,another_string,yet_another_one} — 문자열 'some_string', 'another_string', 'yet_another_one' 중 하나로 치환합니다. 문자열에는 / 기호가 포함될 수 있습니다.
  • {N..M} — >= N 이고 <= M 인 임의의 숫자를 나타냅니다.
{}를 사용하는 구문은 remote 및 file 테이블 함수와 비슷합니다. 예시
  1. HDFS에 다음 URI를 가진 여러 파일이 있다고 가정합니다.
  • ‘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’
  1. 이 파일들의 행 수를 조회합니다.
SELECT count(*)
FROM hdfs('hdfs://hdfs1:9000/{some,another}_dir/some_file_{1..3}', 'TSV', 'name String, value UInt32')
  1. 이 두 디렉터리 내 모든 파일의 행 수를 쿼리합니다:
SELECT count(*)
FROM hdfs('hdfs://hdfs1:9000/{some,another}_dir/*', 'TSV', 'name String, value UInt32')
파일 목록에 앞자리가 0인 숫자 범위가 포함되어 있으면 각 자릿수별로 중괄호를 사용하는 구문을 사용하거나 ?를 사용하십시오.
예시 file000, file001, … , file999와 같은 이름의 파일에서 데이터를 쿼리합니다: 
SELECT count(*)
FROM hdfs('hdfs://hdfs1:9000/big_dir/file{0..9}{0..9}{0..9}', '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 HDFS('hdfs://hdfs1:9000/data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;

​
스토리지 설정

  • hdfs_truncate_on_insert - 파일에 데이터를 삽입하기 전에 해당 파일을 비울 수 있도록 합니다. 기본적으로 비활성화되어 있습니다.
  • hdfs_create_new_file_on_insert - 포맷에 접미사가 있는 경우, 삽입할 때마다 새 파일을 생성할 수 있도록 합니다. 기본적으로 비활성화되어 있습니다.
  • hdfs_skip_empty_files - 읽는 중에 빈 파일을 건너뛸 수 있도록 합니다. 기본적으로 비활성화되어 있습니다.
마지막 수정일 2026년 6월 10일