Vypočítané vlastnosti ve službě Azure Cosmos DB for NoSQL

Článek
07/02/2024

PLATÍ PRO: NoSQL

Vypočítané vlastnosti ve službě Azure Cosmos DB mají hodnoty odvozené z existujících vlastností položek, ale samotné vlastnosti se neuchovávají v položkách. Vypočítané vlastnosti jsou vymezeny na jednu položku a mohou být odkazovány v dotazech, jako by byly trvalé vlastnosti. Vypočítané vlastnosti usnadňují psaní složité logiky dotazů jednou a mnohokrát na ni odkazují. Pro zvýšení výkonu můžete přidat jeden index těchto vlastností nebo je použít jako součást složeného indexu.

Poznámka:

Máte nějaké připomínky k vypočítaným vlastnostem? Chceme to slyšet! Zpětnou vazbu můžete sdílet přímo s technickým týmem služby Azure Cosmos DB: cosmoscomputedprops@microsoft.com

Co je vypočítaná vlastnost?

Vypočítané vlastnosti musí být na nejvyšší úrovni položky a nesmí mít vnořenou cestu. Každá definice vypočítané vlastnosti má dvě komponenty: název a dotaz. Název je název vypočítané vlastnosti a dotaz definuje logiku pro výpočet hodnoty vlastnosti pro každou položku. Vypočítané vlastnosti jsou vymezeny na jednotlivé položky, a proto nemůžou používat hodnoty z více položek nebo spoléhat na jiné vypočítané vlastnosti. Každý kontejner může mít maximálně 20 vypočítaných vlastností.

Příklad definice počítané vlastnosti:

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

Omezení názvů

Důrazně doporučujeme pojmenovat vypočítané vlastnosti, aby nedošlo ke kolizi s trvalým názvem vlastnosti. Abyste se vyhnuli překrývání názvů vlastností, můžete přidat předponu nebo příponu ke všem názvům vypočítaných vlastností. Tento článek používá předponu cp_ ve všech definicích názvů.

Důležité

Definování počítané vlastnosti pomocí stejného názvu jako trvalá vlastnost nemá za následek chybu, ale může vést k neočekávanému chování. Bez ohledu na to, jestli je vypočítaná vlastnost indexovaná, nebudou hodnoty z trvalých vlastností, které sdílejí název s vypočítanou vlastností, zahrnuté do indexu. Dotazy budou vždy používat vypočítanou vlastnost místo trvalé vlastnosti, s výjimkou trvalé vlastnosti, která se vrátí místo vypočítané vlastnosti, pokud v klauzuli SELECT existuje projekce se zástupnými znaky. Projekce zástupných znaků nezahrnuje automaticky vypočítané vlastnosti.

Omezení pro názvy počítaných vlastností jsou:

Všechny vypočítané vlastnosti musí mít jedinečné názvy.
Hodnota name vlastnosti představuje název vlastnosti nejvyšší úrovně, který lze použít k odkazování na vypočítanou vlastnost.
Rezervované systémové názvy vlastností, jako idje například , _rida _ts nelze je použít jako počítané názvy vlastností.
Název počítané vlastnosti nemůže odpovídat cestě k již indexované vlastnosti. Toto omezení platí pro všechny zadané cesty indexování, včetně:
- Zahrnuté cesty
- Vyloučené cesty
- Prostorové indexy
- Složené indexy

Omezení dotazů

Dotazy v definici počítané vlastnosti musí být platné syntakticky a sémanticky, jinak operace vytvoření nebo aktualizace selže. Dotazy by měly být vyhodnoceny jako deterministická hodnota pro všechny položky v kontejneru. U některých položek se dotazy můžou vyhodnotit jako nedefinované nebo null a vypočítané vlastnosti s nedefinovanými nebo nulovými hodnotami se chovají stejně jako trvalé vlastnosti s nedefinovanými nebo nulovými hodnotami při použití v dotazech.

Omezení definic dotazů počítaných vlastností jsou:

Dotazy musí zadat klauzuli FROM, která představuje odkaz na kořenovou položku. Příklady podporovaných klauzulí FROM: FROM c, FROM root ca FROM MyContainer c.
Dotazy musí v projekci použít klauzuli VALUE.
Dotazy nemůžou zahrnovat JOIN.
Dotazy nemůžou používat ne deterministické skalární výrazy. Příklady ne deterministických skalárních výrazů jsou: GetCurrentDateTime, GetCurrentTimeStamp, GetCurrentTicks a RAND.
Dotazy nemůžou používat žádnou z následujících klauzulí: WHERE, GROUP BY, ORDER BY, TOP, DISTINCT, OFFSET LIMIT, EXISTS, ALL, LAST, FIRST a NONE.
Dotazy nemůžou obsahovat skalární poddotaz.
Agregační funkce, prostorové funkce, nedeterministické funkce a uživatelem definované funkce (UDF) se nepodporují.

Vytvoření vypočítaných vlastností

