Introduction to SDQL
Sports Data Query Language (SDQL) is the syntax used to search and analyze data within our sports databases. It allows you to build flexible queries to isolate specific situations, trends, and outcomes across games, teams, players, and seasons.
There are virtually unlimited combinations of queries you can create. This guide focuses on foundational concepts and the most commonly used parameters to help you get started quickly and confidently.
Table of Contents
- Introduction to SDQL
- Basic Query Structure
- Common Mathematical Operators
- Team vs. Opponent Context
- Combining Multiple Conditions
- Using Historical and Future Game Data
- Shortcuts
- Core Game Parameters
Basic Query Structure
An SDQL query is made up of one or more parameters connected using logical operators such as and or or. For most simple queries, the order of parameters does not matter.
Each parameter represents a statistic, attribute, or game condition. Most parameters are paired with a value that defines exactly what you want to filter for.
Common Mathematical Operators
- = equal to
- > greater than
- = greater than or equal to
- < less than
- <= less than or equal to
- != not equal to
- + addition
- – subtraction
- * multiplication
- / division
Example:
To find games where a team scored more than 150 points, use points>150.
Negative values are also important. For example, margin<=-10 refers to a team that lost by 10 or more points.
Team vs. Opponent Context
Queries can be run for a specific team or across all teams in a league.
For example:
- team=‘Rockets’ and points=115 returns games where the Rockets scored exactly 115 points
- points=115 by itself returns all games where any team scored exactly 115 points
Every SDQL query is evaluated from the perspective of a team and its opponent:
- The team is the subject of the query
- The opponent is the team they played in that game
To reference opponent statistics, use the o: prefix.
Examples:
- team=‘Rockets’ and points=115 → Rockets scored 115
- team=‘Rockets’ and o:points=115 → Rockets allowed 115
You can also directly compare statistics:
- rushing yards – o:rushing yards <= -100 identifies games where the team was outrushed by at least 100 yards
Combining Multiple Conditions
You can stack multiple parameters together to build very specific queries.
Example:
points>=30 and passing yards>=300 and o:points<7 and o:turnovers>=2
This returns games where a team:
- Scored at least 30 points
- Passed for at least 300 yards
- Allowed fewer than 7 points
- Forced at least 2 turnovers
This flexibility is one of the most powerful features of SDQL.
Using Historical and Future Game Data
SDQL allows you to query beyond the current game by referencing past or future games.
Common Time-Based Prefixes
- p: team’s previous game
- op: opponent’s previous game
- P: previous matchup between the teams
- n: team’s next game
- on: opponent’s next game
- N: next matchup between the teams
Examples:
- p:W → team won its previous game
- p:HFL → team lost its previous game as a home favorite
- p:rest=0 → team played on zero days of rest in its last game
Next-game examples:
- n:rest>=3 → next game will be on 3 or more days of rest
- n:A → next game is on the road
Matchup examples:
- P:W → team won the last matchup
- PP:W → team won the previous two matchups
Each additional prefix looks one game further back or forward.
Shortcuts
Shortcuts are abbreviated parameters that represent common conditions. Like prefixes, shortcuts can be combined without limit.
- H = Home
- A = Away
- W = Win
- L = Loss
- F = Favorite
- D = Underdog
- O = Over
- U = Under
- C = Conference
Additional combinations:
- HF = Home favorite
- AF = Away favorite
- HD = Home underdog
- AD = Away underdog
Core Game Parameters
team
- Description: Team name
- Syntax: team=‘Rockets’
site
- Description: Game location
- Syntax:
- Home: site=‘home’ or site=‘H’
- Away: site=‘away’ or site=‘A’
game number
- Description: Regular-season game number
- Syntax: game number<=10
playoffs
- Description: Playoff vs. regular season indicator
- Syntax:
- Playoffs: playoffs=1
- Regular season: playoffs=0
season
- Description: Season year
- Syntax:
- Single season: season=2018
- Range: season>=2023
month
- Description: Month of the season (numeric)
- Syntax: month=2
date
- Description: Game date (YYYYMMDD)
- Syntax: date>=20260101 and date<=20260120
time
- Description: Game start time (24-hour ET)
- Syntax: time>=1900
Betting Market Parameters
line
- Description: Point spread
- Examples:
- Favorites of 3+ points: line<=-3
- Underdogs of 10+ points: line>=10
total
- Description: Game total (O/U)
- Syntax: total>=240
Team & Matchup Context
division
- Description: Team division
- Examples:
- Opponent in Central Division: o:division=‘Central’
- Divisional matchup: division=o:division
rest
- Description: Days of rest before the game
- Examples:
- Back-to-back: rest=0
- Well-rested teams: rest>=3
overtime
- Description: Game went to overtime
- Syntax: overtime=1
Playoff-Specific Parameters
series game
- Description: Game number within a playoff series
- Syntax: series game=1
round
- Description: Playoff round
- Syntax: round=2
seed
- Description: Playoff seed
- Syntax: seed=4
Streak Parameters
streak
- Description: Win/loss streak
- Examples:
- Winning streak: streak=2
- Losing streak: streak<=-4
ats streak
- Description: Against-the-spread streak
- Examples:
- Covers streak: ats streak=3
- Non-covers streak: ats streak<=-5
site streak
- Description: Consecutive home or road games
- Examples:
- Home: site streak=3
- Road: site streak=-5
ou streak
- Description: Over/Under streak
- Examples:
- Overs: ou streak=4
- Unders: ou streak<=-2