# DuckDB

[DuckDB](https://github.com/duckdb/duckdb) est un système de gestion de base de données SQL [OLAP](https://en.wikipedia.org/wiki/Online_analytical_processing) en processus. Vous pouvez utiliser les chemins Hugging Face (`hf://`) pour accéder aux données du Hub :

Le [DuckDB CLI](https://duckdb.org/docs/api/cli/overview.html) (interface en ligne de commande) est un exécutable unique, sans dépendance. D'autres API sont également disponibles pour exécuter DuckDB, notamment Python, C++, Go, Java, Rust, et d'autres. Pour plus de détails, consultez leur page [clients](https://duckdb.org/docs/api/overview.html).

> [!TIP]
> Pour les détails d'installation, consultez la [page d'installation](https://duckdb.org/docs/installation).

> [!TIP]
> Si vous utilisez le CLI `hf`, vous pouvez exécuter des requêtes DuckDB directement avec [`hf datasets sql`](/docs/huggingface_hub/package_reference/cli#hf-datasets-sql), par exemple `hf datasets sql "FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3"`. L’authentification pour les jeux de données restreints et privés est configurée automatiquement à partir de votre jeton de connexion, et `--format json` renvoie une sortie lisible par machine.

À partir de la version `v0.10.3`, l'interface en ligne de commande DuckDB prend en charge nativement l'accès aux jeux de données sur le Hugging Face Hub via des URL utilisant le schéma `hf://`. Voici quelques fonctionnalités que vous pouvez exploiter avec cet outil puissant :

- Interroger des jeux de données publics ainsi que vos propres jeux de données privés et à accès restreint
- Analyser les jeux de données et effectuer des opérations SQL
- Combiner des jeux de données et les exporter dans différents formats
- Effectuer une recherche de similarité vectorielle sur des jeux de données d'embeddings
- Mettre en œuvre la recherche en texte intégral sur les jeux de données

Pour obtenir la liste complète des fonctionnalités de DuckDB, consultez la [documentation](https://duckdb.org/docs/) de DuckDB.

Pour démarrer l'interface en ligne de commande, exécutez la commande suivante dans le dossier d'installation :

```bash
./duckdb
```

## Construire l’URL Hugging Face

Pour accéder aux jeux de données Hugging Face, utilisez le format d’URL suivant :

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

- **my-username**, l'utilisateur ou l'organisation du jeu de données, par exemple `ibm`
- **my-dataset**, le nom du jeu de données, par exemple : `duorc`
- **path_to_parquet_file**, le chemin du fichier parquet, qui prend en charge les motifs glob, par exemple `**/*.parquet`, pour interroger tous les fichiers parquet

> [!TIP]
> Vous pouvez interroger les fichiers Parquet convertis automatiquement en utilisant la branche @~parquet, qui correspond à la révision `refs/convert/parquet`. Pour plus de détails, consultez la documentation à l’adresse https://huggingface.co/docs/datasets-server/en/parquet#conversion-to-parquet.
>
> Pour référencer la révision `refs/convert/parquet` d'un jeu de données, utilisez la syntaxe suivante :
>
> ```plaintext
> hf://datasets/{my-username}/{my-dataset}@~parquet/{path_to_file} 
> ```
>
> Voici un exemple d’URL suivant la syntaxe ci-dessus :
>
> ```plaintext
> hf://datasets/ibm/duorc@~parquet/ParaphraseRC/test/0000.parquet
> ```

## Interroger un jeu de données

Commençons par une démo rapide pour interroger toutes les lignes d'un jeu de données :

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

Ou en utilisant la syntaxe SQL traditionnelle :

```sql
SELECT * FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3;
```
Dans les sections suivantes, nous aborderons des opérations plus complexes que vous pouvez effectuer avec DuckDB sur les jeux de données Hugging Face.

> [!TIP]
> **Interroger les buckets de stockage** : DuckDB 2.0 et les versions ultérieures lisent également les [buckets de stockage](./storage-buckets) nativement, depuis le CLI et tous les clients :
> ```sql
> SELECT * FROM 'hf://buckets/username/my-bucket/data.parquet' LIMIT 10;
> ```
> Les buckets ne sont pas versionnés, la syntaxe `@revision` ne s'applique donc pas aux chemins de bucket. Sur DuckDB 1.x, enregistrez le système de fichiers Hugging Face depuis Python à la place : `duckdb.register_filesystem(HfFileSystem())`. Consultez [Query with DuckDB](./storage-buckets-access#query-with-duckdb) pour plus de détails.

## Enregistrer un jeu de données

Utilisez la syntaxe `COPY ... TO` pour enregistrer un jeu de données sur Hugging Face.

1. Installez l'[extension](https://huggingface.co/duckdb-extensions) pour 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. Authentifiez-vous à l'aide de la CLI `hf` ou directement dans DuckDB :

* Dans le CLI :

  ```bash
  hf auth login
  ```

* Dans DuckDB :

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

3. Créez votre dépôt de jeu de données s'il n'existe pas encore :

* Dans le CLI :

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

* Dans DuckDB :

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

4. Exportez votre table vers Hugging Face, par exemple au format Parquet :

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

> [!TIP]
> Utilisez `PARTITION_BY` pour diviser la table en plusieurs fichiers en fonction d’une clé de partition : `COPY tbl TO 'hf://datasets/username/my-dataset/out-directory' (FORMAT parquet, PARTITION_BY (year, month));`. Les fichiers sont placés dans le sous-répertoire approprié en fonction des valeurs de la clé de partition, par exemple `'hf://datasets/username/my-dataset/out-directory/year=2026/month=1/data_1.parquet'`.

Les jeux de données étant des dépôts git, chaque nouveau fichier constitue un commit dans l’historique du jeu de données.