DuckDB

DuckDB — это встроенная в процесс СУБД для SQL OLAP. Вы можете использовать пути Hugging Face (hf://) для доступа к данным на Hub:

ДuckDB CLI (интерфейс командной строки) представляет собой единый исполняемый файл без внешних зависимостей. Также доступны другие API для запуска DuckDB, включая Python, C++, Go, Java, Rust и другие. Дополнительные сведения см. на странице clients.

С подробностями установки см. страницу установки.

Если вы используете CLI hf, вы можете выполнять запросы DuckDB напрямую с помощью hf datasets sql, например hf datasets sql "FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3". Аутентификация для закрытых и приватных датасетов настраивается автоматически на основе вашего токена, а --format json возвращает вывод в машиночитаемом формате.

Начиная с версии v0.10.3, CLI DuckDB включает нативную поддержку доступа к наборам данных на Hugging Face Hub по URL со схемой hf://. Вот некоторые возможности, которые вы можете использовать с этим мощным инструментом:

• Запрос публичных датасетов, а также собственных датасетов с ограниченным доступом и приватных
• Анализ наборов данных и выполнение операций SQL
• Объединение наборов данных и экспорт в различные форматы
• Выполнение поиска по векторному сходству на наборах данных эмбеддингов
• Реализация полнотекстового поиска в наборах данных

Полный список возможностей DuckDB доступен в документации DuckDB.

Для запуска CLI выполните следующую команду в папке установки:

./duckdb

Формирование URL Hugging Face

Для доступа к наборам данных Hugging Face используйте следующий формат URL:

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

• my-username, пользователь или организация, владеющая набором данных, например ibm
• my-dataset, имя набора данных, например: duorc
• path_to_parquet_file, путь к файлу parquet, поддерживающий glob-шаблоны, например **/*.parquet, для запроса всех файлов parquet

Вы можете выполнять запросы к автоматически сконвертированным файлам Parquet, используя ветку @~parquet, которая соответствует ревизии refs/convert/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;

В следующих разделах мы рассмотрим более сложные операции, которые можно выполнять с помощью DuckDB на наборах данных Hugging Face.

Запросы к хранилищам объектов: DuckDB 2.0 и более поздние версии также читают хранилища объектов нативно, из CLI и любого клиента:

Скопировано

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

Бакеты не версионируются, поэтому синтаксис @revision неприменим к путям в бакетах. В DuckDB 1.x регистрируйте файловую систему Hugging Face из Python: duckdb.register_filesystem(HfFileSystem()). Подробности — в разделе Query with DuckDB.

Сохранение набора данных

Используйте синтаксис COPY ... TO, чтобы сохранить набор данных в Hugging Face.

1. Установите расширение для DuckDB >=2.0:

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. Авторизуйтесь с помощью CLI hf или непосредственно в 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. Экспортируйте вашу таблицу в Hugging Face, например, в формате Parquet:

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-репозиториями, каждый новый файл представляет собой коммит в истории набора данных.