fix: improve error messages for unsupported index configurations

python/zvec/model/collection.py

@@ -116,6 +116,14 @@ def create_index(
         Vector index types (HNSW, IVF, FLAT) can only be applied to vector fields.
         Inverted index (`InvertIndexParam`) is for scalar fields.
 
+        Note:
+            Some combinations of vector data type and similarity metric are not yet
+            fully supported by the C++ core. For example, the cosine metric currently
+            works only with floating-point vector types; attempting to create an
+            HNSW/IVF/Flat index with `MetricType.COSINE` on an INT8 vector field will
+            result in an error. This method captures such errors and re-raises them
+            with a more descriptive message.
+
         Args:
             field_name (str): Name of the field to index.
             index_param (Union[HnswIndexParam, IVFIndexParam, FlatIndexParam, InvertIndexParam]):
@@ -125,14 +133,29 @@ def create_index(
 
         Raises:
             ValueError: If a vector index is applied to a non-vector field.
+            RuntimeError: If the combination of metric, index type, or vector data type
+                is not supported by the C++ core.
         """
-        if index_param in _VECTOR_INDEX_TYPES and not self.schema.vector(field_name):
+        if isinstance(index_param, _VECTOR_INDEX_TYPES) and not self.schema.vector(field_name):
             supported_types = ", ".join(cls.__name__ for cls in _VECTOR_INDEX_TYPES)
             raise ValueError(
                 f"Cannot apply vector index to non-vector field '{field_name}'. "
                 f"The field must be of vector type to use index types like {supported_types}."
             )
-        self._obj.CreateIndex(field_name, index_param, option)
+
+        # Attempt to create the index in the C++ core. If it fails (e.g., due to
+        # an unsupported configuration, metric, or data type), catch the error
+        # and provide a more informative message.
+        try:
+            self._obj.CreateIndex(field_name, index_param, option)
+        except RuntimeError as exc:
+            raise RuntimeError(
+                f"Failed to create index on field '{field_name}' with "
+                f"{type(index_param).__name__}. This may occur when using a "
+                f"configuration, metric, or data type that is not yet supported "
+                f"for this index type. Original error: {exc}"
+            ) from exc
+
         self._schema = CollectionSchema._from_core(self._obj.Schema())
 
     def drop_index(self, field_name: str) -> None:
@@ -150,8 +173,23 @@ def optimize(self, option: OptimizeOption = OptimizeOption()) -> None:
         Args:
             option (Optional[OptimizeOption], optional): Optimization options.
                 Defaults to ``OptimizeOption()``.
+
+        Raises:
+            RuntimeError: If optimization fails, possibly due to unsupported index
+                configurations or metrics.
         """
-        self._obj.Optimize(option)
+        try:
+            self._obj.Optimize(option)
+        except RuntimeError as exc:
+            try:
+                collection_path = self.path
+            except Exception:
+                collection_path = "<unavailable>"
+            raise RuntimeError(
+                f"Failed to optimize collection at '{collection_path}'. This may be "
+                f"triggered by unsupported index configurations or metrics. "
+                f"Original error: {exc}"
+            ) from exc
 
     # ========== COLUMN DDL Methods ==========
     def add_column(