Berekende eigenschappen in Azure Cosmos DB for NoSQL (preview)

VAN TOEPASSING OP: NoSQL

Berekende eigenschappen in Azure Cosmos DB hebben waarden die zijn afgeleid van bestaande itemeigenschappen, maar de eigenschappen worden niet opgeslagen in items zelf. Berekende eigenschappen zijn gericht op één item en kunnen worden verwezen in query's alsof ze persistente eigenschappen zijn. Berekende eigenschappen maken het eenvoudiger om eenmaal complexe querylogica te schrijven en ernaar te verwijzen. U kunt één index toevoegen aan deze eigenschappen of deze gebruiken als onderdeel van een samengestelde index voor betere prestaties.

Notitie

Hebt u feedback over berekende eigenschappen? We willen het horen! U kunt feedback rechtstreeks delen met het technische team van Azure Cosmos DB: cosmoscomputedprops@microsoft.com.

Wat is een berekende eigenschap?

Berekende eigenschappen moeten zich op het hoogste niveau in het item bevinden en kunnen geen genest pad hebben. Elke definitie van de berekende eigenschap heeft twee onderdelen: een naam en een query. De naam is de naam van de berekende eigenschap en de query definieert logica om de eigenschapswaarde voor elk item te berekenen. Berekende eigenschappen zijn gericht op een afzonderlijk item en kunnen daarom geen waarden van meerdere items gebruiken of afhankelijk zijn van andere berekende eigenschappen. Elke container kan maximaal 20 berekende eigenschappen hebben.

Voorbeeld van definitie van berekende eigenschap:

{
  "computedProperties": [
    {
      "name": "cp_lowerName",
      "query": "SELECT VALUE LOWER(c.name) FROM c"
    }
  ]
}

Naambeperkingen

We raden u ten zeerste aan berekende eigenschappen een naam te geven, zodat er geen conflicten zijn met een persistente eigenschapsnaam. Om overlappende eigenschapsnamen te voorkomen, kunt u een voor- of achtervoegsel toevoegen aan alle namen van berekende eigenschappen. In dit artikel wordt het voorvoegsel cp_ in alle naamdefinities gebruikt.

Belangrijk

Het definiëren van een berekende eigenschap met dezelfde naam als een persistente eigenschap leidt niet tot een fout, maar kan leiden tot onverwacht gedrag. Ongeacht of de berekende eigenschap is geïndexeerd, worden waarden van persistente eigenschappen die een naam delen met een berekende eigenschap niet opgenomen in de index. Query's gebruiken altijd de berekende eigenschap in plaats van de persistente eigenschap, met uitzondering van de persistente eigenschap die wordt geretourneerd in plaats van de berekende eigenschap als de SELECT-component een jokertekenprojectie bevat. Jokertekenprojectie bevat niet automatisch berekende eigenschappen.

De beperkingen voor namen van berekende eigenschappen zijn:

• Alle berekende eigenschappen moeten unieke namen hebben.
• De waarde van de name eigenschap vertegenwoordigt de naam van de eigenschap op het hoogste niveau die kan worden gebruikt om te verwijzen naar de berekende eigenschap.
• Namen van gereserveerde systeemeigenschappen, zoals id, _riden _ts kunnen niet worden gebruikt als berekende eigenschapsnamen.
• Een berekende eigenschapsnaam kan niet overeenkomen met een eigenschapspad dat al is geïndexeerd. Deze beperking is van toepassing op alle indexeringspaden die zijn opgegeven, waaronder:
  • Opgenomen paden
  • Uitgesloten paden
  • Ruimtelijke indexen
  • Samengestelde indexen

Querybeperkingen

Query's in de definitie van de berekende eigenschap moeten syntactisch en semantisch geldig zijn, anders mislukt de bewerking voor maken of bijwerken. Query's moeten een deterministische waarde opleveren voor alle items in een container. Query's kunnen resulteren in niet-gedefinieerde of null-waarden voor sommige items en berekende eigenschappen met niet-gedefinieerde of null-waarden gedragen zich hetzelfde als persistente eigenschappen met niet-gedefinieerde of null-waarden wanneer ze worden gebruikt in query's.

