Sammlungen

  • Artikel

Azure Cosmos DB ist eine global verteilte Datenbank mit mehreren Modellen, die die Dokument-, Graph- und Schlüssel-Wert-Datenmodelle unterstützt. Der Inhalt in diesem Abschnitt dient zum Erstellen, Abfragen und Verwalten von Sammlungsressourcen mithilfe der SQL-API über REST.

Die REST-API unterstützt grundlegende CRUD-Vorgänge für die Ressourcen unter einem Datenbankkonto. Eine Auflistung ist ein Container für JSON-Dokumente und die zugehörige JavaScript-Anwendungslogik, d. h. gespeicherte Prozeduren, Trigger und benutzerdefinierte Funktionen. In diesem Thema werden die REST-Vorgänge beschrieben, die zum Verwalten von Dokumentsammlungen verwendet werden.

Hinweis

In diesen API-Referenzartikeln wird gezeigt, wie Ressourcen mithilfe der Azure Cosmos DB-Datenebenen-API erstellt werden. Mit der Datenebenen-API können Sie grundlegende Optionen wie Indizierungsrichtlinie und Partitionsschlüssel wie bei Cosmos DB SDKs konfigurieren. Wenn Sie vollständige Featureunterstützung für alle Azure Cosmos DB-Ressourcen benötigen, empfiehlt es sich, den Cosmos DB-Ressourcenanbieter zu verwenden.

Eine Sammlung wird einem Container in Azure Cosmos DB zugeordnet. Daher handelt es sich um eine abrechenbare Entität, bei der die Kosten durch den bereitgestellten Durchsatz bestimmt werden, der in Anforderungseinheiten pro Sekunde ausgedrückt wird. Sammlungen können eine oder mehrere Partitionen/Server umfassen und in Bezug auf den Durchsatz hoch- und herunterskaliert werden. Sammlungen werden von Azure Cosmos DB automatisch in einen oder mehrere physische Server partitioniert.

Da eine Auflistung eine Systemressource ist, hat sie ein festes Schema. Der URI-Pfad einer Auflistung wird durch Colls im Ressourcenmodell dargestellt.

Das folgende Beispiel veranschaulicht die JSON-Definition einer Auflistung:

{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "indexingMode": "consistent",  
    "automatic": true,  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "kind": "Range",  
            "dataType": "String",  
            "precision": -1  
          },  
          {  
            "kind": "Range",  
            "dataType": "Number",  
            "precision": -1  
          }  
        ]  
      }  
    ],  
    "excludedPaths": []  
  },  
  "partitionKey": {  
    "paths": [  
      "/AccountNumber"  
    ],  
    "kind": "Hash"  
  },  
  "_rid": "PD5DALigDgw=",  
  "_ts": 1459200611,  
  "_self": "dbs/PD5DAA==/colls/PD5DALigDgw=/",  
  "_etag": "\"00005900-0000-0000-0000-56f9a2630000\"",  
  "_docs": "docs/",  
  "_sprocs": "sprocs/",  
  "_triggers": "triggers/",  
  "_udfs": "udfs/",  
  "_conflicts": "conflicts/"  
}
Eigenschaft BESCHREIBUNG
id Es ist der eindeutige Name, der die neue Sammlung identifiziert.
indexingPolicy Dies sind die Indizierungsrichtlinieneinstellungen für die Sammlung.
partitionKey Dies sind die Partitionierungskonfigurationseinstellungen für die Sammlung.
_los Es handelt sich um eine vom System generierte Eigenschaft. Die Ressourcen-ID (_rid) ist ein eindeutiger Bezeichner, der auch je nach Ressourcenstapel im Ressourcenmodell hierarchisch ist. Sie wird intern für die Platzierung und Navigation der Berechtigungsressource verwendet.
_Ts Es handelt sich um eine vom System generierte Eigenschaft. Sie gibt den zuletzt aktualisierten Zeitstempel der Ressource an. Der Wert ist ein Zeitstempel.
_Selbst Es handelt sich um eine vom System generierte Eigenschaft. Es handelt sich um den eindeutigen, adressierbaren URI für die Ressource.
_Etag Es handelt sich um eine vom System generierte Eigenschaft, die das Ressourcen-Etag darstellt, das für die Steuerung der optimistischen Parallelität erforderlich ist.
_Doc Es handelt sich um eine vom System generierte Eigenschaft, die den adressierbaren Pfad der Dokumentressource angibt.
_sprocs Es handelt sich um eine vom System generierte Eigenschaft, die den adressierbaren Pfad der Ressource gespeicherte Prozeduren (Sprocs) angibt.
_Trigger Es handelt sich um eine vom System generierte Eigenschaft, die den adressierbaren Pfad der Triggerressource angibt.
_Udfs Es handelt sich um eine vom System generierte Eigenschaft, die den adressierbaren Pfad der ressource benutzerdefinierte Funktionen (udfs) angibt.
_Konflikte Es handelt sich um eine vom System generierte Eigenschaft, die den adressierbaren Pfad der Konfliktressource angibt. Wenn während eines Vorgangs für eine Ressource in einer Auflistung ein Konflikt auftritt, können Benutzer Ressourcen überprüfen, die einen Konflikt verursachen, indem sie einen GET-Aufruf für den URI-Pfad des Konflikts ausführen.

