Playbook
Kaggle Setup
Download, inspect, and publish nbadb through the Kaggle delivery lane.
Kaggle Setup
Use this guide as the loading dock for the public nbadb dataset on Kaggle: wyattowalsh/basketball.
Pick the right delivery format
| If you want… | Use… |
|---|---|
| A single portable database file | nba.sqlite |
| Fast local SQL and inspection | nba.duckdb |
| Columnar files for Polars/Pandas/Arrow | parquet/ |
| Broadest compatibility | csv/ |
nbadb download copies the latest Kaggle dataset into your configured data directory. If Kaggle provides nba.sqlite but not nba.duckdb, nbadb seeds DuckDB from the SQLite file automatically.
Choose your Kaggle route
| If you need to… | Start here | Why |
|---|---|---|
| Get a ready-to-use local dataset through the CLI | Download via the nbadb CLI | Fastest path into the rest of the nbadb command surface |
| Control the download inside Python | Download via kagglehub | Easier notebook or script integration |
| Publish your own refreshed build | Upload your own build | Handles metadata generation and dataset upload |
Download via the nbadb CLI
nbadb downloadThat command downloads the dataset, copies the files into your data directory, and makes the local folder ready for the rest of the CLI.
Download via kagglehub
import kagglehub
path = kagglehub.dataset_download("wyattowalsh/basketball")
print(f"Dataset downloaded to: {path}")Use this route when you want direct control over download handling inside Python.
What lands on disk
A default local layout looks like this:
nbadb/
├── nba.sqlite
├── nba.duckdb
├── parquet/
│ └── <table>/...
├── csv/
│ └── <table>.csv
└── dataset-metadata.json| Path | What it is | Reach for it when… |
|---|---|---|
nba.sqlite | Portable relational export | You need maximum tool compatibility |
nba.duckdb | Fast analytical local database | You want immediate SQL without file globs |
parquet/ | Columnar table exports | Your workflow is Polars, Pandas, Arrow, or DuckDB-over-files |
csv/ | Flat text exports | A downstream system cannot read DuckDB or Parquet |
dataset-metadata.json | Kaggle dataset metadata | You are preparing or inspecting a publish handoff |
Load the files in Python
| Format | Best for |
|---|---|
| SQLite | Portable inspection or compatibility-oriented tools |
| DuckDB | Fast SQL, joins, and ad hoc analysis |
| Parquet | DataFrame-first or file-based analytical workflows |
SQLite
import sqlite3
conn = sqlite3.connect("nbadb/nba.sqlite")
rows = conn.execute("SELECT * FROM dim_player LIMIT 5").fetchall()DuckDB
import duckdb
conn = duckdb.connect("nbadb/nba.duckdb")
df = conn.sql("SELECT * FROM dim_player LIMIT 5").pl()Parquet with Polars
import polars as pl
df = pl.read_parquet("nbadb/parquet/dim_player/dim_player.parquet")Parquet with Pandas
import pandas as pd
df = pd.read_parquet("nbadb/parquet/dim_player/dim_player.parquet")Upload your own build
nbadb uploadPreflight checklist
| Confirm this first | Why |
|---|---|
| Your target data directory already contains the dataset you want to publish | upload publishes what is on disk |
Kaggle credentials are available to the environment that kagglehub uses | Upload cannot authenticate without them |
NBADB_KAGGLE_DATASET points at the correct slug if you are not using the default | Metadata and upload target must agree |
Version notes and metadata
nbadb upload --message "Post-trade-deadline refresh"- The CLI default message is
"Automated update". - nbadb ensures
dataset-metadata.jsonexists before upload. - The metadata generator uses the configured Kaggle dataset slug as the dataset
id.
Related routes
- Daily Updates for recurring refreshes before publish
- Parquet Usage for DataFrame-first workflows
- Troubleshooting Playbook for Kaggle, artifact, and credential misses
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.