cosmos: Add Query::with_text() and Query::append_text() methods (Azure#3045)

Adds methods to modify query text after creation, enabling more
ergonomic query building patterns when working with optional parameters.

## Problem

The `Query` type only allowed adding parameters via `with_parameter()`,
but the query text could not be changed once created. This made it
cumbersome to build queries with optional filters:

```rust
// Previous approach required recreating Query objects
if let Some(high) = high_time {
    query_text.push_str(&format!(" AND c.time <= @high_time"));
    query = Query::from(query_text.as_str());
    query = query.with_parameter("@high_time", high)?;
}
```

## Solution

Added two new methods following the same consumption pattern as
`with_parameter()`:

- `Query::with_text(String) -> Self` - Replaces the current query text
- `Query::append_text(&str) -> Self` - Appends text to the current query
text

Both methods preserve existing parameters and support method chaining:

```rust
// New ergonomic approach
if let Some(high) = high_time {
    query = query.append_text(" AND c.time <= @high_time")
        .with_parameter("@high_time", high)?;
}
```

## Changes

- Added `Query::with_text()` and `Query::append_text()` methods
- Added comprehensive unit tests covering functionality and method
chaining
- Updated documentation with usage examples
- Updated CHANGELOG.md

All existing functionality remains unchanged and fully backward
compatible.

<!-- START COPILOT CODING AGENT SUFFIX -->

----
**Additional instructions:**

> Make sure you structure your commits in a sensible way and include a
concise but descriptive PR description. PREFER concise descriptions and
code. The team knows how this code should work, they don't need
explanations of it. The code should be largely self-explanatory.

Fixes Azure#3044

<!-- START COPILOT CODING AGENT TIPS -->
---

💬 Share your feedback on Copilot coding agent for the chance to win a
$200 gift card! Click
[here](https://survey3.medallia.com/?EAHeSx-AP01bZqG0Ld9QLQ) to start
the survey.

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: analogrelay <[email protected]>

Author: Copilot

sdk/cosmos/azure_data_cosmos/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Features Added
 
+* Added `Query::with_text()` and `Query::append_text()` methods to modify query text after creation ([#3044](https://github.com/Azure/azure-sdk-for-rust/pull/3044))
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/cosmos/azure_data_cosmos/src/query/mod.rs

@@ -27,6 +27,21 @@ pub use engine::*;
 /// # assert_eq!(serde_json::to_string(&query).unwrap(), "{\"query\":\"SELECT * FROM c WHERE c.id = @customer_id\",\"parameters\":[{\"name\":\"@customer_id\",\"value\":42}]}");
 /// ```
 ///
+/// You can also modify the query text using [`Query::with_text()`] to replace it entirely
+/// or [`Query::append_text()`] to add to the existing text:
+///
+/// ```rust
+/// # use azure_data_cosmos::Query;
+/// let query = Query::from("SELECT * FROM c")
+///     .append_text(" WHERE c.time >= @low_time")
+///     .with_parameter("@low_time", "2023-01-01").unwrap()
+///     .append_text(" AND c.time <= @high_time")
+///     .with_parameter("@high_time", "2023-12-31").unwrap();
+/// # // We can't directly access the text field as it's private, but we can serialize to verify
+/// # let serialized = serde_json::to_string(&query).unwrap();
+/// # assert!(serialized.contains("WHERE c.time >= @low_time AND c.time <= @high_time"));
+/// ```
+///
 /// # Specifying Parameters
 ///
 /// Any JSON-serializable value, including an empty tuple (`()`), which indicates `null`, can be used as a parameter.
@@ -92,6 +107,18 @@ impl Query {
 
         Ok(self)
     }
+
+    /// Consumes this [`Query`] instance, replaces its text with the provided value, and returns it.
+    pub fn with_text(mut self, text: String) -> Self {
+        self.text = text;
+        self
+    }
+
+    /// Consumes this [`Query`] instance, appends the provided text to its current text, and returns it.
+    pub fn append_text(mut self, text: &str) -> Self {
+        self.text.push_str(text);
+        self
+    }
 }
 
 impl<T: Into<String>> From<T> for Query {
@@ -169,4 +196,56 @@ mod tests {
         );
         Ok(())
     }
+
+    #[test]
+    pub fn with_text_replaces_query_text() {
+        let query = Query::from("SELECT * FROM c").with_text("SELECT c.id FROM c".to_string());
+        assert_eq!(query.text, "SELECT c.id FROM c");
+    }
+
+    #[test]
+    pub fn with_text_preserves_parameters() -> Result<(), Box<dyn Error>> {
+        let query = Query::from("SELECT * FROM c")
+            .with_parameter("@id", 42)?
+            .with_text("SELECT c.name FROM c WHERE c.id = @id".to_string());
+
+        assert_eq!(query.text, "SELECT c.name FROM c WHERE c.id = @id");
+        assert_eq!(query.parameters.len(), 1);
+        assert_eq!(query.parameters[0].name, "@id");
+        Ok(())
+    }
+
+    #[test]
+    pub fn append_text_adds_to_existing_text() {
+        let query = Query::from("SELECT * FROM c").append_text(" WHERE c.id = @id");
+        assert_eq!(query.text, "SELECT * FROM c WHERE c.id = @id");
+    }
+
+    #[test]
+    pub fn append_text_preserves_parameters() -> Result<(), Box<dyn Error>> {
+        let query = Query::from("SELECT * FROM c")
+            .with_parameter("@id", 42)?
+            .append_text(" WHERE c.id = @id");
+
+        assert_eq!(query.text, "SELECT * FROM c WHERE c.id = @id");
+        assert_eq!(query.parameters.len(), 1);
+        assert_eq!(query.parameters[0].name, "@id");
+        Ok(())
+    }
+
+    #[test]
+    pub fn method_chaining_works_with_new_methods() -> Result<(), Box<dyn Error>> {
+        let query = Query::from("SELECT * FROM c")
+            .append_text(" WHERE c.time >= @low_time")
+            .with_parameter("@low_time", "2023-01-01")?
+            .append_text(" AND c.time <= @high_time")
+            .with_parameter("@high_time", "2023-12-31")?;
+
+        assert_eq!(
+            query.text,
+            "SELECT * FROM c WHERE c.time >= @low_time AND c.time <= @high_time"
+        );
+        assert_eq!(query.parameters.len(), 2);
+        Ok(())
+    }
 }