fix(config): address review feedback on runtime property reindex (#2098)

- wait_for_completion: gate terminal acceptance on the submitted task_id so a
  stale ready/failed/cancelled entry left by a prior reindex can no longer be
  mistaken for this task completing (fixes premature return and spurious raise)
- extract shared __submit_property_index_task for update/rebuild; point
  delete_property_index at the __property_index_path helper
- deprecate string index_name: emit Dep030 when a raw string is passed to
  delete_property_index; the reindex methods take InvertedIndexType
- InvertedIndexStatus.type is now the InvertedIndexType enum; parse the status
  field tolerantly so an unknown state cannot crash the poll loop
- validate wait_for_completion; normalize an empty tenants list to no param
- tests: async mock coverage, a multi-poll transition regression test, a real
  in-flight CANCELLED e2e, and split the one-change-per-request PUT test

Author: g-despot

integration/test_collection_config.py

@@ -47,6 +47,7 @@
 )
 from weaviate.collections.classes.tenants import Tenant
 from weaviate.exceptions import (
+    ReindexCanceledError,
     UnexpectedStatusCodeError,
     WeaviateInvalidInputError,
     WeaviateUnsupportedFeatureError,
@@ -2863,6 +2864,55 @@ def test_property_reindex_coupled_tokenization_change(
     assert filterable.tokenization == Tokenization.FIELD
 
 
+def test_property_reindex_cancel_in_flight(collection_factory: CollectionFactory) -> None:
+    """Cancel a live reindex task and observe an actual CANCELLED result + wait-path raise."""
+    collection_dummy = collection_factory("dummy")
+    if collection_dummy._connection._weaviate_version.is_lower_than(1, 39, 0):
+        pytest.skip("Runtime property reindex requires Weaviate >= 1.39.0")
+
+    collection = collection_factory(
+        properties=[
+            Property(
+                name="name",
+                data_type=DataType.TEXT,
+                index_filterable=True,
+                index_searchable=True,
+                tokenization=Tokenization.WORD,
+            )
+        ],
+    )
+    # a large batch keeps the coupled reindex task live long enough to cancel it
+    collection.data.insert_many([{"name": f"object {i}"} for i in range(1000)])
+
+    task = collection.config.update_property_index(
+        "name", InvertedIndexType.SEARCHABLE, tokenization=Tokenization.FIELD
+    )
+    assert task.status == InvertedIndexTaskStatus.STARTED
+    assert task.task_id is not None
+
+    cancel = collection.config.cancel_property_index_task("name", InvertedIndexType.SEARCHABLE)
+    if cancel.status == InvertedIndexTaskStatus.CANCELLED:
+        # a live task was stopped: the cancellation targets the same coupled task we submitted
+        assert cancel.task_id == task.task_id
+    else:
+        # the task finished before we could cancel it — nothing left to stop
+        assert cancel.status == InvertedIndexTaskStatus.NO_OP
+
+    # the index settles into a terminal state; if cancelled, waiting on it raises
+    if cancel.status == InvertedIndexTaskStatus.CANCELLED:
+        try:
+            status = collection.config.update_property_index(
+                "name",
+                InvertedIndexType.SEARCHABLE,
+                tokenization=Tokenization.FIELD,
+                wait_for_completion=True,
+            )
+            # a resubmit may relaunch and complete instead of surfacing the cancelled entry
+            assert status.status == InvertedIndexState.READY
+        except ReindexCanceledError:
+            pass
+
+
 def test_property_reindex_multi_tenant(collection_factory: CollectionFactory) -> None:
     """Test rangeFilters creation and rebuild with a tenants selection on a multi-tenant collection."""
     collection_dummy = collection_factory("dummy")

mock_tests/test_property_reindex.py

@@ -1,4 +1,5 @@
 import json
+import warnings
 from typing import Generator, Union
 
 import grpc
@@ -51,16 +52,36 @@ def client_139(
 def test_update_property_index_started(
     weaviate_139_mock: HTTPServer, client_139: weaviate.WeaviateClient
 ) -> None:
+    """A single tokenization change is a valid PUT body (the server allows at most one change)."""
     weaviate_139_mock.expect_request(
         f"{SCHEMA_PATH}/properties/name/index/searchable",
         method="PUT",
-        json={"tokenization": "word", "algorithm": "blockmax"},
+        json={"tokenization": "word"},
     ).respond_with_json({"taskId": TASK_ID, "status": "STARTED"}, status=202)
 
     task = client_139.collections.use(COLLECTION).config.update_property_index(
         "name",
         "searchable",
         tokenization=Tokenization.WORD,
+    )
+    assert task.task_id == TASK_ID
+    assert task.status == InvertedIndexTaskStatus.STARTED
+    weaviate_139_mock.check_assertions()
+
+
+def test_update_property_index_algorithm_only(
+    weaviate_139_mock: HTTPServer, client_139: weaviate.WeaviateClient
+) -> None:
+    """An algorithm-only change is also a valid single-change PUT body."""
+    weaviate_139_mock.expect_request(
+        f"{SCHEMA_PATH}/properties/name/index/searchable",
+        method="PUT",
+        json={"algorithm": "blockmax"},
+    ).respond_with_json({"taskId": TASK_ID, "status": "STARTED"}, status=202)
+
+    task = client_139.collections.use(COLLECTION).config.update_property_index(
+        "name",
+        "searchable",
         algorithm="blockmax",
     )
     assert task.task_id == TASK_ID
@@ -112,14 +133,22 @@ def test_update_property_index_wait_for_completion(
         method="PUT",
         json={"tokenization": "word"},
     ).respond_with_json({"taskId": TASK_ID, "status": "STARTED"}, status=202)
+    # the ready entry still carries the submitted task id, so the task_id-gated wait accepts it
     weaviate_139_mock.expect_request(f"{SCHEMA_PATH}/indexes", method="GET").respond_with_json(
         {
             "collection": COLLECTION,
             "properties": [
                 {
                     "name": "name",
                     "dataType": "text",
-                    "indexes": [{"type": "searchable", "status": "ready", "tokenization": "word"}],
+                    "indexes": [
+                        {
+                            "type": "searchable",
+                            "status": "ready",
+                            "taskId": TASK_ID,
+                            "tokenization": "word",
+                        }
+                    ],
                 }
             ],
         }
@@ -378,6 +407,8 @@ def test_get_property_indexes(
     assert name.description == "a text property"
     assert len(name.indexes) == 2
     searchable, filterable = name.indexes
+    # `type` parses strictly into the InvertedIndexType enum; str-enum equality still holds
+    assert searchable.type is InvertedIndexType.SEARCHABLE
     assert searchable.type == "searchable"
     assert searchable.status == InvertedIndexState.INDEXING
     assert searchable.progress == 0.5
@@ -591,6 +622,26 @@ def test_delete_property_index_surfaces_server_message(
     weaviate_139_mock.check_assertions()
 
 
+def test_delete_property_index_string_deprecation_warning(
+    weaviate_139_mock: HTTPServer, client_139: weaviate.WeaviateClient
+) -> None:
+    """A raw-string index_name on delete_property_index warns; the enum form does not."""
+    weaviate_139_mock.expect_request(
+        f"{SCHEMA_PATH}/properties/name/index/searchable",
+        method="DELETE",
+    ).respond_with_json({}, status=200)
+
+    config = client_139.collections.use(COLLECTION).config
+    with pytest.warns(DeprecationWarning, match="Dep030"):
+        assert config.delete_property_index("name", "searchable") is True
+
+    # the InvertedIndexType form is the supported path and must not warn
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        assert config.delete_property_index("name", InvertedIndexType.SEARCHABLE) is True
+    weaviate_139_mock.check_assertions()
+
+
 def test_property_reindex_invalid_input(
     weaviate_139_mock: HTTPServer, client_139: weaviate.WeaviateClient
 ) -> None:
@@ -606,6 +657,126 @@ def test_property_reindex_invalid_input(
     weaviate_139_mock.check_assertions()
 
 
+def _single_index_payload(entry: dict) -> dict:
+    return {
+        "collection": COLLECTION,
+        "properties": [{"name": "name", "dataType": "text", "indexes": [entry]}],
+    }
+
+
+def test_update_property_index_wait_polls_until_submitted_task_ready(
+    weaviate_139_mock: HTTPServer, client_139: weaviate.WeaviateClient
+) -> None:
+    """Regression for the task_id gate (fix #1).
+
+    The wait must ignore a stale ``ready`` left by a PRIOR reindex and only accept the ``ready``
+    that follows the submitted task's own progress — never returning early. If the task_id gate
+    were removed, the first (stale) ready would be returned and the tokenization assertion below
+    would fail.
+    """
+    weaviate_139_mock.expect_ordered_request(
+        f"{SCHEMA_PATH}/properties/name/index/searchable",
+        method="PUT",
+        json={"tokenization": "field"},
+    ).respond_with_json({"taskId": TASK_ID, "status": "STARTED"}, status=202)
+    # poll 1: a stale ready from a prior reindex (different task id) — must NOT be accepted
+    weaviate_139_mock.expect_ordered_request(
+        f"{SCHEMA_PATH}/indexes", method="GET"
+    ).respond_with_json(
+        _single_index_payload(
+            {
+                "type": "searchable",
+                "status": "ready",
+                "taskId": "stale-task",
+                "tokenization": "word",
+            }
+        )
+    )
+    # poll 2: our task mid-finalize (indexing @ 1.0 carrying our task id)
+    weaviate_139_mock.expect_ordered_request(
+        f"{SCHEMA_PATH}/indexes", method="GET"
+    ).respond_with_json(
+        _single_index_payload(
+            {
+                "type": "searchable",
+                "status": "indexing",
+                "progress": 1.0,
+                "taskId": TASK_ID,
+                "tokenization": "word",
+                "targetTokenization": "field",
+            }
+        )
+    )
+    # poll 3: flipped to plain ready with the new tokenization
+    weaviate_139_mock.expect_ordered_request(
+        f"{SCHEMA_PATH}/indexes", method="GET"
+    ).respond_with_json(
+        _single_index_payload({"type": "searchable", "status": "ready", "tokenization": "field"})
+    )
+
+    status = client_139.collections.use(COLLECTION).config.update_property_index(
+        "name",
+        InvertedIndexType.SEARCHABLE,
+        tokenization=Tokenization.FIELD,
+        wait_for_completion=True,
+    )
+    assert status.status == InvertedIndexState.READY
+    assert status.tokenization == Tokenization.FIELD
+    weaviate_139_mock.check_assertions()
+
+
+@pytest.mark.asyncio
+async def test_update_property_index_async(
+    weaviate_139_mock: HTTPServer, start_grpc_server: grpc.Server
+) -> None:
+    """The async fork of update_property_index submits and waits via the task_id gate."""
+    weaviate_139_mock.expect_request(
+        f"{SCHEMA_PATH}/properties/name/index/searchable",
+        method="PUT",
+        json={"tokenization": "word"},
+    ).respond_with_json({"taskId": TASK_ID, "status": "STARTED"}, status=202)
+    weaviate_139_mock.expect_request(f"{SCHEMA_PATH}/indexes", method="GET").respond_with_json(
+        _single_index_payload(
+            {"type": "searchable", "status": "ready", "taskId": TASK_ID, "tokenization": "word"}
+        )
+    )
+
+    async with weaviate.use_async_with_local(
+        host=MOCK_IP, port=MOCK_PORT, grpc_port=MOCK_PORT_GRPC
+    ) as client:
+        status = await client.collections.use(COLLECTION).config.update_property_index(
+            "name",
+            InvertedIndexType.SEARCHABLE,
+            tokenization=Tokenization.WORD,
+            wait_for_completion=True,
+        )
+    assert status.status == InvertedIndexState.READY
+    assert status.tokenization == Tokenization.WORD
+    weaviate_139_mock.check_assertions()
+
+
+@pytest.mark.asyncio
+async def test_rebuild_property_index_async(
+    weaviate_139_mock: HTTPServer, start_grpc_server: grpc.Server
+) -> None:
+    """The async fork of rebuild_property_index submits a POST and returns the task."""
+    weaviate_139_mock.expect_request(
+        f"{SCHEMA_PATH}/properties/name/index/searchable/rebuild",
+        method="POST",
+        json={},
+    ).respond_with_json({"taskId": TASK_ID, "status": "STARTED"}, status=202)
+
+    async with weaviate.use_async_with_local(
+        host=MOCK_IP, port=MOCK_PORT, grpc_port=MOCK_PORT_GRPC
+    ) as client:
+        task = await client.collections.use(COLLECTION).config.rebuild_property_index(
+            "name", InvertedIndexType.SEARCHABLE
+        )
+    assert task.task_id == TASK_ID
+    assert task.status == InvertedIndexTaskStatus.STARTED
+    weaviate_139_mock.check_assertions()
+
+
 def test_property_reindex_unsupported_version(
     weaviate_client: weaviate.WeaviateClient,
 ) -> None:

weaviate/collections/classes/config.py

@@ -110,6 +110,12 @@
     "high",
 ]
 
+# Deprecated: this string alias is superseded by the ``InvertedIndexType`` enum and will be
+# removed in a future release. Prefer ``InvertedIndexType`` for property index type arguments;
+# the string form is still accepted by ``delete_property_index`` (which emits a
+# ``DeprecationWarning``) for backwards compatibility. ``typing_extensions.deprecated`` (PEP 702)
+# cannot annotate a bare type alias — it decorates classes/functions/overloads — so the
+# deprecation is surfaced via this comment and the runtime warning on the accepting method.
 IndexName: TypeAlias = Literal[
     "searchable",
     "filterable",
@@ -2322,8 +2328,14 @@ class _InvertedIndexTask(_ConfigBase):
 
 @dataclass
 class _InvertedIndexStatus(_ConfigBase):
-    type: IndexName  # noqa: A003
-    status: InvertedIndexState
+    """The status of a single property index as reported by the index status endpoint.
+
+    Known `status` values parse to `InvertedIndexState`; unknown server values pass through
+    as plain strings, so that polling a status endpoint never crashes on a new state name.
+    """
+
+    type: InvertedIndexType  # noqa: A003
+    status: Union[InvertedIndexState, str]
     progress: Optional[float]
     task_id: Optional[str]
     tokenization: Optional[Tokenization]

weaviate/collections/classes/config_methods.py

@@ -4,9 +4,9 @@
 from weaviate.collections.classes.config import (
     DataType,
     GenerativeSearches,
-    IndexName,
     InvertedIndexState,
     InvertedIndexTaskStatus,
+    InvertedIndexType,
     PQEncoderDistribution,
     PQEncoderType,
     ReplicationDeletionStrategy,
@@ -583,9 +583,18 @@ def _inverted_index_task_from_json(response: Dict[str, Any]) -> _InvertedIndexTa
 def _inverted_index_status_from_json(index: Dict[str, Any]) -> _InvertedIndexStatus:
     tokenization = index.get("tokenization")
     target_tokenization = index.get("targetTokenization")
+    raw_status = index["status"]
+    try:
+        status: Union[InvertedIndexState, str] = InvertedIndexState(raw_status)
+    except ValueError:
+        # the spec declares the field open-vocabulary; pass unknown values through so that
+        # polling a status endpoint never crashes on a newly-added state name
+        status = raw_status
     return _InvertedIndexStatus(
-        type=cast(IndexName, index["type"]),
-        status=InvertedIndexState(index["status"]),
+        # `type` is closed-vocabulary and server-canonical (always filterable|searchable|
+        # rangeFilters), so parse it strictly into the enum, matching the file convention.
+        type=InvertedIndexType(index["type"]),
+        status=status,
         progress=index.get("progress"),
         task_id=index.get("taskId"),
         tokenization=Tokenization(tokenization) if tokenization is not None else None,