# DuckDB

[DuckDB](https://github.com/duckdb/duckdb) es un sistema de gestión de bases de datos SQL [OLAP](https://en.wikipedia.org/wiki/Online_analytical_processing) en proceso. Puede usar las rutas de Hugging Face (`hf://`) para acceder a los datos del Hub:

El [DuckDB CLI](https://duckdb.org/docs/api/cli/overview.html) (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](https://duckdb.org/docs/api/overview.html).

> [!TIP]
> Para obtener detalles de instalación, visite la [página de instalación](https://duckdb.org/docs/installation).

> [!TIP]
> Si usas la CLI `hf`, puedes ejecutar consultas de DuckDB directamente con [`hf datasets sql`](/docs/huggingface_hub/package_reference/cli#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](https://duckdb.org/docs/) de DuckDB.

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

```bash
./duckdb
```

## Creando la URL de Hugging Face

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

```plaintext
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

> [!TIP]
> 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:
>
> ```plaintext
> hf://datasets/{my-username}/{my-dataset}@~parquet/{path_to_file} 
> ```
>
> Aquí hay una URL de ejemplo que sigue la sintaxis anterior:
>
> ```plaintext
> 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:

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

O usando la sintaxis SQL tradicional:

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

> [!TIP]
> **Consultar buckets de almacenamiento**: DuckDB 2.0 y versiones posteriores también leen [buckets de almacenamiento](./storage-buckets) de forma nativa, desde la CLI y todos los clientes:
> ```sql
> 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](./storage-buckets-access#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](https://huggingface.co/duckdb-extensions) para 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. Autentíquese usando la CLI `hf` o directamente en DuckDB:

* En la CLI:

  ```bash
  hf auth login
  ```

* En DuckDB:

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

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

* En la CLI:

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

* En DuckDB:

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

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

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

> [!TIP]
> 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.