Operasi batch transaksional di Azure Cosmos DB

BERLAKU UNTUK: NoSQL

Batch transaksional menjelaskan sekelompok operasi titik yang perlu berhasil atau gagal bersama dengan kunci partisi yang sama dalam suatu kontainer. Operasi didefinisikan, ditambahkan ke batch, dan batch dijalankan. Jika semua operasi berhasil dalam urutan yang dijelaskan dalam operasi batch transaksional, transaksi akan dilakukan. Namun, jika ada operasi yang gagal, seluruh transaksi digulung balik.

Apa itu transaksi di Azure Cosmos DB

Transaksi dalam database biasa dapat didefinisikan sebagai urutan operasi yang dilakukan sebagai satu unit kerja logis. Setiap transaksi memberikan jaminan properti ACID (Atomicity, Consistency, Isolation, Durability).

• Atomicity (atomisitas) menjamin bahwa semua operasi yang dilakukan di dalam transaksi diperlakukan sebagai satu unit, dan semuanya diterapkan atau tidak sama sekali.
• Consistency (konsistensi) memastikan bahwa data selalu dalam keadaan valid di seluruh transaksi.
• Isolation (isolasi) menjamin bahwa tidak ada dua transaksi yang saling mengganggu; sejumlah sistem komersial menyediakan beberapa tingkat isolasi yang dapat digunakan berdasarkan kebutuhan aplikasi.
• Durability (durabilitas) memastikan agar setiap perubahan yang diterapkan dalam database akan selalu ada. Azure Cosmos DB mendukung transaksi lengkap yang mematuhi ACID dengan isolasi snapshot untuk operasi dalam kunci partisi logis yang sama.

Operasi batch transaksional dan prosedur tersimpan

Azure Cosmos DB saat ini mendukung prosedur tersimpan, yang juga menyediakan cakupan transaksional pada operasi. Namun, operasi batch transaksional menawarkan keuntungan berikut:

• Opsi bahasa - Batch transaksional didukung pada SDK dan bahasa yang sudah Anda fungsikan, sementara prosedur tersimpan perlu ditulis dalam JavaScript.
• Pembuatan versi kode - Pembuatan versi kode aplikasi dan orientasi ke alur CI/CD Anda jauh lebih alami dibandingkan pengaturan pembaruan prosedur tersimpan dan memastikan penerusan terjadi di waktu yang tepat. Ini juga membuat pembatalan berubah lebih mudah.
• Performa - Menurunkan latensi pada operasi yang setara hingga 30% jika dibandingkan dengan eksekusi prosedur tersimpan.
• Serialisasi konten – Setiap operasi dalam batch transaksional dapat menggunakan opsi serialisasi kustom untuk payloadnya.

Cara membuat operasi batch transaksional

.NET

Saat membuat operasi batch transaksional, mulailah dengan instans kontainer dan panggil CreateTransactionalBatch:

PartitionKey partitionKey = new PartitionKey("road-bikes");

TransactionalBatch batch = container.CreateTransactionalBatch(partitionKey);

Selanjutnya, tambahkan beberapa operasi ke batch:

Product bike = new (
    id: "68719520766",
    category: "road-bikes",
    name: "Chropen Road Bike"
);

batch.CreateItem<Product>(bike);

Part part = new (
    id: "68719519885",
    category: "road-bikes",
    name: "Tronosuros Tire",
    productId: bike.id
);

batch.CreateItem<Part>(part);

Terakhir, panggil ExecuteAsync pada batch:

using TransactionalBatchResponse response = await batch.ExecuteAsync();

Setelah respons diterima, periksa apakah respons berhasil. Jika respons menunjukkan sebuah keberhasilan, ekstrak hasilnya:

if (response.IsSuccessStatusCode)
{
    TransactionalBatchOperationResult<Product> productResponse;
    productResponse = response.GetOperationResultAtIndex<Product>(0);
    Product productResult = productResponse.Resource;

    TransactionalBatchOperationResult<Part> partResponse;
    partResponse = response.GetOperationResultAtIndex<Part>(1);
    Part partResult = partResponse.Resource;
}

