# DuckDB

[DuckDB](https://github.com/duckdb/duckdb) — это встроенная в процесс СУБД для SQL [OLAP](https://en.wikipedia.org/wiki/Online_analytical_processing). Вы можете использовать пути Hugging Face (`hf://`) для доступа к данным на Hub:

[DuckDB CLI](https://duckdb.org/docs/api/cli/overview.html) (интерфейс командной строки) представляет собой единый исполняемый файл без внешних зависимостей. Для запуска DuckDB также доступны другие API, в том числе Python, C++, Go, Java, Rust и другие. Дополнительные сведения см. на странице [clients](https://duckdb.org/docs/api/overview.html).

> [!TIP]
> С подробностями установки см. [страницу установки](https://duckdb.org/docs/installation).

> [!TIP]
> Если вы используете CLI `hf`, вы можете выполнять запросы DuckDB напрямую с помощью [`hf datasets sql`](/docs/huggingface_hub/package_reference/cli#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 доступен в [документации](https://duckdb.org/docs/) DuckDB.

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

```bash
./duckdb
```

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

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

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

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

> [!TIP]
> Вы можете выполнять запросы к автоматически сконвертированным файлам Parquet с помощью ветки @~parquet, которая соответствует ревизии `refs/convert/parquet`. Дополнительные сведения см. в документации по адресу https://huggingface.co/docs/datasets-server/en/parquet#conversion-to-parquet.
>
> Чтобы сослаться на ревизию `refs/convert/parquet` набора данных, используйте следующий синтаксис:
>
> ```plaintext
> hf://datasets/{my-username}/{my-dataset}@~parquet/{path_to_file} 
> ```
>
> Вот пример URL, соответствующий описанному выше синтаксису:
>
> ```plaintext
> hf://datasets/ibm/duorc@~parquet/ParaphraseRC/test/0000.parquet
> ```

## Запрос к набору данных

Начнём с короткой демонстрации запроса всех строк набора данных:

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

Или с использованием традиционного синтаксиса SQL:

```sql
SELECT * FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3;
```
В следующих разделах мы рассмотрим более сложные операции, которые можно выполнять с помощью DuckDB на наборах данных Hugging Face.

> [!TIP]
> **Запросы к хранилищам объектов**: DuckDB 2.0 и более поздние версии также читают [хранилища объектов](./storage-buckets) нативно, из CLI и любого клиента:
> ```sql
> 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](./storage-buckets-access#query-with-duckdb).

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

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

1. Установите [расширение](https://huggingface.co/duckdb-extensions) для DuckDB >=2.0:

```sql
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:

  ```bash
  hf auth login
  ```

* В DuckDB:

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

3. Создайте репозиторий датасета, если он ещё не существует:

* В CLI:

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

* В DuckDB:

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

4. Экспортируйте вашу таблицу в Hugging Face, например, в формате Parquet:

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

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