Ein Amazon-Data-Warehouse mit FastAPI und TimescaleDB aufbauen

Amazons SP-API bietet Zugriff auf umfangreiche operative Daten: Bestellungen, Bestände, Abrechnungen und die Leistung des Produktkatalogs. Werbedaten liefert die separate Amazon Ads API. Nützlich sind diese Daten aber nur, wenn sie sich abfragen lassen. Amazons eigene Berichte sind nur vorübergehend verfügbar, unterliegen Aufruflimits und sind nicht auf die operativen Fragen zugeschnitten, die für Verkäufer auf mehreren Marktplätzen am wichtigsten sind. Sie sehen, was passiert ist. Sie können jedoch nicht ohne Weiteres abfragen, was gleichzeitig auf allen Marktplätzen geschieht oder wie sich die Nachfrage nach einer bestimmten ASIN in einer bestimmten Versandregion in den letzten neunzig Tagen entwickelt hat.

Dieser Beitrag beschreibt die Architektur unseres Amazon-Data-Warehouse: FastAPI als API-Schicht, TimescaleDB als Zeitreihenspeicher und Celery für die asynchrone SP-API-Berichtspipeline. Ziel ist ein System, das die Daten, die wir über Amazons APIs abrufen, in einer abfragbaren Form unter Ihrer Kontrolle speichert. Es soll genügend Struktur für Nachfrageprognosen und operative Datenanalysen bieten, ohne dass für seine Pflege ein Data-Engineering-Team nötig ist.

Warum Amazons eigene Tools nicht ausreichen

Berichte aus Seller Central decken die meisten operativen Anforderungen eines einzelnen Marktplatzes mit kleinem Katalog ab. Bei größerem Umfang werden die Lücken sichtbar. Berichte werden auf Anfrage erstellt und verfallen. Eine dauerhafte Abfrageschicht fehlt: Sie erstellen einen Bericht, laden eine Datei herunter, und diese Datei ist Ihr Datenbestand. Wenn Sie denselben Bericht in sechs Monaten erstellen, erhalten Sie die dann aktuellen Daten, nicht die von heute.

Jede historische Analyse setzt daher voraus, dass jemand alle relevanten Berichte in den richtigen Intervallen heruntergeladen und gespeichert hat. Alternativ müssen Sie die Historie aus Exporten auf Transaktionsebene rekonstruieren. Doch auch diese unterliegen Aufruflimits, lassen sich nur innerhalb begrenzter Zeitfenster seitenweise abrufen und sind für den Abruf einzelner Datensätze statt für umfassende Analysen strukturiert.

Amazons Business Reports-Dashboard liefert aggregierte Trenddaten. Deren Detailgrad und Aufbewahrungszeitraum richten sich jedoch nach Amazons Produktentscheidungen, nicht nach Ihren Analyseanforderungen. Die Werbekonsole hat ein eigenes Datenmodell, das sich nicht sauber mit den Versanddaten verknüpfen lässt. Abrechnungsdaten kommen im Zweiwochenrhythmus und müssen aufwendig geparst werden, um sie mit Bestelldaten abzustimmen.

Ein eigenes Data Warehouse löst die Probleme der dauerhaften Speicherung und der Abfragbarkeit gleichzeitig. Sie kontrollieren den Speicher, definieren die Aufbewahrung und schreiben Abfragen, die die tatsächlichen Fragen Ihres Unternehmens beantworten – statt der Fragen, für die Amazons Dashboards konzipiert wurden.

Technologieentscheidungen

Wir haben TimescaleDB als primären Speicher gewählt, weil die meisten operativen Amazon-Daten von Natur aus Zeitreihen sind. Bestellungen haben Zeitstempel, Bestandsaufnahmen beziehen sich auf einen bestimmten Zeitpunkt und Abrechnungszeiträume haben Anfangs- und Enddaten. Werbeausgaben und Impressionen summieren sich im Zeitverlauf. TimescaleDB erweitert PostgreSQL um Hypertables, die Zeitbereichsabfragen über große Datenmengen wesentlich effizienter machen als Standard-PostgreSQL und dabei vollständig SQL-kompatibel bleiben. Es gibt weder eine neue Abfragesprache zu lernen noch ein Betriebsmodell, das sich wesentlich von einer normalen Postgres-Installation unterscheidet.