Penting

Jika ada kegagalan, operasi yang gagal akan memiliki kode status kesalahan yang sesuai. Semua operasi lainnya akan memiliki kode status 424 (dependensi gagal). Jika operasi gagal karena mencoba membuat item yang sudah ada, kode status 409 (konflik) dikembalikan. Kode status memungkinkan seseorang untuk mengidentifikasi penyebab kegagalan transaksi.

Java

Saat membuat operasi batch transaksional, panggil CosmosBatch.createCosmosBatch:

PartitionKey partitionKey = new PartitionKey("road-bikes");

CosmosBatch batch = CosmosBatch.createCosmosBatch(partitionKey);

Selanjutnya, tambahkan beberapa operasi ke batch:

Product bike = new Product();
bike.setId("68719520766");
bike.setCategory("road-bikes");
bike.setName("Chropen Road Bike");

batch.createItemOperation(bike);

Part part = new Part();
part.setId("68719519885");
part.setCategory("road-bikes");
part.setName("Tronosuros Tire");
part.setProductId(bike.getId());

batch.createItemOperation(part);

Terakhir, gunakan instans kontainer untuk memanggil executeCosmosBatch dengan batch:

CosmosBatchResponse response = container.executeCosmosBatch(batch);

Setelah respons diterima, periksa apakah respons berhasil. Jika respons menunjukkan sebuah keberhasilan, ekstrak hasilnya:

if (response.isSuccessStatusCode())
{
    List<CosmosBatchOperationResult> results = response.getResults();
}

Penting

Jika ada kegagalan, operasi yang gagal akan memiliki kode status kesalahan yang sesuai. Semua operasi lainnya akan memiliki kode status 424 (dependensi gagal). Jika operasi gagal karena mencoba membuat item yang sudah ada, kode status 409 (konflik) dikembalikan. Kode status memungkinkan seseorang untuk mengidentifikasi penyebab kegagalan transaksi.

Python

Dapatkan atau buat instans kontainer:

container = database.create_container_if_not_exists(id="batch_container",
                                                        partition_key=PartitionKey(path='/road_bikes'))

Dalam Python, operasi Batch Transaksional terlihat sangat mirip dengan api operasi tunggal, dan merupakan tuple yang berisi (operation_type_string, args_tuple, batch_operation_kwargs_dictionary). Di bawah ini adalah item sampel yang akan digunakan untuk menunjukkan fungsionalitas operasi batch:

create_demo_item = {
    "id": "68719520766",
    "category": "road-bikes",
    "name": "Chropen Road Bike"
}

# for demo, assume that this item already exists in the container. 
# the item id will be used for read operation in the batch
read_demo_item1 = {
    "id": "68719519884",
    "category": "road-bikes",
    "name": "Tronosuros Tire",
    "productId": "68719520766"
}

# for demo, assume that this item already exists in the container. 
# the item id will be used for read operation in the batch
read_demo_item2 = {
    "id": "68719519886",
    "category": "road-bikes",
    "name": "Tronosuros Tire",
    "productId": "68719520766"
}

# for demo, assume that this item already exists in the container. 
# the item id will be used for read operation in the batch
read_demo_item3 = {
    "id": "68719519887",
    "category": "road-bikes",
    "name": "Tronosuros Tire",
    "productId": "68719520766"
}

# for demo, we'll upsert the item with id 68719519885
upsert_demo_item = {
    "id": "68719519885",
    "category": "road-bikes",
    "name": "Tronosuros Tire Upserted",
    "productId": "68719520768"
}

# for replace demo, we'll replace the read_demo_item2 with this item
replace_demo_item = {
    "id": "68719519886",
    "category": "road-bikes",
    "name": "Tronosuros Tire replaced",
    "productId": "68719520769"
}

# for replace with etag match demo, we'll replace the read_demo_item3 with this item
# The use of etags and if-match/if-none-match options allows users to run conditional replace operations
# based on the etag value passed. When using if-match, the request will only succeed if the item's latest etag
# matches the passed in value. For more on optimistic concurrency control, see the link below:
# https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency
replace_demo_item_if_match_operation = {
    "id": "68719519887",
    "category": "road-bikes",
    "name": "Tronosuros Tireh",
    "wasReplaced": "Replaced based on etag match"
    "productId": "68719520769"
}

