DuckDB

DuckDB은 인프로세스 SQL OLAP 데이터베이스 관리 시스템입니다. Hugging Face 경로(hf://)를 사용하여 Hub의 데이터에 액세스할 수 있습니다:

DuckDB CLI(Command Line Interface)는 단일 실행 파일이며 종속성이 없습니다. Python, C++, Go, Java, Rust 등을 포함하여 DuckDB를 실행하기 위한 다른 API도 사용할 수 있습니다. 자세한 내용은 clients 페이지를 방문하세요.

설치 세부 사항은 설치 페이지를 참조하세요.

hf CLI를 사용하는 경우, hf datasets sql을 통해 DuckDB 쿼리를 직접 실행할 수 있습니다. 예를 들어 hf datasets sql "FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3"와 같이 사용할 수 있습니다. 게이트된 데이터셋 및 비공개 데이터셋에 대한 인증은 로그인한 토큰에서 자동으로 구성되며, --format json은 기계가 읽을 수 있는 출력을 반환합니다.

v0.10.3 버전부터 DuckDB CLI는 hf:// 스킴을 가진 URL을 통해 Hugging Face Hub의 데이터셋에 액세스하는 기능을 기본적으로 지원합니다. 이 강력한 도구를 활용하여 사용할 수 있는 기능은 다음과 같습니다:

• 공개 데이터셋과 사용자 소유의 게이트드 및 비공개 데이터셋을 쿼리합니다
• 데이터셋을 분석하고 SQL 작업을 수행합니다
• datasets를 결합하고 다양한 형식으로 내보내기
• 임베딩 데이터셋에서 벡터 유사도 검색 수행
• 데이터셋에 전체 텍스트 검색 구현

DuckDB 기능의 전체 목록은 DuckDB 문서를 참조하세요.

CLI를 시작하려면 설치 폴더에서 다음 명령을 실행하세요:

./duckdb

Hugging Face URL 생성

Hugging Face 데이터셋에 액세스하려면 다음 URL 형식을 사용하세요:

hf://datasets/{my-username}/{my-dataset}/{path_to_file} 

• my-username, 데이터셋의 사용자 또는 조직, 예: ibm
• 데이터셋 이름, 예: my-dataset, duorc
• path_to_parquet_file, the parquet file path which supports glob patterns, e.g. **/*.parquet, to query all parquet files

refs/convert/parquet 리비전에 해당하는 @~parquet 브랜치를 사용하여 자동 변환된 Parquet 파일을 쿼리할 수 있습니다. 자세한 내용은 https://huggingface.co/docs/datasets-server/en/parquet#conversion-to-parquet의 문서를 참조하세요.

데이터셋의 refs/convert/parquet 리비전을 참조하려면 다음 구문을 사용합니다:

복사됨

hf://datasets/{my-username}/{my-dataset}@~parquet/{path_to_file} 

위 문법을 따르는 샘플 URL은 다음과 같습니다:

복사됨

hf://datasets/ibm/duorc@~parquet/ParaphraseRC/test/0000.parquet

데이터셋 쿼리

데이터셋의 모든 행을 쿼리하는 간단한 데모로 시작해 보겠습니다:

FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3;

또는 전통적인 SQL 구문을 사용하여:

SELECT * FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3;

다음 섹션에서는 Hugging Face 데이터셋에서 DuckDB로 수행할 수 있는 더 복잡한 연산들을 다룹니다.

Storage Buckets 쿼리: DuckDB 2.0 이상은 CLI와 모든 클라이언트에서 Storage Buckets를 네이티브로 읽을 수 있습니다:

복사됨

SELECT * FROM 'hf://buckets/username/my-bucket/data.parquet' LIMIT 10;

Buckets에는 버전 관리가 적용되지 않으므로 @revision 구문은 bucket 경로에 사용할 수 없습니다. DuckDB 1.x에서는 대신 Python에서 Hugging Face 파일 시스템을 등록하세요: duckdb.register_filesystem(HfFileSystem()). 자세한 내용은 DuckDB로 쿼리하기를 참고하세요.

데이터셋 저장

COPY ... TO 구문을 사용하여 Hugging Face에 데이터셋을 저장합니다.

1. DuckDB >=2.0용 extension을 설치합니다:

SET allow_extension_repositories = 'allowed';
CREATE OR REPLACE EXTENSION REPOSITORY hf_repo
  WITH PREFIX 'https://hf.co/buckets/duckdb-extensions/builds/resolve';
INSTALL hf FROM hf_repo;
LOAD hf FROM hf_repo;

2. hf CLI 또는 DuckDB에서 직접 인증하세요:

• CLI에서:

  복사됨

  hf auth login

• DuckDB에서:

  복사됨

  CREATE SECRET (TYPE HUGGINGFACE, TOKEN 'hf_...');

3. 아직 데이터셋 저장소가 없으면 생성하세요:

• CLI에서:

  복사됨

  hf repos create username/my-dataset --repo-type dataset --private

• DuckDB에서:

  복사됨

  FROM hf_create_repo('hf://datasets/username/my-dataset', private := true);

4. …

COPY tbl TO 'hf://datasets/username/my-dataset/out.parquet';

PARTITION_BY를 사용하여 파티션 키 기준으로 테이블을 여러 파일로 분할합니다: COPY tbl TO 'hf://datasets/username/my-dataset/out-directory' (FORMAT parquet, PARTITION_BY (year, month));. 파티션 키 값에 따라 파일이 올바른 하위 디렉터리에 배치됩니다. 예를 들어 'hf://datasets/username/my-dataset/out-directory/year=2026/month=1/data_1.parquet'와 같습니다.

데이터셋은 git 저장소이므로, 모든 새 파일은 데이터셋 히스토리의 커밋입니다.