Handbuch

Es besteht eine Eins-zu-wenige-Beziehung, bei der die verknüpften Daten begrenzt, klein und häufig gemeinsam gelesen werden.

→Betten Sie die verknüpften Daten als verschachteltes Objekt oder Array in das Hauptdokument ein.

Warum: Optimiert die Leseleistung durch Abrufen aller notwendigen Daten in einem einzigen Punktlesen, minimiert RU-Kosten und Latenz. Vermeidet clientseitige Joins.

Referenz↗

Eine Eins-zu-viele-Beziehung, bei der die "viele"-Seite unbegrenzt wächst oder unabhängig von der "eins"-Seite aktualisiert wird.

→Speichern Sie verknüpfte Elemente als separate Dokumente und verwenden Sie die ID des übergeordneten Dokuments als Referenz.

Warum: Verhindert, dass Dokumente die 2-MB-Größenbegrenzung überschreiten, und vermeidet hohe RU-Kosten für Aktualisierungen großer eingebetteter Arrays.

Referenz↗

Ein Dokument enthält ein Array, das im Laufe der Zeit unbegrenzt wachsen kann, wodurch das 2-MB-Dokumentgrößenlimit riskiert wird (z. B. Ereignisprotokolle, Kommentare).

→Teilen Sie das Array auf mehrere "Bucket"-Dokumente auf. Wenn ein Bucket einen Größen-/Element-Schwellenwert erreicht, erstellen Sie einen neuen.

Warum: Hält die Größen einzelner Dokumente überschaubar, während die logische Gruppierung verknüpfter Daten beibehalten wird.

Modellierung einer Viele-zu-viele-Beziehung, z. B. Studenten und Kurse oder Artikel und Tags.

→Für begrenzte Beziehungen duplizieren Sie Beziehungsdaten auf beiden Seiten (z. B. Kurs-IDs in Studentendokumenten, Studenten-IDs in Kursdokumenten einbetten). Für unbegrenzte Beziehungen verwenden Sie einen separaten "Join"- oder "Edge"-Dokumentcontainer.

Warum: Denormalisierung optimiert für beide Abfrage-Richtungen (Studenten im Kurs, Kurse für Studenten) ohne Joins. Ein Join-Container ist für unbegrenzte Fälle.

Modellierung hierarchischer Daten (z. B. Organigramm, Produktkategorien) und die Notwendigkeit, alle Nachfolger eines Knotens abzufragen.

→Speichern Sie ein Array aller Vorfahren-IDs oder -Namen (den Pfad) in jedem Dokument.

Warum: Ermöglicht effiziente Unterbaum-Abfragen mit einem einzigen `ARRAY_CONTAINS`-Filter, wodurch kostspielige rekursive Suchen vermieden werden.

Ein Dokument hat ein unbegrenztes Array (z. B. Blogkommentare), aber die häufigste Abfrage benötigt nur die letzten N Elemente.

→Betten Sie eine Untermenge der letzten Elemente in das Hauptdokument ein und speichern Sie alle Elemente als separate referenzierte Dokumente.

Warum: Optimiert den primären Lesepfad für Leistung und Kosten, während bei Bedarf weiterhin der Zugriff auf den vollständigen Datensatz möglich ist.

Speichern einer Sequenz von unveränderlichen Ereignissen für eine Entität und die Notwendigkeit, den aktuellen Zustand oder analytische Aggregate abzufragen.

→Speichern Sie Ereignisse in einem einzigen Container, partitioniert nach der Entitäts-ID. Verwenden Sie Change Feed oder Synapse Link, um materialisierte Ansichten oder Aggregate zu berechnen und zu speichern.

Warum: Bietet einen vollständigen Audit-Trail und entkoppelt das Schreibmodell von verschiedenen Lesemodellen, wodurch hohe Flexibilität geboten wird.

Der Zustand verknüpfter Daten muss zu einem bestimmten Zeitpunkt erhalten bleiben (z. B. die Adresse eines Kunden bei einer Bestellung).

→Betten Sie eine Kopie (Snapshot) der verknüpften Daten in das Dokument ein, anstatt darauf zu verweisen.

Warum: Gewährleistet die historische Genauigkeit, indem das Dokument von zukünftigen Änderungen der referenzierten Daten entkoppelt wird.

Erfassung hochfrequenter Zeitreihendaten (z. B. IoT-Sensormesswerte) und Abfrage nach Geräten über Zeitbereiche hinweg.