Po vytvoření počítaných vlastností můžete spouštět dotazy odkazované na vlastnosti pomocí libovolné metody, včetně všech sad SDK a Azure Data Exploreru na webu Azure Portal.

	Podporovaná verze	Notes
.NET SDK v3	>= 3.34.0-preview	Vypočítané vlastnosti jsou aktuálně k dispozici pouze ve verzích balíčků ve verzi Preview.
Java SDK v4	>= 4,46,0	Vypočítané vlastnosti jsou aktuálně ve verzi Preview.
Python SDK	>= v4.5.2b5	Vypočítané vlastnosti jsou aktuálně ve verzi Preview.

Vytvoření vypočítaných vlastností pomocí sady SDK

Můžete buď vytvořit nový kontejner, který má definované vypočítané vlastnosti, nebo můžete do existujícího kontejneru přidat vypočítané vlastnosti.

Tady je příklad vytvoření vypočítaných vlastností v novém kontejneru:

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);

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);

V seznamu můžete definovat více počítaných vlastností a pak je přidat do vlastností kontejneru. Sada Python SDK v současné době nepodporuje vypočítané vlastnosti pro existující kontejnery.

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)

Vypočítané vlastnosti se dají použít stejně jako jakékoli jiné vlastnosti v dotazech. Počítanou vlastnost cp_lower můžete například použít v dotazu takto:

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

Tady je příklad aktualizace vypočítaných vlastností u existujícího kontejneru:

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);

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);

Tip

Při každé aktualizaci vlastností kontejneru se staré hodnoty přepíšou. Pokud máte existující počítané vlastnosti a chcete přidat nové, nezapomeňte do kolekce přidat nové i existující vypočítané vlastnosti.

Použití vypočítaných vlastností v dotazech

Na vypočítané vlastnosti lze odkazovat v dotazech stejným způsobem jako na trvalé vlastnosti. Hodnoty vypočítaných vlastností, které nejsou indexovány, se vyhodnocují během běhu pomocí definice vypočítané vlastnosti. Pokud je vypočítaná vlastnost indexována, použije se index stejným způsobem jako u trvalých vlastností a vypočítaná vlastnost se vyhodnocuje podle potřeby. Doporučujeme přidat indexy do počítaných vlastností , abyste získali co nejlepší náklady a výkon.

Následující příklady používají datovou sadu produktů pro rychlý start, která je k dispozici v Průzkumníku dat na webu Azure Portal. Začněte tím, že vyberete Spustit rychlý start a načtete datovou sadu do nového kontejneru.

Snímek obrazovky, který ukazuje, jak zahájit rychlý start pro načtení ukázkové datové sady na webu Azure Portal

Tady je příklad položky:

{
  "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
}

Projekce

Pokud je potřeba promítat vypočítané vlastnosti, musí se na tyto vlastnosti explicitně odkazovat. Projekce zástupných znaků, jako jsou SELECT * vrácení všech trvalých vlastností, ale nezahrnují vypočítané vlastnosti.

Tady je příklad definice vypočítané vlastnosti pro převod name vlastnosti na malá písmena:

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

Tato vlastnost se pak dá v dotazu promítnou:

SELECT 
    c.cp_lowerName 
FROM 
    c

Klauzule WHERE

Na vypočítané vlastnosti lze odkazovat v predikátech filtru, jako jsou všechny trvalé vlastnosti. Pokud ve filtrech použijete vypočítané vlastnosti, doporučujeme přidat všechny relevantní jednoúčelové nebo složené indexy.

Tady je příklad definice vypočítané vlastnosti pro výpočet 20procentní slevy za cenu:

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

Tuto vlastnost je pak možné filtrovat, aby se zajistilo, že se vrátí pouze produkty, ve kterých by byla sleva nižší než 50 USD:

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

Klauzule GROUP BY

Stejně jako u trvalých vlastností lze vypočítané vlastnosti odkazovat v klauzuli GROUP BY a kdykoli je to možné, index použít. Pokud chcete dosáhnout nejlepšího výkonu, přidejte všechny relevantní jednoúčelové nebo složené indexy.

Tady je příklad definice vypočítané vlastnosti, která najde primární kategorii pro každou položku z categoryName vlastnosti:

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

Potom můžete seskupit podle cp_primaryCategory , abyste získali počet položek v každé primární kategorii:

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

Tip

I když můžete tento dotaz dosáhnout i bez použití vypočítaných vlastností, použití vypočítaných vlastností výrazně zjednodušuje zápis dotazu a umožňuje zvýšit výkon, protože cp_primaryCategory lze indexovat. SubSTRING () i INDEX_OF() vyžadují úplnou kontrolu všech položek v kontejneru, ale pokud indexujete vypočítanou vlastnost, můžete místo toho celý dotaz obsluhovat z indexu. Možnost obsluhovat dotaz z indexu místo toho, abyste se museli spoléhat na úplné prohledávání, zvyšuje výkon a snižuje náklady na jednotku žádostí o dotazy (RU).

