Számított tulajdonságok az Azure Cosmos DB for NoSQL-ben

A KÖVETKEZŐRE VONATKOZIK: NoSQL

Az Azure Cosmos DB-ben kiszámított tulajdonságok olyan értékekkel rendelkeznek, amelyek a meglévő elemtulajdonságokból származnak, de a tulajdonságok magukban az elemekben nem maradnak meg. A számított tulajdonságok hatóköre egyetlen elemre terjed ki, és a lekérdezésekben úgy hivatkozhat rájuk, mintha megőrizték volna a tulajdonságokat. A számított tulajdonságok megkönnyítik az összetett lekérdezési logika egyszer történő írását, és sokszor hivatkoznak rá. Hozzáadhat egyetlen indexet ezekhez a tulajdonságokhoz, vagy használhatja őket összetett index részeként a nagyobb teljesítmény érdekében.

Mi az a számított tulajdonság?

A számított tulajdonságoknak az elem legfelső szintjén kell lenniük, és nem lehetnek beágyazott elérési útjuk. Minden számított tulajdonságdefiníció két összetevőből áll: egy névből és egy lekérdezésből. A név a kiszámított tulajdonság neve, a lekérdezés pedig logikát definiál az egyes elemek tulajdonságértékének kiszámításához. A számított tulajdonságok hatóköre egy adott elemre terjed ki, ezért nem használhat több elem értékeit, és nem támaszkodhat más számított tulajdonságokra. Minden tároló legfeljebb 20 számított tulajdonsággal rendelkezhet.

Példa számított tulajdonságdefinícióra:

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

Névkorlátozások

Határozottan javasoljuk, hogy nevezze el a számított tulajdonságokat, hogy ne ütközjön a megmaradó tulajdonságnévvel. Az átfedésben lévő tulajdonságnevek elkerülése érdekében előtagot vagy utótagot adhat hozzá az összes számított tulajdonságnévhez. Ez a cikk az előtagot cp_ használja az összes névdefinícióban.

A számított tulajdonságnevekre vonatkozó korlátozások a következők:

• Minden számított tulajdonságnak egyedi névvel kell rendelkeznie.
• A tulajdonság értéke a name számított tulajdonságra való hivatkozáshoz használható legfelső szintű tulajdonságnevet jelöli.
• A fenntartott rendszertulajdonságok nevei, például ida , _ridés _ts nem használhatók számított tulajdonságnevekként.
• A számított tulajdonságnév nem egyezik meg egy már indexelt tulajdonság elérési útjának nevével. Ez a korlátozás az összes megadott indexelési útvonalra vonatkozik, beleértve a következőket:
  • Belefoglalt elérési utak
  • Kizárt elérési utak
  • Térbeli indexek
  • Összetett indexek

Lekérdezési korlátozások

A számított tulajdonságdefiníció lekérdezéseinek szintaktikailag és szemantikailag is érvényesnek kell lenniük, ellenkező esetben a létrehozási vagy frissítési művelet meghiúsul. A lekérdezések egy tároló összes elemének determinisztikus értékére kell kiértékelni. Egyes elemek esetében a lekérdezések kiértékelése nem definiált vagy null értékű, a nem definiált vagy null értékekkel rendelkező számított tulajdonságok pedig ugyanúgy viselkednek, mint a nem definiált vagy null értékekkel rendelkező, lekérdezésekben használt tartós tulajdonságok.

A számított tulajdonság lekérdezés-definícióinak korlátozásai a következők:

• A lekérdezésnek meg kell adnia egy FROM záradékot, amely a gyökérelem-hivatkozást jelöli. A támogatott FROM záradékok például a következők: FROM c, FROM root cés FROM MyContainer c.
• A lekérdezésnek érték záradékot kell használnia a kivetítésben.
• A lekérdezések nem tartalmazhatnak JOIN-t.
• A lekérdezések nem használhatnak nemdeterminista skaláris kifejezéseket. A nemdeterminisztikus skaláris kifejezések például a következők: GetCurrentDateTime, GetCurrentTimeStamp, GetCurrentTicks és RAND.
• A lekérdezések a következő záradékok egyikét sem használhatják: WHERE, GROUP BY, ORDER BY, TOP, DISTINCT, OFFSET LIMIT, EXISTS, ALL, LAST, FIRST és NONE.
• A lekérdezések nem tartalmazhatnak skaláris részqueryt.
• Az összesítő függvények, a térbeli függvények, a nemdeterminisztikus függvények és a felhasználó által definiált függvények (UDF-ek) nem támogatottak.

Számított tulajdonságok létrehozása

