NoSQL için Azure Cosmos DB'de hesaplanan özellikler

UYGULANANLAR: NoSQL

Azure Cosmos DB'deki hesaplanan özellikler, mevcut öğe özelliklerinden türetilen değerlere sahiptir, ancak özellikler öğelerde kalıcı değildir. Hesaplanan özellikler tek bir öğe kapsamındadır ve sorgularda kalıcı özelliklermiş gibi başvurulabilir. Hesaplanan özellikler, karmaşık sorgu mantığını bir kez yazmayı ve buna birçok kez başvurmayı kolaylaştırır. Bu özelliklere tek bir dizin ekleyebilir veya bunları daha yüksek performans için bileşik dizinin bir parçası olarak kullanabilirsiniz.

Hesaplanan özellik nedir?

Hesaplanan özellikler öğenin en üst düzeyinde olmalıdır ve iç içe yerleştirilmiş bir yola sahip olamaz. Hesaplanan her özellik tanımının iki bileşeni vardır: ad ve sorgu. Ad hesaplanan özellik adıdır ve sorgu her öğenin özellik değerini hesaplamak için mantığı tanımlar. Hesaplanan özelliklerin kapsamı tek bir öğeye göre belirlenmiştir ve bu nedenle birden çok öğedeki değerleri kullanamaz veya diğer hesaplanan özelliklere dayanamaz. Her kapsayıcı en fazla 20 hesaplanan özelliğe sahip olabilir.

Hesaplanan özellik tanımı örneği:

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

Ad kısıtlamaları

Kalıcı özellik adıyla çakışma olmaması için hesaplanan özellikleri adlandırmanızı kesinlikle öneririz. Çakışan özellik adlarını önlemek için, hesaplanan tüm özellik adlarına bir ön ek veya sonek ekleyebilirsiniz. Bu makalede, tüm ad tanımlarında ön ek cp_ kullanılır.

Hesaplanan özellik adlarında kısıtlamalar şunlardır:

• Tüm hesaplanan özelliklerin benzersiz adları olmalıdır.
• özelliğinin name değeri, hesaplanan özelliğe başvurmak için kullanılabilecek en üst düzey özellik adını temsil eder.
• , _ridve _ts gibi idayrılmış sistem özellik adları, hesaplanan özellik adları olarak kullanılamaz.
• Hesaplanan özellik adı, zaten dizine alınmış bir özellik yoluyla eşleşemez. Bu kısıtlama, aşağıdakiler dahil olmak üzere belirtilen tüm dizin oluşturma yolları için geçerlidir:
  • Eklenen yollar
  • Dışlanan yollar
  • Uzamsal dizinler
  • Bileşik dizinler

Sorgu kısıtlamaları

Hesaplanan özellik tanımındaki sorgular, sağlam ve tek biçimli olarak geçerli olmalıdır, aksi takdirde oluşturma veya güncelleştirme işlemi başarısız olur. Sorgular, kapsayıcıdaki tüm öğeler için belirleyici bir değer olarak değerlendirilmelidir. Sorgular bazı öğeler için tanımsız veya null olarak değerlendirebilir ve tanımsız veya null değerleri olan hesaplanan özellikler, sorgularda kullanıldığında tanımsız veya null değerlerle kalıcı özelliklerle aynı şekilde davranır.

Hesaplanan özellik sorgu tanımlarıyla ilgili sınırlamalar şunlardır:

• Sorgular, kök öğe başvurularını temsil eden bir FROM yan tümcesi belirtmelidir. Desteklenen FROM yan tümcelerine örnek olarak şunlar verilebilir: FROM c, FROM root c, ve FROM MyContainer c.
• Sorgular projeksiyonda bir VALUE yan tümcesi kullanmalıdır.
• Sorgular JOIN içeremez.
• Sorgular belirsiz Skaler ifadeleri kullanamaz. Belirsiz skaler ifadelere örnek olarak şunlar verilebilir: GetCurrentDateTime, GetCurrentTimeStamp, GetCurrentTicks ve RAND.
• Sorgular şu yan tümcelerden hiçbirini kullanamaz: WHERE, GROUP BY, ORDER BY, TOP, DISTINCT, OFFSET LIMIT, EXISTS, ALL, LAST, FIRST ve NONE.
• Sorgular skaler alt sorgu içeremez.
• Toplama işlevleri, uzamsal işlevler, belirsiz işlevler ve kullanıcı tanımlı işlevler (UDF) desteklenmez.

