Properti komputasi di Azure Cosmos DB untuk NoSQL

BERLAKU UNTUK: NoSQL

Properti komputasi di Azure Cosmos DB memiliki nilai yang berasal dari properti item yang ada, tetapi properti tidak bertahan dalam item itu sendiri. Properti komputasi dilingkup ke satu item dan dapat direferensikan dalam kueri seolah-olah properti tersebut tetap ada. Properti komputasi mempermudah penulisan logika kueri yang kompleks sekali dan mereferensikannya berkali-kali. Anda dapat menambahkan satu indeks pada properti ini atau menggunakannya sebagai bagian dari indeks komposit untuk meningkatkan performa.

Apa itu properti komputasi?

Properti komputasi harus berada di tingkat atas dalam item dan tidak dapat memiliki jalur berlapis. Setiap definisi properti komputasi memiliki dua komponen: nama dan kueri. Nama adalah nama properti komputasi, dan kueri menentukan logika untuk menghitung nilai properti untuk setiap item. Properti komputasi dicakup ke item individual dan oleh karena itu tidak dapat menggunakan nilai dari beberapa item atau mengandalkan properti komputasi lainnya. Setiap kontainer dapat memiliki maksimum 20 properti komputasi.

Contoh definisi properti komputasi:

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

Batasan nama

Kami sangat menyarankan agar Anda memberi nama properti komputasi sehingga tidak ada tabrakan dengan nama properti yang bertahan. Untuk menghindari nama properti yang tumpang tindih, Anda dapat menambahkan awalan atau akhiran ke semua nama properti komputasi. Artikel ini menggunakan awalan cp_ dalam semua definisi nama.

Batasan pada nama properti komputasi adalah:

• Semua properti komputasi harus memiliki nama yang unik.
• Nilai name properti mewakili nama properti tingkat atas yang dapat digunakan untuk mereferensikan properti komputasi.
• Nama properti sistem yang dicadangkan seperti id, _rid, dan _ts tidak dapat digunakan sebagai nama properti komputasi.
• Nama properti komputasi tidak dapat cocok dengan jalur properti yang sudah diindeks. Batasan ini berlaku untuk semua jalur pengindeksan yang ditentukan, termasuk:
  • Jalur yang disertakan
  • Jalur yang dikecualikan
  • Indeks spasial
  • Indeks komposit

Batasan kueri

Kueri dalam definisi properti komputasi harus valid secara sintis dan semantik, jika tidak, operasi buat atau perbarui gagal. Kueri harus mengevaluasi ke nilai deterministik untuk semua item dalam kontainer. Kueri mungkin mengevaluasi ke tidak terdefinisi atau null untuk beberapa item, dan properti komputasi dengan nilai yang tidak terdefinisi atau null berperilaku sama seperti properti yang bertahan dengan nilai tidak terdefinisi atau null saat digunakan dalam kueri.

Batasan definisi kueri properti komputasi adalah:

• Kueri harus menentukan klausa FROM yang mewakili referensi item akar. Contoh klausul FROM yang didukung adalah: FROM c, , FROM root cdan FROM MyContainer c.
• Kueri harus menggunakan klausa VALUE dalam proyeksi.
• Kueri tidak dapat menyertakan JOIN.
• Kueri tidak dapat menggunakan ekspresi Skalar nondeterministik. Contoh ekspresi skalar nondeterministik adalah: GetCurrentDateTime, GetCurrentTimeStamp, GetCurrentTicks, dan RAND.
• Kueri tidak dapat menggunakan salah satu klausul berikut: WHERE, GROUP BY, ORDER BY, TOP, DISTINCT, OFFSET LIMIT, EXISTS, ALL, LAST, FIRST, dan NONE.
• Kueri tidak dapat menyertakan subkueri skalar.
• Fungsi agregat, fungsi spasial, fungsi nondeterministik, dan fungsi yang ditentukan pengguna (UDF) tidak didukung.

Membuat properti komputasi

Setelah properti komputasi dibuat, Anda dapat menjalankan kueri yang mereferensikan properti dengan menggunakan metode apa pun, termasuk semua kit pengembangan perangkat lunak (SDK) dan Azure Data Explorer di portal Azure.

Membuat properti komputasi dengan menggunakan SDK

Anda dapat membuat kontainer baru yang memiliki properti komputasi yang ditentukan, atau Anda dapat menambahkan properti komputasi ke kontainer yang sudah ada.

Berikut adalah contoh cara membuat properti komputasi dalam kontainer baru:

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

Berikut adalah contoh cara memperbarui properti komputasi pada kontainer yang sudah ada:

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

Membuat properti komputasi dengan menggunakan Data Explorer

Anda dapat menggunakan Data Explorer untuk membuat properti komputasi untuk kontainer.

1. Buka kontainer yang sudah ada di Data Explorer.

2. Navigasi ke bagian Pengaturan untuk kontainer Anda. Kemudian, navigasikan ke sub bagian *Properti Komputasi.

3. Edit definisi properti komputasi JSON untuk kontainer Anda. Dalam contoh ini, JSON ini digunakan untuk menentukan properti komputasi untuk membagi SKU string untuk produk ritel menggunakan pemisah - .

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

   

4. Simpan properti komputasi.

Menggunakan properti komputasi dalam kueri