Klauzule ORDER BY

Stejně jako u trvalých vlastností lze na vypočítané vlastnosti odkazovat v klauzuli ORDER BY a musí být indexovány, aby byl dotaz úspěšný. Pomocí vypočítaných vlastností můžete order BY výsledek složitých logických nebo systémových funkcí, který otevírá mnoho nových scénářů dotazů při použití služby Azure Cosmos DB.

Tady je příklad definice vypočítané vlastnosti, která získá měsíc z _ts hodnoty:

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

Než budete moct ORDER BY cp_monthUpdated, musíte ho přidat do zásad indexování. Po aktualizaci zásad indexování můžete řadit podle vypočítané vlastnosti.

SELECT
    *
FROM
    c
ORDER BY
    c.cp_monthUpdated

Vypočítané vlastnosti indexu

Vypočítané vlastnosti se ve výchozím nastavení neindexují a nezabývá se cestami se zástupnými čáry v zásadách indexování. U počítaných vlastností v zásadách indexování můžete přidat jednoduché nebo složené indexy stejným způsobem, jakým byste přidali indexy u trvalých vlastností. Ke všem vypočítaným vlastnostem doporučujeme přidat relevantní indexy. Tyto indexy doporučujeme, protože jsou užitečné při zvýšení výkonu a snížení počtu RU při indexování. Při indexování vypočítaných vlastností se skutečné hodnoty vyhodnocují během operací zápisu položek, aby se vygenerovaly a zachovaly termíny indexu.

Při indexování vypočítaných vlastností je potřeba vzít v úvahu několik aspektů, mezi které patří:

Vypočítané vlastnosti lze zadat v zahrnutých cestách, vyloučených cestách a složených cestách indexu.
Vypočítané vlastnosti nemohou mít definovaný prostorový index.
Cesty se zástupnými znaky ve vypočítané cestě vlastnosti fungují stejně jako u běžných vlastností.
Pokud odebíráte vypočítanou vlastnost, která byla indexována, musí být také odstraněny všechny indexy této vlastnosti.

Poznámka:

Všechny vypočítané vlastnosti jsou definovány na nejvyšší úrovni položky. Cesta je vždy /<computed property name>.

Tip

Poznámka:

Při změně definice indexované vypočítané vlastnosti se automaticky nepřeindexuje. Pokud chcete indexovat upravenou vypočítanou vlastnost, musíte nejprve z indexu vynechat vypočítanou vlastnost. Po dokončení přeindexování přidejte vypočítanou vlastnost zpět do zásad indexu.

Pokud chcete odstranit počítanou vlastnost, musíte ji nejprve odebrat ze zásad indexu.

Přidání jednoho indexu pro vypočítané vlastnosti

Přidání jednoho indexu pro vypočítanou vlastnost s názvem cp_myComputedProperty:

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

Přidání složeného indexu pro vypočítané vlastnosti

Chcete-li přidat složený index pro dvě vlastnosti, ve kterých se jeden vypočítá jako cp_myComputedPropertya druhý se zachová jako myPersistedProperty:

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

Vysvětlení spotřeby jednotek žádosti

Přidání vypočítaných vlastností do kontejneru nevyužívají jednotky RU. Operace zápisu do kontejnerů, které mají definované vypočítané vlastnosti, můžou mít mírné zvýšení RU. Pokud je vypočítaná vlastnost indexována, jednotky RU při operacích zápisu se zvýší, aby odrážely náklady na indexování a vyhodnocení vypočítané vlastnosti.

Sdílet prostřednictvím

Vypočítané vlastnosti ve službě Azure Cosmos DB for NoSQL

Co je vypočítaná vlastnost?

Omezení názvů

Omezení dotazů

Vytvoření vypočítaných vlastností

Vytvoření vypočítaných vlastností pomocí sady SDK

Použití vypočítaných vlastností v dotazech

Projekce

Klauzule WHERE

Klauzule GROUP BY

Klauzule ORDER BY

Vypočítané vlastnosti indexu

Přidání jednoho indexu pro vypočítané vlastnosti

Přidání složeného indexu pro vypočítané vlastnosti

Vysvětlení spotřeby jednotek žádosti

Váš názor

Váš názor

Další materiály

Sdílet prostřednictvím

Vypočítané vlastnosti ve službě Azure Cosmos DB for NoSQL

Co je vypočítaná vlastnost?

Omezení názvů

Omezení dotazů

Vytvoření vypočítaných vlastností

Vytvoření vypočítaných vlastností pomocí sady SDK

Použití vypočítaných vlastností v dotazech

Projekce

Klauzule WHERE

Klauzule GROUP BY

Klauzule ORDER BY

Vypočítané vlastnosti indexu

Přidání jednoho indexu pro vypočítané vlastnosti

Přidání složeného indexu pro vypočítané vlastnosti

Vysvětlení spotřeby jednotek žádosti

Související obsah

Váš názor

Váš názor

Další materiály