DuckDB

DuckDB é um sistema de gerenciamento de banco de dados SQL OLAP em processo. Você pode usar os caminhos do Hugging Face (hf://) para acessar dados no Hub:

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

Para detalhes de instalação, visite a página de instalação.

Se você usa o CLI hf, pode executar consultas DuckDB diretamente com 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 do DuckDB.

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

./duckdb

Forjando a URL do Hugging Face

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

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

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:

Copiado

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

Aqui está uma URL de exemplo seguindo a sintaxe acima:

Copiado

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:

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

Ou usando a sintaxe SQL tradicional:

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.

Consultando Storage Buckets: o DuckDB 2.0 e versões posteriores também leem Storage Buckets nativamente, a partir da CLI e de todos os clientes:

Copiado

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 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 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. Autentique usando o hf CLI ou diretamente no DuckDB:

• Na CLI:

  Copiado

  hf auth login

• No DuckDB:

  Copiado

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

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

• Na CLI:

  Copiado

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

• No DuckDB:

  Copiado

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

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

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

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.