# Exemplo: 3,5 milhões de viagens de táxi por HTTPS

> Consulte por HTTPS um arquivo Parquet de 3,5 milhões de linhas dos táxis de Nova York com DuckDB SQL, e depois desenhe viagens por hora e tipo de pagamento no DuckLocal.

Source: https://ducklocal.app/docs/pt/example-nyc-taxi

A cidade de Nova York publica cada viagem de táxi amarelo como um arquivo Parquet.
Janeiro de 2025 é um único arquivo de 59 MB com 3.475.226 linhas, e o DuckLocal
consegue consultá-lo onde ele está — sem etapa de download, sem cluster, sem
importação. Este passo a passo o leva de uma primeira olhada a três gráficos e um
painel, uma consulta por vez. Para o fluxo de trabalho mais amplo centrado em
arquivos, veja
[análise de dados locais com DuckDB SQL](https://ducklocal.app/pt/use-cases/local-data-analysis/).

Este guia parte do princípio de que você concluiu
[Seus primeiros 10 minutos](tutorial.md) ou já conhece o básico: pressionar **⌘↵**
(Ctrl+Enter no Windows e no Linux) executa a consulta no editor, e a área de
resultados inclui uma aba **Gráfico**.

O arquivo:

```text
https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2025-01.parquet
```

::: tip Rede
A primeira consulta a um endereço `https://` faz o DuckDB baixar sua extensão
`httpfs`, então você precisa estar on-line uma vez. Depois disso, cada consulta lê
apenas as partes do arquivo de que precisa — um arquivo Parquet mantém cada coluna
separada, e o DuckDB pede intervalos de bytes em vez do arquivo inteiro.
:::

## 1. Olhe antes de consultar

Cole isto em uma aba de consulta e pressione **⌘↵**:

```sql
SELECT *
FROM 'https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2025-01.parquet'
LIMIT 100;
```

Cem linhas, vinte colunas: horários de embarque e desembarque, distância, tarifa,
gorjeta, zonas de embarque e desembarque, e como o passageiro pagou. Para ver cada
coluna com seu tipo em vez de rolar para o lado, use `DESCRIBE` na mesma consulta:

```sql
DESCRIBE SELECT *
FROM 'https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2025-01.parquet';
```

As usadas abaixo:

| Coluna | Tipo | Significado |
| --- | --- | --- |
| `tpep_pickup_datetime` | TIMESTAMP | Quando o taxímetro começou |
| `fare_amount` | DOUBLE | A tarifa do taxímetro, em dólares |
| `tip_amount` | DOUBLE | A gorjeta, em dólares — só gorjetas com cartão, veja o passo 4 |
| `payment_type` | BIGINT | `1` cartão de crédito, `2` dinheiro, `3` sem cobrança, `4` contestação |

## 2. Um mês, hora a hora

Quantas viagens começaram em cada hora de janeiro?

```sql
SELECT date_trunc('hour', tpep_pickup_datetime) AS hour,
       count(*) AS trips
FROM 'https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2025-01.parquet'
WHERE tpep_pickup_datetime >= '2025-01-01'
  AND tpep_pickup_datetime <  '2025-02-01'
GROUP BY 1
ORDER BY 1;
```

Ela agrega todas as 3,5 milhões de linhas em 744 — uma por hora do mês — em alguns
segundos. Mude para **Gráfico**: a primeira coluna é um timestamp, então o
DuckLocal desenha um gráfico de área ao longo do tempo. Cada dia aparece como um
pico, e os picos sobem e descem com a semana; a hora mais movimentada do mês foi
18:00 da quinta-feira, 16 de janeiro, com 13.288 viagens.

Dois detalhes tornam o gráfico honesto:

- **A cláusula `WHERE`.** Vinte e duas viagens no arquivo começaram fora de
  janeiro: 21 na véspera de Ano Novo, uma 44 segundos dentro de fevereiro. Sem o
  filtro, elas acrescentam quatro horas soltas nas pontas do gráfico.
- **`ORDER BY 1`.** Os gráficos desenham as linhas na ordem em que a consulta as
  devolve. `GROUP BY` não promete ordem, então sem isso a linha ziguezaguearia.

744 pontos ficam abaixo do limite de 1.500 pontos do gráfico, então cada hora é
desenhada como é, em vez de ter a média calculada em intervalos. Confira o título
do gráfico: ele diz quantos pontos foram desenhados.

## 3. A forma de um dia

Dobre o mês em um único dia: viagens por hora do dia, de 00:00 a 23:00.

```sql
SELECT format('{:02d}:00', hour(tpep_pickup_datetime)) AS pickup_hour,
       count(*) AS trips
FROM 'https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2025-01.parquet'
GROUP BY 1
ORDER BY 1;
```

Agora o **Gráfico** desenha 24 barras. A cidade é mais tranquila às 04:00 (20.033
viagens no mês todo) e mais movimentada às 18:00 (267.951) — mais de treze vezes
mais.

::: warning Por que a hora é texto
O rótulo é construído com `format('{:02d}:00', …)` de propósito. O gráfico de
resultados desenha a **primeira coluna numérica** — e um `hour(…)` simples é um
número. Ele viraria as alturas das barras, e você teria uma escada arrumada de 0 a
23 em vez das contagens de viagens. Uma primeira coluna de texto é um rótulo,
nunca um valor. O preenchimento com zeros (`04:00`, não `4:00`) mantém o texto na
ordem certa sob `ORDER BY`.
:::

## 4. Quem dá gorjeta?

Gorjetas como porcentagem da tarifa, por como a viagem foi paga:

```sql
SELECT CASE payment_type
         WHEN 1 THEN 'Credit card' WHEN 2 THEN 'Cash'
         WHEN 3 THEN 'No charge'   WHEN 4 THEN 'Dispute'
         ELSE 'Other'
       END AS payment,
       round(100 * avg(tip_amount / fare_amount), 1) AS tip_pct,
       count(*) AS trips
FROM 'https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2025-01.parquet'
WHERE fare_amount > 0
GROUP BY 1
ORDER BY trips DESC;
```

| payment | tip_pct | trips |
| --- | --- | --- |
| Credit card | 26.8 | 2444292 |
| Other | 2.7 | 455288 |
| Cash | 0.0 | 375850 |
| Dispute | 0.0 | 38787 |
| No charge | 0.1 | 15493 |

Quem paga com cartão dá cerca de 27% da tarifa; quem paga em dinheiro,
aparentemente, nada. Esses são os dados, não os passageiros: o taxímetro só
registra gorjetas pagas com cartão. Uma gorjeta em dinheiro vai para a mão do
motorista e nunca chega ao arquivo. Saber de onde vem uma coluna importa tanto
quanto o SQL.

`WHERE fare_amount > 0` impede que reembolsos e tarifas zero dividam por zero ou
invertam o sinal. O gráfico desenha `tip_pct` porque é a primeira coluna numérica —
coloque `trips` primeiro para desenhar o volume.

## 5. Guarde como um painel

Três consultas que vale a pena executar de novo pertencem a um
[painel](dashboards.md). Baixe
[nyc-taxi.dash](https://ducklocal.app/docs/samples/nyc-taxi.dash): ele contém a
tendência por hora, as barras por hora do dia, o gráfico de gorjetas e uma tabela
com os números por trás disso. Arraste-o para a janela do DuckLocal, e ele abre
como uma aba que executa todas as consultas e desenha todos os gráficos.

Como o SQL lê um endereço `https://` absoluto, o arquivo funciona como e onde for
aberto. Antes de compartilhá-lo, `ducklocal check` pode executar todas as consultas
para provar que funciona:

```bash
ducklocal check nyc-taxi.dash                         # syntax and references only
ducklocal check nyc-taxi.dash --database any.duckdb   # also runs each query
```

## 6. O mesmo em um terminal

A CLI responde sem janela, que é como um agente de IA perguntaria:

```bash
ducklocal query --format md --sql "
  SELECT format('{:02d}:00', hour(tpep_pickup_datetime)) AS pickup_hour,
         count(*) AS trips
  FROM 'https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2025-01.parquet'
  GROUP BY 1 ORDER BY trips DESC LIMIT 3"
```

## Para ir além

- **Trabalhe off-line, ou mais rápido.** Cada consulta lê pela rede de novo as
  colunas de que precisa. Para guardar uma cópia, execute o `SELECT *` do passo 1
  sem `LIMIT` e use **Exportar Parquet…** — depois arraste o arquivo local, e ele
  vira uma visão que você pode consultar pelo nome.
- **Mais meses.** Os arquivos seguem um padrão, `yellow_tripdata_YYYY-MM.parquet`.
  O DuckDB lê uma lista deles como uma única tabela:
  `FROM read_parquet(['https://…/yellow_tripdata_2025-01.parquet', 'https://…/yellow_tripdata_2025-02.parquet'])`.
  Um glob (`*`) não funciona sobre HTTPS comum, porque não é possível listar um
  servidor web; funciona no [S3](s3.md).
- **Zonas.** `PULocationID` e `DOLocationID` são números de zona de táxi; a NYC
  Taxi & Limousine Commission (TLC) publica a tabela de consulta que dá nome a
  elas.

Os dados são publicados pela
[TLC](https://www.nyc.gov/site/tlc/about/tlc-trip-record-data.page), que também
documenta cada coluna.