Hesaplanan özellikler oluşturma

Hesaplanan özellikler oluşturulduktan sonra, Azure portalındaki tüm yazılım geliştirme setleri (SDK' lar) ve Azure Veri Gezgini dahil olmak üzere herhangi bir yöntemi kullanarak özelliklere başvuran sorgular yürütebilirsiniz.

SDK kullanarak hesaplanan özellikler oluşturma

Hesaplanan özellikleri tanımlanmış yeni bir kapsayıcı oluşturabilir veya mevcut bir kapsayıcıya hesaplanan özellikler ekleyebilirsiniz.

Yeni bir kapsayıcıda hesaplanan özelliklerin nasıl oluşturulacağını gösteren bir örnek aşağıda verilmişti:

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

Burada, mevcut bir kapsayıcıda hesaplanan özellikleri güncelleştirme örneği verilmiştir:

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.");
}

Veri Gezgini kullanarak hesaplanan özellikler oluşturma

kapsayıcı için hesaplanan özellik oluşturmak üzere Veri Gezgini kullanabilirsiniz.

1. var olan kapsayıcınızı Veri Gezgini açın.

2. Kapsayıcınızın Ayarlar bölümüne gidin. Ardından *Hesaplanan Özellikler alt bölümüne gidin.

3. Kapsayıcınız için hesaplanan özellikler tanımı JSON'unu düzenleyin. Bu örnekte bu JSON, sınırlayıcıyı kullanarak - perakende ürünün dizesini SKU bölmek için hesaplanan bir özellik tanımlamak için kullanılır.

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

   

4. Hesaplanan özelliği kaydedin .

Sorgularda hesaplanan özellikleri kullanma

Hesaplanan özelliklere, kalıcı özelliklere başvurulduğundan aynı şekilde sorgularda başvurulabilir. Dizine alınmayacak hesaplanan özelliklerin değerleri, çalışma zamanı sırasında hesaplanan özellik tanımı kullanılarak değerlendirilir. Hesaplanan bir özellik dizine alınırsa, dizin kalıcı özellikler için kullanıldığı gibi kullanılır ve hesaplanan özellik gerektiği gibi değerlendirilir. En iyi maliyet ve performans için hesaplanan özelliklerinize dizinler eklemenizi öneririz.

Aşağıdaki örneklerde, Azure portalındaki Veri Gezgini bulunan hızlı başlangıç ürünleri veri kümesi kullanılır. Başlamak için Hızlı başlangıcı başlat'ı seçin ve veri kümesini yeni bir kapsayıcıya yükleyin.

Aşağıda bir öğe örneği verilmişti:

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

Yansıtma

Hesaplanan özelliklerin yansıtılması gerekiyorsa, bunlara açıkça başvurulmalıdır. Gibi SELECT * joker karakterler tüm kalıcı özellikleri döndürür, ancak hesaplanan özellikleri içermez.

Aşağıda, özelliği küçük harfe dönüştürmek name için hesaplanan özellik tanımı örneği verilmiştir:

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

Bu özellik bir sorguda yansıtılabilir:

SELECT 
    c.cp_lowerName 
FROM 
    c

WHERE yan tümcesi

Hesaplanan özelliklere, kalıcı özellikler gibi filtre koşullarında başvurulabilir. Filtrelerde hesaplanan özellikleri kullanırken ilgili tek veya bileşik dizinleri eklemenizi öneririz.

Yüzde 20 fiyat indirimi hesaplamak için hesaplanan özellik tanımı örneği aşağıda verilmiştir:

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