FastAPI bildet die API-Schicht zwischen den Celery-Workern, die Daten aus der SP-API abrufen, und den internen Anwendungen, die das Data Warehouse abfragen. Es übernimmt Authentifizierung, Anfragevalidierung und Antwortserialisierung mit wenig wiederkehrendem Code. Für einen internen Dienst ohne Zugriff aus dem öffentlichen Internet ist die automatische OpenAPI-Dokumentation besonders nützlich: Sie liefert eine abfragbare Schnittstellendefinition, mit der neue nutzende Anwendungen einfach entwickelt werden können, ohne das Datenmodell aus dem Datenbankschema rekonstruieren zu müssen.

Celery steuert die asynchrone SP-API-Berichtspipeline. Die Berichtserstellung der SP-API ist grundsätzlich asynchron: Sie fordern einen Bericht an, fragen seinen Status ab, laden das fertige Ergebnis herunter und verarbeiten die Datei. Das lässt sich direkt als Celery-Task-Kette abbilden: ein Task für die Berichtsanforderung, ein periodischer Task zur Statusabfrage, ein Task zum Herunterladen und Speichern der Rohdatei sowie ein Task zum Parsen und Laden der strukturierten Daten in TimescaleDB. Redis dient als Celery-Broker und Ergebnis-Backend.

Datenmodell

Die Kerntabellen bilden die wichtigsten Datenbereiche der SP-API ab. Das Gestaltungsprinzip lautet: Jede Tabelle soll eine bestimmte Klasse operativer Fragen beantworten können, ohne Verknüpfungen über mehrere Berichtstypen hinweg zu erfordern.

Orders ist eine nach purchase_date partitionierte Hypertable. Jede Zeile steht für eine einzelne Bestellposition statt für eine ganze Bestellung, weil Analysen auf Positionsebene – nach ASIN, Versandkanal oder Marktplatz – die häufigste Analysegranularität darstellen. Aggregate auf Bestellungsebene werden aus den Positionsdatensätzen abgeleitet. Das Partitionierungsintervall der Hypertable beträgt eine Woche. Das bietet gute Abfrageleistung für die gleitenden Zeitfenster, die bei Nachfrageprognosen verwendet werden.

Bestandsaufnahmen speichert die Ergebnisse der Bestandsberichte zum Zeitpunkt ihres Abrufs. FBA-Bestände sind kein Ereignisstrom, sondern ein sich laufend ändernder Zustand, der sich nicht vollständig aus Bestelldatensätzen rekonstruieren lässt: Retouren, Korrekturen und Umlagerungen verändern Bestände ohne entsprechende Bestellungen. Wir rufen zweimal täglich Bestandsaufnahmen ab und speichern sie als zeitpunktbezogene Datensätze. Die kontinuierlichen Aggregate von TimescaleDB berechnen daraus gleitende Tages- und Wochendurchschnitte, ohne dass eine Abfrage die gesamte Historie der Bestandsaufnahmen durchsuchen muss.

Abrechnungen speichert geparste Abrechnungsberichte mit jeweils einer Position pro Zeile. Das Abrechnungsdatenmodell gehört zu den komplexeren Parsing-Aufgaben im SP-API-Ökosystem: Amazon verwendet je nach Marktplatz unterschiedliche Transaktionstypcodes, und die Benennung der Gebührenpositionen ist regional nicht durchgehend einheitlich. Wir pflegen eine Zuordnungstabelle, die die Gebührentypen der verschiedenen Märkte auf eine einheitliche interne Systematik abbildet.

Katalog speichert eine wöchentlich aktualisierte Momentaufnahme des Produktkatalogs mit ASINs, Titeln, Kategorien und Variantenbeziehungen. Die Tabelle dient vor allem als Nachschlagereferenz für die anderen Tabellen. Sie verwendet keine Hypertable-Struktur, weil die Daten keine wesentlichen Zeitreiheneigenschaften haben.

TimescaleDB in der Praxis

