Verzamelingen

  • Artikel

Azure Cosmos DB is een wereldwijd gedistribueerde database met meerdere modellen die ondersteuning biedt voor de document-, grafiek- en sleutelwaardegegevensmodellen. De inhoud in deze sectie is bedoeld voor het maken, uitvoeren van query's en het beheren van verzamelingsresources met behulp van de SQL API via REST.

De REST API ondersteunt eenvoudige CRUD-bewerkingen op de resources onder een databaseaccount. Een verzameling is een container met JSON-documenten en bijbehorende JavaScript-toepassingslogica, d.w.w. opgeslagen procedures, triggers en door de gebruiker gedefinieerde functies. In dit onderwerp worden de REST-bewerkingen beschreven die worden gebruikt voor het beheren van documentverzamelingen.

Notitie

Deze API-referentieartikelen laten zien hoe u resources maakt met behulp van de Azure Cosmos DB-gegevensvlak-API. Met de gegevensvlak-API kunt u basisopties configureren, zoals indexeringsbeleid en partitiesleutels, net als met Cosmos DB SDK's. Als u volledige functieondersteuning nodig hebt voor alle Azure Cosmos DB-resources, raden we u aan de Cosmos DB-resourceprovider te gebruiken.

Een verzameling wordt toegewezen aan een container in Azure Cosmos DB. Daarom is het een factureerbare entiteit, waarbij de kosten worden bepaald door de ingerichte doorvoer, uitgedrukt in aanvraageenheden per seconde. Verzamelingen kunnen een of meer partities/servers omvatten en omhoog en omlaag worden geschaald in termen van doorvoer. Verzamelingen worden automatisch gepartitioneerd in een of meer fysieke servers door Azure Cosmos DB.

Omdat een verzameling een systeemresource is, heeft deze een vast schema. Het URI-pad van een verzameling wordt vertegenwoordigd door sorteringen in het resourcemodel.

In het volgende voorbeeld ziet u de JSON-definitie van een verzameling:

{  
  "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/"  
}
Eigenschap Beschrijving
id Het is de unieke naam die de nieuwe verzameling identificeert.
indexingPolicy Dit zijn de instellingen voor het indexeringsbeleid voor verzameling.
partitionKey Dit zijn de configuratie-instellingen voor partitionering voor verzameling.
_Ontdoen Het is een door het systeem gegenereerde eigenschap. De resource-id (_rid) is een unieke id die ook hiërarchisch is per resourcestack in het resourcemodel. Het wordt intern gebruikt voor de plaatsing en navigatie van de machtigingsresource.
_Ts Het is een door het systeem gegenereerde eigenschap. Hiermee wordt de tijdstempel van de resource voor het laatst bijgewerkt. De waarde is een tijdstempel.
_Zelf Het is een door het systeem gegenereerde eigenschap. Dit is de unieke adresseerbare URI voor de resource.
_etag Het is een door het systeem gegenereerde eigenschap die de resource-etag vertegenwoordigt die is vereist voor optimistisch gelijktijdigheidsbeheer.
_Doc Het is een door het systeem gegenereerde eigenschap die het adresseerbare pad van de documentresource aangeeft.
_sprocs Het is een door het systeem gegenereerde eigenschap die het adresseerbare pad van de resource opgeslagen procedures (sprocs) aangeeft.
_Triggers Het is een door het systeem gegenereerde eigenschap die het adresseerbare pad van de triggers-resource aangeeft.
_udfs Het is een door het systeem gegenereerde eigenschap waarmee het adresseerbare pad van de door de gebruiker gedefinieerde functiesresource (udfs) wordt opgegeven.
_Conflicten Het is een door het systeem gegenereerde eigenschap die het adresseerbare pad van de conflictresource aangeeft. Tijdens een bewerking op een resource in een verzameling kunnen gebruikers, als er een conflict optreedt, de conflicterende resources inspecteren door een GET uit te voeren op het conflicterende URI-pad.

Eigenschappen onder Indexeringsbeleid

Eigenschap Beschrijving
Automatisch Hiermee wordt aangegeven of automatische indexering is in- of uitgeschakeld. De standaardwaarde is Waar, dus alle documenten worden geïndexeerd. Als u de waarde instelt op Onwaar , kunnen indexeringspaden handmatig worden geconfigureerd.
indexingMode De indexeringsmodus is standaard Consistent. Dit betekent dat indexering synchroon plaatsvindt tijdens het invoegen, vervangen of verwijderen van documenten. Als u wilt dat indexering asynchroon wordt uitgevoerd, stelt u de indexeringsmodus in op lui.
includedPaths De matrix met documentpaden die moeten worden geïndexeerd. Standaard worden twee paden opgenomen: het pad / waarmee wordt aangegeven dat alle documentpaden worden geïndexeerd en het pad _ts, dat indexeert voor een tijdstempelbereikvergelijking.
excludedPaths De matrix met documentpaden die moeten worden uitgesloten van indexering.

Eigenschappen onder Opgenomen paden

Eigenschap Beschrijving
path Het pad waarop het indexeringsgedrag van toepassing is. Indexpaden beginnen met de hoofdmap (/) en eindigen meestal met de ? jokertekenoperator, die aangeeft dat er meerdere mogelijke waarden zijn voor het voorvoegsel. Als u bijvoorbeeld SELECT * FROM Families F WAAR F.familyName = "Andersen" wilt gebruiken, moet u een indexpad voor /familyName/? in het indexbeleid van de verzameling.

