Playbook
Daily Updates
Game-day runbook for keeping nbadb current with daily, monthly, and full refreshes.
Daily Updates
This guide is the game-day operations board for keeping nbadb current once your data directory already exists.
Pick the right play
| Command | Use it when… | What it covers |
|---|---|---|
nbadb daily | You want the normal recurring refresh | Current season, recent games inside the daily lookback window, plus active player/team refresh |
nbadb monthly | You need a broader sweep | The last 3 seasons |
nbadb full | You are recovering from failures or filling old gaps | Failed journal entries first, then the full season range |
nbadb daily is the default half-court set. Reach for monthly when you need a wider recent-history sweep, and use full when you need recovery plus gap-filling without starting from a blank slate.
Fast operator route
| Step | What you do | Why it matters |
|---|---|---|
| 1 | Run the narrowest refresh that fits the need | Shorter possessions are easier to diagnose and rerun |
| 2 | Check status and quality artifacts right after the run | You catch drift while the command context is still fresh |
| 3 | Escalate from daily to monthly or full only when the symptoms demand it | Wider reruns cost more time and hide the original miss |
What nbadb daily actually does
The daily run is more specific than “update everything.” It:
- Detects the current season
- Discovers game IDs for Regular Season and Playoffs
- Filters those games to
now - NBADB_DAILY_LOOKBACK_DAYS(default:7) - Refreshes the active player/team universe
- Runs the matching extract patterns for those recent games and entities
- Rebuilds downstream tables in
replacemode
That makes daily a strong fit for postgame refreshes and recurring automation.
Runbook by command
Daily refresh
nbadb dailyBest fit: the default recurring refresh after your first full build.
Monthly sweep
nbadb monthlyBest fit: a wider recent-history refresh across the last 3 seasons.
Full recovery + gap fill
nbadb fullBest fit: retrying failed extractions first, then scanning the full season range for missed work.
Configuration knobs that actually change the possession
| Setting | Default | Why you touch it |
|---|---|---|
NBADB_DAILY_LOOKBACK_DAYS | 7 | Widen or tighten the recent-game window for daily |
NBADB_DATA_DIR | environment-dependent | Point the CLI at a different local dataset location |
# Widen the recent-game window (default: 7 days)
export NBADB_DAILY_LOOKBACK_DAYS=14
# Move the working dataset somewhere else
export NBADB_DATA_DIR=/path/to/data
# Run the standard refresh play
nbadb dailyOperator cues during the run
| Signal | What it means |
|---|---|
| Textual UI appears | stdout is interactive and --verbose is not set |
| Plain logs appear | you passed --verbose or the run is non-interactive |
--quality-check reports issues | checks ran, but reported failures are informational today |
First Ctrl+C | graceful stop request that preserves resume-safe state |
Second Ctrl+C | forced exit |
Scheduling the possession
A practical recurring pattern is to run after most late games have settled.
# Example: run daily at 6 AM ET
0 6 * * * cd /path/to/nbadb && nbadb daily >> /var/log/nbadb-daily.log 2>&1What to check after the buzzer
| Check | Why | Escalate when… |
|---|---|---|
nbadb status | Inspect pipeline metadata, journal, and watermarks | state looks stale or failed work remains queued |
uv run nbadb run-quality --report-path … | Capture a machine-readable quality report | failed checks point at empty or inconsistent tables |
artifacts/endpoint-coverage/* | Confirm coverage artifacts when extractor/staging work changed | coverage drift appears after a supposedly good refresh |
When to escalate from daily
Move up to monthly or full when you see any of these:
- A wider season scope is needed than the daily lookback window can cover
- Recent runs left failed journal entries behind
- You are backfilling missed history or cleaning up a period of instability
- Health artifacts show missing coverage or missing downstream tables after a supposedly successful refresh
Related routes
- CLI Reference for exact options and shared pipeline behavior
- Kaggle Setup for distribution handoffs
- Troubleshooting Playbook for failed health checks, coverage drift, and docs artifacts
Keep moving
Stay in the same possession
Keep the mental model warm with adjacent pages, section hubs, and search-friendly routes into the same topic cluster.
Analytics Quickstart
Land quick wins fast and move from setup to analysis with intent.
Shot Chart Analysis
Lean into basketball-native visual storytelling on one of the best-fit pages.
Visual Asset Prompt Pack
Generate hero art, OG cards, icons, and texture systems without losing the docs identity.