Soccer Ratings

Import-Pipeline

System

Die Import-Pipeline nutzt ein 5-Tier-Scheduling-System mit automatischer Orchestrierung ueber Celery Beat. Jede Stufe bedient unterschiedliche Frische-Anforderungen — von monatlichen Komplett-Imports bis zu 10-Sekunden Live-Deltas.

Architektur-Ueberblick

Das 5-Tier-System stellt sicher, dass jeder Datentyp mit der passenden Frequenz aktualisiert wird — ohne unnoetige API-Calls.

TierCommandScheduleZweck
1sync_all --full1. Sonntag/Monat, 02:00 UTCKomplett-Import aller Daten
2sync_all --dailyTaeglich, 04:00 UTCAktuelle-Saison Refresh
3async_all --hotAlle 3h tagsüber (06–21 UTC)Hot Window ±48h
3bimport_fixture_detailsAlle 15 Min (10–23 UTC)Details fuer kuerzlich beendete Spiele
4import_fixtures_latestAlle 10 SekundenLive-Score Delta-Sync

Datenfluss

Jede Tier-Stufe verarbeitet unterschiedliche Datenbereiche — von kompletten Referenzdaten bis zu Live-Deltas.

Tier 1 (monatlich):  ALLE Referenzdaten → ALLE Fixtures → ALLE Details → ALLE Standings → ALLE Odds → ALLE Features
Tier 2 (taeglich):   Leagues → Structure → Teams → Fixtures → Players → Coaches → Details → Standings → Odds → Features
Tier 3a (3h):        Fixtures ±48h → Details (letzte 48h) → Standings → Odds → Features
Tier 3b (15min):     Fixture Details (Anpfiff < 4h her)
Tier 4 (10s):        fixtures/latest → Delta-Upsert (nur getrackte Ligen)

FK-Abhaengigkeitsreihenfolge

Alle Commands muessen diese Reihenfolge respektieren. sync_all handhabt dies automatisch.

#CommandEntitiesAbhaengigkeiten
1import_coreCountries, Types, States, CitiesKeine
2import_leaguesLeagues, SeasonsCountries
3import_season_structureStages, RoundsSeasons, Leagues, Types
4import_teamsTeams, VenuesSeasons, Countries, Cities
5import_fixturesFixturesSeasons, Rounds, Teams, Venues
6import_playersPlayers, TeamSquadsSeasons, Teams
7import_coachesCoachesCountries
8import_refereesRefereesCountries
9import_fixture_detailsStats, Events, Lineups, Coaches, SidelinedFixtures, Players, Teams
10import_standingsStandingsSeasons, Teams, Rounds
11import_topscorersTopScorersSeasons, Players, Teams
12import_odds_referenceMarkets, BookmakersKeine
13import_oddsOddValuesFixtures, Markets, Bookmakers
14import_transfersTransfersPlayers, Teams
15compute_featuresFixtureFeatures, EloRatingsFixtures, Odds, Standings

sync_all --full

Monatlich

Komplett-Import aller Daten. Laeuft am 1. Sonntag im Monat um 02:00 UTC.

PhaseCommandScope
1import_coreAlle Lookup-Daten
1import_leaguesAlle Leagues + Seasons
1import_season_structureAlle Seasons (Stages + Rounds)
1import_teamsAlle Seasons (Teams + Venues)
1import_fixturesAlle getrackten Seasons
1import_playersAlle Seasons (Players + Squads)
1import_coachesAlle Coaches
1import_refereesAlle Referees
2import_fixture_detailsAlle beendeten Fixtures ohne Details (nach Datum)
3import_standings --all-trackedAlle Seasons getrackter Ligen
3import_topscorers --all-trackedAlle Seasons getrackter Ligen
4import_odds_referenceMarkets + Bookmakers
4import_odds --backfillAlle Fixtures mit Odds
4import_transfersAlle Transfers
5compute_features --backfillOdds Features
6compute_features --elo-backfillElo Ratings
7compute_features --form-backfillForm (PPG) Features
7compute_features --goals-backfillAverage Goals Features
7compute_features --rates-backfillCS/FTS/BTTS Rates
7compute_features --context-backfillRest Days + Season Progress

sync_all --daily

Taeglich

Aktuelle-Saison-Sync. Laeuft taeglich um 04:00 UTC.

PhaseCommandScope
1import_leaguesRefresh is_current/finished Flags
2import_season_structure --current-onlyNeue Rounds fuer aktuelle getrackte Seasons
3import_teams --current-onlyNeue/aktualisierte Teams fuer aktuelle getrackte Seasons
4import_fixtures --current-onlyAlle Fixtures fuer aktuelle getrackte Seasons
5import_players --current-onlyNeue Zugaenge fuer aktuelle getrackte Seasons
6import_coachesAlle Coaches (global, guenstig)
6import_refereesAlle Referees (global, guenstig)
7import_fixture_detailsBeendete Fixtures ohne Details (aktuelle Seasons)
8import_standingsAktuelle getrackte Seasons
8import_topscorersAktuelle getrackte Seasons
9import_odds --days-ahead 3Odds fuer naechste 3 Tage
10compute_featuresInkrementelle ML Features

sync_all --hot

