DuckDB

DuckDB est un système de gestion de base de données SQL OLAP en processus. Vous pouvez utiliser les chemins Hugging Face (hf://) pour accéder aux données du Hub :

Le DuckDB CLI (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.

Pour les détails d'installation, consultez la page d'installation.

Si vous utilisez le CLI hf, vous pouvez exécuter des requêtes DuckDB directement avec 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 de DuckDB.

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

./duckdb

Construire l’URL Hugging Face

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

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

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 sur 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 :

Copié

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

Voici un exemple d’URL suivant la syntaxe ci-dessus :

Copié

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 :

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

Ou en utilisant la syntaxe SQL traditionnelle :

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.

Interroger les buckets de stockage : DuckDB 2.0 et les versions ultérieures lisent également les buckets de stockage nativement, depuis le CLI et tous les clients :

Copié

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 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 pour 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. Authentifiez-vous à l'aide de la CLI hf ou directement dans DuckDB :

• Dans le CLI :

  Copié

  hf auth login

• Dans DuckDB :

  Copié

  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 :

  Copié

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

• Dans DuckDB :

  Copié

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

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

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

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.