Accompanying blog post.
Bring your own AI agent and ask questions about NBA data in plain English — no SQL required.
> Which players have improved their true shooting percentage the most over the last five seasons?
> Do teams that play at a faster pace win more games in the playoffs?
> Which franchise players have spent their entire career with one team?
Under the hood: Kaggle provides the data as CSV and Parquet files, PlyDB gives your agent unified SQL access to local files, and your agent handles the rest — no warehouse, no ETL, no cloud.
PlyDB is the database gateway that gives your AI agent unified SQL access to local data files. Your agent translates your questions into SQL; PlyDB executes them.
New to PlyDB? The PlyDB quickstart walks through installation, config, and your first queries end-to-end.
The download script requires Python 3.9+ with no third-party packages — it uses
only Python's built-in urllib and zipfile modules.
scripts/download_nba_data.py downloads the Kaggle dataset and writes all
files to data/kaggle-nba/.
data/kaggle-nba/
├── PlayerStatistics.csv # Traditional box scores, every player, every game
├── TeamStatistics.csv # Team-level box scores, every game
├── PlayerStatisticsExtended.csv # Advanced stats per player per game (1996+)
├── TeamStatisticsExtended.csv # Advanced team stats per game (1996+)
├── PlayByPlay.parquet # Play-by-play detail (1996+)
├── Games.csv # One row per game: teams, scores, arena, attendance
├── LeagueSchedule24_25.csv # Full 2024-25 season schedule
├── LeagueSchedule25_26.csv # Full 2025-26 season schedule
├── Players.csv # Player biographical info (height, weight, position, draft)
└── TeamHistories.csv # Franchise history: name changes, relocations
# Download all files (~1 GB total)
python scripts/download_nba_data.py
# Download core tables only (box scores + games + players)
python scripts/download_nba_data.py --files PlayerStatistics.csv Games.csv Players.csv TeamHistories.csv
# Advanced stats and play-by-play (1996+)
python scripts/download_nba_data.py --files PlayerStatisticsExtended.csv PlayByPlay.parquet
# Re-download files that already exist
python scripts/download_nba_data.py --force
# See what's available
python scripts/download_nba_data.py --list-files| File | Description | Size |
|---|---|---|
PlayerStatistics.csv |
Traditional box scores per player per game (1947+). PTS, REB, AST, STL, BLK, FG%, 3P%, FT%, MIN, +/-. | ~370 MB |
TeamStatistics.csv |
Same columns as PlayerStatistics but aggregated at team level (1947+). | ~34 MB |
PlayerStatisticsExtended.csv |
Advanced per-game stats per player (1996+): OFF_RATING, DEF_RATING, TS_PCT, USG_PCT, PACE, PIE, and 100+ more. | ~430 MB |
TeamStatisticsExtended.csv |
Advanced per-game stats at team level (1996+). | ~36 MB |
PlayByPlay.parquet |
Play-by-play events for nearly every game (1996+). One row per event. | ~900 MB |
Games.csv |
One row per game: date, teams, final scores, arena, attendance (1947+). | ~11 MB |
LeagueSchedule24_25.csv |
Full 2024-25 season schedule with locations and times. | ~150 KB |
LeagueSchedule25_26.csv |
Full 2025-26 season schedule with locations and times. | ~185 KB |
Players.csv |
Biographical data for nearly every player: height, weight, position, draft info. | ~515 KB |
TeamHistories.csv |
Franchise history tracking name changes and relocations. | ~7 KB |
Note on size:
PlayByPlay.parquet(~900 MB) andPlayerStatisticsExtended.csv(~430 MB) are the largest files. Start withPlayerStatistics.csv,Games.csv, andPlayers.csv(~380 MB total) for a fast setup.
plydb-config-example.json contains a ready-to-use PlyDB config that registers
all 10 datasets. Copy it and comment out or remove any tables for datasets you
haven't downloaded yet.
cp plydb-config-example.json plydb-config.jsonOpen Claude Code (or any PlyDB-compatible agent) in this directory and start asking questions. The agent will translate your questions into SQL, run them against the local files via PlyDB, and return results.
The greatest scorers of all time: Rank every player by career points per game (minimum 500 games). How do modern scorers compare to legends like Jordan, Kobe, and LeBron when adjusting for pace and era?
Three-point revolution by decade: Track league-wide three-point attempt rate (FG3A / FGA) season by season. When did the revolution really start, and which teams and players were earliest adopters?
Usage vs. efficiency: Plot usage rate against true shooting percentage for all high-usage seasons since 2010. Which stars combine elite usage with elite efficiency — and which high-usage players are actually hurting their teams?
Clutch performers: Using play-by-play data, identify players with the most fourth-quarter points in games decided by 5 or fewer points. Does "clutch" performance in the regular season predict playoff success?
Home-court advantage across eras: Compare home win percentage before 2000, 2000–2010, 2010–2020, and 2020–present. Did the empty-arena COVID season permanently change anything?
Franchise cornerstone or journeyman? Using team histories and player stats, find players who spent at least 80% of their career games with a single franchise. How do their career arcs compare to players who moved frequently?
The load management effect: Identify star players with unusually low games- played counts in recent regular seasons. Do teams that rest stars in the regular season perform better or worse in the playoffs?
Draft class value: Using player statistics and biographical data (draft year), rank NBA draft classes by aggregate career PTS + REB + AST from all players selected. Which draft classes produced the most talent — and which were busts?
| Source | Description |
|---|---|
| Kaggle dataset | Primary data source — historical NBA data and player box scores |
| NBA.com Stats | Original data source for box scores, advanced stats, and play-by-play |
| PlyDB documentation | Full PlyDB reference |