→Verwenden Sie die Geräte-ID als Partitionsschlüssel. Aggregieren Sie Messwerte in zeitlich gruppierte Dokumente (z. B. stündlich oder minütlich) anstatt ein Dokument pro Messwert.

Warum: Reduziert die Dokumentanzahl und die Schreib-RUs drastisch, während Daten für effiziente Zeitbereichsabfragen innerhalb einer Partition zusammengelegt werden.

Mehrere Erstell-, Aktualisierungs- oder Löschvorgänge sollen als eine einzige atomare Transaktion ausgeführt werden.

→Verwenden Sie die TransactionalBatch-Funktion des SDK. Alle Operationen müssen denselben logischen Partitionsschlüssel betreffen.

Warum: Bietet ACID-Garantien für bis zu 100 Operationen innerhalb einer einzelnen Partition und stellt sicher, dass entweder alle Operationen erfolgreich sind oder alle zusammen fehlschlagen.

Dokumente sollen nach einem bestimmten Zeitraum (z. B. 30 Tage) automatisch aus einem Container gelöscht werden.

→Aktivieren Sie Time to Live (TTL) im Container und legen Sie den Standardwert für `ttl` in Sekunden fest (z. B. 2592000 für 30 Tage). Ein `ttl` von -1 bei einem einzelnen Dokument überschreibt den Standardwert und verhindert das Ablaufen.

Warum: TTL ist eine kostenlose Funktion, die übrig gebliebene RUs nutzt, um Hintergrundlöschungen durchzuführen, und bietet eine effiziente, wartungsarme Möglichkeit zur Verwaltung des Datenlebenszyklus.

Große binäre Objekte (Bilder, Videos, Dokumente > 2 MB) sollen zusammen mit Cosmos DB-Metadaten gespeichert werden.

→Speichern Sie das binäre Objekt in Azure Blob Storage. Speichern Sie den URI zum Blob im Cosmos DB-Dokument zusammen mit den Metadaten.

Warum: Cosmos DB ist für strukturierte Metadaten optimiert und hat ein Dokumentlimit von 2 MB. Blob Storage ist ein kostengünstiger und skalierbarer Dienst für die Speicherung großer Objekte.

Dieselbe Daten müssen nach verschiedenen Eigenschaften abgefragt werden, was zu ineffizienten partitionsübergreifenden Abfragen führt (z. B. Abfrage von Bestellungen nach Kunde, dann nach Produkt).

→Verwenden Sie den Change Feed, um einen zweiten Container (eine materialisierte Ansicht) mit denselben Daten zu füllen, jedoch nach der sekundären Abfrageeigenschaft partitioniert.

Warum: Verlagert die Rechenleistung von der Lesezeit auf die Schreibzeit, wodurch effiziente Abfragen für eine einzelne Partition für mehrere Zugriffsmuster ermöglicht werden.

Komplexe analytische Abfragen (Aggregationen, Joins) sollen auf Live-Betriebsdaten ausgeführt werden, ohne die transaktionale Arbeitslast zu beeinträchtigen.

→Aktivieren Sie Azure Synapse Link im Cosmos DB-Container. Führen Sie analytische Abfragen gegen den analytischen Speicher des Containers mit Synapse serverless SQL- oder Spark-Pools aus.

Warum: Bietet eine ETL-freie, cloudnative HTAP-Lösung. Abfragen gegen den spaltenbasierten analytischen Speicher verbrauchen keine transaktionalen RUs und sind hochperformant.

Nachgelagerte Aktionen sollen skalierbar, zuverlässig und serverlos als Reaktion auf Datenänderungen ausgelöst werden.

→Verwenden Sie eine Azure Function mit dem Cosmos DB-Trigger. Der Trigger nutzt die Change Feed Processor-Bibliothek automatisch.

Warum: Dies ist das empfohlene Muster für ereignisgesteuerte Architekturen. Es bietet automatische Skalierung, Checkpointing und Partitions-Lease-Management.

Referenz↗

Eine Operation muss die Datenbank atomar aktualisieren und eine Nachricht an ein Messaging-System (z. B. Service Bus, Event Hubs) veröffentlichen.

→Führen Sie den Datenbank-Schreibvorgang durch. Verwenden Sie einen Change Feed-Prozessor, um die bestätigte Änderung zuverlässig zu lesen und die entsprechende Nachricht mit Wiederholungslogik zu veröffentlichen.

Warum: Vermeidet unzuverlässige Dual Writes und die Notwendigkeit verteilter Transaktionen. Change Feed fungiert als dauerhafte Outbox und garantiert die letztendliche Zustellung der Nachricht.