Indexpaden kunnen ook de jokertekenoperator * gebruiken om het gedrag voor paden recursief op te geven onder het voorvoegsel. U kunt bijvoorbeeld /payload/* gebruiken om alles onder de eigenschap payload van indexering op te nemen.
Datatype Dit is het gegevenstype waarop het indexeringsgedrag wordt toegepast. Dit kan tekenreeks, getal, punt, veelhoek of lijntekenreeks zijn. Booleaanse waarden en null-waarden worden automatisch geïndexeerd
Soort Het type index. Hash-indexen zijn handig voor gelijkheidsvergelijkingen, terwijl bereikindexen nuttig zijn voor gelijkheid, bereikvergelijkingen en sorteren. Ruimtelijke indexen zijn handig voor ruimtelijke query's.
Precisie De precisie van de index. Kan worden ingesteld op -1 voor maximale precisie of tussen 1-8 voor Getal en 1-100 voor Tekenreeks. Niet van toepassing op gegevenstypen Punt, Veelhoek en Lijntekenreeks .

Eigenschappen onder Uitgesloten paden

Eigenschap Beschrijving
path Pad dat is uitgesloten van indexering. Indexpaden beginnen met de hoofdmap (/) en eindigen meestal met de operator * jokerteken. U kunt bijvoorbeeld /payload/* gebruiken om alles onder de eigenschap payload uit te sluiten van indexering.

Eigenschappen onder Partitiesleutel

Eigenschap Beschrijving
path Een matrix met paden waarmee gegevens in de verzameling kunnen worden gepartitioneerd. Paden mogen geen jokerteken of slash bevatten. De JSON-eigenschap 'AccountNumber' is bijvoorbeeld opgegeven als '/AccountNumber'. De matrix mag slechts één waarde bevatten.
Soort Het algoritme dat wordt gebruikt voor partitionering. Alleen hash wordt ondersteund.

Indexeringsbeleid

Wanneer documenten worden toegevoegd aan een verzameling, indexeert Cosmos DB de documenten standaard automatisch, zodat documenten kunnen worden opgevraagd. Het indexeringsbeleid configureert u op verzamelingsniveau. Omdat indexeringsbeleid is ingesteld op verzamelingsniveau, kan elke verzameling in een database een ander indexeringsbeleid hebben.

Het indexeringsbeleid voor een verzameling kan de volgende opties opgeven:

  • Automatisch: u kunt kiezen of u alle documenten automatisch wilt indexeren door de verzameling. Standaard worden alle documenten automatisch geïndexeerd, maar u kunt ervoor kiezen om dit uit te schakelen. Wanneer indexeren is uitgeschakeld, zijn documenten alleen toegankelijk via hun zelfkoppelingen of door query's met behulp van id.

  • Indexeringsmodus: u kunt kiezen tussen synchrone (consistente), asynchrone (luie) indexupdates en geen indexering (geen). Standaard wordt de index synchroon bijgewerkt bij elke invoeging, vervanging of verwijderingsactie die wordt uitgevoerd op een document in de verzameling. Deze update stelt de query's in staat om hetzelfde consistentieniveau te bereiken als het niveau van het lezen van het document zonder enige vertraging, zodat de index een inhaalslag heeft.

  • Indextypen en precisie: het type of schema dat wordt gebruikt voor indexvermeldingen heeft een directe invloed op de opslag en prestaties van de index. Voor een schema met een hogere precisie zijn query's doorgaans sneller. Er is echter ook een hogere opslagoverhead voor de index. Als u een lagere precisie kiest, betekent dit dat er mogelijk meer documenten moeten worden verwerkt tijdens het uitvoeren van de query, maar dat de opslagoverhead lager is.

  • Indexpaden: In documenten kunt u kiezen welke paden moeten worden opgenomen of uitgesloten van indexering, wat betere schrijfprestaties en lagere indexopslag kan bieden voor scenario's waarin de querypatronen vooraf bekend zijn.

In de volgende tabellen ziet u enkele voorbeeldindexeringspaden en hoe deze worden gebruikt in query's.

Eigenschap Beschrijving
/* Standaardpad voor verzameling. Recursief en is van toepassing op de hele documentstructuur.
/Prop/? Indexpad vereist voor het uitvoeren van query's zoals de volgende (met respectievelijk hash- of bereiktypen):

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/* Indexpad voor alle paden onder het opgegeven label. Werkt met de volgende query's:

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/[]/? Indexpad vereist voor het uitvoeren van iteratie- en JOIN-query's voor matrices met scalaire gegevens, zoals

["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/? Indexpad vereist voor iteratie- en JOIN-query's voor matrices met objecten, zoals

[{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/? Indexpad vereist voor het uitvoeren van query's (met respectievelijk hash- of bereiktypen):

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

Zie Cosmos DB-indexeringsbeleid voor meer informatie over cosmos DB-indexeringsbeleid. Voor de REST API-documentatie gebruiken alle voorbeelden automatische indexering.

Aanbiedingen en prestatieniveaus

Wanneer een verzameling wordt gemaakt, wordt er ook een aanbiedingsresource gemaakt die verwijst naar de gemaakte verzameling. De resource Aanbieding bevat configuratie-informatie over de doorvoer van de verzameling in aanvraageenheden per seconde en aanvraageenheden per minuut.

Het prestatieniveau van een verzameling kan worden gewijzigd met Behulp van Aanbieding vervangen.

Taken

U kunt het volgende doen met documentverzamelingen: