Feature-gating Patch as GA preparation

sdk/cosmos/azure_data_cosmos/CHANGELOG.md

@@ -25,6 +25,7 @@
 
 ### Breaking Changes
 
+- `ContainerClient::patch_item()` and `PatchItemOptions` are now gated behind the new, non-default `preview_patch` feature. PATCH is not exactly-once under transport failures: an interrupted patch may re-apply non-idempotent operations (`increment`, `add` on an array, `move`), so it is no longer part of the supported default surface. Enable `preview_patch` to keep using it, and prefer idempotent operations (`set` on a caller-computed value) until the guarantee is fixed. ([#5133](https://github.com/Azure/azure-sdk-for-rust/pull/5133))
 - `CosmosClient::database_client` and `DatabaseClient::container_client` now take `impl Into<ResourceIdentity>` instead of `&str`; call sites passing a deref-able string (for example a `Cow<str>` field) need `&*value` or `.as_ref()`. ([#4687](https://github.com/Azure/azure-sdk-for-rust/pull/4687))
 - `DatabaseClient::id()` now returns `&ResourceIdentity` instead of `&str`. ([#4687](https://github.com/Azure/azure-sdk-for-rust/pull/4687))
 - Control-plane APIs are now gated behind the new `control_plane` feature, which is **not** enabled by default. Code using database or container management (`CosmosClient::create_database`/`query_databases`, `DatabaseClient::read`/`create_container`/`query_containers`/`delete`, `ContainerClient::replace`/`delete`), throughput management (`read_throughput`/`begin_replace_throughput`, `ThroughputPoller`), or the associated model and options types (`DatabaseProperties`, `ThroughputProperties`, and the container create/replace/delete/query, database, and throughput option types) must now enable the `control_plane` feature. Reading container properties via `ContainerClient::read()` — along with `ContainerProperties`, `IndexingPolicy`, `ResourceResponse`, and `ReadContainerOptions` — remains available without the feature, since it works with Entra ID authentication and mirrors the metadata read the SDK already performs internally. ([#4854](https://github.com/Azure/azure-sdk-for-rust/pull/4854))

sdk/cosmos/azure_data_cosmos/Cargo.toml

@@ -106,6 +106,7 @@ metrics = [
 preview_dtx = [
   "azure_data_cosmos_driver/preview_dtx",
 ] # Enables preview Distributed Transaction APIs. Disabled by default and not production-ready.
+preview_patch = [] # Enables the preview PATCH API. Disabled by default and not production-ready: an interrupted patch may re-apply non-idempotent operations.
 __internal_in_memory_emulator = [
   "azure_data_cosmos_driver/__internal_in_memory_emulator",
   "key_auth",
@@ -123,6 +124,7 @@ features = [
   "key_auth",
   "metrics",
   "native_tls",
+  "preview_patch",
   "rustls",
 ]
 
@@ -172,3 +174,10 @@ required-features = ["__internal_in_memory_emulator"]
 name = "cosmos"
 path = "examples/cosmos/main.rs"
 required-features = ["control_plane"]
+
+# The PATCH example calls the preview `patch_item` API, which only exists
+# when `preview_patch` is enabled.
+[[example]]
+name = "cosmos_patch"
+path = "examples/cosmos_patch.rs"
+required-features = ["preview_patch"]

sdk/cosmos/azure_data_cosmos/README.md

@@ -107,7 +107,6 @@ container metadata read the SDK already performs internally.
 ```rust
 use serde::{Serialize, Deserialize};
 use azure_data_cosmos::CosmosClient;
-use azure_data_cosmos::models::{PatchInstructions, PatchOperation};
 
 #[derive(Serialize, Deserialize)]
 struct Item {
@@ -137,21 +136,39 @@ async fn example(cosmos_client: CosmosClient) -> Result<(), Box<dyn std::error::
     // Replace an item
     container.replace_item("partition1", "1", item, None).await?;
 
-    let patch = PatchInstructions::from(vec![
-        PatchOperation::set("/value", serde_json::json!("4")),
-    ]);
-    let patched: Item = container
-        .patch_item("partition1", "1", patch, None)
-        .await?
-        .into_model()?;
-    println!("patched value = {}", patched.value);
-
     // Delete an item
     container.delete_item("partition1", "1", None).await?;
     Ok(())
 }
 ```
 
+### Partial updates with PATCH (preview)
+
+`ContainerClient::patch_item()` applies JSON-Patch-style operations to a single item. It is
+gated behind the `preview_patch` feature and is **not production-ready**:
+
+```sh
+cargo add azure_data_cosmos --features preview_patch
+```
+
+```rust,ignore
+use azure_data_cosmos::models::{PatchInstructions, PatchOperation};
+
+let patch = PatchInstructions::from(vec![
+    PatchOperation::set("/value", serde_json::json!("4")),
+]);
+let patched: Item = container
+    .patch_item("partition1", "1", patch, None)
+    .await?
+    .into_model()?;
+```
+
+PATCH is implemented client-side as a read, a local merge, and an ETag-guarded replace. If the
+replace is interrupted after the service commits it, the pipeline may retry it and the
+read-modify-write loop may re-apply the patch. Non-idempotent operations
+(`increment`, `add` on an array, `move`) can therefore be applied **more than once**. Use
+idempotent operations such as `set` with a caller-computed value until this limitation is fixed.
+
 ## Next steps
 
 * [Resource Model of Azure Cosmos DB Service](https://learn.microsoft.com/azure/cosmos-db/sql-api-resources)