Properti komputasi dapat direferensikan dalam kueri dengan cara yang sama seperti properti yang bertahan direferensikan. Nilai untuk properti komputasi yang tidak diindeks dievaluasi selama runtime dengan menggunakan definisi properti komputasi. Jika properti komputasi diindeks, indeks digunakan dengan cara yang sama seperti yang digunakan untuk properti yang dipertahankan, dan properti komputasi dievaluasi sesuai kebutuhan. Kami menyarankan agar Anda menambahkan indeks pada properti komputasi Anda untuk biaya dan performa terbaik.

Contoh berikut menggunakan himpunan data produk mulai cepat yang tersedia di Data Explorer di portal Azure. Untuk memulai, pilih Luncurkan mulai cepat dan muat himpunan data di kontainer baru.

Berikut adalah contoh item:

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

Proyeksi

Jika properti komputasi perlu diproyeksikan, properti tersebut harus direferensikan secara eksplisit. Proyeksi kartubebas seperti SELECT * mengembalikan semua properti yang bertahan, tetapi tidak menyertakan properti komputasi.

Berikut adalah contoh definisi properti komputasi untuk mengonversi properti menjadi name huruf kecil:

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

Properti ini kemudian dapat diproyeksikan dalam kueri:

SELECT 
    c.cp_lowerName 
FROM 
    c

Klausul WHERE

Properti komputasi dapat direferensikan dalam predikat filter seperti properti yang bertahan. Kami menyarankan agar Anda menambahkan indeks tunggal atau komposit yang relevan saat Anda menggunakan properti komputasi dalam filter.

Berikut adalah contoh definisi properti komputasi untuk menghitung diskon harga 20 persen:

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

Properti ini kemudian dapat difilter untuk memastikan bahwa hanya produk di mana diskon akan kurang dari $50 yang dikembalikan:

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

klausa GROUP BY

Seperti halnya properti yang bertahan, properti komputasi dapat direferensikan dalam klausul GROUP BY dan menggunakan indeks jika memungkinkan. Untuk performa terbaik, tambahkan indeks tunggal atau komposit yang relevan.

Berikut adalah contoh definisi properti komputasi yang menemukan kategori utama untuk setiap item dari categoryName properti:

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

Anda kemudian dapat mengelompokkan menurut cp_primaryCategory untuk mendapatkan jumlah item di setiap kategori utama:

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

Klausul ORDER BY

Seperti halnya properti yang bertahan, properti komputasi dapat direferensikan dalam klausa ORDER BY, dan properti tersebut harus diindeks agar kueri berhasil. Dengan menggunakan properti komputasi, Anda dapat MEMESAN BERDASARKAN hasil fungsi logika atau sistem yang kompleks, yang membuka banyak skenario kueri baru saat Anda menggunakan Azure Cosmos DB.

Berikut adalah contoh definisi properti komputasi yang mendapatkan bulan dari _ts nilai:

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

Sebelum anda dapat ORDER BY cp_monthUpdated, Anda harus menambahkannya ke kebijakan pengindeksan Anda. Setelah kebijakan pengindeksan diperbarui, Anda dapat memesan berdasarkan properti komputasi.

SELECT
    *
FROM
    c
ORDER BY
    c.cp_monthUpdated

Mengindeks properti komputasi

Properti komputasi tidak diindeks secara default dan tidak tercakup oleh jalur kartubebas dalam kebijakan pengindeksan. Anda dapat menambahkan indeks tunggal atau komposit pada properti komputasi dalam kebijakan pengindeksan dengan cara yang sama seperti Anda akan menambahkan indeks pada properti yang dipertahankan. Kami menyarankan agar Anda menambahkan indeks yang relevan ke semua properti komputasi. Kami merekomendasikan indeks ini karena bermanfaat dalam meningkatkan performa dan mengurangi unit permintaan (RU). Ketika properti komputasi diindeks, nilai aktual dievaluasi selama operasi penulisan item untuk menghasilkan dan mempertahankan istilah indeks.

Ada beberapa pertimbangan untuk mengindeks properti komputasi, termasuk:

• Properti komputasi dapat ditentukan dalam jalur yang disertakan, jalur yang dikecualikan, dan jalur indeks komposit
• Properti komputasi tidak dapat memiliki indeks spasial yang ditentukan pada properti tersebut
• Jalur kartubebas di bawah pekerjaan jalur properti komputasi seperti yang mereka lakukan untuk properti reguler
• Indeks terkait pada properti yang dihapus dan diindeks juga harus dihilangkan

Menambahkan indeks tunggal untuk properti komputasi

Untuk menambahkan indeks tunggal untuk properti komputasi bernama cp_myComputedProperty:

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

Menambahkan indeks komposit untuk properti komputasi

Untuk menambahkan indeks komposit pada dua properti di mana, satu dihitung sebagai cp_myComputedProperty, dan yang lainnya dipertahankan sebagai myPersistedProperty:

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

Memahami konsumsi unit permintaan

Menambahkan properti komputasi ke kontainer tidak menggunakan RU. Operasi tulis pada kontainer yang memiliki properti komputasi yang ditentukan mungkin memiliki sedikit peningkatan RU. Jika properti komputasi diindeks, RU pada operasi tulis meningkat untuk mencerminkan biaya untuk pengindeksan dan evaluasi properti komputasi.

Konten terkait

• Mengelola kebijakan pengindeksan
• Data dokumen model