Hypertables sind die zentrale Funktion von TimescaleDB. Um eine normale PostgreSQL-Tabelle in eine Hypertable umzuwandeln, genügt ein Befehl, der die Zeitspalte und das Partitionierungsintervall angibt. Danach funktionieren normale SQL-Abfragen unverändert. Der Abfrageplaner von TimescaleDB schließt automatisch Chunks aus, also Partitionen außerhalb des abgefragten Zeitbereichs. So bleiben zeitlich begrenzte Abfragen auch bei großen Datenmengen schnell.

Kontinuierliche Aggregate sind die zweite Funktion, die wir intensiv nutzen. Ein kontinuierliches Aggregat ist eine materialisierte Sicht, die TimescaleDB inkrementell aktualisiert, sobald neue Daten in der Hypertable eintreffen. Für die Nachfrageprognose führen wir ein tägliches kontinuierliches Aggregat der Verkäufe nach ASIN und Marktplatz, aus dem gleitende Verkaufssummen über 7, 30 und 90 Tage berechnet werden. Es wird automatisch nach einem festgelegten Zeitplan aktualisiert. Abfragen greifen auf vorberechnete Daten statt auf die vollständige Hypertable zu. Dadurch sind Dashboard-Analysen schnell genug für die interaktive Nutzung.

CREATE MATERIALIZED VIEW daily_sales_by_asin
WITH (timescaledb.continuous) AS
SELECT
  time_bucket('1 day', purchase_date) AS day,
  asin,
  marketplace_id,
  SUM(quantity_ordered) AS units_sold,
  SUM(item_price_amount) AS revenue
FROM order_items
GROUP BY day, asin, marketplace_id;

Diese Sicht wird durch die Hintergrundrichtlinie von TimescaleDB automatisch aktualisiert, die wir auf eine stündliche Ausführung eingestellt haben. Die gleitenden 90-Tage-Summen für die Prognose werden mit Fensterfunktionen über dieser materialisierten Sicht berechnet, nicht über der Rohdatentabelle der Bestellpositionen.

Die Celery-Pipeline

Die SP-API-Berichtspipeline besteht aus Celery-Tasks, deren Zeitplan Celery Beat verwaltet. Jeder Berichtstyp hat seinen eigenen Rhythmus: Bestellungen werden stündlich abgerufen, Bestände zweimal täglich und Abrechnungen im Zweiwochenrhythmus entsprechend Amazons Abrechnungszeiträumen.

Die Pipeline folgt für jeden Berichtstyp demselben Aufbau: Ein geplanter Task fordert über die SP-API einen Bericht an und speichert die Anfrage-ID in Redis. Ein Polling-Task läuft alle paar Minuten, prüft über die SP-API den Berichtsstatus und stellt bei einem fertigen Bericht einen Download-Task in die Warteschlange. Dieser lädt das Berichtsdokument herunter, speichert die Rohdatei auf der Festplatte und reiht einen Verarbeitungstask ein. Der Verarbeitungstask parst die Datei und lädt strukturierte Datensätze in TimescaleDB.

Die Deduplizierung erfolgt im Verarbeitungsschritt statt auf Datenbankebene. Die SP-API liefert gelegentlich doppelte Datensätze aus überlappenden Berichtszeiträumen. Wir bilden einen Hash aus den identifizierenden Feldern jedes Datensatzes und prüfen vor dem Einfügen, ob er bereits vorhanden ist. So sammeln sich im Data Warehouse mit der Zeit keine doppelten Zeilen an, solange jeder Berichtstyp sequenziell verarbeitet wird; bei paralleler Verarbeitung wäre zusätzlich eine Eindeutigkeitsbedingung in der Datenbank nötig.

Die Fehlerbehandlung folgt einer einfachen Regel: Vorübergehende SP-API-Fehler, etwa Antworten wegen überschrittener Aufruflimits oder vorübergehender Dienstausfälle, lösen einen Celery-Wiederholungsversuch mit exponentiell verlängerten Wartezeiten aus. Dauerhafte Fehler – fehlerhafte Berichtsdokumente, unerwartete Schemaänderungen oder Parsing-Fehler – werden mit vollständigem Kontext protokolliert und stoppen die Verarbeitung des betroffenen Berichtstyps, ohne andere Pipelines zu beeinträchtigen. Wir prüfen das Fehlerprotokoll bei der wöchentlichen Betriebsprüfung. Als dringende Vorfälle behandeln wir diese Fehler nur, wenn sie Daten für die Abstimmung von Abrechnungen betreffen.