Auswahl eines Partitionsschlüssels für einen neuen Container, um Leistung und Skalierbarkeit zu gewährleisten.

→Wählen Sie eine Eigenschaft mit hoher Kardinalität aus, die in den meisten, wenn nicht allen, Punktlese- und Abfrageoperationen vorhanden ist.

Warum: Die Ausrichtung des Partitionsschlüssels am häufigsten Abfragefilter stellt sicher, dass die meisten Operationen an eine einzelne logische Partition weitergeleitet werden, was das effizienteste Zugriffsmuster ist.

Referenz↗

Ein einzelner Partitionsschlüsselwert empfängt ein unverhältnismäßig hohes Anfragevolumen, was zu Drosselung (einer "Hot Partition") führt.

→Erstellen Sie einen synthetischen Partitionsschlüssel, indem Sie den ursprünglichen Schlüssel mit einem zufälligen Suffix oder einer anderen Eigenschaft mit hoher Kardinalität verketten (z. B. `userId + "-" + random(1-10)`).

Warum: Verteilt die Schreib- und Leselast für eine einzelne logische Entität auf mehrere physische Partitionen und mindert die Drosselung.

Daten müssen auf mehreren Ebenen partitioniert werden (z. B. Mandant, dann Jahr, dann Monat), um große Partitionen zu vermeiden und Abfragen auf mehreren Ebenen zu unterstützen.

→Konfigurieren Sie einen hierarchischen Partitionsschlüssel mit einem geordneten Array von Pfaden, wie `["/tenantId", "/year"]`.

Warum: Ermöglicht Unterpartitionierung, um die logische Partitionsgrenze von 20 GB zu verhindern und eine effizientere Weiterleitung für Abfragen zu ermöglichen, die nach der Hierarchie filtern.

Eine global verteilte Anwendung mit aktivierten Multi-Region-Schreibvorgängen muss gleichzeitige Aktualisierungen desselben Dokuments verarbeiten.

→Für einfache Überschreibungen verwenden Sie Last-Writer-Wins (LWW). Für Operationen, die eine Zusammenführungslogik erfordern (z. B. Inkrementieren eines Zählers, Aktualisieren des Inventars), verwenden Sie eine benutzerdefinierte Konfliktlösungsrichtlinie mit einer Merge-Stored Procedure.

Warum: Benutzerdefinierte Zusammenführungslogik verhindert Datenverlust (z. B. ein verlorenes Inkrement), der bei LWW auftreten würde, und gewährleistet die Datenintegrität für kritische Geschäftsoperationen.

Abwägung von Leselatenz, Verfügbarkeit und Datenkonsistenz für eine global verteilte Anwendung.

→Standardmäßig Session-Konsistenz für eine gute Balance und "read-your-own-writes" verwenden. Für vorhersehbare Leseverzögerungen Bounded Staleness nutzen. Bei Bedarf spezifische kritische Schreib-/Leseoperationen auf Strong-Konsistenz umstellen.

Warum: Session ist die am häufigsten verwendete Ebene, die geringe Latenz und starke Garantien innerhalb einer Client-Sitzung bietet. Das Überschreiben pro Anfrage ermöglicht Flexibilität.

Schreiboperationen verbrauchen übermäßige RUs, und nur eine kleine Untermenge der Dokumenteigenschaften wird jemals in Abfragefiltern verwendet.

→Wechseln Sie von der Standard-Indizierungsrichtlinie zu einer benutzerdefinierten Richtlinie. Schließen Sie explizit Pfade für abgefragte Eigenschaften ein und schließen Sie alle anderen Pfade (`"/*"` in `excludedPaths`) aus.

Warum: Jede indizierte Eigenschaft verursacht RU-Kosten bei Schreibvorgängen. Das Ausschließen ungenutzter Eigenschaften kann den Verbrauch von Schreib-RUs und die Größe des Indexspeichers erheblich reduzieren.

Referenz↗

Eine häufige Abfrage filtert nach einer Eigenschaft und sortiert nach einer anderen (z. B. `WHERE c.status = "active" ORDER BY c.timestamp DESC`).

→Erstellen Sie einen zusammengesetzten Index für die Eigenschaften in der Reihenfolge, in der sie in der Abfrage erscheinen: `(status ASC, timestamp DESC)`.

Warum: Ermöglicht es der Abfrage-Engine, das gefilterte und sortierte Ergebnis direkt aus dem Index zu liefern, wodurch ein kostspieliger Sortiervorgang im Arbeitsspeicher vermieden und die RU-Gebühr drastisch reduziert wird.