De beperkingen voor querydefinities voor berekende eigenschappen zijn:

• Query's moeten een FROM-component opgeven die de verwijzing naar het hoofditem vertegenwoordigt. Voorbeelden van ondersteunde FROM-componenten zijn: FROM c, FROM root cen FROM MyContainer c.
• Query's moeten een VALUE-component in de projectie gebruiken.
• Query's kunnen geen JOIN bevatten.
• Query's kunnen geen niet-deterministische Scalar-expressies gebruiken. Voorbeelden van niet-deterministische scalaire expressies zijn: GetCurrentDateTime, GetCurrentTimeStamp, GetCurrentTicks en RAND.
• Query's kunnen geen van de volgende componenten gebruiken: WHERE, GROUP BY, ORDER BY, TOP, DISTINCT, OFFSET LIMIT, EXISTS, ALL, LAST, FIRST en NONE.
• Query's kunnen geen scalaire subquery bevatten.
• Statistische functies, ruimtelijke functies, niet-deterministische functies en door de gebruiker gedefinieerde functies (UDF's) worden niet ondersteund.

Berekende eigenschappen maken

Tijdens de preview moeten berekende eigenschappen worden gemaakt met behulp van de .NET v3- of Java v4 SDK. Nadat de berekende eigenschappen zijn gemaakt, kunt u query's uitvoeren die verwijzen naar de eigenschappen met behulp van een methode, inclusief alle SDK's en Azure Data Explorer in Azure Portal.

	Ondersteunde versie	Opmerkingen
.NET SDK v3	>= 3.34.0-preview	Berekende eigenschappen zijn momenteel alleen beschikbaar in preview-pakketversies.
Java SDK v4	>= 4,46.0	Berekende eigenschappen zijn momenteel onder preview-versie.
Python SDK	>= v4.5.2b5	Berekende eigenschappen zijn momenteel onder preview-versie.

Berekende eigenschappen maken met behulp van de SDK

U kunt een nieuwe container maken waarop berekende eigenschappen zijn gedefinieerd of u kunt berekende eigenschappen toevoegen aan een bestaande container.

Hier volgt een voorbeeld van het maken van berekende eigenschappen in een nieuwe container:

.NET

ContainerProperties containerProperties = new ContainerProperties("myContainer", "/pk")
{
    ComputedProperties = new Collection<ComputedProperty>
    {
        new ComputedProperty
        {
            Name = "cp_lowerName",
            Query = "SELECT VALUE LOWER(c.name) FROM c"
        }
    }
};

Container container = await client.GetDatabase("myDatabase").CreateContainerAsync(containerProperties);

Java

CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/pk");
List<ComputedProperty> computedProperties = new ArrayList<>(List.of(new ComputedProperty("cp_lowerName", "SELECT VALUE LOWER(c.name) FROM c")));
containerProperties.setComputedProperties(computedProperties);
client.getDatabase("myDatabase").createContainer(containerProperties);

Python

U kunt meerdere berekende eigenschappen definiëren in een lijst en deze vervolgens toevoegen aan de containereigenschappen. Python SDK biedt momenteel geen ondersteuning voor berekende eigenschappen voor bestaande containers.

computed_properties = [{'name': "cp_lower", 'query': "SELECT VALUE LOWER(c.db_group) FROM c"},
                       {'name': "cp_power", 'query': "SELECT VALUE POWER(c.val, 2) FROM c"},
                       {'name': "cp_str_len", 'query': "SELECT VALUE LENGTH(c.stringProperty) FROM c"}]

container_with_computed_props = db.create_container_if_not_exists(
            "myContainer", PartitionKey(path="/pk"), computed_properties=computed_properties)

Berekende eigenschappen kunnen worden gebruikt zoals elke andere eigenschap in query's. U kunt bijvoorbeeld de berekende eigenschap cp_lower in een query als volgt gebruiken:

queried_items = list(
            container_with_computed_props.query_items(query='Select * from c Where c.cp_power = 25', partition_key="test"))

Hier volgt een voorbeeld van het bijwerken van berekende eigenschappen in een bestaande container:

.NET

var container = client.GetDatabase("myDatabase").GetContainer("myContainer");

// Read the current container properties
var containerProperties = await container.ReadContainerAsync();
// Make the necessary updates to the container properties
containerProperties.Resource.ComputedProperties = new Collection<ComputedProperty>
    {
        new ComputedProperty
        {
            Name = "cp_lowerName",
            Query = "SELECT VALUE LOWER(c.name) FROM c"
        },
        new ComputedProperty
        {
            Name = "cp_upperName",
            Query = "SELECT VALUE UPPER(c.name) FROM c"
        }
    };
// Update the container with changes
await container.ReplaceContainerAsync(containerProperties);

Java

CosmosContainer container = client.getDatabase("myDatabase").getContainer("myContainer");
// Read the current container properties
CosmosContainerProperties containerProperties = container.read().getProperties();
// Make the necessary updates to the container properties
Collection<ComputedProperty> modifiedComputedProperites = containerProperties.getComputedProperties();
modifiedComputedProperites.add(new ComputedProperty("cp_upperName", "SELECT VALUE UPPER(c.firstName) FROM c"));
containerProperties.setComputedProperties(modifiedComputedProperites);
// Update the container with changes
container.replace(containerProperties);

Python

Het bijwerken van berekende eigenschappen in een bestaande container wordt niet ondersteund in de Python SDK. U kunt alleen berekende eigenschappen definiëren bij het maken van een nieuwe container. Dit is momenteel een werk dat wordt uitgevoerd.

Tip

Telkens wanneer u containereigenschappen bijwerkt, worden de oude waarden overschreven. Als u bestaande berekende eigenschappen hebt en nieuwe eigenschappen wilt toevoegen, moet u ervoor zorgen dat u zowel nieuwe als bestaande berekende eigenschappen aan de verzameling toevoegt.

Berekende eigenschappen gebruiken in query's

Berekende eigenschappen kunnen worden verwezen in query's op dezelfde manier als waarnaar persistente eigenschappen worden verwezen. Waarden voor berekende eigenschappen die niet zijn geïndexeerd, worden tijdens runtime geëvalueerd met behulp van de definitie van de berekende eigenschap. Als een berekende eigenschap wordt geïndexeerd, wordt de index op dezelfde manier gebruikt als voor persistente eigenschappen en wordt de berekende eigenschap op basis van de benodigde basis geëvalueerd. Het is raadzaam om indexen toe te voegen aan uw berekende eigenschappen voor de beste kosten en prestaties.

In de volgende voorbeelden wordt de gegevensset met quickstartproducten gebruikt die beschikbaar is in Data Explorer in Azure Portal. Als u aan de slag wilt gaan, selecteert u Snel starten en laadt u de gegevensset in een nieuwe container.

Hier volgt een voorbeeld van een item:

{
  "id": "08225A9E-F2B3-4FA3-AB08-8C70ADD6C3C2",
  "categoryId": "75BF1ACB-168D-469C-9AA3-1FD26BB4EA4C",
  "categoryName": "Bikes, Touring Bikes",
  "sku": "BK-T79U-50",
  "name": "Touring-1000 Blue, 50",
  "description": "The product called \"Touring-1000 Blue, 50\"",
  "price": 2384.07,
  "tags": [
    {
      "id": "27B7F8D5-1009-45B8-88F5-41008A0F0393",
      "name": "Tag-61"
    }
  ],
  "_rid": "n7AmAPTJ480GAAAAAAAAAA==",
  "_self": "dbs/n7AmAA==/colls/n7AmAPTJ480=/docs/n7AmAPTJ480GAAAAAAAAAA==/",
  "_etag": "\"01002683-0000-0800-0000-6451fb4b0000\"",
  "_attachments": "attachments/",
  "_ts": 1683094347
}

Projectie

Als berekende eigenschappen moeten worden geprojecteerd, moet er expliciet naar worden verwezen. Jokertekenprojecties, zoals SELECT * het retourneren van alle persistente eigenschappen, maar ze bevatten geen berekende eigenschappen.

Hier volgt een voorbeeld van een definitie van een berekende eigenschap om de name eigenschap te converteren naar kleine letters:

{ 
  "name": "cp_lowerName", 
  "query": "SELECT VALUE LOWER(c.name) FROM c" 
} 

Deze eigenschap kan vervolgens worden geprojecteerd in een query:

SELECT 
    c.cp_lowerName 
FROM 
    c

WHERE-component

In filterpredicaten kan worden verwezen naar berekende eigenschappen, zoals permanente eigenschappen. U wordt aangeraden relevante enkelvoudige of samengestelde indexen toe te voegen wanneer u berekende eigenschappen in filters gebruikt.

Hier volgt een voorbeeld van een berekende eigenschapsdefinitie voor het berekenen van een prijskorting van 20 procent:

{ 
  "name": "cp_20PercentDiscount", 
  "query": "SELECT VALUE (c.price * 0.2) FROM c" 
} 

Deze eigenschap kan vervolgens worden gefilterd om ervoor te zorgen dat alleen producten waarvoor de korting lager is dan $ 50, worden geretourneerd:

SELECT 
    c.price - c.cp_20PercentDiscount as discountedPrice, 
    c.name 
FROM 
    c 
WHERE 
    c.cp_20PercentDiscount < 50.00

Clausule GROUP BY

Net als bij persistente eigenschappen kunnen berekende eigenschappen worden verwezen in de GROUP BY-component en waar mogelijk de index gebruiken. Voeg voor de beste prestaties relevante enkelvoudige of samengestelde indexen toe.

Hier volgt een voorbeeld van een berekende eigenschapsdefinitie waarmee de primaire categorie voor elk item uit de categoryName eigenschap wordt gevonden:

{
  "name": "cp_primaryCategory",
  "query": "SELECT VALUE SUBSTRING(c.categoryName, 0, INDEX_OF(c.categoryName, ',')) FROM c"
}

Vervolgens kunt u groeperen cp_primaryCategory op om het aantal items in elke primaire categorie op te halen:

SELECT 
    COUNT(1), 
    c.cp_primaryCategory 
FROM 
    c 
GROUP BY 
    c.cp_primaryCategory

Tip

Hoewel u deze query ook kunt bereiken zonder berekende eigenschappen te gebruiken, vereenvoudigt het schrijven van de query met behulp van de berekende eigenschappen aanzienlijk en zorgt u voor betere prestaties, omdat cp_primaryCategory deze kan worden geïndexeerd. Voor zowel SUBSTRING() als INDEX_OF() is een volledige scan van alle items in de container vereist, maar als u de berekende eigenschap indexeert, kan de hele query worden geleverd vanuit de index. De mogelijkheid om de query uit de index te leveren in plaats van te vertrouwen op een volledige scan verhoogt de prestaties en verlaagt de kosten van de queryaanvraageenheid (RU).

ORDER BY-component

Net als bij persistente eigenschappen kunnen berekende eigenschappen worden verwezen in de ORDER BY-component en moeten ze worden geïndexeerd om de query te laten slagen. Met behulp van berekende eigenschappen kunt u ORDER BY het resultaat van complexe logica of systeemfuncties, waarmee veel nieuwe queryscenario's worden geopend wanneer u Azure Cosmos DB gebruikt.

Hier volgt een voorbeeld van een berekende eigenschapsdefinitie waarmee de maand uit de _ts waarde wordt opgehaald:

{
  "name": "cp_monthUpdated",
  "query": "SELECT VALUE DateTimePart('m', TimestampToDateTime(c._ts*1000)) FROM c"
}

Voordat u ORDER BY cp_monthUpdatedkunt gebruiken, moet u deze toevoegen aan uw indexeringsbeleid. Nadat uw indexeringsbeleid is bijgewerkt, kunt u bestellen op basis van de berekende eigenschap.

SELECT
    *
FROM
    c
ORDER BY
    c.cp_monthUpdated

Berekende eigenschappen indexeren

Berekende eigenschappen worden niet standaard geïndexeerd en vallen niet onder jokertekenpaden in het indexeringsbeleid. U kunt enkelvoudige of samengestelde indexen toevoegen aan berekende eigenschappen in het indexeringsbeleid op dezelfde manier als u indexen toevoegt aan persistente eigenschappen. U wordt aangeraden relevante indexen toe te voegen aan alle berekende eigenschappen. We raden deze indexen aan omdat ze nuttig zijn bij het verhogen van de prestaties en het verminderen van RU's wanneer ze worden geïndexeerd. Wanneer berekende eigenschappen worden geïndexeerd, worden werkelijke waarden geëvalueerd tijdens schrijfbewerkingen voor items om indextermen te genereren en te behouden.

Er zijn enkele overwegingen voor het indexeren van berekende eigenschappen, waaronder:

• Berekende eigenschappen kunnen worden opgegeven in opgenomen paden, uitgesloten paden en samengestelde indexpaden.
• Berekende eigenschappen kunnen geen ruimtelijke index hebben gedefinieerd.
• Jokertekenpaden onder het berekende eigenschapspad werken zoals bij normale eigenschappen.
• Als u een berekende eigenschap verwijdert die is geïndexeerd, moeten alle indexen op die eigenschap ook worden verwijderd.

Notitie

Alle berekende eigenschappen worden gedefinieerd op het hoogste niveau van het item. Het pad is altijd /<computed property name>.

Tip

Telkens wanneer u containereigenschappen bijwerkt, worden de oude waarden overschreven. Als u bestaande berekende eigenschappen hebt en nieuwe eigenschappen wilt toevoegen, moet u ervoor zorgen dat u zowel nieuwe als bestaande berekende eigenschappen aan de verzameling toevoegt.

Notitie

Wanneer de definitie van een geïndexeerde berekende eigenschap wordt gewijzigd, wordt deze niet automatisch opnieuw geïndexeerd. Als u de gewijzigde berekende eigenschap wilt indexeren, moet u eerst de berekende eigenschap uit de index verwijderen. Nadat het opnieuw indexeren is voltooid, voegt u de berekende eigenschap weer toe aan het indexbeleid.

Als u een berekende eigenschap wilt verwijderen, moet u deze eerst verwijderen uit het indexbeleid.

Eén index toevoegen voor berekende eigenschappen

Eén index toevoegen voor een berekende eigenschap met de naam cp_myComputedProperty:

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [
    {
      "path": "/*"
    },
    {
      "path": "/cp_myComputedProperty/?"
    }
  ],
  "excludedPaths": [
    {
      "path": "/\"_etag\"/?"
    }
  ]
}

Een samengestelde index toevoegen voor berekende eigenschappen

Als u een samengestelde index wilt toevoegen aan twee eigenschappen waarin de ene wordt berekend als cp_myComputedPropertyen de andere wordt behouden als myPersistedProperty:

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [
    {
      "path": "/*"
    }
  ],
  "excludedPaths": [
    {
      "path": "/\"_etag\"/?"
    }
  ],
  "compositeIndexes": [
    [
      {
        "path": "/cp_myComputedProperty"
      },
      {
        "path": "/path/to/myPersistedProperty"
      }
    ]
  ]
}

Inzicht in verbruik van aanvraageenheden

Het toevoegen van berekende eigenschappen aan een container verbruikt geen RU's. Schrijfbewerkingen voor containers die berekende eigenschappen hebben gedefinieerd, kunnen een lichte RU-toename hebben. Als een berekende eigenschap wordt geïndexeerd, nemen RU's voor schrijfbewerkingen toe om de kosten voor het indexeren en evalueren van de berekende eigenschap weer te geven. In preview kunnen RU-kosten die betrekking hebben op berekende eigenschappen, worden gewijzigd.

Gerelateerde inhoud

• Indexeringsbeleid beheren
• Documentgegevens modelleren