Merge pull request #166 from weaviate/rod/hfresh-followup

Fix distance_metric enum conversion and add hfresh unit tests

Author: jfrancoa

.claude/skills/operating-weaviate-cli/references/collections.md

@@ -26,7 +26,7 @@ weaviate-cli create collection \
 - `--collection` -- Name (default: "Movies")
 - `--replication_factor` -- Number of replicas (default: 3)
 - `--async_enabled` -- Enable async replication
-- `--vector_index` -- Index type: hnsw, flat, dynamic, hnsw_pq, hnsw_bq, hnsw_sq, hnsw_rq, hnsw_acorn, hnsw_multivector, flat_bq, dynamic_*
+- `--vector_index` -- Index type: hnsw, flat, dynamic, hnsw_pq, hnsw_bq, hnsw_sq, hnsw_rq, hnsw_acorn, hnsw_multivector, flat_bq, dynamic_*, hfresh
 - `--inverted_index` -- Inverted index: timestamp, null, length
 - `--training_limit` -- PQ/SQ training limit (default: 10000)
 - `--multitenant` -- Enable multi-tenancy
@@ -43,6 +43,28 @@ weaviate-cli create collection \
 - `--object_ttl_time` -- Time to live in seconds (default: None, TTL disabled when omitted)
 - `--object_ttl_filter_expired` -- Filter expired-but-not-yet-deleted objects from queries
 - `--object_ttl_property_name` -- Date property name for TTL when `object_ttl_type=property` (default: "releaseDate"). **Only valid when `--object_ttl_type=property`**; rejected otherwise.
