DuckDB

DuckDB는 인프로세스(in-process) SQL OLAP 데이터베이스 관리 시스템이에요. Hugging Face 경로(hf://)를 사용해서 Hub의 데이터에 접근할 수 있어요.

DuckDB CLI(커맨드 라인 인터페이스)는 의존성이 없는 단일 실행 파일이에요. DuckDB를 실행할 수 있는 다른 API도 있는데 Python, C++, Go, Java, Rust 등이 있어요. 자세한 내용은 클라이언트 페이지를 참고해요.

[!TIP] 설치 방법은 설치 페이지를 참고해요.

[!TIP] 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 연산
데이터셋 결합 및 다른 형식으로 내보내기
임베딩 데이터셋에 대한 벡터 유사도 검색
데이터셋 전체 텍스트 검색

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, glob 패턴을 지원하는 parquet 파일 경로, 예: 모든 parquet 파일을 쿼리하는 **/*.parquet

[!TIP] @~parquet 브랜치(즉 refs/convert/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로 수행할 수 있는 더 복잡한 연산을 다룰게요.

[!TIP] Storage Buckets 쿼리: DuckDB Python 클라이언트를 사용할 때 Hugging Face 파일시스템을 등록하면 Storage Buckets에 저장된 데이터를 쿼리할 수 있어요:
import duckdb
from huggingface_hub import HfFileSystem
duckdb.register_filesystem(HfFileSystem())
duckdb.sql("SELECT * FROM 'hf://buckets/username/my-bucket/data.parquet' LIMIT 10")
DuckDB의 네이티브 hf://buckets/ 지원은 향후 릴리스에서 제공될 예정이에요.

더 알아보기 (Learn more)

hf://datasets/... 경로 하나로 DuckDB에서 Hub 데이터셋을 바로 쿼리할 수 있어요.
@~parquet 브랜치로 자동 변환된 Parquet에 접근할 수 있어요.
DuckDB 문서에서 지원 기능 전체를 확인해 보세요.