Merge pull request #2050 from LijuanTang94/fix/remove-deprecated-async-enabled

feat: deprecate `async_enabled` replication argument removed server-side

Author: g-despot

integration/test_collection_config.py

@@ -1706,9 +1706,14 @@ def test_replication_config_with_async_config(collection_factory: CollectionFact
         assert ac.alive_nodes_checking_frequency is None
 
 
-def test_replication_config_remove_async_config_by_disabling_async_replication(
+def test_replication_config_async_config_preserved_when_disabling_async_replication(
     collection_factory: CollectionFactory,
 ) -> None:
+    """Disabling `async_enabled` must leave the collection's async replication tuning intact.
+
+    `config.update()` is a read-modify-write PUT of the whole collection, so dropping `asyncConfig`
+    from the merged payload would silently reset the tuning to server defaults.
+    """
     collection_dummy = collection_factory("dummy")
     if collection_dummy._connection._weaviate_version.is_lower_than(1, 34, 18):
         pytest.skip("async replication config requires Weaviate >= 1.34.18")
@@ -1733,8 +1738,14 @@ def test_replication_config_remove_async_config_by_disabling_async_replication(
         ),
     )
     config = collection.config.get()
+    # False on both sides of the v1.38 compatibility shim: older servers store the
+    # `asyncEnabled` we just sent, newer ones derive it as `factor > 1 and not globally
+    # disabled` — and this collection has factor=1.
     assert config.replication_config.async_enabled is False
-    assert config.replication_config.async_config is None
+    ac = config.replication_config.async_config
+    assert ac is not None
+    assert ac.propagation_concurrency == 4
+    assert ac.hashtree_height == 20
 
 
 def test_replication_config_remove_async_config(collection_factory: CollectionFactory) -> None:

test/collection/test_config.py

@@ -3308,6 +3308,36 @@ def test_replication_config_update_merge_with_missing_async_config() -> None:
     assert result["factor"] == 3
 
 
+@pytest.mark.parametrize(
+    "config_factory",
+    [Configure.replication, Reconfigure.replication],
+)
+@pytest.mark.parametrize("async_enabled", [True, False])
+def test_replication_async_enabled_emits_deprecation_warning(
+    config_factory: object, async_enabled: bool
+) -> None:
+    """`async_enabled` was removed from the server schema in v1.38 and must warn when passed.
+
+    Both booleans are covered: `False` was the explicit opt-out, so a future truthiness
+    check must not silently stop warning for it.
+    """
+    with pytest.warns(DeprecationWarning, match="Dep030"):
+        config_factory(async_enabled=async_enabled)  # type: ignore[operator]
+
+
+@pytest.mark.parametrize(
+    "config_factory",
+    [Configure.replication, Reconfigure.replication],
+)
+def test_replication_without_async_enabled_does_not_warn(config_factory: object) -> None:
+    """Omitting `async_enabled` must not emit the deprecation warning."""
+    import warnings
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", DeprecationWarning)
+        config_factory(factor=3)  # type: ignore[operator]
+
+
 def test_nested_property_with_id_name_is_allowed() -> None:
     """A nested property named 'id' must not raise — only top-level 'id' is reserved."""
     prop = Property(

test/collection/test_config_update.py

@@ -122,8 +122,8 @@ def test_replication_async_config_replace_on_update() -> None:
     assert "hashtreeHeight" not in result["asyncConfig"]
 
 
-def test_replication_async_config_cleared_when_async_disabled() -> None:
-    """Test asyncConfig is removed from schema when asyncEnabled is set to False."""
+def test_replication_async_config_preserved_when_async_disabled() -> None:
+    """Test asyncConfig is preserved when asyncEnabled is set to False."""
     schema = {
         "factor": 1,
         "asyncEnabled": True,
@@ -132,7 +132,7 @@ def test_replication_async_config_cleared_when_async_disabled() -> None:
     update = Reconfigure.replication(async_enabled=False)
     result = update.merge_with_existing(schema)
     assert result["asyncEnabled"] is False
-    assert "asyncConfig" not in result
+    assert result["asyncConfig"] == {"maxWorkers": 8, "hashtreeHeight": 20}
 
 
 def test_replication_async_config_preserved_when_not_provided() -> None:

weaviate/collections/classes/config.py

@@ -353,8 +353,6 @@ def merge_with_existing(self, schema: Dict[str, Any]) -> Dict[str, Any]:
             schema["factor"] = self.factor
         if self.asyncEnabled is not None:
             schema["asyncEnabled"] = self.asyncEnabled
-            if not self.asyncEnabled:
-                schema.pop("asyncConfig", None)
         if self.deletionStrategy is not None:
             schema["deletionStrategy"] = str(self.deletionStrategy.value)
         if self.asyncConfig is not None:
@@ -2922,14 +2920,21 @@ def replication(
     ) -> _ReplicationConfigCreate:
         """Create a `ReplicationConfigCreate` object to be used when defining the replication configuration of Weaviate.
 
-        NOTE: `async_enabled` is only available with WeaviateDB `>=v1.26.0`
+        Note:
+            `async_enabled` is deprecated. On servers `>=v1.38` the `asyncEnabled` field no longer
+            exists in the schema: it is silently dropped, and async replication is decided
+            server-side (on by default for any collection with a replication factor > 1, unless the
+            `ASYNC_REPLICATION_DISABLED` runtime override is set). On older servers it still takes
+            effect. Passing it emits a ``DeprecationWarning``; it will be removed in a future release.
 
         Args:
             factor: The replication factor.
             async_enabled: Enabled async replication.
             deletion_strategy: How conflicts between different nodes about deleted objects are resolved.
-            async_config: The configuration for async replication. This is only relevant if `async_enabled` is `True`.
+            async_config: The configuration for async replication.
         """
+        if async_enabled is not None:
+            _Warnings.async_enabled_field_removed_server_side()
         return _ReplicationConfigCreate(
             factor=factor,
             asyncEnabled=async_enabled,
@@ -3210,12 +3215,21 @@ def replication(
 
         Use this method when defining the `replication_config` argument in `collection.update()`.
 
+        Note:
+            `async_enabled` is deprecated. On servers `>=v1.38` the `asyncEnabled` field no longer
+            exists in the schema: it is silently dropped, and async replication is decided
+            server-side (on by default for any collection with a replication factor > 1, unless the
+            `ASYNC_REPLICATION_DISABLED` runtime override is set). On older servers it still takes
+            effect. Passing it emits a ``DeprecationWarning``; it will be removed in a future release.
+
         Args:
             factor: The replication factor.
             async_enabled: Enable async replication.
             deletion_strategy: How conflicts between different nodes about deleted objects are resolved.
-            async_config: The async replication configuration. This is only applicable if `async_enabled` is set to `True`.
+            async_config: The async replication configuration.
         """
+        if async_enabled is not None:
+            _Warnings.async_enabled_field_removed_server_side()
         return _ReplicationConfigUpdate(
             factor=factor,
             asyncEnabled=async_enabled,

weaviate/warnings.py

@@ -261,6 +261,18 @@ def async_replication_field_removed_server_side(argument: str) -> None:
             stacklevel=1,
         )
 
+    @staticmethod
+    def async_enabled_field_removed_server_side() -> None:
+        warnings.warn(
+            message="""Dep030: The `async_enabled` argument in `Configure.replication` / `Reconfigure.replication` is deprecated.
+            On Weaviate v1.38 and newer the `asyncEnabled` field no longer exists in the server schema: it is silently dropped,
+            and whether async replication runs is decided server-side, on by default for any collection with a replication
+            factor > 1 unless the `ASYNC_REPLICATION_DISABLED` runtime override is set.
+            On older servers the argument still takes effect, but it is deprecated and will be removed in a future release.""",
+            category=DeprecationWarning,
+            stacklevel=1,
+        )
+
     @staticmethod
     def datetime_insertion_with_no_specified_timezone(date: datetime) -> None:
         warnings.warn(