# DuckDB

[DuckDB](https://github.com/duckdb/duckdb) é um sistema de gerenciamento de banco de dados SQL [OLAP](https://en.wikipedia.org/wiki/Online_analytical_processing) em processo. Você pode usar os caminhos do Hugging Face (`hf://`) para acessar dados no Hub:

O [DuckDB CLI](https://duckdb.org/docs/api/cli/overview.html) (Interface de Linha de Comando) é um executável único, sem dependências. Também há outras APIs disponíveis para executar o DuckDB, incluindo Python, C++, Go, Java, Rust e mais. Para mais detalhes, visite a página de [clients](https://duckdb.org/docs/api/overview.html) deles.

> [!TIP]
> Para detalhes de instalação, visite a [página de instalação](https://duckdb.org/docs/installation).

> [!TIP]
> Se você usa o CLI `hf`, pode executar consultas DuckDB diretamente com [`hf datasets sql`](/docs/huggingface_hub/package_reference/cli#hf-datasets-sql), por exemplo, `hf datasets sql "FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3"`. A autenticação para datasets restritos e privados é configurada automaticamente a partir do seu token de login, e `--format json` retorna uma saída legível por máquina.

A partir da versão `v0.10.3`, o CLI do DuckDB inclui suporte nativo para acessar datasets no Hugging Face Hub por meio de URLs com o esquema `hf://`. Aqui estão alguns recursos que você pode aproveitar com essa poderosa ferramenta:

- Consulte conjuntos de dados públicos e seus próprios conjuntos de dados restritos e privados
- Analisar conjuntos de dados e executar operações SQL
- Combine conjuntos de dados e exporte-os para diferentes formatos
- Realize buscas de similaridade vetorial em conjuntos de dados de incorporações
- Implemente a busca de texto completo em conjuntos de dados

Para uma lista completa dos recursos do DuckDB, visite a [documentação](https://duckdb.org/docs/) do DuckDB.

Para iniciar o CLI, execute o seguinte comando na pasta de instalação:

```bash
./duckdb
```

## Forjando a URL do Hugging Face

Para acessar os conjuntos de dados do Hugging Face, use o seguinte formato de URL:

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

- **my-username**, o usuário ou organização do dataset, por exemplo, `ibm`
- **my-dataset**, o nome do conjunto de dados, por exemplo: `duorc`
- **path_to_parquet_file**, o caminho do arquivo parquet que suporta padrões glob, por exemplo, `**/*.parquet`, para consultar todos os arquivos parquet

> [!TIP]
> Você pode consultar arquivos Parquet convertidos automaticamente usando o ramo @~parquet, que corresponde à revisão `refs/convert/parquet`. Para mais detalhes, consulte a documentação em https://huggingface.co/docs/datasets-server/en/parquet#conversion-to-parquet.
>
> Para referenciar a revisão `refs/convert/parquet` de um conjunto de dados, use a seguinte sintaxe:
>
> ```plaintext
> hf://datasets/{my-username}/{my-dataset}@~parquet/{path_to_file} 
> ```
>
> Aqui está uma URL de exemplo seguindo a sintaxe acima:
>
> ```plaintext
> hf://datasets/ibm/duorc@~parquet/ParaphraseRC/test/0000.parquet
> ```

## Consultar um conjunto de dados

Vamos começar com uma demonstração rápida para consultar todas as linhas de um conjunto de dados:

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

Ou usando a sintaxe SQL tradicional:

```sql
SELECT * FROM 'hf://datasets/ibm/duorc/ParaphraseRC/*.parquet' LIMIT 3;
```
Nas seções a seguir, abordaremos operações mais complexas que você pode executar com DuckDB em datasets do Hugging Face.

> [!TIP]
> **Consultando Storage Buckets**: o DuckDB 2.0 e versões posteriores também leem [Storage Buckets](./storage-buckets) nativamente, a partir da CLI e de todos os clientes:
> ```sql
> SELECT * FROM 'hf://buckets/username/my-bucket/data.parquet' LIMIT 10;
> ```
> Buckets não são versionados, portanto a sintaxe `@revision` não se aplica a caminhos de bucket. No DuckDB 1.x, registre o sistema de arquivos do Hugging Face a partir do Python: `duckdb.register_filesystem(HfFileSystem())`. Consulte [Query with DuckDB](./storage-buckets-access#query-with-duckdb) para mais detalhes.

## Salvar um conjunto de dados

Use a sintaxe `COPY ... TO` para salvar um conjunto de dados no Hugging Face.

1. Instale a [extensão](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. Autentique usando o `hf` CLI ou diretamente no DuckDB:

* Na CLI:

  ```bash
  hf auth login
  ```

* No DuckDB:

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

3. Crie o repositório do seu conjunto de dados, caso ele ainda não exista:

* Na CLI:

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

* No DuckDB:

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

4. Exporte sua tabela para o Hugging Face, por exemplo, no formato Parquet:

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

> [!TIP]
> Use `PARTITION_BY` para dividir a tabela em vários arquivos com base em uma chave de partição: `COPY tbl TO 'hf://datasets/username/my-dataset/out-directory' (FORMAT parquet, PARTITION_BY (year, month));`. Os arquivos são colocados no subdiretório correto com base nos valores da chave de partição, por exemplo, `'hf://datasets/username/my-dataset/out-directory/year=2026/month=1/data_1.parquet'`.

Como os conjuntos de dados são repositórios git, cada novo arquivo é um commit no histórico do conjunto de dados.