Court Geometry
Schema Reference
Scouting dossier for the nbadb warehouse model and schema-backed reference tiers
Schema Reference
The nbadb analytical surface currently exposes 141 public tables/views across dimensions, facts, bridges, derived aggregations, and analytics views.
Treat this section like the warehouse playbook: the curated pages explain how the lineup fits together, while the generated reference pages give you the box-score-exact schema contracts when you need to check a column, key, or constraint at 2am.
The curated pages explain how to use the model. The raw, staging, and star reference pages are generated, schema-backed artifacts: use them for exact contracts, and regenerate them instead of hand-editing when the code changes.
How to work this section
- Pick the right family first. Use the curated pages to decide whether the question belongs in dimensions, facts,
agg_rollups, oranalytics_shortcuts. - Lock the join lane second. Use Relationships once you know the tables but need the safest path between them.
- Confirm exact contracts last. Finish on the generated Raw Reference, Staging Reference, or Star Reference when the question becomes "what are the exact columns and constraints?"
Quick navigation
Find the right table family
Use Dimensions, Facts & Bridges, Derived Aggregations, and Analytics Views when you are still deciding which surface actually answers the question.
Plan the join lane
Jump to Relationships when you already know the tables involved but need the clean join path, common keys, or naming traps before you write SQL.
Check the generated contract
Go straight to Raw Reference, Staging Reference, or Star Reference when the question is about exact fields, nullability, or schema-backed constraints.
Move from concept to query
Start on the curated page for judgment, then switch to the generated tier page for exactness once the table family and join lane are locked in.
Choose by working state
| If you are currently... | Best first page | Why |
|---|---|---|
| deciding which table family probably owns the answer | Dimensions, Facts & Bridges, Derived Aggregations, or Analytics Views | The curated family pages optimize for judgment, not exhaustive column detail |
| holding a known table but unsure how to join it safely | Relationships | It maps the clean join lanes and common naming traps |
| verifying exact field names, types, or nullability | Star Reference | The generated star page is the contract surface for public analytical objects |
| tracing where a field looked the way it did before transformation | Raw Reference or Staging Reference | Those pages preserve the upstream and normalized tiers feeding the warehouse |
| trying to move from a notebook question to a stable reusable query | Start on the curated family page, then end on the generated tier page | That sequence keeps discovery and exactness separate instead of forcing one page to do both |
Choose by question
| If you need to answer... | Start here | Why this page is the right first pass |
|---|---|---|
| Who is this row about, and what entity context exists? | Dimensions | The dimension lineup card explains identity, calendar, venue, and vocabulary tables |
| Where do the measures actually live? | Facts & Bridges | The fact scouting report groups the 102 fact outputs by grain and job |
| How should I join these surfaces without duplicating rows? | Relationships | The join playbook shows common lanes across player, team, game, and event analysis |
| Is there already a rollup for this question? | Derived Aggregations | The second-unit tables precompute recurring player, team, and league summaries |
| Can I skip manual joins for a common workflow? | Analytics Views | The analytics views are the fast-break outlets for notebooks and dashboards |
| What is the exact generated contract for a schema-backed tier? | Raw Reference, Staging Reference, or Star Reference | These dense pages are the source-of-truth reference sheets for generated schema docs |
Entry routes by starting handle
I have a player or team question
Start with Facts & Bridges if the question is about stats, or Dimensions if you need identity, franchise, or roster context first.
I have a game_id
Start with Facts & Bridges for player-game, team-game, play-by-play, shot, or rotation grain. Then use Relationships to add both teams and supporting dimensions cleanly.
I have a season-level reporting ask
Start with Derived Aggregations for reusable rollups, then fall back to Facts & Bridges only when the needed split or metric does not already exist.
I just need the exact schema
Skip the curated guide layer and go straight to the generated Star Reference or the upstream Raw / Staging references.
Public categories
| Category | Count | Prefix | What it covers |
|---|---|---|---|
| Dimensions | 17 | dim_ | Conformed context such as players, teams, games, seasons, dates, arenas, and lookup vocabularies |
| Facts | 102 | fact_ | Event-, game-, season-, dashboard-, and specialty-grain measurements for analysis |
| Bridges | 2 | bridge_ | Many-to-many connectors used to fan out officials and play participants cleanly |
| Derived Aggregations | 16 | agg_ | Pre-aggregated rollups for repeat player, team, lineup, and league questions |
| Analytics Views | 4 | analytics_ | Pre-joined analyst-friendly surfaces for first-pass reads |
Curated vs generated boundaries
| Page type | What it is optimized for | What it is not trying to be |
|---|---|---|
| Curated schema guides | Table-family choice, join judgment, workflow advice, and "where should I start?" questions | Exhaustive field-by-field contracts |
| Generated tier references | Exact columns, types, nullability, and schema-backed constraints | Narrative explanation of how an analyst should use the model |
| Relationships page | Join patterns, key lanes, and duplicate-row avoidance | Full generated ER output or field dictionary detail |
Generated tier references
Use these pages when the question is not conceptual but contractual.
| Tier | Page | What it represents | Best for |
|---|---|---|---|
| Inbound feed contracts | Raw Reference | Endpoint-shaped schemas closest to nba_api result sets | Tracing source naming, original payload fidelity, and extraction expectations |
| Warehouse-ready normalization | Staging Reference | Cleaned, typed staging schemas after normalization and key alignment | Understanding load-time cleanup and the shape feeding transforms |
| Public schema-backed surface | Star Reference | Generated final-tier schemas for dimensions, facts, bridges, and selected public outputs | Verifying exact public columns, nullability, and constraints |
| Join strategy | Relationships | Curated join patterns across the star surface | Planning how those tiers come back together in SQL |
Regenerate the command-owned reference pages with:
uv run nbadb docs-autogen --docs-root docs/content/docsWarehouse offensive system
- Star first: dimensions create stable context around fact grains so common queries stay join-friendly.
- History where it matters:
dim_playeranddim_team_historyuse SCD Type 2 semantics for time-aware identity tracking. - Conformed anchors:
player_id,team_id,game_id, andseason_yeardo most of the passing across the model. - Smallest useful grain: start at the narrowest fact that answers the question, then climb to
agg_oranalytics_only when the use case repeats. - Generated pages for exactness, curated pages for judgment: use both together rather than expecting one page to do every job.
Prefix quick read
| If the object starts with... | Read it as... | Usually start on... |
|---|---|---|
dim_ | conformed context and identity | Dimensions |
fact_ | measurable events or summaries at a defined grain | Facts & Bridges |
bridge_ | many-to-many connector | Facts & Bridges or Relationships |
agg_ | reusable pre-aggregated rollup | Derived Aggregations |
analytics_ | pre-joined convenience surface | Analytics Views |
stg_ / raw_ | upstream non-public reference tiers | Staging Reference or Raw Reference |
Naming conventions
| Prefix | Meaning | Example |
|---|---|---|
dim_ | Dimension table | dim_player |
fact_ | Fact table | fact_player_game_traditional |
bridge_ | Bridge table | bridge_game_official |
agg_ | Aggregate table | agg_player_career |
analytics_ | Analytics view/table | analytics_player_game_complete |
stg_ | Staging table | stg_league_game_finder__by_team |
raw_ | Raw schema/reference object | raw_boxscoretraditionalv3 |
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.