Eine Abfrage ruft große Dokumente ab, aber die Anwendung benötigt nur ein oder zwei kleine Eigenschaften davon.

→Verwenden Sie die Abfrageprojektion, um nur die benötigten Eigenschaften auszuwählen (z. B. `SELECT c.id, c.name FROM c`) anstelle von `SELECT *`.

Warum: Reduziert die RU-Kosten, indem die vom Datenbank-Engine an den Client übertragene Datenmenge verringert wird.

Eine Anwendung fragt häufig nach Dokumentaktualisierungen, die Daten ändern sich jedoch selten, was zu hohen RU-Kosten für Lesevorgänge führt.

→Speichern Sie den ETag des letzten Lesevorgangs. Senden Sie bei nachfolgenden Lesevorgängen den ETag im `If-None-Match`-Header.

Warum: Wenn sich das Dokument nicht geändert hat, gibt Cosmos DB den Status 304 Not Modified mit einer minimalen RU-Gebühr (typischerweise ~1 RU) zurück, was Kosten und Bandbreite spart.

Eine Arbeitslast weist variable oder unvorhersehbare Verkehrsmuster mit erheblichen Spitzen und Tälern auf.

→Konfigurieren Sie den Autoscale-Durchsatz für die Datenbank oder den Container. Legen Sie die maximalen RU/s fest, die für die Spitzenlast benötigt werden.

Warum: Skaliert den Durchsatz je nach Nutzung automatisch zwischen 10 % des Maximums und den maximalen RU/s, wodurch Kosten optimiert werden, da nicht für ungenutzte bereitgestellte Kapazität bezahlt werden muss.

Eine Arbeitslast dient der Entwicklung, dem Testen oder einer Anwendung mit geringem Datenverkehr und langen Leerlaufzeiten.

→Verwenden Sie den Serverless-Kapazitätsmodus für das Cosmos DB-Konto.

Warum: Sie zahlen nur für die pro Operation verbrauchten RUs, ohne eine minimale bereitgestellte Kapazität. Dies ist die kostengünstigste Option für sporadische Arbeitslasten.

Eine große Anzahl von Dokumenten (Tausende bis Millionen) soll so schnell wie möglich aufgenommen oder geändert werden.

→Verwenden Sie die Bulk-Support-Funktion des SDK (z. B. `AllowBulkExecution = true` im .NET SDK v3).

Warum: Das SDK optimiert für hohen Durchsatz, indem es Operationen bündelt, Parallelität verwaltet und Wiederholungen/Drosselung intern handhabt, was sequentielle Operationen bei weitem übertrifft.

Eine Stored Procedure, die eine große Anzahl von Dokumenten verarbeitet, überschreitet das Zeitlimit.

→Implementieren Sie eine begrenzte Ausführung. Die Stored Procedure sollte prüfen, ob sie sich der 5-Sekunden-Ausführungsgrenze nähert, und falls ja, ein Fortsetzungstoken an den Client zurückgeben. Der Client ruft dann die Prozedur mit dem Token erneut auf, um die Verarbeitung fortzusetzen.

Warum: Stored Procedures haben eine feste Ausführungszeitbegrenzung. Ein Fortsetzungsmuster ist die Standardmethode zur Behandlung langlaufender, mehrstufiger serverseitiger Logik.

Eine geschäftskritische Anwendung erfordert hohe Verfügbarkeit mit minimalem Datenverlust (RPO) und schneller Wiederherstellungszeit (RTO) im Falle eines regionalen Ausfalls.

→Konfigurieren Sie das Cosmos DB-Konto mit mehreren Schreibregionen und aktivieren Sie den automatischen Failover.

Warum: Bietet den niedrigsten RPO und RTO. Daten werden regionsübergreifend repliziert, und im Falle eines Ausfalls befördert Cosmos DB automatisch eine sekundäre Region zur neuen primären Schreibregion.

Die Möglichkeit zur Wiederherstellung nach versehentlicher Datenlöschung oder -beschädigung durch Wiederherstellung der Datenbank zu einem bestimmten Zeitpunkt wird benötigt.

→Aktivieren Sie den Modus für kontinuierliche Sicherung (Continuous Backup) im Cosmos DB-Konto.

Warum: Die kontinuierliche Sicherung ermöglicht die Wiederherstellung zu jedem beliebigen Zeitpunkt (sekundengenau) innerhalb des Aufbewahrungszeitraums (7 oder 30 Tage). Der Wiederherstellungsvorgang erstellt ein neues Konto.

