From af297b6912fe427d42556c64e8d6c575736f2849 Mon Sep 17 00:00:00 2001
From: Brendan Clement <brendan.clement@lancedb.com>
Date: Mon, 1 Jun 2026 20:21:17 -0700
Subject: [PATCH] feat: deprecate replace_field_metadata for
 update_field_metadata

---
 python/python/lancedb/table.py | 16 ++++++++++++++++
 python/src/table.rs            |  1 +
 rust/lancedb/src/table.rs      |  2 ++
 3 files changed, 19 insertions(+)

diff --git a/python/python/lancedb/table.py b/python/python/lancedb/table.py
index deb289fd6..7adc2cc54 100644
--- a/python/python/lancedb/table.py
+++ b/python/python/lancedb/table.py
@@ -3666,10 +3666,18 @@ class LanceTable(Table):
         """
         LOOP.run(self._table.migrate_v2_manifest_paths())
 
+    @deprecation.deprecated(
+        deprecated_in="0.33.1",
+        current_version=__version__,
+        details="Use update_field_metadata() instead.",
+    )
     def replace_field_metadata(self, field_name: str, new_metadata: Dict[str, str]):
         """
         Replace the metadata of a field in the schema
 
+        .. deprecated:: 0.33.1
+            Use :func:`update_field_metadata` instead.
+
         Parameters
         ----------
         field_name: str
@@ -5554,12 +5562,20 @@ class AsyncTable:
         """
         await self._inner.migrate_manifest_paths_v2()
 
+    @deprecation.deprecated(
+        deprecated_in="0.33.1",
+        current_version=__version__,
+        details="Use update_field_metadata() instead.",
+    )
     async def replace_field_metadata(
         self, field_name: str, new_metadata: dict[str, str]
     ):
         """
         Replace the metadata of a field in the schema
 
+        .. deprecated:: 0.33.1
+            Use :func:`update_field_metadata` instead.
+
         Parameters
         ----------
         field_name: str
diff --git a/python/src/table.rs b/python/src/table.rs
index a0462caf3..bfb38a3ab 100644
--- a/python/src/table.rs
+++ b/python/src/table.rs
@@ -1118,6 +1118,7 @@ impl Table {
         })
     }
 
+    #[allow(deprecated)]
     pub fn replace_field_metadata<'a>(
         self_: PyRef<'a, Self>,
         field_name: String,
diff --git a/rust/lancedb/src/table.rs b/rust/lancedb/src/table.rs
index 0eb6b578a..bb224dd8c 100644
--- a/rust/lancedb/src/table.rs
+++ b/rust/lancedb/src/table.rs
@@ -2604,6 +2604,7 @@ impl NativeTable {
     ///   field id and the second element is a hashmap of metadata key-value
     ///   pairs.
     ///
+    #[deprecated(since = "0.33.1", note = "Use `update_field_metadata` instead")]
     pub async fn replace_field_metadata(
         &self,
         new_values: impl IntoIterator<Item = (u32, HashMap<String, String>)>,
@@ -4482,6 +4483,7 @@ mod tests {
 
         let mut new_field_metadata = HashMap::<String, String>::new();
         new_field_metadata.insert("test_field_key1".into(), "test_field_val1".into());
+        #[allow(deprecated)]
         native_tbl
             .replace_field_metadata(vec![(field.id as u32, new_field_metadata)])
             .await