# 例：HTTPS 経由で 350 万件のタクシー乗車

> 350 万行の NYC タクシー Parquet ファイルを HTTPS 経由で DuckDB SQL でクエリし、DuckLocal で時間帯と支払い方法ごとの乗車をグラフにします。

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

ニューヨーク市はイエローキャブのすべての乗車を Parquet ファイルで公開しています。2025 年 1 月分は 59 MB の 1 ファイルで 3,475,226 行あり、DuckLocal はそれが置かれている場所のままクエリできます。ダウンロードの手順も、クラスターも、インポートも不要です。このチュートリアルでは、最初の確認から 3 つのグラフと 1 つのダッシュボードまでを、1 クエリずつ進めます。より広いファイルファーストのワークフローについては、[DuckDB SQL によるローカルデータ分析](https://ducklocal.app/use-cases/local-data-analysis/) を参照してください。

このガイドは、[最初の 10 分間](tutorial.md) を終えているか、基本をすでに理解していることを前提としています。**⌘↵**（Windows と Linux では Ctrl+Enter）でエディタ内のクエリが実行され、結果エリアには **Chart** タブがある、という点です。

ファイルはこちらです。

```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 か月を 1 時間ずつ

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 行（1 か月の各時間に 1 行ずつ）に集計します。**Chart** に切り替えてください。最初の列がタイムスタンプなので、DuckLocal は時系列のエリアグラフを描画します。毎日が山として現れ、山は週に合わせて上下します。1 か月で最も混雑した時間は 1 月 16 日木曜日の 18:00 で、13,288 件の乗車がありました。

グラフを誠実にする 2 つのポイントがあります。

- **`WHERE` 句。** ファイル内の 22 件の乗車は 1 月の外で始まっています。大みそかの 21 件と、2 月に入って 44 秒の 1 件です。フィルターがないと、グラフの両端に 4 つの余計な時間が加わります。
- **`ORDER BY 1`。** グラフはクエリが返した順序で行をプロットします。`GROUP BY` は順序を保証しないため、これがないと線がジグザグになります。

744 ポイントはグラフの 1,500 ポイント上限を下回るので、各時間はバケットに平均化されず、そのまま描画されます。グラフのタイトルを確認してください。プロットされたポイント数が表示されています。

## 3. 1 日の形

1 か月を 1 日に畳み込みます。時刻ごとの乗車数で、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;
```

**Chart** は今度 24 本の棒を描画します。街が最も静かなのは 04:00（1 か月で 20,033 件）、最も混雑するのは 18:00（267,951 件）で、13 倍以上です。

::: warning 時刻がテキストである理由
ラベルは意図的に `format('{:02d}:00', …)` で組み立てています。結果のグラフは **最初の数値列** をプロットし、素の `hour(…)` は数値です。それが棒の高さになってしまい、乗車数ではなく 0 から 23 への整った階段が表示されます。最初の列がテキストならラベルとして扱われ、値にはなりません。ゼロ埋め（`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` は、返金や運賃ゼロによるゼロ除算や符号の反転を防ぎます。グラフが `tip_pct` をプロットするのは、それが最初の数値列だからです。代わりに件数をグラフにしたい場合は `trips` を先頭にしてください。

## 5. ダッシュボードとして残す

何度も実行する価値のある 3 つのクエリは、[ダッシュボード](dashboards.md) に入れるべきです。[nyc-taxi.dash](https://ducklocal.app/docs/samples/nyc-taxi.dash) をダウンロードしてください。時間ごとの推移、時刻ごとの棒グラフ、チップのグラフ、そしてその背後にある数値の表が含まれています。DuckLocal のウィンドウにドラッグすると、すべてのクエリを実行し、すべてのプロットを描画するタブとして開きます。

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` なしで実行し、**Export Parquet…** を使います。その後、ローカルファイルをドラッグすれば、名前でクエリできるビューになります。
- **より多くの月。** ファイルは `yellow_tripdata_YYYY-MM.parquet` という 1 つのパターンに従います。DuckDB はそれらのリストを 1 つのテーブルとして読めます：`FROM read_parquet(['https://…/yellow_tripdata_2025-01.parquet', 'https://…/yellow_tripdata_2025-02.parquet'])`。glob（`*`）は素の HTTPS では使えません。Web サーバーの一覧を取得できないからです。[S3](s3.md) では使えます。
- **ゾーン。** `PULocationID` と `DOLocationID` はタクシーゾーンの番号です。ニューヨーク市タクシー＆リムジン委員会（TLC）が、それらに名前を付ける参照テーブルを公開しています。

データは [TLC](https://www.nyc.gov/site/tlc/about/tlc-trip-record-data.page) が公開しており、すべての列の説明もそこにあります。