Referenz↗

Eine Compliance-Anforderung schreibt vor, dass die Datenverschlüsselungsschlüssel vom Kunden verwaltet und kontrolliert werden müssen.

→Konfigurieren Sie das Cosmos DB-Konto mit Customer-Managed Keys (CMK) unter Verwendung eines Schlüssels aus einem Azure Key Vault.

Warum: Bietet eine zusätzliche Sicherheitsebene, bei der Sie den Schlüssel-Lebenszyklus (einschließlich Rotation und Widerruf) für die Verschlüsselung im Ruhezustand kontrollieren.

Einer Anwendung oder einem Benutzer soll ein detaillierter, identitätsbasierter Zugriff auf Daten nach dem Prinzip der geringsten Rechte gewährt werden.

→Verwenden Sie die Azure AD-Integration und weisen Sie eine integrierte Rolle (z. B. Cosmos DB Built-in Data Reader) oder eine benutzerdefinierte RBAC-Rolle zu, die auf den spezifischen Container oder die Datenbank beschränkt ist.

Warum: Eliminiert die Notwendigkeit, Master-Schlüssel zu verwalten und zu teilen. RBAC bietet eine auditierbare, identitätsbasierte Zugriffssteuerung.

Ein Cosmos DB-Konto darf nur innerhalb eines bestimmten Azure Virtual Network (VNet) zugänglich sein, ohne Datenverkehr über das öffentliche Internet.

→Erstellen Sie einen Private Endpoint für das Cosmos DB-Konto im VNet und deaktivieren Sie den öffentlichen Netzwerkzugriff in den Firewall-Einstellungen.

Warum: Private Endpoints stellen eine private IP-Adresse für das Cosmos DB-Konto innerhalb Ihres VNet bereit und stellen sicher, dass der gesamte Datenverkehr über das sichere Azure-Backbone fließt.

Diagnose der Ursache von HTTP 429 (Too Many Requests) Drosselungsfehlern.

→Überwachen Sie die Metrik "Normalized RU Consumption" in Azure Monitor. Verwenden Sie Diagnoseprotokolle (`CDBPartitionKeyRUConsumption`), um zu identifizieren, welche Partitionsschlüssel die meisten RUs verbrauchen.

Warum: Die normalisierte RU-Nutzung zeigt an, ob der gesamte Durchsatz ausgeschöpft ist. Protokolle auf Partitionsebene identifizieren Hot Partitions, eine häufige Ursache für Drosselung, selbst wenn die Gesamtnutzung gering ist.

Anforderungs-Latenz muss überwacht und bei Überschreitung benachrichtigt werden, um die SLA-Konformität sicherzustellen.

→Überwachen Sie die Metrik "Server Side Latency P99" in Azure Monitor. Erstellen Sie eine Benachrichtigungsregel, wenn diese Metrik den SLA-Schwellenwert überschreitet.

Warum: Die P99-Latenz stellt die Worst-Case-Erfahrung für 99 % der Anfragen dar und ist die Grundlage für Cosmos DB SLAs. Sie ist ein aussagekräftigerer Indikator für Leistungsprobleme als die durchschnittliche Latenz.

Eine Compliance-Anforderung schreibt vor, dass alle Datenzugriffsoperationen (Lesen, Schreiben, Abfragen) geprüft werden müssen.

→Aktivieren Sie die Diagnoseeinstellungen im Cosmos DB-Konto und leiten Sie die Protokollkategorie `DataPlaneRequests` an einen Log Analytics-Arbeitsbereich oder ein Speicherkonto weiter.

Warum: Das `DataPlaneRequests`-Protokoll liefert detaillierte Informationen zu jeder Datenoperation, einschließlich Operationstyp, Client-IP und zugegriffener Ressource, was für Sicherheitsaudits unerlässlich ist.

Ein nicht vertrauenswürdiger Client (z. B. eine mobile App) benötigt temporären, eingeschränkten Zugriff auf bestimmte Cosmos DB-Ressourcen (z. B. nur Dokumente in seiner eigenen Partition).

→Implementieren Sie einen vertrauenswürdigen Middle-Tier-Dienst, der den Benutzer authentifiziert und dann einen Master-Schlüssel verwendet, um ein kurzlebiges, berechtigungsbezogenes Ressourcentoken zu generieren und an den Client zurückzugeben.

Warum: Dies ist das sicherste Muster für den clientseitigen Zugriff, da es die Offenlegung von Master-Schlüsseln vermeidet und eine fein abgestufte, temporäre Zugriffssteuerung bietet.