Como executar uma consulta SQL em um arquivo local

Carregue um arquivo CSV, TSV, JSON, NDJSON ou Parquet e consulte-o com SQL: a página entrega o arquivo a um motor DuckDB que roda dentro da aba, expõe o conteúdo como a tabela data e mostra o resultado da sua instrução SELECT ou WITH em uma tabela que pode ser exportada. O motor é o DuckDB-Wasm 1.32.0 em um Web Worker — os bytes do arquivo vão para esse worker e para mais nenhum lugar.

O escopo é estreito de propósito: um arquivo por vez, instruções somente de leitura e uma prévia de no máximo 200 linhas. Isso cobre os usos típicos de uma página assim — conferir o esquema antes de importar um dump, fazer um GROUP BY sobre um relatório exportado ou dar uma primeira olhada em um Parquet quando não há leitor instalado — sem precisar subir um banco de dados.

Escolha um arquivo em Arquivo de dados local e clique em Carregar arquivo selecionado. O seletor aceita .csv, .tsv, .json, .ndjson, .jsonl, .parquet e .txt, e um .txt é lido como CSV separado por vírgulas. Assim que o motor lê o arquivo, a linha de status informa: «orders.csv está pronto na tabela local data. Execute uma consulta SELECT abaixo.»
Escreva uma instrução sobre data na caixa, ou mantenha a padrão SELECT * FROM data LIMIT 100. Para testar sem arquivo, clique em Carregar dados de exemplo: são carregadas quatro linhas de um CSV pequeno (id, name, team, monthly_events) e uma consulta GROUP BY que devolve três linhas.
Clique em Executar consulta para rodar a instrução no navegador. A tabela de resultados mostra os nomes de coluna devolvidos pelo motor e até 200 linhas, e a faixa acima indica o arquivo, o número de colunas e as linhas na tela — um valor como 200+ significa que o resultado era maior que a prévia.
Exportar o CSV visível salva exatamente as linhas na tela, com cabeçalho, como kivtools-query-results.csv; Redefinir consulta devolve a instrução padrão e limpa a tabela. O botão de exportação fica desativado até que uma consulta devolva linhas.

Onde a consulta roda, o que a ferramenta lê e de onde vem o limite de 200 linhas

Formatos, a tabela data e a regra de apenas SELECT

CSV e TXT passam pelo leitor de CSV, TSV por esse mesmo leitor com tabulação como separador, JSON e NDJSON/JSONL pelo leitor de JSON e Parquet pelo leitor de Parquet, então os tipos das colunas são deduzidos do arquivo em vez de declarados por você. Tudo entra em uma view chamada data, e carregar outro arquivo a substitui: não existe segunda tabela nem junção entre dois arquivos.

Só são aceitas instruções que começam com SELECT ou WITH. DROP TABLE data e DELETE FROM data são recusados antes de chegar ao motor, com a mensagem «Por segurança, o Data Lab executa apenas consultas SELECT e WITH.» Um ponto e vírgula final isolado não atrapalha, mas cada clique executa uma instrução: SELECT 1; SELECT 2 termina em Parser Error, e uma extensão não suportada como .xlsx é recusada com uma mensagem que lista os formatos aceitos.

A prévia de 200 linhas é limite de exibição, não de consulta

O que você digita é executado como SELECT * FROM (<sua consulta>) AS kivtools_visible_result LIMIT 201, e a página desenha no máximo 200 das linhas devolvidas. Peça SELECT * FROM data em um Parquet de 1.000 linhas e a linha de status dirá «200 linhas exibidas (limitado a 200)» enquanto as métricas contam 200+; com um ORDER BY salary DESC LIMIT 5 seu, vêm exatamente cinco linhas.

Exportar o CSV visível grava o que a tabela mostra — uma linha de cabeçalho mais essas mesmas linhas, até 200, com quebras CRLF — e não o resultado completo; um resultado agrupado de cinco linhas exporta cinco linhas de dados. Para mais, agregue ou recorte dentro da instrução: a prévia serve para ler, não para tirar o arquivo inteiro do navegador.

O que uma consulta que falha informa

As mensagens de erro vêm do próprio motor e aparecem como chegam. Uma coluna escrita errado gera Binder Error: Referenced column “nope” not found in FROM clause! Candidate bindings: “name”, “monthly_events”; uma tabela inexistente gera Catalog Error: Table with name nowhere does not exist!; sintaxe quebrada gera um Parser Error com a posição marcada; um Parquet truncado gera Invalid Input Error: No magic bytes found at end of file.

Uma instrução que falha deixa o resultado anterior na tela e não estraga a sessão: o próximo clique em Executar consulta funciona normalmente e o arquivo continua carregado. Como as falhas chegam como texto de mensagem e não como página quebrada, dá para corrigir a instrução na caixa sem recarregar a página nem escolher o arquivo de novo.

Velocidade, primeiro download e privacidade

No Chrome, um CSV de 6 MB com 200.000 linhas ficou consultável em cerca de um quarto de segundo, e um GROUP BY e uma função de janela sobre ele responderam em tempo parecido; um Parquet de 1.000 linhas e 13 colunas levou alguns segundos na primeira leitura. A primeira visita à página baixa o motor — 34 MB de WebAssembly mais os módulos do Apache Arrow — antes de rodar a primeira consulta, e as visitas seguintes o iniciam do cache do navegador em cerca de um segundo.

Os arquivos escolhidos são lidos dentro da aba: os bytes são registrados no Web Worker que hospeda o motor, e nem o arquivo, nem a instrução digitada, nem as linhas do resultado são enviados ao VoriTools. Com o painel de rede aberto, executar uma consulta em um arquivo carregado não gera requisição alguma. O outro lado disso é que a ferramenta não busca arquivo por URL, e uma pergunta que exige dois arquivos precisa ser feita em duas etapas.

Consultar CSV, JSON e Parquet com SQL