Alle 3h

Hot-Window-Sync fuer das ±48h-Fenster. Laeuft alle 3 Stunden tagsüber (06, 09, 12, 15, 18, 21 UTC).

PhaseCommandScope
1import_fixtures±48h Datumsbereich
2import_fixture_detailsBeendete Fixtures der letzten 48h
3import_standingsAktuelle getrackte Seasons
4import_odds --days-ahead 3Odds fuer naechste 3 Tage
5compute_featuresInkrementelle ML Features

Automatisches Scheduling

Celery Beat steuert alle automatischen Imports. Die Schedule ist in config/settings/base.py definiert.

TaskScheduleCelery Task
Full Monthly Sync1. Sonntag/Monat, 02:00 UTCsync_monthly
Daily SyncTaeglich, 04:00 UTCsync_daily
Hot Window ±48hAlle 3h (06,09,12,15,18,21 UTC)sync_hot_window
Recent DetailsAlle 15 Min (10–23 UTC)sync_recent_details
Live Delta-SyncAlle 10 Sekundensync_fixtures_latest

Typischer Tagesablauf (UTC)

02:00  [1. So/Monat] Full Import startet (sync_monthly)
04:00  Daily Sync startet (sync_daily)
06:00  Hot Window Sync (sync_hot_window)
09:00  Hot Window Sync
10:00  Recent Details starten alle 15 Min
10:00  Live Delta-Sync laeuft alle 10 Sekunden (kontinuierlich)
12:00  Hot Window Sync
15:00  Hot Window Sync
18:00  Hot Window Sync
21:00  Hot Window Sync
23:00  Recent Details und Live Delta-Sync enden fuer den Tag

League Tracking (is_tracked)

Das is_tracked Flag auf League steuert, welche Ligen von automatischen Commands importiert werden.

SzenarioVerhalten
Bulk Import (ohne --league-id)Setzt is_tracked nicht. Neue Ligen bekommen is_tracked=False.
Single Import (--league-id 271)Setzt is_tracked=True fuer diese Liga.
Fixture ImportsVerarbeiten nur getrackte Ligen.
Standings/Topscorers (Standard)Nur aktuelle Seasons getrackter Ligen.
Standings/Topscorers (--all-tracked)Alle Seasons getrackter Ligen.

Neue Liga tracken

python manage.py import_leagues --league-id 271     # Importiert + setzt is_tracked=True
python manage.py sync_all --daily                    # Wird beim naechsten Daily Sync erfasst

Command-Referenz

Tier 0: Core Lookup Data

CommandOptionenEntities
import_core--skip-cities, --only {countries,types,states,cities}Countries, Types, States, Cities

Tier 1: League Structure

CommandOptionenEntities
import_leagues--league-id IDLeagues, Seasons
import_season_structure--season-id ID, --current-onlyStages, Rounds

Tier 2: Entities

CommandOptionenEntities
import_teams--season-id ID, --current-onlyTeams, Venues
import_players--season-id ID, --current-onlyPlayers, TeamSquads
import_coaches--country-id IDCoaches
import_referees--country-id IDReferees

Tier 3: Fixtures

CommandOptionenEntities
import_fixtures--season-id, --date, --date-from/--date-to, --current-only, --light-checkFixtures
import_fixtures_latestKeine (nur --task-id)Fixtures (Delta)

Tier 4: Fixture Enrichment

CommandOptionenEntities
import_fixture_details--date, --since-hours NStats, Events, Lineups, Coaches, Sidelined
import_fixture_stats--season-id, --date, --batch-sizeFixtureStatistic
import_fixture_events--season-id, --dateFixtureEvent
import_fixture_enrichment--season-id, --dateLineups, Formations, Coaches, Sidelined

Tier 5: Standings & Top Scorers

CommandOptionenEntities
import_standings--season-id, --all-trackedStandings
import_topscorers--season-id, --all-trackedTopScorers

Tier 6: Odds

CommandOptionenEntities
import_odds_referenceKeineMarkets, Bookmakers
import_odds--days-ahead N, --fixture-id, --date, --backfillOddValues

Tier 7: Transfers

CommandOptionenEntities
import_transfersKeine (nur --task-id)Transfers

Tier 8: ML Features

CommandOptionenEntities
compute_features--backfill, --fixture-id, --date, --elo-backfill, --form-backfill, --goals-backfill, --rates-backfill, --context-backfill, --force, --batch-sizeFixtureFeatures, EloRatings

Hinweise

  • Idempotenz: Alle Commands nutzen update_or_create() und koennen sicher mehrfach ausgefuehrt werden.
  • FK-Validierung: Alle Commands pruefen die Existenz von Foreign Keys vor dem Setzen von Referenzen.
  • ImportLog: Alle Commands akzeptieren --task-id fuer die ImportLog-Integration (automatisch durch Celery Tasks uebergeben).
  • Rate Limits: Sportmonks Rate Limits sind pro Entity-Typ (3000 Calls/Stunde). Verschiedene Entity-Typen haben separate Budgets.
  • --current-only: Filtert auf Season.is_current=True AND League.is_tracked=True.
  • --all-tracked: Filtert auf League.is_tracked=True (alle Seasons, nicht nur aktuelle).