DuckDB

DuckDB es un sistema de gestión de bases de datos SQL OLAP en proceso. Puedes usar las rutas de Hugging Face (hf://) para acceder a los datos del Hub:

El DuckDB CLI (Command Line Interface) es un único ejecutable sin dependencias. También hay otras APIs disponibles para ejecutar DuckDB, entre ellas Python, C++, Go, Java, Rust y más. Para obtener más detalles, visita su página de clients.

Para obtener detalles de instalación, visite la página de instalación.

Si usas la CLI hf, puedes ejecutar consultas de DuckDB directamente con hf datasets sql, por ejemplo hf datasets sql "FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3". La autenticación para conjuntos de datos con acceso restringido y privados se configura automáticamente desde tu token de sesión, y --format json devuelve una salida legible por máquina.

A partir de la versión v0.10.3, la CLI de DuckDB incluye soporte nativo para acceder a conjuntos de datos en el Hugging Face Hub mediante URLs con el esquema hf://. A continuación se presentan algunas de las funcionalidades que puedes aprovechar con esta potente herramienta:

• Consulta conjuntos de datos públicos y tus propios conjuntos de datos con acceso restringido y privados
• Analizar conjuntos de datos y realizar operaciones SQL
• Combinar conjuntos de datos y exportarlos a diferentes formatos
• Realizar búsquedas de similitud vectorial en conjuntos de datos de embeddings
• Implementar la búsqueda de texto completo en conjuntos de datos

Para obtener una lista completa de las características de DuckDB, visite la documentación de DuckDB.

Para iniciar la CLI, ejecute el siguiente comando en la carpeta de instalación:

./duckdb

Creando la URL de Hugging Face

Para acceder a los conjuntos de datos de Hugging Face, use el siguiente formato de URL:

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

• my-username, el usuario u organización del conjunto de datos, p. ej. ibm
• my-dataset, el nombre del conjunto de datos, p. ej.: duorc
• path_to_parquet_file, la ruta del archivo parquet que admite patrones glob, p. ej. **/*.parquet, para consultar todos los archivos parquet

Puede consultar los archivos Parquet convertidos automáticamente usando la rama @~parquet, que corresponde a la revisión refs/convert/parquet. Para más detalles, consulte la documentación en https://huggingface.co/docs/datasets-server/en/parquet#conversion-to-parquet.

Para hacer referencia a la revisión refs/convert/parquet de un conjunto de datos, use la siguiente sintaxis:

Copiado

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

Aquí hay una URL de ejemplo que sigue la sintaxis anterior:

Copiado

hf://datasets/ibm/duorc@~parquet/ParaphraseRC/test/0000.parquet

Consultar un conjunto de datos

Comencemos con una breve demostración para consultar todas las filas de un conjunto de datos:

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

O usando la sintaxis SQL tradicional:

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

En las siguientes secciones, cubriremos operaciones más complejas que puedes realizar con DuckDB en los conjuntos de datos de Hugging Face.

Consultar buckets de almacenamiento: DuckDB 2.0 y versiones posteriores también leen buckets de almacenamiento de forma nativa, desde la CLI y todos los clientes:

Copiado

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

Los buckets no tienen versiones, por lo que la sintaxis @revision no se aplica a las rutas de bucket. En DuckDB 1.x, registre el sistema de archivos de Hugging Face desde Python: duckdb.register_filesystem(HfFileSystem()). Consulte Query with DuckDB para más detalles.

Guardar un conjunto de datos

Use la sintaxis COPY ... TO para guardar un conjunto de datos en Hugging Face.

1. Instale la extensión para 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. Autentíquese usando la CLI hf o directamente en DuckDB:

• En la CLI:

  Copiado

  hf auth login

• En DuckDB:

  Copiado

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

3. Crea tu repositorio de datos si aún no existe:

• En la CLI:

  Copiado

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

• En DuckDB:

  Copiado

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

4. Exporta tu tabla a Hugging Face, por ejemplo, en formato Parquet:

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

Use PARTITION_BY para dividir la tabla en varios archivos basándose en una clave de partición: COPY tbl TO 'hf://datasets/username/my-dataset/out-directory' (FORMAT parquet, PARTITION_BY (year, month));. Los archivos se colocan en el subdirectorio correcto según los valores de la clave de partición, por ejemplo, 'hf://datasets/username/my-dataset/out-directory/year=2026/month=1/data_1.parquet'.

Dado que los conjuntos de datos son repositorios de git, cada archivo nuevo es un commit en el historial del conjunto de datos.