A számított tulajdonságok létrehozása után bármilyen módszerrel végrehajthat olyan lekérdezéseket, amelyek hivatkoznak a tulajdonságokra, beleértve az összes szoftverfejlesztői készletet (SDK-t) és az Azure Data Explorert az Azure Portalon.

Számított tulajdonságok létrehozása az SDK használatával

Létrehozhat egy új tárolót, amely definiált számítási tulajdonságokkal rendelkezik, vagy hozzáadhat számított tulajdonságokat egy meglévő tárolóhoz.

Íme egy példa arra, hogyan hozhat létre számított tulajdonságokat egy új tárolóban:

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

 const { resource: contDefinition } = await containerWithComputedProperty.read();
  const upperName = {
    name: "upperLastName",
    query:
      "SELECT VALUE UPPER(IS_DEFINED(c.lastName) ? c.lastName : c.parents[0].familyName) FROM c",
  };
  if (contDefinition) {
    // update computed properties
    contDefinition.computedProperties = [upperName];
    // replace container definition with updated computed properties
    await containerWithComputedProperty.replace(contDefinition);
    console.log("Computed properties updated");
  } else {
    console.log("Container definition is undefined.");
  }

const lowerName = {
    name: "lowerLastName",
    query:
      "SELECT VALUE LOWER(IS_DEFINED(c.lastName) ? c.lastName : c.parents[0].familyName) FROM c",
};

const { container: containerWithComputedProperty } = await database.containers.createIfNotExists({
  id: containerId,
  computedProperties: [lowerName],
});

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)

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

Íme egy példa arra, hogyan frissítheti a számított tulajdonságokat egy meglévő tárolón:

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

const { resource: contDefinition } = await containerWithComputedProperty.read();
const upperName = {
name: "upperLastName", query: "SELECT VALUE UPPER(IS_DEFINED(c.lastName) ? c.lastName : c.parents[0].familyName) FROM c",
};
if (contDefinition) {
// update computed properties contDefinition.computedProperties = [upperName]; // replace container definition with updated computed properties await containerWithComputedProperty.replace(contDefinition); console.log("Computed properties updated");
} else {
console.log("Container definition is undefined.");
}

Számított tulajdonságok létrehozása az Adatkezelővel

Az Adatkezelővel létrehozhat egy számítási tulajdonságot egy tárolóhoz.

1. Nyissa meg a meglévő tárolót az Adatkezelőben.

2. Lépjen a tároló Beállítások szakaszára. Ezután keresse meg a *Számított tulajdonságok alszakaszt.

3. Szerkessze a tároló számított tulajdonságdefiníciójának JSON-definícióját. Ebben a példában ez a JSON egy számított tulajdonság meghatározására szolgál, amely felosztja egy SKU kereskedelmi termék sztringét a - határoló használatával.

   [
     {
       "name": "cp_splitSku",
       "query": "SELECT VALUE StringSplit(p.sku, \"-\") FROM products p"
     }
   ]
   

   

4. Mentse a számított tulajdonságot.

Számított tulajdonságok használata lekérdezésekben

A számított tulajdonságok ugyanúgy hivatkozhatók a lekérdezésekben, mint a tartós tulajdonságokra. Az indexeletlen számított tulajdonságok értékeit futásidőben értékeli ki a rendszer a számított tulajdonságdefiníció használatával. Ha egy számított tulajdonság indexelve van, a rendszer ugyanúgy használja az indexet, mint a tartós tulajdonságok esetében, és a számított tulajdonság kiértékelése igény szerint történik. Javasoljuk, hogy a legjobb költség és teljesítmény érdekében adjon hozzá indexeket a számított tulajdonságokhoz .

Az alábbi példák az Azure Portal Adatkezelőjében elérhető gyorsútmutató termékadatkészletet használják. Első lépésként válassza a Gyorsindítás indítása lehetőséget, és töltse be az adathalmazt egy új tárolóba.

Íme egy példa egy elemre:

{
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "categoryId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
  "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": "cccccccc-2222-3333-4444-dddddddddddd",
      "name": "Tag-61"
    }
  ],
  "_rid": "n7AmAPTJ480GAAAAAAAAAA==",
  "_self": "dbs/n7AmAA==/colls/n7AmAPTJ480=/docs/n7AmAPTJ480GAAAAAAAAAA==/",
  "_etag": "\"01002683-0000-0800-0000-6451fb4b0000\"",
  "_attachments": "attachments/",
  "_ts": 1683094347
}

Vetület

Ha a számított tulajdonságokat előre kell vetíteni, explicit módon kell hivatkozni rájuk. Az olyan helyettesítő karakterek, mint az SELECT * összes megmaradó tulajdonság visszaadása, de nem tartalmazzák a számított tulajdonságokat.

