Court Geometry
Dimensions
Playbook for the 17 dimension outputs that define identity, calendar, venue, and lookup context
Dimension Tables
Dimensions are the lineup card for the warehouse: they tell you who is on the floor, which game or season a row belongs to, where it happened, and which controlled vocabulary should decode the action.
SCD Type 2 alert: dim_player and dim_team_history preserve change over time. Use their business keys for ordinary joins, and reach for surrogate/history fields only when you need time-aware snapshots.
How to use this page
- Pick the dimension family by asking whether you need identity, team/game frame, time buckets, or lookup vocabularies.
- Start with the default hub first (
dim_player,dim_team,dim_game, or the season/date dimensions) before reaching for richer or historical companion tables. - Jump to the generated Star Reference after the family is chosen and the question becomes "what exact columns does this dimension expose?"
Quick navigation
Anchor hubs
Go to Anchor hubs for the tables that carry most analyst joins: player, team, game, and season/date context.
Supporting context
Jump to Supporting context when the question is about people, venues, franchise history, or lookup vocabularies rather than the primary join hubs.
Join anchors
Use Join anchors and watchouts when you need the safest key to bring a dimension into a query.
Exact contracts
Switch to the generated Star Reference once you know the dimension family and need exact schema-backed columns or constraints.
Start by join anchor
| If your query starts from... | Default dimension first | Add these only when needed |
|---|---|---|
| player facts or player-season rollups | dim_player | dim_all_players for wider lookup coverage, dim_college for background context |
| team or standings facts | dim_team | dim_team_extended for richer team profile detail, dim_team_history / dim_defunct_team for era-aware franchise work |
| game, matchup, or event facts | dim_game | dim_arena for venue detail, dim_date / season dimensions for reporting slices |
| time-sliced reporting | dim_date, dim_season, dim_season_week, dim_season_phase | Other hubs only after the time frame is locked |
| play-by-play or shot-taxonomy analysis | dim_play_event_type, dim_shot_zone | dim_game, dim_player, or dim_team once readable labels are in place |
Dimension families at a glance
| Cluster | Tables in the rotation | What they add to the possession |
|---|---|---|
| People and identity | dim_player, dim_all_players, dim_coach, dim_official, dim_college | Stable person and background context for players, coaches, referees, and schools |
| Teams, franchise history, and venues | dim_team, dim_team_extended, dim_team_history, dim_defunct_team, dim_arena | Current team context plus branding, franchise-history, and arena details |
| Game and calendar frame | dim_game, dim_date, dim_season, dim_season_week, dim_season_phase | Schedule, season boundaries, date slicing, and NBA-specific calendar semantics |
| Controlled vocabularies | dim_play_event_type, dim_shot_zone | Reusable labels for play-by-play event codes and shot geography |
Anchor hubs
dim_player
Start here for current player identity, position, jersey, and team context. It is the default player join for most fact families unless you explicitly need a broader lookup-only roster list.
dim_team
The safest current-team join for names, abbreviations, conference/division context, and arena linkage. Reach for dim_team_extended only when the baseline team surface is too thin.
dim_game
The game anchor for both sides of the matchup. It carries game_id plus home_team_id and visitor_team_id, so you can add both clubs without inventing a separate matchup table.
Season + date dimensions
Use dim_season, dim_season_phase, dim_season_week, and dim_date when the question is temporal first: reporting windows, weekday splits, regular season vs playoffs, or NBA-specific calendar framing.
Supporting context
People and school context
dim_all_players, dim_coach, dim_official, and dim_college support broader person lookup, staffing, officiating, and background workflows that do not belong on every fact row.
Franchise, venue, and history context
dim_team_history, dim_defunct_team, and dim_arena cover branding changes, relocated franchises, retired identities, and venue metadata that would otherwise clutter the core team and game dimensions.
Controlled vocabularies
dim_play_event_type and dim_shot_zone decode repeated codes and geography into readable labels. They are small tables with outsized value because they keep event and shot facts interpretable.
History-aware joins
When time-aware history matters, use the SCD2 fields on dim_player or the historical rows in dim_team_history. For ordinary analyst joins, stick to the business keys and current rows.
Fast picks by analyst task
| Need | Start with | Why |
|---|---|---|
| Current player identity, jersey, position, and team context | dim_player | It is the main player join hub for most fact surfaces |
| Exhaustive player lookup coverage beyond the main curated hub | dim_all_players | Useful for broad roster/entity lookup workflows |
| Current franchise/team attributes | dim_team | Best default join for team names, conference, division, and arena context |
| Richer team profile details from team background-style feeds | dim_team_extended | Use when current-team context needs more than the core dim_team surface |
| Historical branding or franchise moves | dim_team_history and dim_defunct_team | These preserve city/nickname/franchise history rather than only the latest team state |
| Venue-level reporting | dim_arena | Keeps arena metadata separate from individual game records |
| Game-level join anchor | dim_game | Carries game_id plus home_team_id and visitor_team_id for both sides of the matchup |
| Calendar slicing and NBA-specific time buckets | dim_date, dim_season, dim_season_week, dim_season_phase | Use dimensions instead of hand-parsing date strings in every query |
| Decoding event or shot taxonomy | dim_play_event_type, dim_shot_zone | Standardizes event codes and shot areas across the model |
When to reach past the default hub
| Default choice | Reach past it when... | Better follow-up |
|---|---|---|
dim_player | you need a wider lookup-oriented player registry than the main curated join hub | dim_all_players |
dim_team | the baseline current-team surface is too thin for the question | dim_team_extended |
dim_team | the analysis is era-aware and cares about branding, relocation, or retired franchise identity | dim_team_history or dim_defunct_team |
dim_game | the real question is venue reporting rather than matchup framing | dim_arena |
dim_game or raw dates on facts | the report needs season windows, phases, weeks, or reusable calendar buckets | dim_date, dim_season, dim_season_week, dim_season_phase |
Join anchors and watchouts
| Table | Primary join fields | Scouting note |
|---|---|---|
dim_player | player_id (plus history fields when needed) | Default player hub; only use the SCD2/history fields when you need row state over time |
dim_team | team_id | Best current-team join for most analytical work |
dim_team_history | historical team keying + franchise fields | Use for era-specific branding and long-horizon franchise work |
dim_game | game_id, home_team_id, visitor_team_id | Matchups are modeled with visitor, not away, on the main game dimension |
dim_date | date_key, full_date | Calendar helper for reporting windows, weekdays, and season-aligned date work |
dim_season / dim_season_phase / dim_season_week | season and phase/week fields | Useful when the question is temporal first and statistical second |
dim_play_event_type / dim_shot_zone | event or zone identifiers | Lookup tables that turn event codes and shot coordinates into readable categories |
Default dimension habits
- Use business keys first. Most analyst joins should start with
player_id,team_id,game_id, and season/date keys rather than history-specific fields. - Treat SCD2 as opt-in complexity. Only pull history windows or surrogate keys when the question explicitly depends on time-aware identity state.
- Keep lookups small and purposeful.
dim_play_event_typeanddim_shot_zoneare best used to make facts readable, not as primary starting tables. - Do not over-join. If the dimension adds no filter, label, or grouping value to the final result, leave it off the possession.
Use this page as the scouting summary. When you need the exact schema-backed contract for a specific dimension, jump to the generated Star Reference.
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.