# 예시: HTTPS로 350만 건의 택시 운행

> 350만 행의 NYC 택시 Parquet 파일을 HTTPS로 DuckDB SQL에서 쿼리한 뒤, DuckLocal에서 시간대와 결제 유형별 운행을 차트로 그립니다.

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

뉴욕시는 모든 옐로캡 운행 기록을 Parquet 파일로 공개합니다. 2025년 1월분은 59 MB짜리 파일 하나에 3,475,226행이 들어 있고, DuckLocal은 그 파일이 있는 자리에서 바로 쿼리할 수 있습니다. 다운로드 단계도, 클러스터도, 가져오기도 필요 없습니다. 이번 따라 하기에서는 첫 살펴보기부터 세 개의 차트와 대시보드 하나까지 쿼리 하나씩 진행합니다. 더 넓은 파일 우선 워크플로는 [DuckDB SQL로 하는 로컬 데이터 분석](https://ducklocal.app/use-cases/local-data-analysis/)을 참고하세요.

이 가이드는 [처음 10분](tutorial.md)을 마쳤거나 기본은 이미 알고 있다고 가정합니다. **⌘↵**(Windows와 Linux에서는 Ctrl+Enter)를 누르면 편집기의 쿼리가 실행되고, 결과 영역에 **차트** 탭이 있다는 정도입니다.

파일은 다음과 같습니다.

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

::: tip 네트워크
`https://` 주소에 대한 첫 쿼리는 DuckDB가 `httpfs` 확장 기능을 내려받게 하므로, 한 번은 온라인 상태여야 합니다. 그 뒤로는 각 쿼리가 필요한 부분만 파일에서 읽습니다. Parquet 파일은 열마다 데이터를 따로 보관하고, DuckDB는 파일 전체가 아니라 바이트 범위를 요청하기 때문입니다.
:::

## 1. 쿼리하기 전에 살펴보기

쿼리 탭에 다음을 붙여 넣고 **⌘↵**를 누르세요.

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

100행, 20개 열입니다. 승차와 하차 시각, 거리, 요금, 팁, 승차와 하차 존, 그리고 승객이 어떻게 지불했는지가 들어 있습니다. 옆으로 스크롤하지 않고 모든 열과 타입을 보려면 같은 쿼리를 `DESCRIBE`하세요.

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

아래에서 사용하는 열은 다음과 같습니다.

| 열 | 타입 | 의미 |
| --- | --- | --- |
| `tpep_pickup_datetime` | TIMESTAMP | 미터기가 시작된 시각 |
| `fare_amount` | DOUBLE | 미터 요금(달러) |
| `tip_amount` | DOUBLE | 팁(달러). 카드 팁만 포함되며, 4단계를 참고 |
| `payment_type` | BIGINT | `1` 신용카드, `2` 현금, `3` 무료, `4` 이의 제기 |

## 2. 한 달을 시간별로

1월의 각 시간대에 몇 건의 운행이 시작되었을까요?

```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;
```

350만 행 전체를 몇 초 만에 744행, 즉 한 달의 시간마다 한 행으로 집계합니다. **차트**로 전환하세요. 첫 열이 타임스탬프이므로 DuckLocal은 시간축 위의 영역 차트를 그립니다. 매일이 하나의 봉우리로 나타나고, 봉우리는 요일에 따라 오르내립니다. 한 달 중 가장 붐빈 시간은 1월 16일 목요일 18시로, 13,288건의 운행이 있었습니다.

차트를 정직하게 만드는 두 가지 세부 사항이 있습니다.

- **`WHERE` 절.** 파일 안의 22건은 1월 밖에서 시작했습니다. 섣달그믐 21건, 2월로 넘어간 지 44초 된 1건입니다. 필터가 없으면 차트 양 끝에 네 개의 엉뚱한 시간이 추가됩니다.
- **`ORDER BY 1`.** 차트는 쿼리가 반환한 순서대로 행을 그립니다. `GROUP BY`는 순서를 보장하지 않으므로 이것이 없으면 선이 지그재그가 됩니다.

744개 지점은 차트의 1,500 지점 한도보다 적으므로, 각 시간은 버킷으로 평균되지 않고 그대로 그려집니다. 차트 제목을 확인하세요. 몇 개의 지점이 그려졌는지 나옵니다.

## 3. 하루의 모양

한 달을 하루로 접어 봅니다. 00:00부터 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;
```

이제 **차트**가 막대 24개를 그립니다. 도시는 04:00에 가장 조용하고(한 달 전체 20,033건), 18:00에 가장 붐빕니다(267,951건). 열세 배가 넘습니다.

::: warning 시간을 텍스트로 두는 이유
레이블을 `format('{:02d}:00', …)`로 만든 것은 의도한 것입니다. 결과 차트는 **첫 번째 숫자 열**을 그리고, 평범한 `hour(…)`는 숫자입니다. 그러면 그것이 막대 높이가 되어 운행 수 대신 0에서 23까지의 깔끔한 계단이 그려집니다. 첫 열이 텍스트이면 레이블로 취급되고 값으로 쓰이지 않습니다. 0을 채우는 것(`4:00`이 아니라 `04:00`)은 `ORDER BY`에서 텍스트 순서를 올바르게 유지합니다.
:::

## 4. 누가 팁을 줄까?

운행이 어떻게 지불되었는지에 따른, 요금 대비 팁 비율입니다.

```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 |

카드 승객은 요금의 약 27%를 팁으로 냅니다. 현금 승객은 보기에는 아무것도 내지 않습니다. 그것은 승객이 아니라 데이터의 성질입니다. 미터기는 카드로 지불한 팁만 기록합니다. 현금 팁은 기사 손에 들어가고 파일에는 닿지 않습니다. 열이 어디에서 왔는지 아는 것은 SQL만큼 중요합니다.

`WHERE fare_amount > 0`은 환불과 0요금이 0으로 나뉘거나 부호가 뒤집히는 것을 막습니다. 차트는 첫 번째 숫자 열이므로 `tip_pct`를 그립니다. 대신 운행량을 그리고 싶다면 `trips`를 앞에 두세요.

## 5. 대시보드로 남기기

다시 실행할 가치가 있는 세 개의 쿼리는 [대시보드](dashboards.md)에 들어갈 자격이 있습니다. [nyc-taxi.dash](https://ducklocal.app/docs/samples/nyc-taxi.dash)를 내려받으세요. 시간별 추세, 시간대별 막대, 팁 차트, 그리고 그 수치를 담은 표가 들어 있습니다. 이 파일을 DuckLocal 창으로 끌어다 놓으면 모든 쿼리를 실행하고 모든 plot을 그리는 탭으로 열립니다.

SQL이 절대 `https://` 주소를 읽으므로, 이 파일은 어떻게 어디서 열든 동작합니다. 공유하기 전에 `ducklocal check`로 모든 쿼리를 실행해 동작을 증명할 수 있습니다.

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

## 6. 터미널에서 똑같이

CLI는 창 없이도 답합니다. AI 에이전트라면 이렇게 물었을 것입니다.

```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"
```

## 더 나아가기

- **오프라인으로, 또는 더 빠르게.** 각 쿼리는 필요한 열을 네트워크에서 다시 읽습니다. 사본을 남기려면 1단계의 `SELECT *`를 `LIMIT` 없이 실행하고 **Parquet으로 내보내기…** 를 사용하세요. 그런 다음 로컬 파일을 끌어다 놓으면 이름으로 쿼리할 수 있는 뷰가 됩니다.
- **더 많은 달.** 파일은 `yellow_tripdata_YYYY-MM.parquet`라는 하나의 패턴을 따릅니다. DuckDB는 파일 목록을 하나의 테이블로 읽습니다: `FROM read_parquet(['https://…/yellow_tripdata_2025-01.parquet', 'https://…/yellow_tripdata_2025-02.parquet'])`. 평범한 HTTPS에서는 glob(`*`)이 동작하지 않습니다. 웹 서버의 목록을 가져올 수 없기 때문입니다. [S3](s3.md)에서는 동작합니다.
- **존.** `PULocationID`와 `DOLocationID`는 택시 존 번호입니다. 뉴욕시 택시·리무진 위원회(TLC)가 그 이름을 담은 조회 테이블을 공개합니다.

데이터는 [TLC](https://www.nyc.gov/site/tlc/about/tlc-trip-record-data.page)가 공개하며, 이곳에서 모든 열에 대한 설명도 볼 수 있습니다.
