# Seus primeiros 10 minutos

> Um tutorial de dez minutos do DuckLocal com um CSV de exemplo: consulte-o com SQL, plote os resultados, exporte-os e faça a mesma pergunta pela CLI.

Source: https://ducklocal.app/docs/pt/tutorial

Um tour guiado: abra um arquivo pequeno de vendas, execute algumas consultas, plote
as respostas e exporte os resultados. Ele assume que o DuckLocal está instalado —
se não estiver, comece por [Primeiros passos](getting-started.md).

## 1. Baixe o arquivo de exemplo {#sample-file}

Baixe [sales.csv](https://ducklocal.app/docs/samples/sales.csv), que contém duas semanas de dados fictícios de pedidos
em 224 linhas. Você também pode baixá-lo pelo terminal:

```bash
curl -LO https://ducklocal.app/docs/samples/sales.csv
```

Ele tem cinco colunas:

| Coluna | Tipo | Exemplo |
| --- | --- | --- |
| `date` | DATE | `2026-09-01` |
| `channel` | VARCHAR | `Web`, `Mobile app`, `Store`, `Phone` |
| `region` | VARCHAR | `North`, `South`, `East`, `West` |
| `orders` | BIGINT | `72` |
| `revenue` | DOUBLE | `4181.04` |

Você não precisou dizer nada disso ao DuckLocal: o DuckDB lê o cabeçalho e
infere os tipos sozinho.

## 2. Abra o arquivo

Arraste `sales.csv` para a janela do DuckLocal. (Ou clique em **Abrir arquivos…**, ou execute
`ducklocal sales.csv` se você [adicionou o comando](getting-started.md#add-command).)

Uma notificação confirma **View sales criada.** Na barra lateral, **Arquivos
locais** agora lista `sales` com suas 224 linhas; expanda para ver as colunas e
seus tipos.

## 3. Veja as linhas

Na barra lateral, clique no botão de play ao lado de `sales`. O editor é preenchido com um
`SELECT * … LIMIT 100` para ela — pressione **⌘↵** para executar.

A grade abaixo do editor mostra as linhas. Experimente a caixa de filtro acima dela: digite
`Store` e pressione Enter para manter apenas as linhas que mencionam isso. O filtro
atua sobre as linhas já carregadas e nunca consulta de novo.

## 4. Faça uma pergunta

Substitua o SQL por este e pressione **⌘↵**:

```sql
SELECT channel, round(sum(revenue), 2) AS revenue
FROM sales
GROUP BY channel
ORDER BY revenue DESC;
```

| channel | revenue |
| --- | --- |
| Mobile app | 290549.76 |
| Web | 289544.8 |
| Store | 240067.6 |
| Phone | 82511.2 |

Agora alterne o painel de resultados de **Resultados** para **Gráfico**. Como a primeira
coluna é texto, você vê uma barra por canal, dimensionada pela primeira coluna numérica.

::: tip Autocompletar
Enquanto você digita, o editor oferece primeiro nomes de tabelas e colunas da barra
lateral, depois funções do DuckDB e palavras-chave SQL — digite `rev` e `revenue` é
a primeira sugestão.
:::

## 5. Plote uma tendência

Os gráficos são desenhados a partir das linhas exatamente como a consulta as retorna, então dê
ao resultado a forma como você quer que ele seja plotado. Uma coluna por canal dá uma linha
por canal:

```sql
SELECT
  date,
  round(sum(revenue) FILTER (WHERE channel = 'Web'), 2)        AS web,
  round(sum(revenue) FILTER (WHERE channel = 'Mobile app'), 2) AS mobile,
  round(sum(revenue) FILTER (WHERE channel = 'Store'), 2)      AS store
FROM sales
GROUP BY date
ORDER BY date;
```

`FILTER (WHERE …)` agrega apenas as linhas correspondentes (sintaxe do DuckDB).

Com uma data na primeira coluna, **Gráfico** desenha um gráfico de área ao longo do tempo,
uma série por coluna numérica. [Resultados e gráficos](results-and-charts.md)
cobre as regras e os limites.

## 6. Exporte a resposta

**Exportar sobrescreve um arquivo existente sem perguntar.** Com a tendência ainda
no painel de resultados, clique em **Exportar CSV**. A caixa de diálogo sugere
`~/Desktop/export.csv`; mude o caminho se quiser e confirme.

Exportar executa a consulta de novo, então o arquivo contém o resultado completo — não apenas o que
está visível na grade.

## 7. Encontre tudo de novo amanhã

Abra a aba **Histórico** na barra lateral: toda consulta que você executou está lá, inclusive
as que falharam. Clicar em uma substitui o que o editor tem neste momento —
clique em uma entrada para colocar aquela consulta de volta no editor.

Saia do DuckLocal e abra de novo. `sales` continua em **Arquivos locais**:
os arquivos abertos são lembrados pelo caminho e relidos a cada início, então uma edição
no CSV aparece na próxima vez que você consultar.

## 8. Bônus: a mesma pergunta a partir de um terminal

Se você adicionou o comando `ducklocal`, a CLI responde sem abrir uma
janela — prático para scripts e para agentes de IA:

```bash
ducklocal query --format md --sql "
  SELECT channel, round(sum(revenue), 2) AS revenue
  FROM 'sales.csv' GROUP BY channel ORDER BY revenue DESC"
```

Omita `--format md` para JSON estruturado. O [guia da CLI](cli.md) e a
skill de agente oficial — um pacote de skills que assistentes de programação com IA
podem chamar — são o ponto de partida.

## Próximo

- Experimente com dados reais: 3,5 milhões de corridas de táxi, consultadas por HTTPS — veja [Exemplo: corridas de táxi de Nova York](example-nyc-taxi.md)
- Aponte o DuckLocal para seus próprios arquivos ou pastas — veja [Fontes de dados](data-sources.md)
- Consulte arquivos em armazenamento compatível com S3 — veja [S3 e httpfs](s3.md)
- Monte um painel de consultas salvas — veja [Painéis (.dash)](dashboards.md)