+- `--hfresh_max_posting_size_kb` -- (hfresh only) Max posting list size in KB (default: None, uses server default)
+- `--hfresh_replicas` -- (hfresh only) Number of replicas per element across posting lists (default: None, uses server default)
+- `--hfresh_search_probe` -- (hfresh only) Search probe size (default: None, uses server default)
+- `--distance_metric` -- Distance metric: cosine, dot, l2-squared, hamming, manhattan (default: None, uses server default). Applies to all vector index types.
+- `--rescore_limit` -- Rescore limit for quantized indexes (default: None, uses server default)
+
+**hfresh examples:**
+```bash
+# Basic hfresh collection
+weaviate-cli create collection --collection Movies --vector_index hfresh --json
+
+# hfresh with all tuning parameters
+weaviate-cli create collection \
+  --collection Movies \
+  --vector_index hfresh \
+  --hfresh_max_posting_size_kb 64 \
+  --hfresh_replicas 2 \
+  --hfresh_search_probe 100 \
+  --distance_metric cosine \
+  --rescore_limit 200 \
+  --json
+```
 
 **Object TTL examples:**
 ```bash

test/unittests/test_managers/test_collection_manager.py

@@ -777,3 +777,86 @@ def test_update_collection_with_ttl_disable_type(mock_client, mock_wvc_object_tt
     assert update_call_kwargs["object_ttl_config"] is not None
     # Verify the disable method was called
     mock_wvc_object_ttl["reconfigure"].disable.assert_called_once()
+
+
+def test_create_collection_with_hfresh_defaults(mock_client, mock_wvc_object_ttl):
+    """Test creating a collection with hfresh vector index using default parameters."""
+    mock_collections = MagicMock()
+    mock_client.collections = mock_collections
+    mock_collections.exists.side_effect = [False, True]
+
+    manager = CollectionManager(mock_client)
+
+    manager.create_collection(
+        collection="TestCollection",
+        vector_index="hfresh",
+    )
+
+    mock_collections.create.assert_called_once()
+    create_call_kwargs = mock_collections.create.call_args.kwargs
+    assert create_call_kwargs["name"] == "TestCollection"
+    assert create_call_kwargs["vector_index_config"] is not None
+
+
+def test_create_collection_with_hfresh_all_params(mock_client, mock_wvc_object_ttl):
+    """Test creating a collection with hfresh vector index with all parameters set."""
+    mock_collections = MagicMock()
+    mock_client.collections = mock_collections
+    mock_collections.exists.side_effect = [False, True]
+
+    manager = CollectionManager(mock_client)
+
+    manager.create_collection(
+        collection="TestCollection",
+        vector_index="hfresh",
+        hfresh_max_posting_size_kb=64,
+        hfresh_replicas=2,
+        hfresh_search_probe=100,
+        distance_metric="cosine",
+        rescore_limit=200,
+    )
+
+    mock_collections.create.assert_called_once()
+    create_call_kwargs = mock_collections.create.call_args.kwargs
+    assert create_call_kwargs["name"] == "TestCollection"
+    assert create_call_kwargs["vector_index_config"] is not None
+
+
+def test_create_collection_with_hfresh_valid_distance_metrics(
+    mock_client, mock_wvc_object_ttl
+):
+    """Test creating an hfresh collection with each valid distance metric."""
+    valid_metrics = ["cosine", "dot", "l2-squared", "hamming", "manhattan"]
+    for metric in valid_metrics:
+        mock_collections = MagicMock()
+        mock_client.collections = mock_collections
+        mock_collections.exists.side_effect = [False, True]
+
+        manager = CollectionManager(mock_client)
+        manager.create_collection(
+            collection="TestCollection",
+            vector_index="hfresh",
+            distance_metric=metric,
+        )
+        mock_collections.create.assert_called_once()
+
+
+def test_create_collection_with_hfresh_invalid_distance_metric(
+    mock_client, mock_wvc_object_ttl
+):
+    """Test that an unsupported distance metric raises ValueError."""
+    mock_collections = MagicMock()
+    mock_client.collections = mock_collections
+    mock_collections.exists.return_value = False
+
+    manager = CollectionManager(mock_client)
+
+    with pytest.raises(ValueError) as exc_info:
+        manager.create_collection(
+            collection="TestCollection",
+            vector_index="hfresh",
+            distance_metric="invalid_metric",
+        )
+
+    assert "Invalid distance_metric: 'invalid_metric'" in str(exc_info.value)
+    mock_collections.create.assert_not_called()

weaviate_cli/managers/collection_manager.py

@@ -147,35 +147,42 @@ def _print_text():
     def get_all_collections(self) -> dict[str, _CollectionConfigSimple]:
         return self.client.collections.list_all()
 
+    _DISTANCE_METRIC_MAP = {
+        "cosine": wvc.VectorDistances.COSINE,
+        "dot": wvc.VectorDistances.DOT,
+        "l2-squared": wvc.VectorDistances.L2_SQUARED,
+        "hamming": wvc.VectorDistances.HAMMING,
+        "manhattan": wvc.VectorDistances.MANHATTAN,
+    }
+
+    def _resolve_distance_metric(
+        self, distance_metric: Optional[str]
+    ) -> Optional[wvc.VectorDistances]:
+        """Convert a distance metric string to its VectorDistances enum value."""
+        if distance_metric is None:
+            return None
+        if distance_metric not in self._DISTANCE_METRIC_MAP:
+            raise ValueError(
+                f"Invalid distance_metric: '{distance_metric}'. "
+                f"Must be one of: {list(self._DISTANCE_METRIC_MAP.keys())}"
+            )
+        return self._DISTANCE_METRIC_MAP[distance_metric]
+
     def _build_hfresh_config(
         self,
         max_posting_size_kb: Optional[int] = None,
-        distance_metric: Optional[str] = "cosine",
+        distance_metric: Optional[wvc.VectorDistances] = None,
         rescore_limit: Optional[int] = None,
         replicas: Optional[int] = None,
         search_probe: Optional[int] = None,
     ):
         """Build hfresh configuration with provided parameters."""
-        # Explicit mapping of distance metric strings to enum values
-        distance_metric_map = {
-            "cosine": wvc.VectorDistances.COSINE,
-            "dot": wvc.VectorDistances.DOT,
-            "l2-squared": wvc.VectorDistances.L2_SQUARED,
-            "hamming": wvc.VectorDistances.HAMMING,
-            "manhattan": wvc.VectorDistances.MANHATTAN,
-        }
-
         kwargs = {}
 
         if max_posting_size_kb is not None:
             kwargs["max_posting_size_kb"] = max_posting_size_kb
         if distance_metric is not None:
-            if distance_metric not in distance_metric_map:
-                raise ValueError(
-                    f"Invalid distance_metric: '{distance_metric}'. "
-                    f"Must be one of: {list(distance_metric_map.keys())}"
-                )
-            kwargs["distance_metric"] = distance_metric_map[distance_metric]
+            kwargs["distance_metric"] = distance_metric
         if replicas is not None:
             kwargs["replicas"] = replicas
         if search_probe is not None:
@@ -248,56 +255,62 @@ def create_collection(
                 "Error: Named vector name is only supported with named vectors. Please use --named_vector to enable named vectors."
             )
 
+        distance_metric_enum = self._resolve_distance_metric(distance_metric)
+
         vector_index_map: Dict[str, wvc.VectorIndexConfig] = {
-            "hnsw": wvc.Configure.VectorIndex.hnsw(distance_metric=distance_metric),
-            "flat": wvc.Configure.VectorIndex.flat(distance_metric=distance_metric),
+            "hnsw": wvc.Configure.VectorIndex.hnsw(
+                distance_metric=distance_metric_enum
+            ),
+            "flat": wvc.Configure.VectorIndex.flat(
+                distance_metric=distance_metric_enum
+            ),
             "dynamic": wvc.Configure.VectorIndex.dynamic(),
             "dynamic_flat_bq": wvc.Configure.VectorIndex.dynamic(
                 flat=wvc.Configure.VectorIndex.flat(
                     quantizer=wvc.Configure.VectorIndex.Quantizer.bq(),
-                    distance_metric=distance_metric,
+                    distance_metric=distance_metric_enum,
                 )
             ),
             "dynamic_flat_bq_hnsw_pq": wvc.Configure.VectorIndex.dynamic(
                 flat=wvc.Configure.VectorIndex.flat(
                     quantizer=wvc.Configure.VectorIndex.Quantizer.bq(
                         rescore_limit=rescore_limit
                     ),
-                    distance_metric=distance_metric,
+                    distance_metric=distance_metric_enum,
                 ),
                 hnsw=wvc.Configure.VectorIndex.hnsw(
                     quantizer=wvc.Configure.VectorIndex.Quantizer.pq(
                         training_limit=training_limit
                     ),
-                    distance_metric=distance_metric,
+                    distance_metric=distance_metric_enum,
                 ),
             ),
             "dynamic_flat_bq_hnsw_sq": wvc.Configure.VectorIndex.dynamic(
                 flat=wvc.Configure.VectorIndex.flat(
                     quantizer=wvc.Configure.VectorIndex.Quantizer.bq(
                         rescore_limit=rescore_limit
                     ),
-                    distance_metric=distance_metric,
+                    distance_metric=distance_metric_enum,
                 ),
                 hnsw=wvc.Configure.VectorIndex.hnsw(
                     quantizer=wvc.Configure.VectorIndex.Quantizer.sq(
                         rescore_limit=rescore_limit, training_limit=training_limit
                     ),
-                    distance_metric=distance_metric,
+                    distance_metric=distance_metric_enum,
                 ),
             ),
             "dynamic_flat_bq_hnsw_bq": wvc.Configure.VectorIndex.dynamic(
                 flat=wvc.Configure.VectorIndex.flat(
                     quantizer=wvc.Configure.VectorIndex.Quantizer.bq(
                         rescore_limit=rescore_limit
                     ),
-                    distance_metric=distance_metric,
+                    distance_metric=distance_metric_enum,
                 ),
                 hnsw=wvc.Configure.VectorIndex.hnsw(
                     quantizer=wvc.Configure.VectorIndex.Quantizer.bq(
                         rescore_limit=rescore_limit
                     ),
-                    distance_metric=distance_metric,
+                    distance_metric=distance_metric_enum,
                 ),
             ),
             "dynamic_hnsw_pq": wvc.Configure.VectorIndex.dynamic(
@@ -312,70 +325,70 @@ def create_collection(
                     quantizer=wvc.Configure.VectorIndex.Quantizer.sq(
                         rescore_limit=rescore_limit, training_limit=training_limit
                     ),
-                    distance_metric=distance_metric,
+                    distance_metric=distance_metric_enum,
                 )
             ),
             "dynamic_hnsw_bq": wvc.Configure.VectorIndex.dynamic(
                 hnsw=wvc.Configure.VectorIndex.hnsw(
                     quantizer=wvc.Configure.VectorIndex.Quantizer.bq(
                         rescore_limit=rescore_limit
                     ),
-                    distance_metric=distance_metric,
+                    distance_metric=distance_metric_enum,
                 )
             ),
             "hnsw_pq": wvc.Configure.VectorIndex.hnsw(
                 quantizer=wvc.Configure.VectorIndex.Quantizer.pq(
                     training_limit=training_limit
                 ),
-                distance_metric=distance_metric,
+                distance_metric=distance_metric_enum,
             ),
             "hnsw_bq": wvc.Configure.VectorIndex.hnsw(
                 quantizer=wvc.Configure.VectorIndex.Quantizer.bq(
                     rescore_limit=rescore_limit
                 ),
-                distance_metric=distance_metric,
+                distance_metric=distance_metric_enum,
             ),
             "hnsw_bq_cache": wvc.Configure.VectorIndex.hnsw(
                 quantizer=wvc.Configure.VectorIndex.Quantizer.bq(
                     cache=True, rescore_limit=rescore_limit
                 ),
-                distance_metric=distance_metric,
+                distance_metric=distance_metric_enum,
             ),
             "hnsw_sq": wvc.Configure.VectorIndex.hnsw(
                 quantizer=wvc.Configure.VectorIndex.Quantizer.sq(
                     rescore_limit=rescore_limit, training_limit=training_limit
                 ),
-                distance_metric=distance_metric,
+                distance_metric=distance_metric_enum,
             ),
             "hnsw_rq": wvc.Configure.VectorIndex.hnsw(
                 quantizer=wvc.Configure.VectorIndex.Quantizer.rq(
                     rescore_limit=rescore_limit
                 ),
-                distance_metric=distance_metric,
+                distance_metric=distance_metric_enum,
             ),
             "hnsw_acorn": wvc.Configure.VectorIndex.hnsw(
                 filter_strategy=VectorFilterStrategy.ACORN,
-                distance_metric=distance_metric,
+                distance_metric=distance_metric_enum,
             ),
             "hnsw_multivector": wvc.Configure.VectorIndex.hnsw(
                 multi_vector=wvc.Configure.VectorIndex.MultiVector.multi_vector(),
-                distance_metric=distance_metric,
+                distance_metric=distance_metric_enum,
             ),
             "flat_bq": wvc.Configure.VectorIndex.flat(
                 quantizer=wvc.Configure.VectorIndex.Quantizer.bq(
                     rescore_limit=rescore_limit
                 ),
-                distance_metric=distance_metric,
+                distance_metric=distance_metric_enum,
             ),
             "flat_bq_cache": wvc.Configure.VectorIndex.flat(
                 quantizer=wvc.Configure.VectorIndex.Quantizer.bq(
                     cache=True, rescore_limit=rescore_limit
                 ),
-                distance_metric=distance_metric,
+                distance_metric=distance_metric_enum,
             ),
             "hfresh": self._build_hfresh_config(
                 max_posting_size_kb=hfresh_max_posting_size_kb,
-                distance_metric=distance_metric,
+                distance_metric=distance_metric_enum,
                 rescore_limit=rescore_limit,
                 replicas=hfresh_replicas,
                 search_probe=hfresh_search_probe,