Eigenschaften unter Indizierungsrichtlinie

Eigenschaft BESCHREIBUNG
Automatisch Gibt an, ob die automatische Indizierung aktiviert oder deaktiviert ist. Der Standardwert ist True, sodass alle Dokumente indiziert werden. Wenn Sie den Wert auf False festlegen, können Indizierungspfade manuell konfiguriert werden.
indexingMode Standardmäßig ist der Indizierungsmodus konsistent. Dies bedeutet, dass die Indizierung beim Einfügen, Ersetzen oder Löschen von Dokumenten synchron erfolgt. Wenn die Indizierung asynchron erfolgen soll, legen Sie den Indizierungsmodus auf "lazy" fest.
includedPaths Das Array, das die Dokumentenpfade enthält, die indiziert werden sollen. Standardmäßig sind zwei Pfade enthalten: der Pfad /, der angibt, dass alle Dokumentpfade indiziert werden, und der _ts Pfad, der für einen Zeitstempelbereichsvergleich indiziert wird.
excludedPaths Das Array, das die Dokumentenpfade enthält, die aus der Indizierung ausgeschlossen werden sollen.

Eigenschaften unter Eingeschlossene Pfade

Eigenschaft BESCHREIBUNG
path Pfad, für den das Indizierungsverhalten gilt. Indexpfade beginnen mit dem Stamm (/) und enden in der Regel mit dem Platzhalterzeichen "?", das angibt, dass mehrere mögliche Werte für das Präfix verfügbar sind. Für SELECT * FROM Families F WHERE F.familyName = "Andersen" müssen Sie z. B. einen Indexpfad für /familyName/? in die Indexrichtlinie der Sammlung einbinden.