Siapkan operasi yang akan ditambahkan ke batch:

create_item_operation = ("create", (create_demo_item,), {})
read_item_operation = ("read", ("68719519884",), {})
delete_item_operation = ("delete", ("68719519885",), {})
upsert_item_operation = ("upsert", (upsert_demo_item,), {})
replace_item_operation = ("replace", ("68719519886", replace_demo_item), {})
replace_item_if_match_operation = ("replace",
                                       ("68719519887", replace_demo_item_if_match_operation),
                                       {"if_match_etag": container.client_connection.last_response_headers.get("etag")})

Tambahkan operasi ke batch:

batch_operations = [
        create_item_operation,
        read_item_operation,
        delete_item_operation,
        upsert_item_operation,
        replace_item_operation,
        replace_item_if_match_operation
    ]

Terakhir, jalankan batch:

try:
    # Run that list of operations
    batch_results = container.execute_item_batch(batch_operations=batch_operations, partition_key="road_bikes")
    # Batch results are returned as a list of item operation results - or raise a CosmosBatchOperationError if
    # one of the operations failed within your batch request.
    print("\nResults for the batch operations: {}\n".format(batch_results))
except exceptions.CosmosBatchOperationError as e:
        error_operation_index = e.error_index
        error_operation_response = e.operation_responses[error_operation_index]
        error_operation = batch_operations[error_operation_index]
        print("\nError operation: {}, error operation response: {}\n".format(error_operation, error_operation_response))
    # [END handle_batch_error]

Catatan untuk menggunakan operasi patch dan operasi replace_if_match_etag dalam batch
Kamus kwargs operasi batch terbatas, dan hanya mengambil total tiga nilai kunci yang berbeda. Dalam kasus ingin menggunakan patching kondisional dalam batch, penggunaan kunci filter_predicate tersedia untuk operasi patch, atau jika ingin menggunakan etag dengan salah satu operasi, penggunaan kunci if_match_etag/if_none_match_etag juga tersedia.

batch_operations = [
       ("replace", (item_id, item_body), {"if_match_etag": etag}),
       ("patch", (item_id, operations), {"filter_predicate": filter_predicate, "if_none_match_etag": etag}),
   ]

Penting

Jika ada kegagalan, operasi yang gagal akan memiliki kode status kesalahan yang sesuai. Semua operasi lainnya akan memiliki kode status 424 (dependensi gagal). Jika operasi gagal karena mencoba membuat item yang sudah ada, kode status 409 (konflik) dikembalikan. Kode status memungkinkan seseorang untuk mengidentifikasi penyebab kegagalan transaksi.

Cara operasi batch transaksional dijalankan

Ketika Batch Transaksional dijalankan, semua operasi dalam Batch Transaksional dikelompokkan, diserialisasikan ke dalam satu payload, dan dikirim sebagai satu permintaan ke layanan Azure Cosmos DB.

Layanan ini menerima permintaan dan menjalankan semua operasi dalam cakupan transaksional, lalu mengembalikan respons menggunakan protokol serialisasi yang sama. Respons ini sukses, atau gagal, dan memasok respons operasi individual per operasi.

SDK memaparkan respons bagi Anda untuk memverifikasi hasilnya dan, secara opsional, mengekstrak setiap hasil operasi internal.

Batasan

Saat ini, ada dua batasan yang diketahui:

• Batas ukuran permintaan Azure Cosmos DB membatasi ukuran payload Batch Transaksional tidak melebihi 2 MB, dan waktu eksekusi maksimum adalah 5 detik.
• Ada batas saat ini sebesar 100 operasi per Batch Transaksi untuk memastikan performa seperti yang diharapkan dan dalam SLA.

Langkah berikutnya

• Pelajari selengkapnya tentang hal yang dapat Anda lakukan dengan TransactionalBatch

• Kunjungi sampel kami untuk cara lain menggunakan Azure Cosmos DB .NET SDK kami