docs: state the coupled retokenization contract explicitly (#2098)

Documents on update_property_index that a tokenization change via the
searchable index also retokenizes an existing filterable index as one
coupled task (shared taskId) and thereby changes filter matching, with
filterable as the target for bucket-only changes and cancellation
applying to the whole task. Explains why PropertyIndexes.data_type is a
plain str (primitives match the DataType enum, references carry the
target collection name) and pins reference-property parsing with a mock
test.

Author: g-despot

mock_tests/test_property_reindex.py

@@ -9,6 +9,7 @@
 import weaviate
 from mock_tests.conftest import MOCK_IP, MOCK_PORT, MOCK_PORT_GRPC
 from weaviate.collections.classes.config import (
+    DataType,
     PropertyIndexState,
     PropertyIndexTaskStatus,
     PropertyIndexType,
@@ -455,6 +456,43 @@ def test_delete_property_index_enum_and_literal_hit_same_route(
     weaviate_139_mock.check_assertions()
 
 
+def test_get_property_indexes_reference_property(
+    weaviate_139_mock: HTTPServer, client_139: weaviate.WeaviateClient
+) -> None:
+    """Reference properties carry the target collection name as dataType and still parse."""
+    weaviate_139_mock.expect_request(f"{SCHEMA_PATH}/indexes", method="GET").respond_with_json(
+        {
+            "collection": COLLECTION,
+            "properties": [
+                {
+                    "name": "title",
+                    "dataType": "text",
+                    "indexes": [{"type": "searchable", "status": "ready", "tokenization": "word"}],
+                },
+                {
+                    "name": "ofArticle",
+                    "dataType": "Article",
+                    "indexes": [{"type": "filterable", "status": "ready"}],
+                },
+            ],
+        }
+    )
+
+    indexes = client_139.collections.use(COLLECTION).config.get_property_indexes()
+    title, ref = indexes.properties
+    # primitive values match the DataType str-enum
+    assert title.data_type == DataType.TEXT
+    # reference properties carry the qualified target collection name instead
+    assert ref.name == "ofArticle"
+    assert ref.data_type == "Article"
+    assert ref.indexes[0].type == "filterable"
+
+    out = json.loads(json.dumps(indexes.to_dict()))
+    assert out["properties"][1]["dataType"] == "Article"
+
+    weaviate_139_mock.check_assertions()
+
+
 def test_delete_property_index_surfaces_server_message(
     weaviate_139_mock: HTTPServer, client_139: weaviate.WeaviateClient
 ) -> None:

weaviate/collections/classes/config.py

@@ -2281,6 +2281,9 @@ class _PropertyIndexStatus(_ConfigBase):
 @dataclass
 class _PropertyIndexes(_ConfigBase):
     name: str
+    # For primitive properties the value matches the `DataType` str-enum (comparisons like
+    # `data_type == DataType.TEXT` work); reference properties instead carry the qualified
+    # target collection name (e.g. "Article"), which is why this is a plain str, not `DataType`.
     data_type: str
     description: Optional[str]
     indexes: List[PropertyIndexStatus]

weaviate/collections/config/executor.py

@@ -790,6 +790,12 @@ def update_property_index(
         configuration. If the configuration already matches, no work is submitted and the returned
         task reports a `NO_OP` status. The server accepts at most one configuration change per request.
 
+        Caution: changing `tokenization` via the `searchable` index ALSO retokenizes the property's
+        `filterable` index when one exists. Both indexes are migrated by a single coupled task (their
+        status entries share one `taskId`), and the retokenization changes how filters match on that
+        property. To retokenize only the filterable bucket, target the `filterable` index instead.
+        Cancelling via either index type cancels the whole coupled task.
+
         Args:
             property_name: The property whose index to create or migrate.
             index_name: The type of the index, a `PropertyIndexType` value or one of the literals