Grundlage der Nachfrageprognose

Das Data Warehouse selbst implementiert keine Nachfrageprognose. Es liefert die Datengrundlage dafür: saubere Verkaufszeitreihen auf der Ebene ASIN–Marktplatz–Tag mit genügend Historie, um saisonale Muster zu erkennen und statistisch aussagekräftige Trendschätzungen zu berechnen.

Das oben beschriebene tägliche kontinuierliche Aggregat bildet die Grundlage für gleitende Nachfragesignale über 7, 30 und 90 Tage. Diese fließen in einfache Prognosemodelle ein: gewichtete gleitende Durchschnitte und lineare Trendextrapolation für stabile Produkte sowie manuelle Anpassungsfaktoren bei bekannter Saisonalität. Die Modelle laufen als FastAPI-Endpunkte, die die kontinuierlichen Aggregate abfragen und Punktprognosen mit Konfidenzintervallen zurückgeben.

Komplexere Prognoseverfahren werden praktikabel, sobald die Datengrundlage steht. Wir haben für Produkte mit klaren saisonalen Zyklen mit exponentieller Glättung nach Holt-Winters experimentiert. Bei Produkten, deren Nachfrage wesentlich von externen Signalen wie Werbeausgaben oder Preisänderungen abhängt, haben wir einfache Regressionen auf diese Signale getestet. Für die meisten Produkte verbessern diese komplexeren Ansätze die Prognosegenauigkeit gegenüber gut abgestimmten gewichteten gleitenden Durchschnitten jedoch nur geringfügig. Datenqualität und Länge der Historie sind wichtiger als die Modellkomplexität.

Was möglich wird

Die konkreten Möglichkeiten des Data Warehouse verdienen eine ausdrückliche Erwähnung. Sie verändern qualitativ, was im operativen Betrieb möglich ist, statt nur die Berichterstellung etwas zu beschleunigen.

Marktplatzübergreifende Bestandsplanung wird praktikabel. Mit Daten zur Verkaufsgeschwindigkeit auf ASIN-Marktplatz-Ebene und den aktuellen FBA-Beständen aus der Tabelle der Bestandsaufnahmen können wir die Bestandsreichweite in Tagen für jede SKU auf jedem Marktplatz berechnen und Nachbestellempfehlungen automatisch erzeugen, statt jeden Marktplatz manuell zu prüfen.

Die Abstimmung von Abrechnungen wird nachvollziehbar prüfbar. Werden Bestell- und Abrechnungsdaten im selben System gespeichert, lässt sich kontrollieren, ob jede Bestellposition zum erwarteten Satz abgerechnet wurde. So werden Gebührenabweichungen, falsche Erstattungen und Abrechnungsfehler erkannt, die sonst nur Verkäufern auffallen, die einzelne Positionen manuell abstimmen. Diese Prüfung läuft als wöchentlicher Bericht über das Data Warehouse und erfordert keine manuelle Arbeit.

Werbeanalysen werden auf ASIN-Ebene möglich. Durch die Verknüpfung von Werbe- und Bestelldaten über gemeinsame Kennungen können wir verfolgen, wie sich Werbeausgaben und organische Verkäufe im Zeitverlauf gemeinsam entwickeln. Amazons Werbekonsole beantwortet diese Frage nicht direkt: Sie zeigt werbezugeordnete Verkäufe, aber nicht die organischen Verkäufe in deren zeitlichem Umfeld. Die verknüpften Daten zeigen Korrelationen; um Veränderungen der organischen Platzierung der Werbung zuzuschreiben, wären zusätzlich Rankingdaten und ein kontrollierter Vergleich nötig.

Weiterführende Beiträge

Flatfile-Automatisierung: Produktangebote auf mehreren Amazon-Marktplätzen verwalten – Die Katalogverwaltung als Ergänzung zum Data Warehouse
Vertriebssysteme entwickeln: Systeme, die verkaufen, damit Sie es nicht selbst tun müssen – Der strategische Rahmen, den das Data Warehouse unterstützt
Über hundert Docker-Container: Unsere monatliche Zustandsprüfung – Die Infrastrukturpflege, die diesen Stack funktionsfähig hält