Íme egy példa számított tulajdonságdefinícióra a name tulajdonság kisbetűssé alakításához:

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

Ez a tulajdonság ezután kivetíthető egy lekérdezésben:

SELECT 
    c.cp_lowerName 
FROM 
    c

WHERE záradék

A kiszámított tulajdonságokra a szűrő predikátumaiban hivatkozhat, mint minden megőrzött tulajdonságra. Javasoljuk, hogy minden releváns egy- vagy összetett indexet vegyen fel, ha számított tulajdonságokat használ szűrőkben.

Íme egy példa a 20 százalékos árengedmény kiszámításához kiszámított számított tulajdonságdefinícióra:

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

Ezt a tulajdonságot ezután szűrni lehet, hogy csak azok a termékek legyenek visszaadva, amelyeknél a kedvezmény 50 usd-nél kisebb lenne:

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

GROUP BY záradék

A megmaradó tulajdonságokhoz hasonlóan a számított tulajdonságokra is hivatkozhat a GROUP BY záradékban, és lehetőség szerint használhatja az indexet. A legjobb teljesítmény érdekében adjon hozzá minden releváns önálló vagy összetett indexet.

Íme egy példa számított tulajdonságdefinícióra, amely megkeresi a tulajdonság egyes elemeinek elsődleges kategóriáját categoryName :

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

Ezután csoportosítással cp_primaryCategory lekérheti az egyes elsődleges kategóriák elemeinek számát:

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

ORDER BY záradék

A megmaradó tulajdonságokhoz hasonlóan a számított tulajdonságokra is hivatkozni lehet az ORDER BY záradékban, és indexelni kell őket a lekérdezés sikerességéhez. A kiszámított tulajdonságok használatával összetett logikai vagy rendszerfüggvények alapján rendelhet, amelyek számos új lekérdezési forgatókönyvet nyitnak meg az Azure Cosmos DB használatakor.

Íme egy példa számított tulajdonságdefinícióra, amely kiolvasja a hónapot az _ts értékből:

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

A ORDER BY cp_monthUpdatedparancshoz hozzá kell adnia az indexelési szabályzathoz. Az indexelési szabályzat frissítése után a számított tulajdonság alapján rendelhet.

SELECT
    *
FROM
    c
ORDER BY
    c.cp_monthUpdated

Számított tulajdonságok indexelése

A számított tulajdonságok alapértelmezés szerint nem indexelhetők, és nem fedik le az indexelési szabályzat helyettesítő elérési útjai. Az indexelési szabályzatban a számított tulajdonságokhoz ugyanúgy adhat hozzá önálló vagy összetett indexeket, mint a tartós tulajdonságok indexeit. Javasoljuk, hogy minden számított tulajdonsághoz adjon hozzá releváns indexeket. Ezeket az indexeket azért javasoljuk, mert előnyösek a teljesítmény növelésében és a kérelemegységek (RU-k) csökkentésében. A számított tulajdonságok indexelésekor a rendszer az elemírási műveletek során kiértékeli a tényleges értékeket az indexkifejezések létrehozásához és megőrzéséhez.

A számított tulajdonságok indexelésének néhány szempontja van, például:

• A számított tulajdonságok megadhatóak a belefoglalt elérési utakban, a kizárt elérési utakban és az összetett index elérési útjaiban
• A számított tulajdonságok nem definiálhatnak térbeli indexet rajtuk
• A számított tulajdonság elérési útja alatti helyettesítő karakterek úgy működnek, mint a normál tulajdonságok esetében.
• Az eltávolított és indexelt tulajdonság kapcsolódó indexeit is el kell távolítani

Egyetlen index hozzáadása a számított tulajdonságokhoz

Egyetlen index hozzáadása a következő nevű cp_myComputedPropertyszámított tulajdonsághoz:

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

Összetett index hozzáadása számított tulajdonságokhoz

Összetett index két tulajdonsághoz való hozzáadásához az egyiket a következőképpen számítja ki cp_myComputedProperty, a másik pedig a következő módon myPersistedPropertymarad meg:

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

A kérelemegység-használat ismertetése

A számított tulajdonságok tárolóhoz való hozzáadása nem használ kérelemegységeket. A definiált számítási tulajdonságokkal rendelkező tárolók írási műveletei enyhe ru-növekedéssel járhatnak. Ha egy számított tulajdonság indexelt, az írási műveletek kérelemegységei növekednek, hogy tükrözzék a számított tulajdonság indexelési és kiértékelési költségeit.

Kapcsolódó tartalom

• Indexelési szabályzatok kezelése
• Dokumentumadatok modellezése