Bu özellik daha sonra yalnızca indirimin 50 TL'den az olacağı ürünlerin döndürülmesini sağlamak için filtrelenebilir:

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

GROUP BY yan tümcesi

Kalıcı özelliklerde olduğu gibi, hesaplanan özelliklere GROUP BY yan tümcesinde başvurabilir ve mümkün olduğunda dizini kullanabilirsiniz. En iyi performans için ilgili tek veya bileşik dizinleri ekleyin.

Aşağıda, özelliğinden her öğe için birincil kategoriyi bulan hesaplanan özellik tanımı örneği verilmiştir categoryName :

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

Ardından, her birincil kategorideki öğelerin sayısını almak için gruplandırabilirsiniz cp_primaryCategory :

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

ORDER BY yan tümcesi

Kalıcı özelliklerde olduğu gibi, hesaplanan özelliklere ORDER BY yan tümcesinde başvurulabilir ve sorgunun başarılı olması için bunlar dizine alınmalıdır. Hesaplanan özellikleri kullanarak, Karmaşık mantık veya sistem işlevlerinin sonucu olarak ORDER BY işlevini kullanabilirsiniz. Bu, Azure Cosmos DB'yi kullandığınızda birçok yeni sorgu senaryosu açar.

Aşağıda, ayı değerden alan hesaplanan özellik tanımı örneği _ts verilmiştir:

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

ORDER BY cp_monthUpdatedyapabilmeniz için önce dizin oluşturma ilkenize eklemeniz gerekir. Dizin oluşturma ilkeniz güncelleştirildikten sonra hesaplanan özelliğe göre sıralama yapabilirsiniz.

SELECT
    *
FROM
    c
ORDER BY
    c.cp_monthUpdated

Hesaplanan özellikleri dizine ekleme

Hesaplanan özellikler varsayılan olarak dizine kaydedilmez ve dizin oluşturma ilkesindeki joker karakter yolları kapsamında değildir. Dizin oluşturma ilkesindeki hesaplanan özelliklere tek veya bileşik dizinler, kalıcı özelliklerde dizinler eklediğiniz gibi ekleyebilirsiniz. Tüm hesaplanan özelliklere ilgili dizinler eklemenizi öneririz. Performansı artırma ve istek birimlerini (RU) azaltma açısından yararlı olduğundan bu dizinleri öneririz. Hesaplanan özellikler dizine eklendiğinde, dizin terimleri oluşturmak ve kalıcı hale getirmek için öğe yazma işlemleri sırasında gerçek değerler değerlendirilir.

Hesaplanan özelliklerin dizinini oluşturmak için dikkat edilmesi gereken birkaç nokta vardır:

• Hesaplanan özellikler dahil edilen yollarda, dışlanan yollarda ve bileşik dizin yollarında belirtilebilir
• Hesaplanan özelliklerde tanımlı uzamsal dizin olamaz
• Hesaplanan özellik yolunun altındaki joker karakterler normal özelliklerde olduğu gibi çalışır
• Kaldırılan ve dizine alınmış bir özellik üzerindeki ilgili dizinler de bırakılmalıdır

Hesaplanan özellikler için tek bir dizin ekleme

adlı cp_myComputedPropertyhesaplanan özelliğe tek bir dizin eklemek için:

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

Hesaplanan özellikler için bileşik dizin ekleme

biri olarak cp_myComputedPropertyhesaplandığı, diğeri ise olarak myPersistedPropertykalıcı olduğu iki özelliğe bileşik dizin eklemek için:

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

İstek birimi tüketimini anlama

Bir kapsayıcıya hesaplanan özellikler eklemek RU'ları kullanmaz. Tanımlanmış hesaplanan özelliklere sahip kapsayıcılardaki yazma işlemlerinde küçük bir RU artışı olabilir. Hesaplanan özellik dizine alınmışsa, yazma işlemlerindeki RU'lar, hesaplanan özelliğin dizin oluşturma ve değerlendirme maliyetlerini yansıtacak şekilde artar.

İlgili içerik

• Dizin oluşturma ilkelerini yönetme
• Belge verilerini modelleme