Indexpfade können auch das Platzhalterzeichen * verwenden, um das Verhalten für Pfade rekursiv unter dem Präfix anzugeben. Beispielsweise kann /payload/* verwendet werden, um alles unter der Nutzlasteigenschaft aus der Indizierung einzubeziehen.
dataType Dies ist der Datentyp, auf den das Indizierungsverhalten angewendet wird. Kann String, Number, Point, Polygon oder LineString sein. Booleane und NULL-Werte werden automatisch indiziert
kind Der Indextyp. Hashindizes sind für Gleichheitsvergleiche nützlich, während Bereichsindizes für Gleichheit, Bereichsvergleiche und Sortierung nützlich sind. Räumliche Indizes sind für räumliche Abfragen nützlich.
precision Die Genauigkeit des Indexes. Kann entweder auf -1 für maximale Genauigkeit oder zwischen 1-8 für Zahl und 1-100 für String festgelegt werden. Gilt nicht für dieDatentypen Point, Polygon und LineString .

Eigenschaften unter Ausgeschlossene Pfade

Eigenschaft BESCHREIBUNG
path Pfad, der von der Indizierung ausgeschlossen ist. Indexpfade beginnen mit dem Stamm (/) und enden in der Regel mit dem Platzhalteroperator *. Beispielsweise kann „/payload/*“ dazu verwendet werden, um sämtliche Elemente unter der payload-Eigenschaft von der Indizierung auszuschließen.

Eigenschaften unter Partitionsschlüssel

Eigenschaft BESCHREIBUNG
path Ein Array von Pfaden, mit denen Daten innerhalb der Sammlung partitioniert werden können. Pfade dürfen keinen Wildcard oder einen nachgestellten Schrägstrich enthalten. Beispielsweise wird die JSON-Eigenschaft "AccountNumber" als "/AccountNumber" angegeben. Das Array darf nur einen einzelnen Wert enthalten.
kind Der algorithmus, der für die Partitionierung verwendet wird. Nur Hash wird unterstützt.

Indizierungsrichtlinien

Wenn Dokumente zu einer Sammlung hinzugefügt werden, indiziert Cosmos DB standardmäßig automatisch die Dokumente, sodass Dokumente abgefragt werden können. Die Indizierungsrichtlinie wird auf der Auflistungsebene konfiguriert. Da die Indizierungsrichtlinie auf der Auflistungsebene festgelegt wird, kann jede Auflistung in einer Datenbank verschiedene Indizierungsrichtlinien aufweisen.

Die Indizierungsrichtlinie für eine Auflistung kann die folgenden Optionen angeben:

  • Automatisch: Sie können auswählen, ob die Sammlung alle Dokumente automatisch indiziert oder nicht. Standardmäßig werden automatisch alle Dokumente indiziert, aber Sie können diese Option bei Bedarf deaktivieren. Wenn die Indizierung deaktiviert ist, kann auf die Dokumente nur über ihre eigenen Links oder über Abfragen mithilfe der ID zugegriffen werden.

  • Indizierungsmodus: Sie können zwischen synchronen (konsistent), asynchronen (lazy) Indexupdates und keiner Indizierung (Keine) wählen. Der Index wird bei jedem Einfügen, Ersetzen oder Löschen eines Dokuments der Auflistung standardmäßig synchron aktualisiert. Dieses Update ermöglicht es den Abfragen, die gleiche Konsistenzebene wie die des gelesenen Dokuments zu berücksichtigen, ohne dass der Index nachgeholt werden kann.

  • Indextypen und Genauigkeit: Der für Indexeinträge verwendete Typ oder Schema hat direkte Auswirkungen auf den Indexspeicher und die Indexleistung. Für ein Schema mit höherer Genauigkeit werden Abfragen in der Regel schneller verarbeitet. Es ergibt sich für den Index jedoch auch ein höheren Speichermehraufwand. Die Auswahl einer geringeren Genauigkeit bedeutet, dass während der Abfrageausführung möglicherweise mehr Dokumente verarbeitet werden müssen, aber dafür ist der Speichermehraufwand geringer.

  • Indexpfade: In Dokumenten können Sie auswählen, welche Pfade eingeschlossen oder von der Indizierung ausgeschlossen werden müssen, was eine verbesserte Schreibleistung und einen geringeren Indexspeicher für Szenarien bieten kann, in denen die Abfragemuster vorher bekannt sind.

In den folgenden Tabellen werden einige Beispiele zu Indexpfaden und deren Verwendung in Abfragen veranschaulicht.

Eigenschaft BESCHREIBUNG
/* Der Standardpfad für die Sammlung. Rekursiv und gilt für die gesamte Dokumentstruktur.
/prop/? Zum Verarbeiten der nachfolgenden Abfragen erforderlicher Indexpfad (entsprechend mit Hash- und Bereichstyp):

SELECT * FROM collection c WHERE c.prop = "value"

SELECT * FROM collection c WHERE c.prop > 5

SELECT * FROM collection c ORDER BY c.prop
/prop/* Indexpfad für alle Pfade unter der angegebenen Bezeichnung. Funktioniert mit den folgenden Abfragen:

SELECT * FROM collection c WHERE c.prop = "value"

SELECT * FROM collection c WHERE c.prop.subprop > 5

SELECT * FROM collection c WHERE c.prop.subprop.nextprop = "value"

SELECT * FROM collection c ORDER BY c.prop
/props/[]/? Indexpfad erforderlich, um Iterations- und JOIN-Abfragen für Arrays von Skalaren wie z. B.

["a", "b", "c"]:

SELECT tag FROM tag IN collection.props WHERE tag = "value"

SELECT tag FROM collection c JOIN tag IN c.props WHERE tag > 5
/props/[]/subprop/? Indexpfad erforderlich, um Iterations- und JOIN-Abfragen für Arrays von Objekten wie

[{subprop: "a"}, {subprop: "b"}]:

SELECT tag FROM tag IN collection.props WHERE tag.subprop = "value"

SELECT tag FROM collection c JOIN tag IN c.props WHERE tag.subprop = "value"
/prop/subprop/? Zum Verarbeiten der nachfolgenden Abfragen erforderlicher Indexpfad (entsprechend mit Hash- oder Bereichstyp):

SELECT * FROM collection c WHERE c.prop.subprop = "value"

SELECT * FROM collection c WHERE c.prop.subprop > 5

SELECT * FROM collection c ORDER BY c.prop.subprop

Weitere Informationen zu Cosmos DB-Indizierungsrichtlinien finden Sie unter Cosmos DB-Indizierungsrichtlinien. Im Rahmen der REST-API-Dokumentation wird für alle Beispiele automatische Indizierung verwendet.

Angebote und Leistungsstufen

Wenn eine Sammlung erstellt wird, wird auch eine Angebotsressource erstellt, die auf die erstellte Auflistung verweist. Die Angebotsressource enthält Konfigurationsinformationen zum Sammlungsdurchsatz in Anforderungseinheiten pro Sekunde und Anforderungseinheiten pro Minute.

Das Leistungsniveau einer Sammlung kann mithilfe von Angebot ersetzen geändert werden.

Aufgaben

Mit Dokumentsammlungen können Sie folgendes tun: