Quickstart: ingest your first race

Zero to a verified race on disk in five minutes: install, ingest one session, verify, and explore it lap by lap.

Ingestion needs no credentials and no cloud account a single Python process talks to FastF1, runs it through the data-quality gate, and writes Hive-partitioned Parquet to data/bronze/. This page takes you from a clean clone to one verified race on disk.

1. Install dependencies

   From the project root, make setup creates a virtual environment and installs every Python dependency the pipeline needs ingestion included.

   make setup
   
2. Ingest one race

   Pull a single session straight from FastF1. The first race of the 2024 season is a good test case small enough to finish in a couple of minutes.

   Single race

   python ingestion/src/ingest.py --season 2024 --round 1 --session R
   

   A single race writes laps, telemetry, weather, and race-control data under data/bronze/<dataset>/season=2024/race=bahrain_grand_prix/. Expect output like this (exact lap counts vary by race):

   Ingestion run 20240315T091500Z: 2024–2024 | sessions=R | force=False | skip_telemetry=False | telemetry_full=False
   Bronze: /path/to/off-the-pace/data/bronze
   === Season 2024 Rd1 ===
     [PULL] R  2024 Rd1 bahrain_grand_prix
     [OK]   R  2024 Rd1 bahrain_grand_prix   57 laps
   === COMPLETE: 1 sessions newly written ===
   
3. Verify what landed

   Confirm the race passed every integrity check row counts, null rates, duplicate keys, required columns.

   make verify-bronze
   

   verify_bronze.py only checks seasons present on disk, so this works identically after a single-race pull, make ingest-recent, or a full backfill.

4. Explore it lap by lap

   Replay the race you just ingested to see the data move, without writing any SQL.

   python ingestion/src/replay_simulator.py \
     --parquet_path data/bronze/laps/season=2024/race=bahrain_grand_prix/2024_bahrain_grand_prix_laps.parquet \
     --race_id 2024_1 \
     --speed 10 \
     --dry_run
   

   See Replay for what --dry_run does and why it’s the working invocation today.

You now have a verified, partitioned Bronze race on disk ready for the transform layer to build on.

Next

Choose your scope

Pick the right amount of data to pull for what you’re building.

CLI reference

Every ingest.py flag, with the why and when.

Bronze schemas

What’s actually in the Parquet files you just wrote.