chore: import upstream snapshot with attribution

python/tests/detail/distance_helper.py

@@ -0,0 +1,392 @@
+import logging
+import math
+import numpy as np
+
+from zvec import (
+    MetricType,
+    DataType,
+    QuantizeType,
+    Doc,
+    CollectionSchema,
+    FieldSchema,
+    VectorSchema,
+)
+
+from typing import Dict
+
+
+def is_float_equal(actual, expected, rel_tol=1e-5, abs_tol=1e-8):
+    if actual is None and expected is None:
+        return True
+    return math.isclose(actual, expected, rel_tol=rel_tol, abs_tol=abs_tol)
+
+
+def is_dense_vector_equal(vec1, vec2, rtol=1e-5, atol=1e-8):
+    """Compare two dense vectors with tolerance."""
+    return np.allclose(vec1, vec2, rtol=rtol, atol=atol)
+
+
+def is_sparse_vector_equal(vec1, vec2, rtol=1e-5, atol=1e-8):
+    """Compare two sparse vectors with tolerance."""
+    # Check if they have the same keys
+    if set(vec1.keys()) != set(vec2.keys()):
+        return False
+
+    # Check if all values are close
+    for key in vec1:
+        if not math.isclose(vec1[key], vec2[key], rel_tol=rtol, abs_tol=atol):
+            return False
+
+    return True
+
+
+def is_float_array_equal(arr1, arr2, rtol=1e-5, atol=1e-8):
+    """Compare two float arrays with tolerance."""
+    return np.allclose(arr1, arr2, rtol=rtol, atol=atol)
+
+
+def is_double_array_equal(arr1, arr2, rtol=1e-9, atol=1e-12):
+    """Compare two double arrays with tolerance."""
+    return np.allclose(arr1, arr2, rtol=rtol, atol=atol)
+
+
+def is_int_array_equal(arr1, arr2):
+    """Compare two integer arrays with exact equality."""
+    return np.array_equal(arr1, arr2)
+
+
+def cosine_distance_dense(
+    vec1,
+    vec2,
+    dtype: DataType = DataType.VECTOR_FP32,
+    quantize_type: QuantizeType = QuantizeType.UNDEFINED,
+):
+    if dtype == DataType.VECTOR_FP16 or quantize_type == QuantizeType.FP16:
+        # More stable conversion to float16 to avoid numerical issues
+        vec1 = [float(np.float16(a)) for a in vec1]
+        vec2 = [float(np.float16(b)) for b in vec2]
+    elif dtype == DataType.VECTOR_INT8:
+        # For INT8 vectors, convert to integers for proper calculation
+        vec1 = [
+            int(round(min(max(val, -128), 127))) for val in vec1
+        ]  # Clamp to valid INT8 range
+        vec2 = [
+            int(round(min(max(val, -128), 127))) for val in vec2
+        ]  # Clamp to valid INT8 range
+
+    dot_product = sum(a * b for a, b in zip(vec1, vec2))
+
+    magnitude1 = math.sqrt(sum(a * a for a in vec1))
+    magnitude2 = math.sqrt(sum(b * b for b in vec2))
+
+    if magnitude1 == 0 or magnitude2 == 0:
+        return 1.0  # Zero vector case - maximum distance
+
+    cosine_similarity = dot_product / (magnitude1 * magnitude2)
+
+    # Clamp to [-1, 1] range to handle floating-point precision errors
+    cosine_similarity = max(-1.0, min(1.0, cosine_similarity))
+
+    # For identical vectors (within floating point precision), ensure cosine distance is 0.0
+    # This is especially important for low-precision types which have limited precision
+    if (
+        dtype == DataType.VECTOR_FP16
+        or quantize_type == QuantizeType.FP16
+        or dtype == DataType.VECTOR_INT8
+    ):
+        if (
+            abs(cosine_similarity - 1.0) < 1e-3
+        ):  # Handle precision issues for low-precision types
+            cosine_similarity = 1.0
+
+    # Return cosine distance (1 - cosine similarity) to maintain compatibility
+    # with system internal processing and existing test expectations
+    return 1.0 - cosine_similarity
+
+
+def dp_distance_dense(
+    vec1,
+    vec2,
+    dtype: DataType = DataType.VECTOR_FP32,
+    quantize_type: QuantizeType = QuantizeType.UNDEFINED,
+):
+    if dtype == DataType.VECTOR_FP16 or quantize_type == QuantizeType.FP16:
+        # More stable computation to avoid numerical issues
+        products = [
+            float(np.float16(a)) * float(np.float16(b)) for a, b in zip(vec1, vec2)
+        ]
+        return sum(products)
+    elif dtype == DataType.VECTOR_INT8:
+        # For INT8 vectors, convert to integers for proper calculation
+        products = [
+            int(round(min(max(a, -128), 127))) * int(round(min(max(b, -128), 127)))
+            for a, b in zip(vec1, vec2)
+        ]
+        return sum(products)
+    return sum(a * b for a, b in zip(vec1, vec2))
+
+
+def euclidean_distance_dense(
+    vec1,
+    vec2,
+    dtype: DataType = DataType.VECTOR_FP32,
+    quantize_type: QuantizeType = QuantizeType.UNDEFINED,
+):
+    if dtype == DataType.VECTOR_FP16 or quantize_type == QuantizeType.FP16:
+        # Convert to float16 and compute squared differences safely
+        # Use a more stable computation to avoid overflow
+        squared_diffs = []
+        for a, b in zip(vec1, vec2):
+            diff = np.float16(a) - np.float16(b)
+            squared_diff = float(diff) * float(
+                diff
+            )  # Convert to float for multiplication
+            squared_diffs.append(squared_diff)
+        squared_distance = sum(squared_diffs)
+    elif dtype == DataType.VECTOR_INT8:
+        # For INT8 vectors, convert to integers and handle potential scaling
+        # INT8 values might be treated differently in the library implementation
+        vec1_int = [
+            int(round(min(max(val, -128), 127))) for val in vec1
+        ]  # Clamp to valid INT8 range
+        vec2_int = [
+            int(round(min(max(val, -128), 127))) for val in vec2
+        ]  # Clamp to valid INT8 range
+        # Use float type to prevent overflow when summing large squared differences
+        squared_distance = sum(float(a - b) ** 2 for a, b in zip(vec1_int, vec2_int))
+    else:
+        squared_distance = sum((a - b) ** 2 for a, b in zip(vec1, vec2))
+
+    return squared_distance  # Return squared distance for INT8
+
+
+def distance_dense(
+    vec1,
+    vec2,
+    metric: MetricType,
+    data_type: DataType = DataType.VECTOR_FP32,
+    quantize_type: QuantizeType = QuantizeType.UNDEFINED,
+):
+    if metric == MetricType.COSINE:
+        return cosine_distance_dense(vec1, vec2, data_type, quantize_type)
+    elif metric == MetricType.L2:
+        return euclidean_distance_dense(vec1, vec2, data_type, quantize_type)
+    elif metric == MetricType.IP:
+        return dp_distance_dense(vec1, vec2, data_type, quantize_type)
+    else:
+        raise ValueError("Unsupported metric type")
+
+
+def dp_distance_sparse(
+    vec1,
+    vec2,
+    data_type: DataType = DataType.SPARSE_VECTOR_FP32,
+    quantize_type: QuantizeType = QuantizeType.UNDEFINED,
+):
+    dot_product = 0.0
+    for dim in set(vec1.keys()) & set(vec2.keys()):
+        print("dim,vec1,vec2:\n")
+        print(dim, vec1, vec2)
+        if (
+            data_type == DataType.SPARSE_VECTOR_FP16
+            or quantize_type == QuantizeType.FP16
+        ):
+            vec1[dim] = np.float16(vec1[dim])
+            vec2[dim] = np.float16(vec2[dim])
+        dot_product += vec1[dim] * vec2[dim]
+    return dot_product
+
+
+def distance(
+    vec1,
+    vec2,
+    metric: MetricType,
+    data_type: DataType,
+    quantize_type: QuantizeType = QuantizeType.UNDEFINED,
+):
+    is_sparse = (
+        data_type == DataType.SPARSE_VECTOR_FP32
+        or data_type == DataType.SPARSE_VECTOR_FP16
+    )
+
+    if is_sparse:
+        if metric != MetricType.IP:
+            raise ValueError("Unsupported metric type for sparse vectors")
+
+    if is_sparse:
+        return dp_distance_sparse(vec1, vec2, data_type, quantize_type)
+    else:
+        return distance_dense(vec1, vec2, metric, data_type, quantize_type)
+
+
+def distance_recall(
+    vec1,
+    vec2,
+    metric: MetricType,
+    data_type: DataType,
+    quantize_type: QuantizeType = QuantizeType.UNDEFINED,
+):
+    is_sparse = (
+        data_type == DataType.SPARSE_VECTOR_FP32
+        or data_type == DataType.SPARSE_VECTOR_FP16
+    )
+
+    if is_sparse:
+        return dp_distance_sparse(vec1, vec2, data_type, quantize_type)
+    else:
+        if data_type in [DataType.VECTOR_FP32, DataType.VECTOR_FP16]:
+            return distance_dense(vec1, vec2, metric, data_type, quantize_type)
+        elif data_type in [DataType.VECTOR_INT8] and metric in [
+            MetricType.L2,
+            MetricType.IP,
+        ]:
+            return distance_dense(vec1, vec2, metric, data_type, quantize_type)
+        else:
+            return dp_distance_dense(vec1, vec2, data_type, quantize_type)
+
+
+def calculate_rrf_score(rank, k=60):
+    return 1.0 / (k + rank + 1)
+
+
+def calculate_multi_vector_rrf_scores(query_results: Dict[str, Doc], k=60):
+    rrf_scores = {}
+
+    for vector_name, docs in query_results.items():
+        for rank, doc in enumerate(docs):
+            doc_id = doc.id
+            rrf_score = calculate_rrf_score(rank, k)
+            if doc_id in rrf_scores:
+                rrf_scores[doc_id] += rrf_score
+            else:
+                rrf_scores[doc_id] = rrf_score
+
+    return rrf_scores
+
+
+def calculate_multi_vector_weighted_scores(
+    query_results: Dict[str, Doc], weights: Dict[str, float], metric: MetricType
+):
+    def _normalize_score(score: float, metric: MetricType) -> float:
+        if metric == MetricType.L2:
+            return 1.0 - 2 * math.atan(score) / math.pi
+        if metric == MetricType.IP:
+            return 0.5 + math.atan(score) / math.pi
+        if metric == MetricType.COSINE:
+            return 1.0 - score / 2.0
+        raise ValueError("Unsupported metric type")
+
+    weighted_scores = {}
+
+    for vector_name, docs in query_results.items():
+        weight = weights.get(vector_name, 1.0)
+
+        for doc in docs:
+            doc_id = doc.id
+            weighted_score = (_normalize_score(doc.score, metric)) * weight
+            if doc_id in weighted_scores:
+                weighted_scores[doc_id] += weighted_score
+            else:
+                weighted_scores[doc_id] = weighted_score
+
+    return weighted_scores
+
+
+def is_field_equal(field1, field2, schema: FieldSchema) -> bool:
+    if field1 is None and field2 is None:
+        return True
+    if field1 is None or field2 is None:
+        return False
+
+    if schema.data_type == DataType.ARRAY_FLOAT:
+        return is_float_array_equal(field1, field2)
+    elif schema.data_type == DataType.ARRAY_DOUBLE:
+        return is_double_array_equal(field1, field2)
+    elif schema.data_type in [
+        DataType.ARRAY_INT32,
+        DataType.ARRAY_INT64,
+        DataType.ARRAY_BOOL,
+        DataType.ARRAY_STRING,
+        DataType.ARRAY_UINT32,
+        DataType.ARRAY_UINT64,
+        DataType.ARRAY_INT64,
+    ]:
+        return is_int_array_equal(field1, field2)
+    elif schema.data_type in [DataType.FLOAT, DataType.DOUBLE]:
+        return is_float_equal(field1, field2)
+
+    return field1 == field2
+
+
+def is_vector_equal(vec1, vec2, schema: VectorSchema) -> bool:
+    if (
+        schema.data_type == DataType.SPARSE_VECTOR_FP16
+        or schema.data_type == DataType.VECTOR_FP16
+    ):
+        # skip fp16 vector equal
+        return True
+
+    is_sparse = (
+        schema.data_type == DataType.SPARSE_VECTOR_FP32
+        or schema.data_type == DataType.SPARSE_VECTOR_FP16
+    )
+
+    if is_sparse:
+        return is_sparse_vector_equal(vec1, vec2)
+    else:
+        return is_dense_vector_equal(vec1, vec2)
+
+
+def is_doc_equal(
+    doc1: Doc,
+    doc2: Doc,
+    schema: CollectionSchema,
+    except_score: bool = True,
+    include_vector: bool = True,
+):
+    if doc1.id != doc2.id:
+        logging.error("doc ids are not equal")
+        return False
+
+    reduce_field_names = set(doc1.field_names() + doc2.field_names())
+    reduce_vector_names = set(doc1.vector_names() + doc2.vector_names())
+
+    is_doc1_fields_empty = doc1.fields is None or doc1.fields == {}
+    is_doc2_fields_empty = doc2.fields is None or doc2.fields == {}
+
+    if is_doc1_fields_empty or is_doc2_fields_empty:
+        if is_doc1_fields_empty != is_doc2_fields_empty:
+            return False
+    else:
+        for field_name in reduce_field_names:
+            field_schema = schema.field(field_name)
+            if field_schema is None:
+                return False
+            if is_field_equal(
+                doc1.field(field_name), doc2.field(field_name), field_schema
+            ):
+                continue
+            else:
+                logging.error(f"{field_name} are not equal")
+                return False
+
+    if include_vector:
+        is_doc1_vectors_empty = doc1.vectors is None or doc1.vectors == {}
+        is_doc2_vectors_empty = doc2.vectors is None or doc2.vectors == {}
+
+        if is_doc1_vectors_empty or is_doc2_vectors_empty:
+            if is_doc1_fields_empty != is_doc2_vectors_empty:
+                return False
+        else:
+            for vector_name in reduce_vector_names:
+                vector_schema = schema.vector(vector_name)
+                if vector_schema is None:
+                    return False
+                if is_vector_equal(
+                    doc1.vector(vector_name), doc2.vector(vector_name), vector_schema
+                ):
+                    continue
+                else:
+                    return False
+
+    return True

python/tests/detail/doc_helper.py

@@ -0,0 +1,464 @@
+from zvec import CollectionSchema, Doc
+
+from support_helper import *
+
+import numpy as np
+from typing import Literal, Optional, Union, Tuple
+
+import random
+import string
+import math
+
+
+def generate_constant_vector(
+    i: int, dimension: int, dtype: Literal["int8", "float16", "float32"] = "float32"
+):
+    if dtype == "int8":
+        vec = [(i % 127)] * dimension
+        vec[i % dimension] = (i + 1) % 127
+    else:
+        base_val = (i % 1000) / 256.0
+        special_val = ((i + 1) % 1000) / 256.0
+        vec = [base_val] * dimension
+        vec[i % dimension] = special_val
+
+    return vec
+
+
+def generate_constant_vector_recall(
+    i: int, dimension: int, dtype: Literal["int8", "float16", "float32"] = "float32"
+):
+    if dtype == "int8":
+        vec = [(i % 127)] * dimension
+        vec[i % dimension] = (i + 1) % 127
+    else:
+        base_val = math.sin((i) * 1000) / 256.0
+        special_val = math.sin((i + 1) * 1000) / 256.0
+        vec = [base_val] * dimension
+        vec[i % dimension] = special_val
+
+    return vec
+
+
+def generate_sparse_vector(i: int):
+    return {i: i + 0.1}
+
+
+def generate_vectordict(i: int, schema: CollectionSchema) -> Doc:
+    doc_fields = {}
+    doc_vectors = {}
+    doc_fields = {}
+    doc_vectors = {}
+    for field in schema.fields:
+        if field.data_type == DataType.BOOL:
+            doc_fields[field.name] = i % 2 == 0
+        elif field.data_type == DataType.INT32:
+            doc_fields[field.name] = i
+        elif field.data_type == DataType.UINT32:
+            doc_fields[field.name] = i
+        elif field.data_type == DataType.INT64:
+            doc_fields[field.name] = i
+        elif field.data_type == DataType.UINT64:
+            doc_fields[field.name] = i
+        elif field.data_type == DataType.FLOAT:
+            doc_fields[field.name] = float(i) + 0.1
+        elif field.data_type == DataType.DOUBLE:
+            doc_fields[field.name] = float(i) + 0.11
+        elif field.data_type == DataType.STRING:
+            doc_fields[field.name] = f"test_{i}"
+        elif field.data_type == DataType.ARRAY_BOOL:
+            doc_fields[field.name] = [i % 2 == 0, i % 3 == 0]
+        elif field.data_type == DataType.ARRAY_INT32:
+            doc_fields[field.name] = [i, i + 1, i + 2]
+        elif field.data_type == DataType.ARRAY_UINT32:
+            doc_fields[field.name] = [i, i + 1, i + 2]
+        elif field.data_type == DataType.ARRAY_INT64:
+            doc_fields[field.name] = [i, i + 1, i + 2]
+        elif field.data_type == DataType.ARRAY_UINT64:
+            doc_fields[field.name] = [i, i + 1, i + 2]
+        elif field.data_type == DataType.ARRAY_FLOAT:
+            doc_fields[field.name] = [float(i + 0.1), float(i + 1.1), float(i + 2.1)]
+        elif field.data_type == DataType.ARRAY_DOUBLE:
+            doc_fields[field.name] = [float(i + 0.11), float(i + 1.11), float(i + 2.11)]
+        elif field.data_type == DataType.ARRAY_STRING:
+            doc_fields[field.name] = [f"test_{i}", f"test_{i + 1}", f"test_{i + 2}"]
+        else:
+            raise ValueError(f"Unsupported field type: {field.data_type}")
+    for vector in schema.vectors:
+        if vector.data_type == DataType.VECTOR_FP16:
+            doc_vectors[vector.name] = generate_constant_vector(
+                i, vector.dimension, "float16"
+            )
+        elif vector.data_type == DataType.VECTOR_FP32:
+            doc_vectors[vector.name] = generate_constant_vector(
+                i, vector.dimension, "float32"
+            )
+        elif vector.data_type == DataType.VECTOR_INT8:
+            doc_vectors[vector.name] = generate_constant_vector(
+                i,
+                vector.dimension,
+                "int8",
+            )
+        elif vector.data_type == DataType.SPARSE_VECTOR_FP32:
+            doc_vectors[vector.name] = generate_sparse_vector(i)
+        elif vector.data_type == DataType.SPARSE_VECTOR_FP16:
+            doc_vectors[vector.name] = generate_sparse_vector(i)
+        else:
+            raise ValueError(f"Unsupported vector type: {vector.data_type}")
+    return doc_fields, doc_vectors
+
+
+def generate_vectordict_recall(i: int, schema: CollectionSchema) -> Doc:
+    doc_fields = {}
+    doc_vectors = {}
+    doc_fields = {}
+    doc_vectors = {}
+    for field in schema.fields:
+        if field.data_type == DataType.BOOL:
+            doc_fields[field.name] = i % 2 == 0
+        elif field.data_type == DataType.INT32:
+            doc_fields[field.name] = i
+        elif field.data_type == DataType.UINT32:
+            doc_fields[field.name] = i
+        elif field.data_type == DataType.INT64:
+            doc_fields[field.name] = i
+        elif field.data_type == DataType.UINT64:
+            doc_fields[field.name] = i
+        elif field.data_type == DataType.FLOAT:
+            doc_fields[field.name] = float(i) + 0.1
+        elif field.data_type == DataType.DOUBLE:
+            doc_fields[field.name] = float(i) + 0.11
+        elif field.data_type == DataType.STRING:
+            doc_fields[field.name] = f"test_{i}"
+        elif field.data_type == DataType.ARRAY_BOOL:
+            doc_fields[field.name] = [i % 2 == 0, i % 3 == 0]
+        elif field.data_type == DataType.ARRAY_INT32:
+            doc_fields[field.name] = [i, i + 1, i + 2]
+        elif field.data_type == DataType.ARRAY_UINT32:
+            doc_fields[field.name] = [i, i + 1, i + 2]
+        elif field.data_type == DataType.ARRAY_INT64:
+            doc_fields[field.name] = [i, i + 1, i + 2]
+        elif field.data_type == DataType.ARRAY_UINT64:
+            doc_fields[field.name] = [i, i + 1, i + 2]
+        elif field.data_type == DataType.ARRAY_FLOAT:
+            doc_fields[field.name] = [float(i + 0.1), float(i + 1.1), float(i + 2.1)]
+        elif field.data_type == DataType.ARRAY_DOUBLE:
+            doc_fields[field.name] = [float(i + 0.11), float(i + 1.11), float(i + 2.11)]
+        elif field.data_type == DataType.ARRAY_STRING:
+            doc_fields[field.name] = [f"test_{i}", f"test_{i + 1}", f"test_{i + 2}"]
+        else:
+            raise ValueError(f"Unsupported field type: {field.data_type}")
+    for vector in schema.vectors:
+        if vector.data_type == DataType.VECTOR_FP16:
+            doc_vectors[vector.name] = generate_constant_vector_recall(
+                i, vector.dimension, "float16"
+            )
+        elif vector.data_type == DataType.VECTOR_FP32:
+            doc_vectors[vector.name] = generate_constant_vector_recall(
+                i, vector.dimension, "float32"
+            )
+        elif vector.data_type == DataType.VECTOR_INT8:
+            doc_vectors[vector.name] = generate_constant_vector_recall(
+                i,
+                vector.dimension,
+                "int8",
+            )
+        elif vector.data_type == DataType.SPARSE_VECTOR_FP32:
+            doc_vectors[vector.name] = generate_sparse_vector(i)
+        elif vector.data_type == DataType.SPARSE_VECTOR_FP16:
+            doc_vectors[vector.name] = generate_sparse_vector(i)
+        else:
+            raise ValueError(f"Unsupported vector type: {vector.data_type}")
+    return doc_fields, doc_vectors
+
+
+def generate_vectordict_update(i: int, schema: CollectionSchema) -> Doc:
+    doc_fields = {}
+    doc_vectors = {}
+    doc_fields = {}
+    doc_vectors = {}
+    for field in schema.fields:
+        if field.data_type == DataType.BOOL:
+            doc_fields[field.name] = (i + 1) % 2 == 0
+        elif field.data_type == DataType.INT32:
+            doc_fields[field.name] = i + 1
+        elif field.data_type == DataType.UINT32:
+            doc_fields[field.name] = i + 1
+        elif field.data_type == DataType.INT64:
+            doc_fields[field.name] = i + 1
+        elif field.data_type == DataType.UINT64:
+            doc_fields[field.name] = i + 1
+        elif field.data_type == DataType.FLOAT:
+            doc_fields[field.name] = float(i + 1) + 0.1
+        elif field.data_type == DataType.DOUBLE:
+            doc_fields[field.name] = float(i + 1) + 0.11
+        elif field.data_type == DataType.STRING:
+            doc_fields[field.name] = f"test_{i + 1}"
+        elif field.data_type == DataType.ARRAY_BOOL:
+            doc_fields[field.name] = [(i + 1) % 2 == 0, (i + 1) % 3 == 0]
+        elif field.data_type == DataType.ARRAY_INT32:
+            doc_fields[field.name] = [i + 1, i + 1, i + 2]
+        elif field.data_type == DataType.ARRAY_UINT32:
+            doc_fields[field.name] = [i + 1, i + 1, i + 2]
+        elif field.data_type == DataType.ARRAY_INT64:
+            doc_fields[field.name] = [i + 1, i + 1, i + 2]
+        elif field.data_type == DataType.ARRAY_UINT64:
+            doc_fields[field.name] = [i + 1, i + 1, i + 2]
+        elif field.data_type == DataType.ARRAY_FLOAT:
+            doc_fields[field.name] = [float(i + 1.1), float(i + 2.1), float(i + 3.1)]
+        elif field.data_type == DataType.ARRAY_DOUBLE:
+            doc_fields[field.name] = [float(i + 1.11), float(i + 2.11), float(i + 3.11)]
+        elif field.data_type == DataType.ARRAY_STRING:
+            doc_fields[field.name] = [f"test_{i + 1}", f"test_{i + 2}", f"test_{i + 3}"]
+        else:
+            raise ValueError(f"Unsupported field type: {field.data_type}")
+    for vector in schema.vectors:
+        if vector.data_type == DataType.VECTOR_FP16:
+            doc_vectors[vector.name] = generate_constant_vector(
+                i + 1, vector.dimension, "float16"
+            )
+        elif vector.data_type == DataType.VECTOR_FP32:
+            doc_vectors[vector.name] = generate_constant_vector(
+                i + 1, vector.dimension, "float32"
+            )
+        elif vector.data_type == DataType.VECTOR_INT8:
+            doc_vectors[vector.name] = generate_constant_vector(
+                i + 1,
+                vector.dimension,
+                "int8",
+            )
+        elif vector.data_type == DataType.SPARSE_VECTOR_FP32:
+            doc_vectors[vector.name] = generate_sparse_vector(i + 1)
+        elif vector.data_type == DataType.SPARSE_VECTOR_FP16:
+            doc_vectors[vector.name] = generate_sparse_vector(i + 1)
+        else:
+            raise ValueError(f"Unsupported vector type: {vector.data_type}")
+    return doc_fields, doc_vectors
+
+
+def generate_doc(i: int, schema: CollectionSchema) -> Doc:
+    doc_fields = {}
+    doc_vectors = {}
+    doc_fields, doc_vectors = generate_vectordict(i, schema)
+    doc = Doc(id=str(i), fields=doc_fields, vectors=doc_vectors)
+    return doc
+
+
+def generate_doc_recall(i: int, schema: CollectionSchema) -> Doc:
+    doc_fields = {}
+    doc_vectors = {}
+    doc_fields, doc_vectors = generate_vectordict_recall(i, schema)
+    doc = Doc(id=str(i), fields=doc_fields, vectors=doc_vectors)
+    return doc
+
+
+def generate_update_doc(i: int, schema: CollectionSchema) -> Doc:
+    doc_fields = {}
+    doc_vectors = {}
+    doc_fields, doc_vectors = generate_vectordict_update(i, schema)
+    doc = Doc(id=str(i), fields=doc_fields, vectors=doc_vectors)
+    return doc
+
+
+def generate_doc_random(i, schema: CollectionSchema) -> Doc:
+    doc_fields = {}
+    doc_vectors = {}
+
+    random.seed(i)
+
+    for field in schema.fields:
+        if field.data_type == DataType.BOOL:
+            doc_fields[field.name] = random.choice([True, False])
+        elif field.data_type == DataType.INT32:
+            doc_fields[field.name] = random.randint(-2147483648, 2147483647)
+        elif field.data_type == DataType.UINT32:
+            doc_fields[field.name] = random.randint(0, 4294967295)
+        elif field.data_type == DataType.INT64:
+            doc_fields[field.name] = random.randint(
+                -9223372036854775808, 9223372036854775807
+            )
+        elif field.data_type == DataType.UINT64:
+            doc_fields[field.name] = random.randint(0, 18446744073709551615)
+        elif field.data_type == DataType.FLOAT:
+            doc_fields[field.name] = random.uniform(-3.4028235e38, 3.4028235e38)
+        elif field.data_type == DataType.DOUBLE:
+            doc_fields[field.name] = random.uniform(
+                -1.7976931348623157e308, 1.7976931348623157e308
+            )
+        elif field.data_type == DataType.STRING:
+            length = random.randint(1, 999)
+            doc_fields[field.name] = "".join(
+                random.choices(string.ascii_letters + string.digits, k=length)
+            )
+        elif field.data_type == DataType.ARRAY_BOOL:
+            array_length = random.randint(0, 10)
+            doc_fields[field.name] = [
+                random.choice([True, False]) for _ in range(array_length)
+            ]
+        elif field.data_type == DataType.ARRAY_INT32:
+            array_length = random.randint(0, 10)
+            doc_fields[field.name] = [
+                random.randint(-2147483648, 2147483647) for _ in range(array_length)
+            ]
+        elif field.data_type == DataType.ARRAY_UINT32:
+            array_length = random.randint(0, 10)
+            doc_fields[field.name] = [
+                random.randint(0, 4294967295) for _ in range(array_length)
+            ]
+        elif field.data_type == DataType.ARRAY_INT64:
+            array_length = random.randint(0, 10)
+            doc_fields[field.name] = [
+                random.randint(-9223372036854775808, 9223372036854775807)
+                for _ in range(array_length)
+            ]
+        elif field.data_type == DataType.ARRAY_UINT64:
+            array_length = random.randint(0, 10)
+            doc_fields[field.name] = [
+                random.randint(0, 18446744073709551615) for _ in range(array_length)
+            ]
+        elif field.data_type == DataType.ARRAY_FLOAT:
+            array_length = random.randint(0, 10)
+            doc_fields[field.name] = [
+                random.uniform(-3.4028235e38, 3.4028235e38) for _ in range(array_length)
+            ]
+        elif field.data_type == DataType.ARRAY_DOUBLE:
+            array_length = random.randint(0, 10)
+            doc_fields[field.name] = [
+                random.uniform(-1.7976931348623157e308, 1.7976931348623157e308)
+                for _ in range(array_length)
+            ]
+        elif field.data_type == DataType.ARRAY_STRING:
+            array_length = random.randint(0, 10)
+            doc_fields[field.name] = [
+                "".join(
+                    random.choices(
+                        string.ascii_letters + string.digits, k=random.randint(1, 100)
+                    )
+                )
+                for _ in range(array_length)
+            ]
+        else:
+            raise ValueError(f"Unsupported field type: {field.data_type}")
+
+    for vector in schema.vectors:
+        if vector.data_type == DataType.VECTOR_FP16:
+            doc_vectors[vector.name] = generate_constant_vector(
+                random.randint(1, 100), DEFAULT_VECTOR_DIMENSION, "float16"
+            )
+        elif vector.data_type == DataType.VECTOR_FP32:
+            doc_vectors[vector.name] = generate_constant_vector(
+                random.randint(1, 100), DEFAULT_VECTOR_DIMENSION, "float32"
+            )
+        elif vector.data_type == DataType.VECTOR_INT8:
+            doc_vectors[vector.name] = generate_constant_vector(
+                random.randint(1, 100), DEFAULT_VECTOR_DIMENSION, "int8"
+            )
+        elif vector.data_type == DataType.SPARSE_VECTOR_FP32:
+            doc_vectors[vector.name] = generate_sparse_vector(random.randint(1, 100))
+        elif vector.data_type == DataType.SPARSE_VECTOR_FP16:
+            doc_vectors[vector.name] = generate_sparse_vector(random.randint(1, 100))
+        else:
+            raise ValueError(f"Unsupported vector type: {vector.data_type}")
+
+    doc = Doc(id=i, fields=doc_fields, vectors=doc_vectors)
+    return doc
+
+
+def generate_vectordict_random(schema: CollectionSchema):
+    doc_fields = {}
+    doc_vectors = {}
+    for field in schema.fields:
+        if field.data_type == DataType.BOOL:
+            doc_fields[field.name] = random.choice([True, False])
+        elif field.data_type == DataType.INT32:
+            doc_fields[field.name] = random.randint(-2147483648, 2147483647)
+        elif field.data_type == DataType.UINT32:
+            doc_fields[field.name] = random.randint(0, 4294967295)
+        elif field.data_type == DataType.INT64:
+            doc_fields[field.name] = random.randint(
+                -9223372036854775808, 9223372036854775807
+            )
+        elif field.data_type == DataType.UINT64:
+            doc_fields[field.name] = random.randint(0, 18446744073709551615)
+        elif field.data_type == DataType.FLOAT:
+            doc_fields[field.name] = random.uniform(-3.4028235e38, 3.4028235e38)
+        elif field.data_type == DataType.DOUBLE:
+            doc_fields[field.name] = random.uniform(
+                -1.7976931348623157e308, 1.7976931348623157e308
+            )
+        elif field.data_type == DataType.STRING:
+            length = random.randint(1, 999)
+            doc_fields[field.name] = "".join(
+                random.choices(string.ascii_letters + string.digits, k=length)
+            )
+        elif field.data_type == DataType.ARRAY_BOOL:
+            array_length = random.randint(0, 10)
+            doc_fields[field.name] = [
+                random.choice([True, False]) for _ in range(array_length)
+            ]
+        elif field.data_type == DataType.ARRAY_INT32:
+            array_length = random.randint(0, 10)
+            doc_fields[field.name] = [
+                random.randint(-2147483648, 2147483647) for _ in range(array_length)
+            ]
+        elif field.data_type == DataType.ARRAY_UINT32:
+            array_length = random.randint(0, 10)
+            doc_fields[field.name] = [
+                random.randint(0, 4294967295) for _ in range(array_length)
+            ]
+        elif field.data_type == DataType.ARRAY_INT64:
+            array_length = random.randint(0, 10)
+            doc_fields[field.name] = [
+                random.randint(-9223372036854775808, 9223372036854775807)
+                for _ in range(array_length)
+            ]
+        elif field.data_type == DataType.ARRAY_UINT64:
+            array_length = random.randint(0, 10)
+            doc_fields[field.name] = [
+                random.randint(0, 18446744073709551615) for _ in range(array_length)
+            ]
+        elif field.data_type == DataType.ARRAY_FLOAT:
+            array_length = random.randint(0, 10)
+            doc_fields[field.name] = [
+                random.uniform(-3.4028235e38, 3.4028235e38) for _ in range(array_length)
+            ]
+        elif field.data_type == DataType.ARRAY_DOUBLE:
+            array_length = random.randint(0, 10)
+            doc_fields[field.name] = [
+                random.uniform(-1.7976931348623157e308, 1.7976931348623157e308)
+                for _ in range(array_length)
+            ]
+        elif field.data_type == DataType.ARRAY_STRING:
+            array_length = random.randint(0, 10)
+            doc_fields[field.name] = [
+                "".join(
+                    random.choices(
+                        string.ascii_letters + string.digits, k=random.randint(1, 100)
+                    )
+                )
+                for _ in range(array_length)
+            ]
+        else:
+            raise ValueError(f"Unsupported field type: {field.data_type}")
+
+    for vector in schema.vectors:
+        if vector.data_type == DataType.VECTOR_FP16:
+            doc_vectors[vector.name] = generate_constant_vector(
+                random.randint(1, 100), vector.dimension, "float16"
+            )
+        elif vector.data_type == DataType.VECTOR_FP32:
+            doc_vectors[vector.name] = generate_constant_vector(
+                random.randint(1, 100), vector.dimension, "float32"
+            )
+        elif vector.data_type == DataType.VECTOR_INT8:
+            doc_vectors[vector.name] = generate_constant_vector(
+                random.randint(1, 100), vector.dimension, "int8"
+            )
+        elif vector.data_type == DataType.SPARSE_VECTOR_FP32:
+            doc_vectors[vector.name] = generate_sparse_vector(random.randint(1, 100))
+        elif vector.data_type == DataType.SPARSE_VECTOR_FP16:
+            doc_vectors[vector.name] = generate_sparse_vector(random.randint(1, 100))
+        else:
+            raise ValueError(f"Unsupported vector type: {vector.data_type}")
+
+    return doc_fields, doc_vectors

python/tests/detail/fixture_helper.py

@@ -0,0 +1,652 @@
+import pytest
+import logging
+import platform
+
+DISKANN_SUPPORTED = platform.system() == "Linux" and platform.machine() in (
+    "x86_64",
+    "AMD64",
+    "i686",
+    "i386",
+)
+
+from typing import Any, Generator
+from zvec.typing import DataType, StatusCode, MetricType, QuantizeType
+import zvec
+
+
+# Cache the DiskAnn plugin preload status so we pay the load cost once per
+# test session. The plugin normally auto-loads on first DiskAnn use, but we
+# preload it explicitly here so a missing libaio / misplaced plugin .so
+# surfaces as a clear pytest skip instead of a confusing
+# "Create vector column indexer failed" deep inside the collection code path.
+_DISKANN_PRELOAD_REASON: str | None = None
+_DISKANN_PRELOAD_DONE: bool = False
+
+
+def _ensure_diskann_runtime_or_reason() -> str | None:
+    """Preload the DiskAnn plugin and return None on success or a human-readable
+    skip reason on failure. Idempotent across calls."""
+    global _DISKANN_PRELOAD_DONE, _DISKANN_PRELOAD_REASON
+    if _DISKANN_PRELOAD_DONE:
+        return _DISKANN_PRELOAD_REASON
+    _DISKANN_PRELOAD_DONE = True
+
+    if not DISKANN_SUPPORTED:
+        _DISKANN_PRELOAD_REASON = "DiskAnn only supported on Linux x86_64"
+        return _DISKANN_PRELOAD_REASON
+
+    if not zvec.is_libaio_available():
+        _DISKANN_PRELOAD_REASON = (
+            "libaio is not available on this host; DiskAnn cannot run. "
+            "Install libaio1 (or libaio1t64 on Ubuntu 24.04+) and retry."
+        )
+        return _DISKANN_PRELOAD_REASON
+
+    status = zvec.load_diskann_plugin()
+    if status != zvec.DISKANN_PLUGIN_OK:
+        _DISKANN_PRELOAD_REASON = (
+            f"Failed to load DiskAnn plugin (status={status}); "
+            "check that libzvec_diskann_plugin.so is installed alongside "
+            "_zvec.so in the Python site-packages directory."
+        )
+        return _DISKANN_PRELOAD_REASON
+
+    _DISKANN_PRELOAD_REASON = None
+    return None
+
+
+from zvec import (
+    CollectionOption,
+    InvertIndexParam,
+    HnswIndexParam,
+    FlatIndexParam,
+    IVFIndexParam,
+    FieldSchema,
+    VectorSchema,
+    CollectionSchema,
+    Collection,
+    Doc,
+    Query,
+)
+
+from support_helper import *
+
+
+@pytest.fixture(scope="session")
+def basic_schema(collection_name="test_collection") -> CollectionSchema:
+    return CollectionSchema(
+        name=collection_name if len(collection_name) > 0 else "test_collection",
+        fields=[
+            FieldSchema(
+                "id",
+                DataType.INT64,
+                nullable=False,
+                index_param=InvertIndexParam(enable_range_optimization=True),
+            ),
+            FieldSchema(
+                "name", DataType.STRING, nullable=False, index_param=InvertIndexParam()
+            ),
+            FieldSchema("weight", DataType.FLOAT, nullable=True),
+        ],
+        vectors=[
+            VectorSchema(
+                "dense",
+                DataType.VECTOR_FP32,
+                dimension=128,
+                index_param=HnswIndexParam(),
+            ),
+            VectorSchema(
+                "sparse", DataType.SPARSE_VECTOR_FP32, index_param=HnswIndexParam()
+            ),
+        ],
+    )
+
+
+@pytest.fixture(scope="session")
+def full_schema(
+    nullable: bool = False,
+    has_index: bool = False,
+) -> CollectionSchema:
+    scalar_index_param = None
+    vector_index_param = None
+    if has_index:
+        scalar_index_param = InvertIndexParam(enable_range_optimization=True)
+        vector_index_param = HnswIndexParam()
+
+    fields = []
+    for k, v in DEFAULT_SCALAR_FIELD_NAME.items():
+        fields.append(
+            FieldSchema(
+                v,
+                k,
+                nullable=nullable,
+                index_param=scalar_index_param,
+            )
+        )
+    vetors = []
+    for k, v in DEFAULT_VECTOR_FIELD_NAME.items():
+        vetors.append(
+            VectorSchema(
+                v,
+                k,
+                dimension=DEFAULT_VECTOR_DIMENSION,
+                index_param=vector_index_param,
+            )
+        )
+
+    return CollectionSchema(
+        name="full_collection",
+        fields=fields,
+        vectors=vetors,
+    )
+
+
+@pytest.fixture(scope="function")
+def full_schema_new(request) -> CollectionSchema:
+    if hasattr(request, "param"):
+        nullable, has_index, vector_index = request.param
+    else:
+        nullable, has_index, vector_index = True, False, HnswIndexParam()
+
+    # Skip DiskAnn tests on unsupported platforms or when the runtime cannot
+    # be brought up (missing libaio, plugin .so not installed, etc.).
+    from zvec.model.param import DiskAnnIndexParam
+
+    if isinstance(vector_index, DiskAnnIndexParam):
+        skip_reason = _ensure_diskann_runtime_or_reason()
+        if skip_reason is not None:
+            pytest.skip(skip_reason)
+
+    scalar_index_param = None
+    vector_index_param = None
+    if has_index:
+        scalar_index_param = InvertIndexParam(enable_range_optimization=True)
+        vector_index_param = vector_index
+
+    fields = []
+    for k, v in DEFAULT_SCALAR_FIELD_NAME.items():
+        fields.append(
+            FieldSchema(
+                v,
+                k,
+                nullable=nullable,
+                index_param=scalar_index_param,
+            )
+        )
+    vectors = []
+
+    if vector_index_param in [
+        HnswIndexParam(),
+        FlatIndexParam(),
+        HnswIndexParam(
+            metric_type=MetricType.IP,
+            m=16,
+            ef_construction=100,
+        ),
+        FlatIndexParam(
+            metric_type=MetricType.IP,
+        ),
+    ]:
+        for k, v in DEFAULT_VECTOR_FIELD_NAME.items():
+            vectors.append(
+                VectorSchema(
+                    v,
+                    k,
+                    dimension=DEFAULT_VECTOR_DIMENSION,
+                    index_param=vector_index_param,
+                )
+            )
+    elif vector_index_param in [
+        IVFIndexParam(),
+        IVFIndexParam(
+            metric_type=MetricType.IP,
+            n_list=100,
+            n_iters=10,
+            use_soar=False,
+        ),
+        IVFIndexParam(
+            metric_type=MetricType.L2,
+            n_list=200,
+            n_iters=20,
+            use_soar=True,
+        ),
+        (
+            IVFIndexParam(
+                metric_type=MetricType.COSINE,
+                n_list=150,
+                n_iters=15,
+                use_soar=False,
+            )
+        ),
+        (
+            HnswIndexParam(
+                metric_type=MetricType.COSINE,
+                m=24,
+                ef_construction=150,
+            )
+        ),
+        (
+            HnswIndexParam(
+                metric_type=MetricType.L2,
+                m=32,
+                ef_construction=200,
+            )
+        ),
+        (
+            FlatIndexParam(
+                metric_type=MetricType.COSINE,
+            )
+        ),
+        (
+            FlatIndexParam(
+                metric_type=MetricType.L2,
+            )
+        ),
+    ]:
+        for k, v in DEFAULT_VECTOR_FIELD_NAME.items():
+            if v in ["vector_fp16_field", "vector_fp32_field"]:
+                vectors.append(
+                    VectorSchema(
+                        v,
+                        k,
+                        dimension=DEFAULT_VECTOR_DIMENSION,
+                        index_param=vector_index_param,
+                    )
+                )
+            elif v in ["vector_int8_field"] and vector_index_param in [
+                IVFIndexParam(
+                    metric_type=MetricType.L2,
+                    n_list=200,
+                    n_iters=20,
+                    use_soar=True,
+                ),
+                (
+                    HnswIndexParam(
+                        metric_type=MetricType.L2,
+                        m=32,
+                        ef_construction=200,
+                    )
+                ),
+                (
+                    FlatIndexParam(
+                        metric_type=MetricType.L2,
+                    )
+                ),
+            ]:
+                vectors.append(
+                    VectorSchema(
+                        v,
+                        k,
+                        dimension=DEFAULT_VECTOR_DIMENSION,
+                        index_param=vector_index_param,
+                    )
+                )
+            else:
+                vectors.append(
+                    VectorSchema(
+                        v,
+                        k,
+                        dimension=DEFAULT_VECTOR_DIMENSION,
+                        index_param=HnswIndexParam(),
+                    )
+                )
+    else:
+        for k, v in DEFAULT_VECTOR_FIELD_NAME.items():
+            if v in ["vector_fp16_field", "vector_fp32_field"]:
+                vectors.append(
+                    VectorSchema(
+                        v,
+                        k,
+                        dimension=DEFAULT_VECTOR_DIMENSION,
+                        index_param=vector_index_param,
+                    )
+                )
+            else:
+                vectors.append(
+                    VectorSchema(
+                        v,
+                        k,
+                        dimension=DEFAULT_VECTOR_DIMENSION,
+                        index_param=HnswIndexParam(),
+                    )
+                )
+
+    return CollectionSchema(
+        name="full_collection_new",
+        fields=fields,
+        vectors=vectors,
+    )
+
+
+@pytest.fixture(scope="function")
+def full_schema_ivf(request) -> CollectionSchema:
+    if hasattr(request, "param"):
+        nullable, has_index, vector_index = request.param
+    else:
+        nullable, has_index, vector_index = True, False, IVFIndexParam()
+
+    scalar_index_param = None
+    vector_index_param = None
+    if has_index:
+        scalar_index_param = InvertIndexParam(enable_range_optimization=True)
+        vector_index_param = vector_index
+
+    fields = []
+    for k, v in DEFAULT_SCALAR_FIELD_NAME.items():
+        fields.append(
+            FieldSchema(
+                v,
+                k,
+                nullable=nullable,
+                index_param=scalar_index_param,
+            )
+        )
+    vectors = []
+    for k, v in DEFAULT_VECTOR_FIELD_NAME.items():
+        if v in ["vector_fp16_field", "vector_fp32_field"]:
+            vectors.append(
+                VectorSchema(
+                    v,
+                    k,
+                    dimension=DEFAULT_VECTOR_DIMENSION,
+                    index_param=vector_index_param,
+                )
+            )
+
+    return CollectionSchema(
+        name="full_collection_ivf",
+        fields=fields,
+        vectors=vectors,
+    )
+
+
+@pytest.fixture(scope="function")
+def full_schema_1024(request) -> CollectionSchema:
+    if hasattr(request, "param"):
+        nullable, has_index, vector_index = request.param
+    else:
+        nullable, has_index, vector_index = True, False, HnswIndexParam()
+
+    scalar_index_param = None
+    vector_index_param = None
+    if has_index:
+        scalar_index_param = InvertIndexParam(enable_range_optimization=True)
+        vector_index_param = vector_index
+
+    fields = []
+    for k, v in DEFAULT_SCALAR_FIELD_NAME.items():
+        fields.append(
+            FieldSchema(
+                v,
+                k,
+                nullable=nullable,
+                index_param=scalar_index_param,
+            )
+        )
+    vectors = []
+
+    if vector_index_param in [
+        HnswIndexParam(),
+        FlatIndexParam(),
+        HnswIndexParam(
+            metric_type=MetricType.IP,
+            m=16,
+            ef_construction=100,
+        ),
+        FlatIndexParam(
+            metric_type=MetricType.IP,
+        ),
+    ]:
+        for k, v in DEFAULT_VECTOR_FIELD_NAME.items():
+            vectors.append(
+                VectorSchema(
+                    v,
+                    k,
+                    dimension=VECTOR_DIMENSION_1024,
+                    index_param=vector_index_param,
+                )
+            )
+    elif vector_index_param in [
+        IVFIndexParam(),
+        IVFIndexParam(
+            metric_type=MetricType.IP,
+            n_list=100,
+            n_iters=10,
+            use_soar=False,
+        ),
+        IVFIndexParam(
+            metric_type=MetricType.L2,
+            n_list=200,
+            n_iters=20,
+            use_soar=True,
+        ),
+        IVFIndexParam(
+            metric_type=MetricType.COSINE,
+            n_list=150,
+            n_iters=15,
+            use_soar=False,
+        ),
+    ]:
+        for k, v in DEFAULT_VECTOR_FIELD_NAME.items():
+            if v in ["vector_fp16_field", "vector_fp32_field"]:
+                vectors.append(
+                    VectorSchema(
+                        v,
+                        k,
+                        dimension=VECTOR_DIMENSION_1024,
+                        index_param=vector_index_param,
+                    )
+                )
+            elif v in ["vector_int8_field"] and vector_index_param in [
+                IVFIndexParam(
+                    metric_type=MetricType.L2,
+                    n_list=200,
+                    n_iters=20,
+                    use_soar=True,
+                ),
+                IVFIndexParam(
+                    metric_type=MetricType.COSINE,
+                    n_list=150,
+                    n_iters=15,
+                    use_soar=False,
+                ),
+            ]:
+                vectors.append(
+                    VectorSchema(
+                        v,
+                        k,
+                        dimension=DVECTOR_DIMENSION_1024,
+                        index_param=vector_index_param,
+                    )
+                )
+            else:
+                vectors.append(
+                    VectorSchema(
+                        v,
+                        k,
+                        dimension=VECTOR_DIMENSION_1024,
+                        index_param=HnswIndexParam(),
+                    )
+                )
+    else:
+        for k, v in DEFAULT_VECTOR_FIELD_NAME.items():
+            if v in ["vector_fp16_field", "vector_fp32_field", "vector_int8_field"]:
+                vectors.append(
+                    VectorSchema(
+                        v,
+                        k,
+                        dimension=VECTOR_DIMENSION_1024,
+                        index_param=vector_index_param,
+                    )
+                )
+            else:
+                vectors.append(
+                    VectorSchema(
+                        v,
+                        k,
+                        dimension=VECTOR_DIMENSION_1024,
+                        index_param=HnswIndexParam(),
+                    )
+                )
+
+    return CollectionSchema(
+        name="full_collection_new",
+        fields=fields,
+        vectors=vectors,
+    )
+
+
+@pytest.fixture(scope="function")
+def single_vector_schema(
+    data_type: DataType,
+) -> CollectionSchema:
+    vector_schema = [
+        VectorSchema(
+            DEFAULT_VECTOR_FIELD_NAME[data_type],
+            data_type,
+            DEFAULT_VECTOR_DIMENSION,
+        )
+    ]
+
+    return CollectionSchema(
+        name="full_collection",
+        vectors=vector_schema,
+    )
+
+
+@pytest.fixture(scope="function")
+def single_vector_schema_with_index_param(
+    data_type: DataType, index_param
+) -> CollectionSchema:
+    vector_schema = [
+        VectorSchema(
+            DEFAULT_VECTOR_FIELD_NAME[data_type],
+            data_type,
+            DEFAULT_VECTOR_DIMENSION,
+            index_param,
+        )
+    ]
+
+    return CollectionSchema(
+        name="full_collection",
+        vectors=vector_schema,
+    )
+
+
+def create_collection_fixture(
+    collection_temp_dir, schema: CollectionSchema, collection_option: CollectionOption
+) -> Generator[Any, Any, Collection]:
+    """Common helper function to create and manage collection fixtures."""
+    coll = zvec.create_and_open(
+        path=str(collection_temp_dir),
+        schema=schema,
+        option=collection_option,
+    )
+
+    assert coll is not None, "Failed to create and open collection"
+    assert coll.path == str(collection_temp_dir)
+    assert coll.schema.name == schema.name
+    assert list(coll.schema.fields) == list(schema.fields)
+    assert list(coll.schema.vectors) == list(schema.vectors)
+    assert coll.option.read_only == collection_option.read_only
+    assert coll.option.enable_mmap == collection_option.enable_mmap
+
+    try:
+        yield coll
+    finally:
+        if hasattr(coll, "destroy") and coll is not None:
+            try:
+                coll.destroy()
+            except Exception as e:
+                logging.warning(f"Warning: failed to destroy collection: {e}")
+
+
+@pytest.fixture(scope="function")
+def basic_collection(
+    collection_temp_dir, basic_schema, collection_option
+) -> Generator[Any, Any, Collection]:
+    yield from create_collection_fixture(
+        collection_temp_dir, basic_schema, collection_option
+    )
+
+
+@pytest.fixture(scope="function")
+def collection_option():
+    return CollectionOption(read_only=False, enable_mmap=True)
+
+
+@pytest.fixture(scope="function")
+def collection_temp_dir(tmp_path_factory):
+    temp_dir = tmp_path_factory.mktemp("zvec")
+    collection_path = temp_dir / "test_collection_path"
+    return str(collection_path)
+
+
+@pytest.fixture(scope="function")
+def full_collection(
+    collection_temp_dir,
+    full_schema,
+    collection_option,
+    nullable: bool = True,
+    has_index: bool = False,
+) -> Generator[Any, Any, Collection]:
+    yield from create_collection_fixture(
+        collection_temp_dir, full_schema, collection_option
+    )
+
+
+@pytest.fixture(scope="function")
+def full_collection_new(
+    collection_temp_dir, full_schema_new, collection_option
+) -> Generator[Any, Any, Collection]:
+    yield from create_collection_fixture(
+        collection_temp_dir, full_schema_new, collection_option
+    )
+
+
+@pytest.fixture(scope="function")
+def full_collection_ivf(
+    collection_temp_dir, full_schema_ivf, collection_option
+) -> Generator[Any, Any, Collection]:
+    yield from create_collection_fixture(
+        collection_temp_dir, full_schema_ivf, collection_option
+    )
+
+
+@pytest.fixture(scope="function")
+def full_collection_1024(
+    collection_temp_dir, full_schema_1024, collection_option
+) -> Generator[Any, Any, Collection]:
+    yield from create_collection_fixture(
+        collection_temp_dir, full_schema_1024, collection_option
+    )
+
+
+@pytest.fixture
+def sample_field_list(nullable: bool = True, scalar_index_param=None, name_prefix=""):
+    field_list = []
+    for k, v in DEFAULT_SCALAR_FIELD_NAME.items():
+        field_list.append(
+            FieldSchema(
+                f"{name_prefix}_{v}" if len(name_prefix) > 0 else v,
+                k,
+                nullable=nullable,
+                index_param=scalar_index_param,
+            )
+        )
+    return field_list
+
+
+@pytest.fixture
+def sample_vector_list(vector_index_param=None, name_prefix=""):
+    vector_list = []
+    for k, v in DEFAULT_VECTOR_FIELD_NAME.items():
+        vector_list.append(
+            VectorSchema(
+                f"{name_prefix}_{v}" if len(name_prefix) > 0 else v,
+                k,
+                dimension=DEFAULT_VECTOR_DIMENSION,
+                index_param=vector_index_param,
+            )
+        )
+    return vector_list

python/tests/detail/params_helper.py

@@ -0,0 +1,209 @@
+from zvec import (
+    CollectionOption,
+    IndexOption,
+    OptimizeOption,
+    InvertIndexParam,
+    HnswIndexParam,
+    IVFIndexParam,
+    FlatIndexParam,
+    AlterColumnOption,
+    AddColumnOption,
+    DataType,
+    MetricType,
+    QuantizeType,
+)
+
+
+VALID_VECTOR_DATA_TYPE_INDEX_PARAM_MAP = {
+    DataType.VECTOR_FP32: [
+        HnswIndexParam(),
+        HnswIndexParam(
+            metric_type=MetricType.IP,
+            m=16,
+            ef_construction=100,
+            quantize_type=QuantizeType.INT8,
+        ),
+        HnswIndexParam(
+            metric_type=MetricType.COSINE,
+            m=24,
+            ef_construction=150,
+            quantize_type=QuantizeType.INT4,
+        ),
+        HnswIndexParam(
+            metric_type=MetricType.L2,
+            m=32,
+            ef_construction=200,
+            quantize_type=QuantizeType.FP16,
+        ),
+        FlatIndexParam(),
+        FlatIndexParam(metric_type=MetricType.IP, quantize_type=QuantizeType.INT4),
+        FlatIndexParam(metric_type=MetricType.L2, quantize_type=QuantizeType.INT8),
+        FlatIndexParam(metric_type=MetricType.COSINE, quantize_type=QuantizeType.FP16),
+        IVFIndexParam(),
+        IVFIndexParam(
+            metric_type=MetricType.IP,
+            quantize_type=QuantizeType.INT4,
+            n_list=100,
+            n_iters=10,
+            use_soar=False,
+        ),
+        IVFIndexParam(
+            metric_type=MetricType.L2,
+            quantize_type=QuantizeType.INT8,
+            n_list=200,
+            n_iters=20,
+            use_soar=True,
+        ),
+        IVFIndexParam(
+            metric_type=MetricType.COSINE,
+            quantize_type=QuantizeType.FP16,
+            n_list=150,
+            n_iters=15,
+            use_soar=False,
+        ),
+    ],
+    DataType.VECTOR_FP16: [
+        HnswIndexParam(),
+        FlatIndexParam(),
+        # IVFIndexParam(),
+    ],
+    DataType.VECTOR_INT8: [
+        HnswIndexParam(),
+        FlatIndexParam(),
+        # IVFIndexParam(),
+    ],
+    DataType.SPARSE_VECTOR_FP32: [
+        HnswIndexParam(),
+        FlatIndexParam(),
+        HnswIndexParam(
+            metric_type=MetricType.IP,
+            m=16,
+            ef_construction=100,
+            quantize_type=QuantizeType.FP16,
+        ),
+    ],
+    DataType.SPARSE_VECTOR_FP16: [
+        HnswIndexParam(),
+        FlatIndexParam(),
+        HnswIndexParam(
+            metric_type=MetricType.IP,
+            m=16,
+            ef_construction=100,
+        ),
+    ],
+}
+
+VALID_VECTOR_DATA_TYPE_INDEX_PARAM_MAP_PARAMS = [
+    (data_type, param)
+    for data_type, params in VALID_VECTOR_DATA_TYPE_INDEX_PARAM_MAP.items()
+    for param in params
+]
+
+INVALID_VECTOR_DATA_TYPE_INDEX_PARAM_MAP = {
+    DataType.VECTOR_FP32: [
+        InvertIndexParam(),
+    ],
+    DataType.VECTOR_FP16: [
+        InvertIndexParam(),
+    ],
+    DataType.VECTOR_INT8: [
+        InvertIndexParam(),
+    ],
+    DataType.SPARSE_VECTOR_FP32: [
+        HnswIndexParam(metric_type=MetricType.L2),
+        FlatIndexParam(metric_type=MetricType.COSINE),
+        IVFIndexParam(),
+        InvertIndexParam(),
+    ],
+    DataType.SPARSE_VECTOR_FP16: [
+        HnswIndexParam(metric_type=MetricType.L2),
+        FlatIndexParam(metric_type=MetricType.COSINE),
+        IVFIndexParam(),
+        InvertIndexParam(),
+    ],
+}
+
+INVALID_VECTOR_DATA_TYPE_INDEX_PARAM_MAP_PARAMS = [
+    (data_type, param)
+    for data_type, params in INVALID_VECTOR_DATA_TYPE_INDEX_PARAM_MAP.items()
+    for param in params
+]
+
+COLLECTION_NAME_MAX_LENGTH = 64
+
+COLLECTION_NAME_VALID_LIST = [
+    "col",
+    "C0llECTION",
+    "Collection1",
+    "collection_2",
+    "123collection-",
+    "a" * COLLECTION_NAME_MAX_LENGTH,
+]
+
+COLLECTION_NAME_INVALID_LIST = [
+    "l",
+    "1C",
+    "",
+    " ",
+    None,
+    "abcdefghijklmnopqrstuvwxzy123456abcdefghijklmnopqrstuvwxzy1234561",
+    "test/",
+    "!@#$%^&*()test",
+]
+
+FIELD_NAME_VALID_LIST = [
+    "1",
+    "12",
+    "col",
+    "ID",
+    "name1",
+    "Weigt_12-",
+    "123age",
+    "name_with_underscores",
+    "123numeric_start",
+    "name-with-dashes",
+]
+
+FIELD_NAME_INVALID_LIST = [
+    "",
+    " ",
+    None,
+    "abcdefghijklmnopqrstuvwxzy1234561",
+    "test/",
+    "!@#$%^&*()test",
+    "name@with#special$chars",
+    "name with spaces",
+]
+
+FIELD_LIST_MAX_LENGTH = 1024
+VECTOR_LIST_MAX_LENGTH = 5
+DENSE_VECTOR_MAX_DIMENSION = 20000
+SPARSE_VECTOR_MAX_DIMENSION = 4096
+
+FIELD_VECTOR_LIST_DIMENSION_VALID_LIST = [
+    # field_list_len, vector_list_len, dimension
+    (1, 1, 1),
+    (2, 2, 512),
+    (512, 3, 1024),
+    (1024, 4, 20000),
+]
+
+FIELD_VECTOR_LIST_DIMENSION_INVALID_LIST = [
+    # field_list_len, vector_list_len, dimension
+    (1, 1, 0),
+    (1, 1, -1),
+    (1, 1, "1"),
+    (1, 1, 20001),
+]
+
+
+INCOMPATIBLE_CONSTRUCTOR_ERROR_MSG = "incompatible constructor arguments"
+SCHEMA_VALIDATE_ERROR_MSG = "schema validate failed"
+CREATE_READ_ONLY_ERROR_MSG = "Unable to create collection with read-only mode"
+INCOMPATIBLE_FUNCTION_ERROR_MSG = "incompatible function arguments"
+INVALID_PATH_ERROR_MSG = "path validate failed"
+INDEX_NON_EXISTENT_COLUMN_ERROR_MSG = "not found in schema"
+ACCESS_DESTROYED_COLLECTION_ERROR_MSG = "is already destroyed"
+COLLECTION_PATH_NOT_EXIST_ERROR_MSG = "not exist"
+NOT_SUPPORT_ADD_COLUMN_ERROR_MSG = "Only support basic numeric data type"
+NOT_EXIST_COLUMN_TO_DROP_ERROR_MSG = "Column not exists"

python/tests/detail/support_helper.py

@@ -0,0 +1,126 @@
+from zvec import (
+    CollectionOption,
+    IndexOption,
+    OptimizeOption,
+    InvertIndexParam,
+    HnswIndexParam,
+    IVFIndexParam,
+    FlatIndexParam,
+    DataType,
+    IndexType,
+    QuantizeType,
+)
+
+SUPPORT_SCALAR_DATA_TYPES = [
+    DataType.BOOL,
+    DataType.FLOAT,
+    DataType.DOUBLE,
+    DataType.INT32,
+    DataType.INT64,
+    DataType.UINT32,
+    DataType.UINT64,
+    DataType.STRING,
+    DataType.ARRAY_BOOL,
+    DataType.ARRAY_FLOAT,
+    DataType.ARRAY_DOUBLE,
+    DataType.ARRAY_INT32,
+    DataType.ARRAY_INT64,
+    DataType.ARRAY_UINT32,
+    DataType.ARRAY_UINT64,
+    DataType.ARRAY_STRING,
+]
+
+DEFAULT_SCALAR_FIELD_NAME = {
+    DataType.BOOL: "bool_field",
+    DataType.FLOAT: "float_field",
+    DataType.DOUBLE: "double_field",
+    DataType.INT32: "int32_field",
+    DataType.INT64: "int64_field",
+    DataType.UINT32: "uint32_field",
+    DataType.UINT64: "uint64_field",
+    DataType.STRING: "string_field",
+    DataType.ARRAY_BOOL: "array_bool_field",
+    DataType.ARRAY_FLOAT: "array_float_field",
+    DataType.ARRAY_DOUBLE: "array_double_field",
+    DataType.ARRAY_INT32: "array_int32_field",
+    DataType.ARRAY_INT64: "array_int64_field",
+    DataType.ARRAY_UINT32: "array_uint32_field",
+    DataType.ARRAY_UINT64: "array_uint64_field",
+    DataType.ARRAY_STRING: "array_string_field",
+}
+
+SUPPORT_SCALAR_INDEX_TYPES = [
+    IndexType.INVERT,
+]
+
+SUPPORT_VECTOR_DATA_TYPES = [
+    DataType.VECTOR_FP16,
+    DataType.VECTOR_FP32,
+    DataType.VECTOR_INT8,
+    DataType.SPARSE_VECTOR_FP32,
+    DataType.SPARSE_VECTOR_FP16,
+]
+
+SUPPORT_VECTOR_INDEX_TYPES = [
+    IndexType.FLAT,
+    IndexType.HNSW,
+    IndexType.IVF,
+]
+
+DEFAULT_VECTOR_FIELD_NAME = {
+    DataType.VECTOR_FP16: "vector_fp16_field",
+    DataType.VECTOR_FP32: "vector_fp32_field",
+    DataType.VECTOR_INT8: "vector_int8_field",
+    DataType.SPARSE_VECTOR_FP32: "sparse_vector_fp32_field",
+    DataType.SPARSE_VECTOR_FP16: "sparse_vector_fp16_field",
+}
+
+DEFAULT_VECTOR_DIMENSION = 128
+VECTOR_DIMENSION_1024 = 4
+SUPPORT_VECTOR_DATA_TYPE_INDEX_MAP = {
+    DataType.VECTOR_FP16: [IndexType.FLAT, IndexType.HNSW, IndexType.IVF],
+    DataType.VECTOR_FP32: [IndexType.FLAT, IndexType.HNSW, IndexType.IVF],
+    DataType.VECTOR_INT8: [IndexType.FLAT, IndexType.HNSW],
+    DataType.SPARSE_VECTOR_FP32: [IndexType.FLAT, IndexType.HNSW],
+    DataType.SPARSE_VECTOR_FP16: [IndexType.FLAT, IndexType.HNSW],
+}
+
+SUPPORT_VECTOR_DATA_TYPE_INDEX_MAP_PARAMS = [
+    (data_type, index_type)
+    for data_type, index_types in SUPPORT_VECTOR_DATA_TYPE_INDEX_MAP.items()
+    for index_type in index_types
+]
+
+DEFAULT_INDEX_PARAMS = {
+    IndexType.FLAT: FlatIndexParam(),
+    IndexType.HNSW: HnswIndexParam(),
+    IndexType.IVF: IVFIndexParam(),
+    IndexType.INVERT: InvertIndexParam(),
+}
+
+SUPPORT_VECTOR_DATA_TYPE_QUANT_MAP = {
+    DataType.VECTOR_FP32: [QuantizeType.FP16, QuantizeType.INT8, QuantizeType.INT4],
+    DataType.SPARSE_VECTOR_FP32: [QuantizeType.FP16],
+}
+
+SUPPORT_ADD_COLUMN_DATA_TYPE = [
+    DataType.INT32,
+    DataType.UINT32,
+    DataType.INT64,
+    DataType.UINT64,
+    DataType.FLOAT,
+    DataType.DOUBLE,
+]
+
+NOT_SUPPORT_ADD_COLUMN_DATA_TYPE = [
+    DataType.BOOL,
+    DataType.STRING,
+    DataType.ARRAY_BOOL,
+    DataType.ARRAY_INT32,
+    DataType.ARRAY_INT64,
+    DataType.ARRAY_UINT32,
+    DataType.ARRAY_UINT64,
+    DataType.ARRAY_FLOAT,
+    DataType.ARRAY_DOUBLE,
+    DataType.ARRAY_STRING,
+]

python/tests/detail/test_collection_concurrency.py

@@ -0,0 +1,429 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+import pytest
+import threading
+import numpy as np
+import zvec
+
+from zvec import (
+    CollectionOption,
+    InvertIndexParam,
+    HnswIndexParam,
+    Collection,
+    Doc,
+    DataType,
+    FieldSchema,
+    VectorSchema,
+)
+
+
+class TestCollectionConcurrency:
+    @pytest.fixture(scope="function")
+    def test_collection(self, tmp_path_factory):
+        """Fixture to create a test collection"""
+        collection_schema = zvec.CollectionSchema(
+            name="test_collection",
+            fields=[
+                FieldSchema(
+                    "id",
+                    DataType.INT64,
+                    nullable=False,
+                    index_param=InvertIndexParam(enable_range_optimization=True),
+                ),
+                FieldSchema(
+                    "name",
+                    DataType.STRING,
+                    nullable=False,
+                    index_param=InvertIndexParam(),
+                ),
+                FieldSchema("weight", DataType.FLOAT, nullable=True),
+            ],
+            vectors=[
+                VectorSchema(
+                    "dense",
+                    DataType.VECTOR_FP32,
+                    dimension=128,
+                    index_param=HnswIndexParam(),
+                ),
+                VectorSchema(
+                    "sparse", DataType.SPARSE_VECTOR_FP32, index_param=HnswIndexParam()
+                ),
+            ],
+        )
+
+        collection_option = CollectionOption(read_only=False, enable_mmap=True)
+
+        temp_dir = tmp_path_factory.mktemp("zvec")
+        collection_path = temp_dir / "test_collection"
+
+        coll = zvec.create_and_open(
+            path=str(collection_path),
+            schema=collection_schema,
+            option=collection_option,
+        )
+
+        assert coll is not None, "Failed to create and open collection"
+
+        yield coll
+
+        # Clean up
+        if hasattr(coll, "destroy") and coll is not None:
+            try:
+                coll.destroy()
+            except Exception as e:
+                print(f"Warning: failed to destroy collection: {e}")
+
+    def test_concurrent_read_write(self, test_collection: Collection):
+        results = []
+
+        def insert_docs(thread_id):
+            try:
+                docs = [
+                    Doc(
+                        id=f"{thread_id}_{i}",
+                        fields={
+                            "id": int(f"{thread_id}{i}"),
+                            "name": f"thread_{thread_id}_doc_{i}",
+                            "weight": float(i),
+                        },
+                        vectors={
+                            "dense": np.random.random(128).tolist(),
+                            "sparse": {1: float(i), 2: float(i * 2)},
+                        },
+                    )
+                    for i in range(5)
+                ]
+
+                result = test_collection.insert(docs)
+                results.append((thread_id, "insert", len(result)))
+            except Exception as e:
+                results.append((thread_id, "insert_exception", str(e)))
+
+        def query_docs(thread_id):
+            try:
+                result = test_collection.query(filter="id > 0", topk=10)
+                results.append((thread_id, "query", len(result)))
+            except Exception as e:
+                results.append((thread_id, "query_exception", str(e)))
+
+        # Create threads for concurrent operations
+        threads = []
+
+        # Start insert threads
+        for i in range(3):
+            thread = threading.Thread(target=insert_docs, args=(i,))
+            threads.append(thread)
+            thread.start()
+
+        # Start query threads
+        for i in range(3):
+            thread = threading.Thread(target=query_docs, args=(i,))
+            threads.append(thread)
+            thread.start()
+
+        # Wait for all threads to complete
+        for thread in threads:
+            thread.join()
+
+        # Analyze results
+        insert_results = [r for r in results if r[1] == "insert"]
+        query_results = [r for r in results if r[1] == "query"]
+
+        logging.info(
+            f"Concurrent read/write results - Inserts: {len(insert_results)}, Queries: {len(query_results)}"
+        )
+
+        # At least some operations should succeed
+        assert len(insert_results) + len(query_results) > 0
+
+    def test_concurrent_query(self, test_collection: Collection):
+        # First insert some data
+        docs = [
+            Doc(
+                id=f"{i}",
+                fields={"id": i, "name": f"test_{i}", "weight": float(i)},
+                vectors={
+                    "dense": np.random.random(128).tolist(),
+                    "sparse": {1: float(i), 2: float(i * 2)},
+                },
+            )
+            for i in range(20)
+        ]
+
+        insert_result = test_collection.insert(docs)
+        assert len(insert_result) == 20
+
+        results = []
+
+        def query_operation(thread_id):
+            """Perform query operation from a thread"""
+            try:
+                result = test_collection.query(filter=f"id > {thread_id}", topk=5)
+                results.append((thread_id, "query", len(result)))
+            except Exception as e:
+                results.append((thread_id, "query_exception", str(e)))
+
+        # Create multiple threads for concurrent queries
+        threads = []
+        for i in range(5):
+            thread = threading.Thread(target=query_operation, args=(i,))
+            threads.append(thread)
+            thread.start()
+
+        # Wait for all threads to complete
+        for thread in threads:
+            thread.join()
+
+        # Analyze results
+        query_results = [r for r in results if r[1] == "query"]
+        logging.info(f"Concurrent query results - Queries: {len(query_results)}")
+
+        # All query operations should succeed
+        assert len(query_results) == 5
+
+    def test_concurrent_modifications(self, test_collection: Collection):
+        # First insert some data
+        docs = [
+            Doc(
+                id=f"{i}",
+                fields={"id": i, "name": f"test_{i}", "weight": float(i)},
+                vectors={
+                    "dense": np.random.random(128).tolist(),
+                    "sparse": {1: float(i), 2: float(i * 2)},
+                },
+            )
+            for i in range(10)
+        ]
+
+        insert_result = test_collection.insert(docs)
+        assert len(insert_result) == 10
+
+        results = []
+
+        def update_operation(thread_id):
+            """Perform update operation from a thread"""
+            try:
+                # Each thread updates different documents
+                update_docs = [
+                    Doc(
+                        id=f"{i}",
+                        fields={
+                            "id": i,
+                            "name": f"updated_by_thread_{thread_id}",
+                            "weight": float(i + thread_id),
+                        },
+                        vectors={
+                            "dense": np.random.random(128).tolist(),
+                            "sparse": {1: float(i) + 0.5, 2: float(i * 2) + 0.5},
+                        },
+                    )
+                    for i in range(thread_id * 2, thread_id * 2 + 2)
+                ]
+
+                result = test_collection.update(update_docs)
+                results.append((thread_id, "update", len(result)))
+            except Exception as e:
+                results.append((thread_id, "update_exception", str(e)))
+
+        def delete_operation(thread_id):
+            """Perform delete operation from a thread"""
+            try:
+                # Each thread deletes different documents
+                delete_ids = [f"{thread_id * 2 + 2}", f"{thread_id * 2 + 3}"]
+                result = test_collection.delete(delete_ids)
+                results.append((thread_id, "delete", len(result)))
+            except Exception as e:
+                results.append((thread_id, "delete_exception", str(e)))
+
+        # Create threads for concurrent operations
+        threads = []
+
+        # Start update threads
+        for i in range(3):
+            thread = threading.Thread(target=update_operation, args=(i,))
+            threads.append(thread)
+            thread.start()
+
+        # Start delete threads
+        for i in range(2):
+            thread = threading.Thread(target=delete_operation, args=(i,))
+            threads.append(thread)
+            thread.start()
+
+        # Wait for all threads to complete
+        for thread in threads:
+            thread.join()
+
+        # Analyze results
+        update_results = [r for r in results if r[1] == "update"]
+        delete_results = [r for r in results if r[1] == "delete"]
+
+        logging.info(
+            f"Concurrent modification results - Updates: {len(update_results)}, Deletes: {len(delete_results)}"
+        )
+
+        # At least some operations should succeed
+        assert len(update_results) + len(delete_results) > 0
+
+    def test_read_write_locking(self, test_collection: Collection):
+        # Perform operations that should be thread-safe
+        docs = [
+            Doc(
+                id=f"{i}",
+                fields={"id": i, "name": f"test_{i}", "weight": float(i)},
+                vectors={
+                    "dense": np.random.random(128).tolist(),
+                    "sparse": {1: float(i), 2: float(i * 2)},
+                },
+            )
+            for i in range(5)
+        ]
+
+        # Insert data
+        insert_result = test_collection.insert(docs)
+        assert len(insert_result) == 5
+
+        # Concurrent operations should not cause data corruption
+        results = []
+
+        def mixed_operation(thread_id):
+            """Perform mixed operations from a thread"""
+            try:
+                # Mix of read and write operations
+                if thread_id % 2 == 0:
+                    # Read operation
+                    result = test_collection.fetch([f"{thread_id % 5}"])
+                    results.append((thread_id, "read", len(result)))
+                else:
+                    # Write operation
+                    doc = Doc(
+                        id=f"{thread_id % 5}",
+                        fields={
+                            "id": thread_id % 5,
+                            "name": f"mixed_op_{thread_id}",
+                            "weight": float(thread_id),
+                        },
+                        vectors={
+                            "dense": np.random.random(128).tolist(),
+                            "sparse": {1: float(thread_id), 2: float(thread_id * 2)},
+                        },
+                    )
+                    result = test_collection.upsert(doc)
+                    results.append((thread_id, "write", len(result)))
+            except Exception as e:
+                results.append((thread_id, "exception", str(e)))
+
+        # Create multiple threads
+        threads = []
+        for i in range(10):
+            thread = threading.Thread(target=mixed_operation, args=(i,))
+            threads.append(thread)
+            thread.start()
+
+        # Wait for all threads to complete
+        for thread in threads:
+            thread.join()
+
+        # Verify that the collection is still in a consistent state
+        final_result = test_collection.query()
+        assert len(final_result) >= 0  # Should not crash or return corrupted data
+
+    def test_race_condition_detection(self, test_collection: Collection):
+        # Insert initial data
+        docs = [
+            Doc(
+                id=f"{i}",
+                fields={"id": i, "name": f"initial_{i}", "weight": float(i)},
+                vectors={
+                    "dense": np.random.random(128).tolist(),
+                    "sparse": {1: float(i), 2: float(i * 2)},
+                },
+            )
+            for i in range(10)
+        ]
+
+        insert_result = test_collection.insert(docs)
+        assert len(insert_result) == 10
+
+        # Perform many rapid concurrent operations
+        operation_count = 100
+        results = []
+
+        def rapid_operation(op_id):
+            """Perform rapid operations"""
+            try:
+                # Alternate between different types of operations
+                if op_id % 4 == 0:
+                    # Insert
+                    doc = Doc(
+                        id=f"rapid_{op_id}",
+                        fields={
+                            "id": op_id,
+                            "name": f"rapid_{op_id}",
+                            "weight": float(op_id),
+                        },
+                        vectors={
+                            "dense": np.random.random(128).tolist(),
+                            "sparse": {1: float(op_id), 2: float(op_id * 2)},
+                        },
+                    )
+                    result = test_collection.insert(doc)
+                    results.append(("insert", len(result)))
+                elif op_id % 4 == 1:
+                    # Update
+                    doc = Doc(
+                        id=f"{op_id % 10}",
+                        fields={
+                            "id": op_id % 10,
+                            "name": f"rapid_update_{op_id}",
+                            "weight": float(op_id),
+                        },
+                        vectors={
+                            "dense": np.random.random(128).tolist(),
+                            "sparse": {1: float(op_id), 2: float(op_id * 2)},
+                        },
+                    )
+                    result = test_collection.update(doc)
+                    results.append(("update", len(result)))
+                elif op_id % 4 == 2:
+                    # Query
+                    result = test_collection.query(filter=f"id > {op_id % 5}", topk=3)
+                    results.append(("query", len(result)))
+                else:
+                    # Fetch
+                    result = test_collection.fetch([f"{op_id % 10}"])
+                    results.append(("fetch", len(result)))
+            except Exception as e:
+                results.append(("exception", str(e)))
+
+        # Create many threads for rapid concurrent operations
+        threads = []
+        for i in range(operation_count):
+            thread = threading.Thread(target=rapid_operation, args=(i,))
+            threads.append(thread)
+            thread.start()
+
+        # Wait for all threads to complete
+        for thread in threads:
+            thread.join()
+
+        # Verify collection is still functional
+        final_query = test_collection.query()
+        assert len(final_query) >= 0  # Should not be corrupted
+
+        logging.info(
+            f"Rapid concurrent operations completed - Total operations: {len(results)}"
+        )

python/tests/detail/test_collection_create_and_open.py

@@ -0,0 +1,791 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import threading
+import os
+
+from distance_helper import *
+from fixture_helper import *
+from doc_helper import *
+from params_helper import *
+
+
+def check_collection_info(
+    coll: Collection, schema: CollectionSchema, option: CollectionOption, path: str
+):
+    assert coll is not None, "Failed to create and open collection"
+    assert coll.path == path
+    assert coll.schema.name == schema.name
+    assert list(coll.schema.fields) == list(schema.fields)
+    assert list(coll.schema.vectors) == list(schema.vectors)
+    assert coll.option.read_only == option.read_only
+    assert coll.option.enable_mmap == option.enable_mmap
+
+
+def check_collection_basic(coll: Collection, optimize: bool = False):
+    schema = coll.schema
+
+    docs = [generate_doc(i, schema) for i in range(10)]
+
+    results = coll.insert(docs=docs)
+    assert len(results) == len(docs)
+    for result in results:
+        assert result.ok()
+
+    assert coll.stats.doc_count == len(docs)
+
+    def check_fetch_query():
+        results = coll.fetch([str(i) for i in range(len(docs))])
+        assert len(results) == len(docs)
+        for i in range(len(docs)):
+            assert str(i) in results
+
+        results = coll.query()
+        assert len(results) == len(docs)
+
+    check_fetch_query()
+
+    if optimize:
+        coll.optimize()
+        check_fetch_query()
+
+
+def check_collection_full(coll: Collection):
+    test_doc = generate_doc(1, coll.schema)
+
+    insert_result = coll.insert(test_doc)
+    assert insert_result.ok()
+
+    stats = coll.stats
+    assert stats.doc_count == 1
+
+    fetched_docs = coll.fetch(ids=["1"])
+    assert len(fetched_docs) == 1
+    assert "1" in fetched_docs
+    assert fetched_docs["1"] is not None
+    assert is_doc_equal(fetched_docs["1"], test_doc, coll.schema)
+
+    query_result = coll.query()
+    assert len(query_result) == 1
+
+    updated_doc = Doc(
+        id="1",
+        fields={"int32_field": 1},
+        vectors={"vector_fp32_field": [0.2] * 128},
+    )
+    update_result = coll.update(updated_doc)
+    assert update_result.ok()
+
+    upserted_doc = generate_doc(1, coll.schema)
+    upsert_result = coll.upsert(upserted_doc)
+    assert upsert_result.ok()
+
+    # 8. Delete document
+    delete_result = coll.delete("1")
+    assert delete_result.ok()
+
+    # Verify document was deleted
+    stats = coll.stats
+    assert stats.doc_count == 0
+
+
+valid_collection_options = [
+    # (read_only, enable_mmap)
+    (False, True),
+    (False, False),
+]
+invalid_collection_options = [
+    # (read_only, enable_mmap)
+    (True, True),
+    (True, False),
+]
+duplicate_names_test = [
+    ("field1", "field1", "vector1", "vector2"),
+    ("field1", "field2", "vector1", "vector1"),
+    (
+        "shared_name1",
+        "shared_name2",
+        "shared_name1",
+        "shared_name2",
+    ),
+]
+long_names = [
+    "a" * 100,  # 100 characters
+    "b" * 200,  # 200 characters
+]
+
+valid_path_list = [
+    "/tmp/nonexistent/directory/test_collection",
+    "test/collection/with/slashes",
+    "test/collection/with/slashes/哈哈",
+]
+invalid_path_list = [
+    "invalid\0path",
+    "",
+]
+
+
+class TestCreateAndOpen:
+    @pytest.mark.parametrize("collection_name", COLLECTION_NAME_VALID_LIST)
+    def test_valid_collection_name(
+        self,
+        collection_temp_dir,
+        collection_name,
+        collection_option,
+        sample_field_list,
+        sample_vector_list,
+    ):
+        collection_schema = zvec.CollectionSchema(
+            name=collection_name,
+            fields=sample_field_list,
+            vectors=sample_vector_list,
+        )
+
+        coll = zvec.create_and_open(
+            path=collection_temp_dir,
+            schema=collection_schema,
+            option=collection_option,
+        )
+
+        check_collection_info(
+            coll, collection_schema, collection_option, collection_temp_dir
+        )
+        check_collection_basic(coll)
+
+        coll.destroy()
+
+    @pytest.mark.parametrize("collection_name", COLLECTION_NAME_INVALID_LIST)
+    def test_invalid_collection_name(
+        self,
+        collection_temp_dir,
+        collection_name,
+        collection_option,
+        sample_field_list,
+        sample_vector_list,
+    ):
+        with pytest.raises(Exception) as exc_info:
+            collection_schema = zvec.CollectionSchema(
+                name=collection_name,
+                fields=sample_field_list,
+                vectors=sample_vector_list,
+            )
+
+            coll = zvec.create_and_open(
+                path=collection_temp_dir,
+                schema=collection_schema,
+                option=collection_option,
+            )
+
+        assert SCHEMA_VALIDATE_ERROR_MSG in str(exc_info.value), str(exc_info.value)
+
+    @pytest.mark.parametrize("name_prefix", FIELD_NAME_VALID_LIST)
+    def test_valid_field_vector_name(
+        self,
+        collection_temp_dir,
+        collection_option,
+        name_prefix,
+        sample_field_list,
+        sample_vector_list,
+    ):
+        collection_schema = zvec.CollectionSchema(
+            name="test_collection",
+            fields=sample_field_list,
+            vectors=sample_vector_list,
+        )
+
+        coll = zvec.create_and_open(
+            path=collection_temp_dir,
+            schema=collection_schema,
+            option=collection_option,
+        )
+
+        check_collection_info(
+            coll, collection_schema, collection_option, collection_temp_dir
+        )
+        check_collection_basic(coll)
+
+        coll.destroy()
+
+    @pytest.mark.parametrize("field_name", FIELD_NAME_INVALID_LIST)
+    def test_invalid_field_name(
+        self, collection_temp_dir, collection_option, field_name
+    ):
+        with pytest.raises(Exception) as exc_info:
+            field_list = [FieldSchema(field_name, DataType.STRING)]
+            vector_list = [
+                VectorSchema(
+                    "dense",
+                    DataType.VECTOR_FP32,
+                    dimension=128,
+                    index_param=HnswIndexParam(),
+                )
+            ]
+
+            collection_schema = zvec.CollectionSchema(
+                name="collection_name", fields=field_list, vectors=vector_list
+            )
+
+            coll = zvec.create_and_open(
+                path=collection_temp_dir,
+                schema=collection_schema,
+                option=collection_option,
+            )
+
+        assert SCHEMA_VALIDATE_ERROR_MSG in str(exc_info.value), str(exc_info.value)
+
+    @pytest.mark.parametrize("vector_name", FIELD_NAME_INVALID_LIST)
+    def test_invalid_vector_name(
+        self, collection_temp_dir, collection_option, vector_name
+    ):
+        with pytest.raises(Exception) as exc_info:
+            field_list = [
+                FieldSchema(
+                    "id",
+                    DataType.INT64,
+                    nullable=False,
+                    index_param=InvertIndexParam(enable_range_optimization=True),
+                )
+            ]
+            vector_list = [
+                VectorSchema(vector_name, DataType.VECTOR_FP32, dimension=128)
+            ]
+
+            collection_schema = zvec.CollectionSchema(
+                name="collection_name", fields=field_list, vectors=vector_list
+            )
+
+            coll = zvec.create_and_open(
+                path=collection_temp_dir,
+                schema=collection_schema,
+                option=collection_option,
+            )
+
+        assert SCHEMA_VALIDATE_ERROR_MSG in str(exc_info.value), str(exc_info.value)
+
+    @pytest.mark.parametrize(
+        "field_list_len,vector_list_len,dimension",
+        FIELD_VECTOR_LIST_DIMENSION_VALID_LIST,
+    )
+    def test_valid_field_vector_size_dimension(
+        self,
+        collection_temp_dir,
+        collection_option,
+        field_list_len,
+        vector_list_len,
+        dimension,
+    ):
+        field_list = []
+        vector_list = []
+        for i in range(0, field_list_len):
+            field_list.append(
+                FieldSchema("id_" + str(i), DataType.INT64, nullable=True)
+            )
+
+        for i in range(0, vector_list_len):
+            vector_list.append(
+                VectorSchema(
+                    "dense_vector_" + str(i),
+                    DataType.VECTOR_FP32,
+                    dimension=dimension,
+                    index_param=HnswIndexParam(),
+                )
+            )
+
+        collection_schema = zvec.CollectionSchema(
+            name="test_dense_vector_list", fields=field_list, vectors=vector_list
+        )
+
+        coll = zvec.create_and_open(
+            path=collection_temp_dir,
+            schema=collection_schema,
+            option=collection_option,
+        )
+
+        check_collection_info(
+            coll, collection_schema, collection_option, collection_temp_dir
+        )
+        check_collection_basic(coll)
+
+        coll.destroy()
+
+    @pytest.mark.parametrize(
+        "field_list_len,vector_list_len,dimension",
+        FIELD_VECTOR_LIST_DIMENSION_INVALID_LIST,
+    )
+    def test_invalid_field_vector_size_dimension(
+        self,
+        collection_temp_dir,
+        collection_option,
+        vector_list_len,
+        field_list_len,
+        dimension,
+    ):
+        with pytest.raises(Exception) as exc_info:
+            field_list = []
+            vector_list = []
+            for i in range(0, field_list_len):
+                field_list.append(
+                    FieldSchema(
+                        "id_" + str(i),
+                        DataType.INT64,
+                        nullable=False,
+                    )
+                )
+
+            for i in range(0, vector_list_len):
+                vector_list.append(
+                    VectorSchema(
+                        "dense_vector_" + str(i),
+                        DataType.VECTOR_FP32,
+                        dimension=dimension,
+                        index_param=HnswIndexParam(),
+                    )
+                )
+
+            collection_schema = zvec.CollectionSchema(
+                name="test_dense_vector_list", fields=field_list, vectors=vector_list
+            )
+
+            coll = zvec.create_and_open(
+                path=collection_temp_dir,
+                schema=collection_schema,
+                option=collection_option,
+            )
+
+        assert SCHEMA_VALIDATE_ERROR_MSG in str(exc_info.value), str(exc_info.value)
+
+    def test_valid_single_vector_field_construction(
+        self, collection_temp_dir, collection_option
+    ):
+        field = FieldSchema(
+            "id",
+            DataType.INT64,
+            nullable=True,
+            index_param=InvertIndexParam(enable_range_optimization=True),
+        )
+
+        vector = VectorSchema(
+            "dense_vector",
+            DataType.VECTOR_FP32,
+            dimension=128,
+            index_param=HnswIndexParam(),
+        )
+
+        collection_schema = zvec.CollectionSchema(
+            name="test_single_dense_vector_non_list",
+            fields=field,
+            vectors=vector,  # Non-list form
+        )
+
+        coll = zvec.create_and_open(
+            path=collection_temp_dir,
+            schema=collection_schema,
+            option=collection_option,
+        )
+
+        check_collection_info(
+            coll, collection_schema, collection_option, collection_temp_dir
+        )
+        check_collection_basic(coll)
+        coll.destroy()
+
+    def test_collection_concurrent_create(
+        self, collection_temp_dir, basic_schema, collection_option
+    ):
+        results = []
+        errors = []
+        lock = threading.Lock()
+
+        # Function to be executed by each thread
+        def create_collection_thread(thread_id):
+            try:
+                coll = zvec.create_and_open(
+                    path=collection_temp_dir,
+                    schema=basic_schema,
+                    option=collection_option,
+                )
+                with lock:
+                    results.append((thread_id, coll))
+            except Exception as e:
+                with lock:
+                    errors.append((thread_id, str(e)))
+
+        threads = []
+        for i in range(5):
+            thread = threading.Thread(target=create_collection_thread, args=(i,))
+            threads.append(thread)
+            thread.start()
+
+        for thread in threads:
+            thread.join()
+        assert len(results) == 1, (
+            f"Expected exactly one successful creation, but got {len(results)}"
+        )
+        assert len(errors) == 4, (
+            f"Expected exactly four failures, but got {len(errors)}"
+        )
+
+        successful_thread_id, successful_collection = results[0]
+        assert successful_collection is not None, (
+            "Successful creation should return a valid collection"
+        )
+        assert successful_collection.path == collection_temp_dir, (
+            "Collection path mismatch"
+        )
+
+    def test_create_open_loop(
+        self, collection_temp_dir, collection_option, full_schema
+    ):
+        for cycle in range(10):
+            coll = zvec.create_and_open(
+                path=collection_temp_dir,
+                schema=full_schema,
+                option=collection_option,
+            )
+            assert coll is not None, (
+                f"Failed to create and open collection in cycle {cycle}"
+            )
+            assert coll.path == collection_temp_dir, (
+                f"Collection path mismatch in cycle {cycle}"
+            )
+
+            del coll
+
+            reopened_coll = zvec.open(
+                path=collection_temp_dir, option=collection_option
+            )
+            assert reopened_coll is not None, (
+                f"Failed to reopen collection in cycle {cycle}"
+            )
+            assert reopened_coll.path == collection_temp_dir, (
+                f"Reopened collection path mismatch in cycle {cycle}"
+            )
+
+            check_collection_full(reopened_coll)
+
+            reopened_coll.destroy()
+
+    @pytest.mark.parametrize(
+        "data_type, index_param", VALID_VECTOR_DATA_TYPE_INDEX_PARAM_MAP_PARAMS
+    )
+    def test_valid_vector_index_params(
+        self,
+        data_type,
+        index_param,
+        single_vector_schema_with_index_param,
+        collection_temp_dir,
+        collection_option,
+    ):
+        coll = zvec.create_and_open(
+            path=collection_temp_dir,
+            schema=single_vector_schema_with_index_param,
+            option=collection_option,
+        )
+
+        check_collection_info(
+            coll,
+            single_vector_schema_with_index_param,
+            collection_option,
+            collection_temp_dir,
+        )
+
+        check_collection_basic(coll, True)
+
+    @pytest.mark.parametrize(
+        "data_type, index_param", INVALID_VECTOR_DATA_TYPE_INDEX_PARAM_MAP_PARAMS
+    )
+    def test_invalid_vector_index_params(
+        self,
+        data_type,
+        index_param,
+        single_vector_schema_with_index_param,
+        collection_temp_dir,
+        collection_option,
+    ):
+        with pytest.raises(Exception) as exc_info:
+            coll = zvec.create_and_open(
+                path=collection_temp_dir,
+                schema=single_vector_schema_with_index_param,
+                option=collection_option,
+            )
+
+        assert SCHEMA_VALIDATE_ERROR_MSG in str(exc_info.value), str(exc_info.value)
+
+    def test_open_concurrent_same_path(self, tmp_path_factory, collection_option):
+        """Test concurrent opening of the same collection path.
+
+        - Multi-threading concurrency: 5 threads simultaneously open the same collection
+        - Result verification: Verify that only one can open successfully, others must fail
+        """
+        # Create a temporary directory and path for the collection
+        temp_dir = tmp_path_factory.mktemp("zvec")
+        collection_path = temp_dir / "concurrent_open_test_collection"
+
+        # First, create a collection that we'll try to open concurrently
+        field_list = [
+            FieldSchema(
+                "id",
+                DataType.INT64,
+                nullable=False,
+                index_param=InvertIndexParam(enable_range_optimization=True),
+            ),
+            FieldSchema(
+                "name", DataType.STRING, nullable=False, index_param=InvertIndexParam()
+            ),
+        ]
+
+        vector_list = [
+            VectorSchema(
+                "dense_vector",
+                DataType.VECTOR_FP32,
+                dimension=128,
+                index_param=HnswIndexParam(),
+            )
+        ]
+
+        collection_schema = zvec.CollectionSchema(
+            name="concurrent_open_test_collection",
+            fields=field_list,
+            vectors=vector_list,
+        )
+
+        # Create the collection first
+        coll = zvec.create_and_open(
+            path=str(collection_path),
+            schema=collection_schema,
+            option=collection_option,
+        )
+
+        # Close the collection so we can test opening it
+        if hasattr(coll, "close") and coll is not None:
+            coll.close()
+
+        # Shared variables to collect results from threads
+        results = []
+        errors = []
+
+        # Lock for thread-safe operations
+        lock = threading.Lock()
+        # Clean up the created collection reference
+        del coll
+
+        # Function to be executed by each thread
+        def open_collection_thread(thread_id):
+            try:
+                reopened_coll = zvec.open(
+                    path=str(collection_path), option=collection_option
+                )
+                with lock:
+                    results.append((thread_id, reopened_coll))
+                # Clean up the collection if opened successfully
+                if hasattr(reopened_coll, "close") and reopened_coll is not None:
+                    reopened_coll.close()
+            except Exception as e:
+                with lock:
+                    errors.append((thread_id, str(e)))
+
+        # Create and start 5 threads
+        threads = []
+        for i in range(5):
+            thread = threading.Thread(target=open_collection_thread, args=(i,))
+            threads.append(thread)
+            thread.start()
+
+        # Wait for all threads to complete
+        for thread in threads:
+            thread.join()
+
+        # Verify results:
+        # 1. Only one open should succeed (exactly one collection in results)
+        # 2. Others should fail (4 errors in errors)
+        assert len(results) == 1, (
+            f"Expected exactly one successful open, but got {len(results)}"
+        )
+        assert len(errors) == 4, (
+            f"Expected exactly four failures, but got {len(errors)}"
+        )
+
+        # Additional verification: check that the successful open has a valid collection
+        successful_thread_id, successful_collection = results[0]
+        assert successful_collection is not None, (
+            "Successful open should return a valid collection"
+        )
+        assert successful_collection.path == str(collection_path), (
+            "Collection path mismatch"
+        )
+
+    @pytest.mark.parametrize("read_only,enable_mmap", valid_collection_options)
+    def test_valid_option(
+        self, collection_temp_dir, basic_schema, read_only, enable_mmap
+    ):
+        option = CollectionOption(read_only=read_only, enable_mmap=enable_mmap)
+
+        coll = zvec.create_and_open(
+            path=collection_temp_dir,
+            schema=basic_schema,
+            option=option,
+        )
+
+        check_collection_info(coll, basic_schema, option, collection_temp_dir)
+        check_collection_basic(coll)
+
+        coll.destroy()
+
+    def test_valid_none_option(self, collection_temp_dir, basic_schema):
+        zvec.create_and_open(
+            path=collection_temp_dir,
+            schema=basic_schema,
+            option=None,
+        )
+
+    @pytest.mark.parametrize("read_only,enable_mmap", invalid_collection_options)
+    def test_invalid_option(
+        self, collection_temp_dir, basic_schema, read_only, enable_mmap
+    ):
+        with pytest.raises(Exception) as exc_info:
+            coll = zvec.create_and_open(
+                path=collection_temp_dir,
+                schema=basic_schema,
+                option=CollectionOption(read_only=read_only, enable_mmap=enable_mmap),
+            )
+
+        assert CREATE_READ_ONLY_ERROR_MSG in str(exc_info.value), str(exc_info.value)
+
+    @pytest.mark.parametrize(
+        "field_name1,field_name2,vector_name1,vector_name2",
+        duplicate_names_test,
+    )
+    def test_duplicate_field_names(
+        self,
+        collection_temp_dir,
+        collection_option,
+        field_name1,
+        field_name2,
+        vector_name1,
+        vector_name2,
+    ):
+        with pytest.raises(Exception) as exc_info:
+            collection_schema = zvec.CollectionSchema(
+                name="test_collection",
+                fields=[
+                    FieldSchema(
+                        field_name1,
+                        DataType.INT64,
+                        nullable=False,
+                        index_param=InvertIndexParam(enable_range_optimization=True),
+                    ),
+                    FieldSchema(
+                        field_name2,
+                        DataType.INT64,
+                        nullable=False,
+                        index_param=InvertIndexParam(enable_range_optimization=True),
+                    ),
+                ],
+                vectors=[
+                    VectorSchema(
+                        vector_name1,
+                        DataType.VECTOR_FP32,
+                        dimension=128,
+                        index_param=HnswIndexParam(),
+                    ),
+                    VectorSchema(
+                        vector_name2,
+                        DataType.VECTOR_FP32,
+                        dimension=128,
+                        index_param=HnswIndexParam(),
+                    ),
+                ],
+            )
+
+            coll = zvec.create_and_open(
+                path=collection_temp_dir,
+                schema=collection_schema,
+                option=collection_option,
+            )
+
+        assert SCHEMA_VALIDATE_ERROR_MSG in str(exc_info.value), str(exc_info.value)
+
+    @pytest.mark.parametrize("long_name", long_names)
+    def test_invalid_long_field_names(
+        self, collection_option, collection_temp_dir, long_name
+    ):
+        collection_schema = zvec.CollectionSchema(
+            name=long_name,
+            fields=[
+                FieldSchema(
+                    long_name + "_field",
+                    DataType.INT64,
+                    nullable=False,
+                    index_param=InvertIndexParam(enable_range_optimization=True),
+                ),
+            ],
+            vectors=[
+                VectorSchema(
+                    long_name + "_vector",
+                    DataType.VECTOR_FP32,
+                    dimension=128,
+                    index_param=HnswIndexParam(),
+                )
+            ],
+        )
+
+        with pytest.raises(Exception) as exc_info:
+            coll = zvec.create_and_open(
+                path=collection_temp_dir,
+                schema=collection_schema,
+                option=collection_option,
+            )
+
+        assert SCHEMA_VALIDATE_ERROR_MSG in str(exc_info.value), str(exc_info.value)
+
+    def test_invalid_empty_fields_and_vectors(
+        self, collection_temp_dir, collection_option
+    ):
+        collection_schema = zvec.CollectionSchema(
+            name="test_collection",
+            fields=[],  # Empty fields
+            vectors=[],  # Empty vectors
+        )
+
+        with pytest.raises(Exception) as exc_info:
+            coll = zvec.create_and_open(
+                path=collection_temp_dir,
+                schema=collection_schema,
+                option=collection_option,
+            )
+
+        assert SCHEMA_VALIDATE_ERROR_MSG in str(exc_info.value), str(exc_info.value)
+
+    @pytest.mark.parametrize("valid_path", valid_path_list)
+    def test_valid_path(self, basic_schema, collection_option, valid_path):
+        if os.path.exists(valid_path):
+            import shutil
+
+            shutil.rmtree(valid_path)
+
+        coll = zvec.create_and_open(
+            path=valid_path, schema=basic_schema, option=collection_option
+        )
+
+        check_collection_info(coll, basic_schema, collection_option, valid_path)
+
+        coll.destroy()
+
+    @pytest.mark.parametrize("invalid_path", invalid_path_list)
+    def test_invalid_path(self, basic_schema, collection_option, invalid_path):
+        with pytest.raises(Exception) as exc_info:
+            coll = zvec.create_and_open(
+                path=invalid_path, schema=basic_schema, option=collection_option
+            )
+
+        assert INVALID_PATH_ERROR_MSG in str(exc_info.value), str(exc_info.value)

python/tests/detail/test_collection_exception.py

@@ -0,0 +1,328 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+import logging
+import pytest
+import numpy as np
+import zvec
+
+from zvec import (
+    CollectionOption,
+    InvertIndexParam,
+    HnswIndexParam,
+    DataType,
+    Collection,
+    Doc,
+    FieldSchema,
+    Query,
+    VectorSchema,
+)
+
+
+class TestCollectionExceptionHandling:
+    @pytest.fixture(scope="function")
+    def test_collection(self, tmp_path_factory):
+        """Fixture to create a test collection"""
+        collection_schema = zvec.CollectionSchema(
+            name="test_collection",
+            fields=[
+                FieldSchema(
+                    "id",
+                    DataType.INT64,
+                    nullable=False,
+                    index_param=InvertIndexParam(enable_range_optimization=True),
+                ),
+                FieldSchema(
+                    "name",
+                    DataType.STRING,
+                    nullable=False,
+                    index_param=InvertIndexParam(),
+                ),
+                FieldSchema("weight", DataType.FLOAT, nullable=True),
+            ],
+            vectors=[
+                VectorSchema(
+                    "dense",
+                    DataType.VECTOR_FP32,
+                    dimension=128,
+                    index_param=HnswIndexParam(),
+                ),
+                VectorSchema(
+                    "sparse", DataType.SPARSE_VECTOR_FP32, index_param=HnswIndexParam()
+                ),
+            ],
+        )
+
+        collection_option = CollectionOption(read_only=False, enable_mmap=True)
+
+        temp_dir = tmp_path_factory.mktemp("zvec")
+        collection_path = temp_dir / "test_collection"
+
+        coll = zvec.create_and_open(
+            path=str(collection_path),
+            schema=collection_schema,
+            option=collection_option,
+        )
+
+        assert coll is not None, "Failed to create and open collection"
+
+        yield coll
+
+        # Clean up
+        if hasattr(coll, "destroy") and coll is not None:
+            try:
+                coll.destroy()
+            except Exception as e:
+                print(f"Warning: failed to destroy collection: {e}")
+
+    def test_create_and_open_missing_path(self, tmp_path_factory):
+        collection_schema = zvec.CollectionSchema(
+            name="test_collection",
+            fields=[
+                FieldSchema(
+                    "id",
+                    DataType.INT64,
+                    nullable=False,
+                    index_param=InvertIndexParam(enable_range_optimization=True),
+                ),
+                FieldSchema(
+                    "name",
+                    DataType.STRING,
+                    nullable=False,
+                    index_param=InvertIndexParam(),
+                ),
+            ],
+            vectors=[
+                VectorSchema(
+                    "dense",
+                    DataType.VECTOR_FP32,
+                    dimension=128,
+                    index_param=HnswIndexParam(),
+                )
+            ],
+        )
+
+        collection_option = CollectionOption(read_only=False, enable_mmap=True)
+
+        with pytest.raises(Exception) as exc_info:
+            coll = zvec.create_and_open(
+                schema=collection_schema, option=collection_option
+            )
+        assert exc_info.value is not None, (
+            "Expected exception for missing path parameter"
+        )
+
+    def test_create_and_open_missing_schema(self, tmp_path_factory):
+        temp_dir = tmp_path_factory.mktemp("zvec")
+        collection_path = temp_dir / "test_collection"
+
+        collection_option = CollectionOption(read_only=False, enable_mmap=True)
+
+        with pytest.raises(Exception) as exc_info:
+            coll = zvec.create_and_open(
+                path=str(collection_path), option=collection_option
+            )
+        assert exc_info.value is not None, (
+            "Expected exception for missing schema parameter"
+        )
+
+    def test_open_missing_path(self):
+        collection_option = CollectionOption(read_only=False, enable_mmap=True)
+
+        with pytest.raises(Exception) as exc_info:
+            coll = zvec.open(option=collection_option)
+        assert exc_info.value is not None, (
+            "Expected exception for missing path parameter"
+        )
+
+    def test_insert_missing_docs(self, test_collection: Collection):
+        with pytest.raises(Exception) as exc_info:
+            result = test_collection.insert()
+        assert exc_info.value is not None, (
+            "Expected exception for missing docs parameter"
+        )
+
+    def test_update_missing_docs(self, test_collection: Collection):
+        with pytest.raises(Exception) as exc_info:
+            result = test_collection.update()
+        assert exc_info.value is not None, (
+            "Expected exception for missing docs parameter"
+        )
+
+    def test_upsert_missing_docs(self, test_collection: Collection):
+        with pytest.raises(Exception) as exc_info:
+            result = test_collection.upsert()
+        assert exc_info.value is not None, (
+            "Expected exception for missing docs parameter"
+        )
+
+    def test_delete_missing_ids(self, test_collection: Collection):
+        with pytest.raises(Exception) as exc_info:
+            result = test_collection.delete()
+        assert exc_info.value is not None, (
+            "Expected exception for missing ids parameter"
+        )
+
+    def test_fetch_missing_ids(self, test_collection: Collection):
+        with pytest.raises(Exception) as exc_info:
+            result = test_collection.fetch()
+        assert exc_info.value is not None, (
+            "Expected exception for missing ids parameter"
+        )
+
+    def test_query_missing_query_field_name(self, test_collection: Collection):
+        with pytest.raises(Exception) as exc_info:
+            result = test_collection.query([Query()])
+        assert exc_info.value is not None, (
+            "Expected exception for missing Query field_name parameter"
+        )
+
+    def test_add_column_missing_field_schema(self, test_collection: Collection):
+        with pytest.raises(Exception) as exc_info:
+            test_collection.add_column()
+        assert exc_info.value is not None, (
+            "Expected exception for missing field_schema parameter"
+        )
+
+    def test_alter_column_missing_old_name(self, test_collection: Collection):
+        with pytest.raises(Exception) as exc_info:
+            test_collection.alter_column(new_name="new_name")
+        assert exc_info.value is not None, (
+            "Expected exception for missing old_name parameter"
+        )
+
+    def test_alter_column_missing_new_name(self, test_collection: Collection):
+        with pytest.raises(Exception) as exc_info:
+            test_collection.alter_column(old_name="old_name")
+        assert exc_info.value is not None, (
+            "Expected exception for missing new_name parameter"
+        )
+
+    def test_drop_column_missing_field_name(self, test_collection: Collection):
+        with pytest.raises(Exception) as exc_info:
+            test_collection.drop_column()
+        assert exc_info.value is not None, (
+            "Expected exception for missing field_name parameter"
+        )
+
+    def test_invalid_parameter_types(self, test_collection: Collection):
+        # This test depends on specific implementation details
+        # Generally, we would expect TypeErrors or similar exceptions
+        pass
+
+    def test_missing_required_parameters(self, test_collection: Collection):
+        # This test depends on specific implementation details
+        # Generally, we would expect TypeErrors or similar exceptions
+        pass
+
+    def test_empty_collection_operations(self, tmp_path_factory):
+        collection_schema = zvec.CollectionSchema(
+            name="empty_test_collection",
+            fields=[
+                FieldSchema(
+                    "id",
+                    DataType.INT64,
+                    nullable=False,
+                    index_param=InvertIndexParam(enable_range_optimization=True),
+                ),
+                FieldSchema(
+                    "name",
+                    DataType.STRING,
+                    nullable=False,
+                    index_param=InvertIndexParam(),
+                ),
+            ],
+            vectors=[
+                VectorSchema(
+                    "dense",
+                    DataType.VECTOR_FP32,
+                    dimension=128,
+                    index_param=HnswIndexParam(),
+                )
+            ],
+        )
+
+        collection_option = CollectionOption(read_only=False, enable_mmap=True)
+
+        temp_dir = tmp_path_factory.mktemp("zvec")
+        collection_path = temp_dir / "empty_test_collection"
+
+        coll = zvec.create_and_open(
+            path=str(collection_path),
+            schema=collection_schema,
+            option=collection_option,
+        )
+
+        assert coll is not None, "Failed to create and open collection"
+
+        # Test fetch on empty collection
+        result = coll.fetch(["1"])
+        assert len(result) >= 0  # May be empty or have special handling
+
+        # Test query on empty collection
+        result = coll.query()
+        assert len(result) == 0
+
+        # Test update on empty collection
+        doc = Doc(
+            id="1",
+            fields={"id": 1, "name": "test"},
+            vectors={"dense": np.random.random(128).tolist()},
+        )
+
+        result = coll.update(doc)
+        # Should handle gracefully, possibly with NOT_FOUND status
+
+        # Clean up
+        if hasattr(coll, "destroy") and coll is not None:
+            try:
+                coll.destroy()
+            except Exception as e:
+                print(f"Warning: failed to destroy collection: {e}")
+
+    def test_resource_management(self, test_collection: Collection):
+        doc = Doc(
+            id="1",
+            fields={"id": 1, "name": "test", "weight": 80.5},
+            vectors={
+                "dense": np.random.random(128).tolist(),
+                "sparse": {1: 1.0, 2: 2.0},
+            },
+        )
+
+        # Insert
+        result = test_collection.insert(doc)
+        assert result.ok()
+
+        # Fetch
+        result = test_collection.fetch(["1"])
+        assert len(result) == 1
+
+        # Query
+        result = test_collection.query()
+        assert len(result) >= 0
+
+        # Update
+        result = test_collection.update(doc)
+        assert result.ok()
+
+        # Delete
+        result = test_collection.delete("1")
+        assert result.ok()
+
+    def test_exception_resource_cleanup(self, test_collection: Collection):
+        # This test would need to simulate exception conditions
+        # which is difficult without specific failure injection points
+        pass

python/tests/detail/test_collection_open.py

@@ -0,0 +1,967 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+import threading
+import numpy as np
+
+from fixture_helper import *
+
+COLLECTION_OPTION_TEST_CASES_VALID = [
+    # (read_only, enable_mmap, description)
+    (False, True, "Read-write with mmap enabled"),
+    (False, False, "Read-write with mmap disabled"),
+    (True, True, "Read-only with mmap enabled"),
+    (True, False, "Read-only with mmap disabled"),
+]
+
+# Test data for invalid paths
+INVALID_PATH_LIST = [
+    "/nonexistent/directory/test_collection",
+    "invalid:path",
+    "",  # Empty path
+]
+
+
+@pytest.fixture(scope="session")
+def collection_schema():
+    return zvec.CollectionSchema(
+        name="test_collection",
+        fields=[
+            FieldSchema(
+                "id",
+                DataType.INT64,
+                nullable=False,
+                index_param=InvertIndexParam(enable_range_optimization=True),
+            ),
+            FieldSchema(
+                "name", DataType.STRING, nullable=False, index_param=InvertIndexParam()
+            ),
+            FieldSchema(
+                "weight", DataType.FLOAT, nullable=False, index_param=InvertIndexParam()
+            ),
+        ],
+        vectors=[
+            VectorSchema(
+                "dense",
+                DataType.VECTOR_FP32,
+                dimension=128,
+                index_param=HnswIndexParam(),
+            ),
+            VectorSchema(
+                "sparse", DataType.SPARSE_VECTOR_FP32, index_param=HnswIndexParam()
+            ),
+        ],
+    )
+
+
+@pytest.fixture
+def single_doc():
+    id = 0
+    return Doc(
+        id=f"{id}",
+        fields={"id": id, "name": "test"},
+        vectors={
+            "dense": [id + 0.1] * 128,
+        },
+    )
+
+
+@pytest.fixture(scope="function")
+def test_collection(
+    tmp_path_factory, collection_schema, collection_option
+) -> Generator[Any, Any, Collection]:
+    temp_dir = tmp_path_factory.mktemp("zvec")
+    collection_path = temp_dir / "test_collection"
+
+    coll = zvec.create_and_open(
+        path=str(collection_path), schema=collection_schema, option=collection_option
+    )
+
+    assert coll is not None, "Failed to create and open collection"
+    assert coll.path == str(collection_path)
+    assert coll.schema.name == collection_schema.name
+    assert list(coll.schema.fields) == list(collection_schema.fields)
+    assert list(coll.schema.vectors) == list(collection_schema.vectors)
+    assert coll.option.read_only == collection_option.read_only
+    assert coll.option.enable_mmap == collection_option.enable_mmap
+
+    try:
+        yield coll
+    finally:
+        if hasattr(coll, "destroy") and coll is not None:
+            try:
+                coll.destroy()
+            except Exception as e:
+                print(f"Warning: failed to destroy collection: {e}")
+
+
+class TestCollectionOpen:
+    def test_open_basic_functionality(
+        self, tmp_path_factory, collection_schema, collection_option
+    ):
+        import sys
+        import time
+        import os
+
+        # Create unique temp directory
+        temp_dir = tmp_path_factory.mktemp("zvec")
+        collection_path = temp_dir / "test_collection"
+
+        # Ensure the path exists
+        collection_path_str = str(collection_path)
+        print(f"DEBUG: Collection path: {collection_path_str}")
+        print(f"DEBUG: Temp directory exists: {temp_dir.exists()}")
+
+        # Create and open collection first
+        created_coll = zvec.create_and_open(
+            path=collection_path_str, schema=collection_schema, option=collection_option
+        )
+
+        assert created_coll is not None, (
+            f"Failed to create collection, returned None instead of valid Collection object. Path: {collection_path_str}"
+        )
+        assert created_coll.path == collection_path_str, (
+            f"Collection path mismatch. Expected: {collection_path_str}, Actual: {created_coll.path}"
+        )
+        assert created_coll.schema.name == "test_collection", (
+            f"Collection schema name mismatch. Expected: test_collection, Actual: {created_coll.schema.name}"
+        )
+
+        # Insert multiple documents to verify persistence
+        docs = []
+        for i in range(3):
+            doc = Doc(
+                id=f"{i}",
+                fields={"id": i, "name": f"test_{i}", "weight": float(i * 10)},
+                vectors={
+                    "dense": [float(j + i) for j in range(128)],
+                    "sparse": {j: float(j + i) for j in range(5)},
+                },
+            )
+            docs.append(doc)
+
+        result = created_coll.insert(docs)
+        assert len(result) == 3, f"Expected 3 insertion results, but got {len(result)}"
+        for i, res in enumerate(result):
+            assert res.ok(), (
+                f"Insertion result {i} is not OK. Status code: {res.code()}, Message: {res.message()}"
+            )
+
+        # Verify documents were inserted using fetch interface
+        fetched_docs_after_insert = created_coll.fetch(["0", "1", "2"])
+        assert len(fetched_docs_after_insert) == 3, (
+            f"Expected 3 fetched documents after insertion, but got {len(fetched_docs_after_insert)}"
+        )
+        assert "0" in fetched_docs_after_insert, (
+            "Document with ID '0' not found in fetched results after insertion"
+        )
+        assert "1" in fetched_docs_after_insert, (
+            "Document with ID '1' not found in fetched results after insertion"
+        )
+        assert "2" in fetched_docs_after_insert, (
+            "Document with ID '2' not found in fetched results after insertion"
+        )
+
+        # Verify fetched document content after insertion
+        for i in range(3):
+            doc = fetched_docs_after_insert[f"{i}"]
+            assert doc is not None, (
+                f"Fetched document with ID '{i}' is None after insertion"
+            )
+            assert doc.id == f"{i}", (
+                f"Document ID mismatch for document '{i}' after insertion. Expected: {i}, Actual: {doc.id}"
+            )
+            assert doc.field("id") == i, (
+                f"Document id field mismatch for document '{i}' after insertion. Expected: {i}, Actual: {doc.field('id')}"
+            )
+            assert doc.field("name") == f"test_{i}", (
+                f"Document name field mismatch for document '{i}' after insertion. Expected: test_{i}, Actual: {doc.field('name')}"
+            )
+            assert doc.field("weight") == float(i * 10), (
+                f"Document weight field mismatch for document '{i}' after insertion. Expected: {float(i * 10)}, Actual: {doc.field('weight')}"
+            )
+
+            # Verify vector access after insertion
+            assert doc.vector("dense") is not None, (
+                f"Document {i} should have dense vector after insertion"
+            )
+            assert doc.vector("sparse") is not None, (
+                f"Document {i} should have sparse vector after insertion"
+            )
+
+            # Verify vector types after insertion
+            assert isinstance(doc.vector("dense"), list), (
+                f"Document {i} dense vector should be dict after insertion, got {type(doc.vector('dense'))}"
+            )
+            assert isinstance(doc.vector("sparse"), dict), (
+                f"Document {i} sparse vector should be dict after insertion, got {type(doc.vector('sparse'))}"
+            )
+
+        # Verify documents were inserted using stats
+        stats = created_coll.stats
+        assert stats is not None, "Collection stats should not be None"
+        assert stats.doc_count == 3, (
+            f"Document count mismatch after insertion. Expected: 3, Actual: {stats.doc_count}"
+        )
+
+        # Store the collection path before cleanup
+        collection_path = created_coll.path
+
+        # Clean up the created collection reference
+        del created_coll
+
+        # Wait and verify the path still exists
+        print(f"DEBUG: Collection path after destroy: {collection_path}")
+        print(f"DEBUG: Path exists after destroy: {os.path.exists(collection_path)}")
+
+        # Now open the existing collection
+        try:
+            print(f"DEBUG: Path exists before open: {os.path.exists(collection_path)}")
+
+            # List contents of parent directory for debugging
+            parent_dir = os.path.dirname(collection_path)
+            if os.path.exists(parent_dir):
+                print(f"DEBUG: Parent directory contents: {os.listdir(parent_dir)}")
+
+            opened_coll = zvec.open(path=collection_path, option=collection_option)
+
+            assert opened_coll is not None, (
+                f"Failed to open existing collection at path: {collection_path}. Returned None instead of valid Collection object"
+            )
+            assert opened_coll.path == collection_path, (
+                f"Opened collection path mismatch. Expected: {collection_path}, Actual: {opened_coll.path}"
+            )
+            assert opened_coll.schema.name == "test_collection", (
+                f"Opened collection schema name mismatch. Expected: test_collection, Actual: {opened_coll.schema.name}"
+            )
+
+            # Check reference count of opened collection
+            opened_ref_count = sys.getrefcount(opened_coll)
+            print(f"DEBUG: Reference count of opened collection: {opened_ref_count}")
+
+            # Verify data persistence
+            # Verify data persistence using fetch interface
+            fetched_docs = opened_coll.fetch(["0", "1", "2"])
+            assert len(fetched_docs) == 3, (
+                f"Expected 3 fetched documents after reopening, but got {len(fetched_docs)}"
+            )
+            assert "0" in fetched_docs, (
+                "Document with ID '0' not found in fetched results after reopening"
+            )
+            assert "1" in fetched_docs, (
+                "Document with ID '1' not found in fetched results after reopening"
+            )
+            assert "2" in fetched_docs, (
+                "Document with ID '2' not found in fetched results after reopening"
+            )
+
+            # Verify fetched document content after reopening collection
+            for i in range(3):
+                doc = fetched_docs[f"{i}"]
+                assert doc is not None, (
+                    f"Fetched document with ID '{i}' is None after reopening collection"
+                )
+                assert doc.id == f"{i}", (
+                    f"Document ID mismatch for document '{i}' after reopening. Expected: {i}, Actual: {doc.id}"
+                )
+                assert doc.field("id") == i, (
+                    f"Document id field mismatch for document '{i}' after reopening. Expected: {i}, Actual: {doc.field('id')}"
+                )
+                assert doc.field("name") == f"test_{i}", (
+                    f"Document name field mismatch for document '{i}' after reopening. Expected: test_{i}, Actual: {doc.field('name')}"
+                )
+                assert doc.field("weight") == float(i * 10), (
+                    f"Document weight field mismatch for document '{i}' after reopening. Expected: {float(i * 10)}, Actual: {doc.field('weight')}"
+                )
+
+                # Verify vector access after reopening
+                assert doc.vector("dense") is not None, (
+                    f"Document {i} should have dense vector after reopening"
+                )
+                assert doc.vector("sparse") is not None, (
+                    f"Document {i} should have sparse vector after reopening"
+                )
+
+                # Verify vector types after reopening
+                assert isinstance(doc.vector("dense"), list), (
+                    f"Document {i} dense vector should be dict after reopening, got {type(doc.vector('dense'))}"
+                )
+                assert isinstance(doc.vector("sparse"), dict), (
+                    f"Document {i} sparse vector should be dict after reopening, got {type(doc.vector('sparse'))}"
+                )
+
+                # Verify score attribute exists
+                assert hasattr(doc, "score"), (
+                    f"Document {i} should have a score attribute after reopening"
+                )
+                assert isinstance(doc.score, (int, float)), (
+                    f"Document {i} score should be numeric after reopening, got {type(doc.score)}"
+                )
+                # For fetch operations, score is typically 0.0
+                assert doc.score == 0.0, (
+                    f"Document {i} score should be 0.0 for fetch operation after reopening, but got {doc.score}"
+                )
+
+            # Test query functionality
+            query_result = opened_coll.query(include_vector=True)
+            assert len(query_result) == 3, (
+                f"Expected 3 query results, but got {len(query_result)}"
+            )
+
+            # Verify query results have proper structure and content with detailed validation
+            returned_doc_ids = set()
+            for doc in query_result:
+                # Verify basic document structure
+                assert doc.id is not None, f"Query result document should have an ID"
+                assert doc.id in ["0", "1", "2"], (
+                    f"Query result document ID should be one of ['0', '1', '2'], but got {doc.id}"
+                )
+                returned_doc_ids.add(doc.id)
+
+                # Verify field access
+                assert doc.field("id") is not None, (
+                    f"Document {doc.id} should have id field"
+                )
+                assert doc.field("name") is not None, (
+                    f"Document {doc.id} should have name field"
+                )
+                assert doc.field("weight") is not None, (
+                    f"Document {doc.id} should have weight field"
+                )
+
+                # Verify field values
+                expected_id = int(doc.id)
+                assert doc.field("id") == expected_id, (
+                    f"Document {doc.id} id field mismatch. Expected: {expected_id}, Actual: {doc.field('id')}"
+                )
+                assert doc.field("name") == f"test_{expected_id}", (
+                    f"Document {doc.id} name field mismatch. Expected: test_{expected_id}, Actual: {doc.field('name')}"
+                )
+                assert doc.field("weight") == float(expected_id * 10), (
+                    f"Document {doc.id} weight field mismatch. Expected: {float(expected_id * 10)}, Actual: {doc.field('weight')}"
+                )
+
+                # Verify vector access
+                assert doc.vector("dense") is not None, (
+                    f"Document {doc.id} should have dense vector"
+                )
+                assert doc.vector("sparse") is not None, (
+                    f"Document {doc.id} should have sparse vector"
+                )
+
+                # Verify vector types
+                assert isinstance(doc.vector("dense"), list), (
+                    f"Document {doc.id} dense vector should be list, got {type(doc.vector('dense'))}"
+                )
+                assert isinstance(doc.vector("sparse"), dict), (
+                    f"Document {doc.id} sparse vector should be dict, got {type(doc.vector('sparse'))}"
+                )
+
+                # Verify score attribute exists
+                assert hasattr(doc, "score"), (
+                    f"Document {doc.id} should have a score attribute"
+                )
+                assert isinstance(doc.score, (int, float)), (
+                    f"Document {doc.id} score should be numeric, got {type(doc.score)}"
+                )
+
+            # Verify all expected documents are returned
+            expected_doc_ids = {"0", "1", "2"}
+            assert returned_doc_ids == expected_doc_ids, (
+                f"Query should return all expected documents. Expected: {expected_doc_ids}, Actual: {returned_doc_ids}"
+            )
+
+            # === Enhanced validation based on test_collection_dql_operations.py ===
+
+            # Verify vector field names accessibility for all documents
+            for doc in query_result:
+                vector_names = doc.vector_names()
+                expected_vector_names = {"dense", "sparse"}
+                assert set(vector_names) == expected_vector_names, (
+                    f"Document {doc.id} vector names mismatch. Expected: {expected_vector_names}, Actual: {set(vector_names)}"
+                )
+
+                # Verify all vector fields can be accessed
+                for vector_name in expected_vector_names:
+                    vector_data = doc.vector(vector_name)
+                    assert vector_data is not None, (
+                        f"Document {doc.id} should have accessible vector '{vector_name}'"
+                    )
+                    if vector_name == "dense":
+                        assert isinstance(vector_data, list), (
+                            f"Document {doc.id} vector '{vector_name}' should be list, got {type(vector_data)}"
+                        )
+                    else:
+                        assert isinstance(vector_data, dict), (
+                            f"Document {doc.id} vector '{vector_name}' should be dict, got {type(vector_data)}"
+                        )
+
+            # Test query with filter
+            filtered_result = opened_coll.query(filter="id >= 1", include_vector=True)
+            assert len(filtered_result) == 2, (
+                f"Expected 2 filtered query results (id >= 1), but got {len(filtered_result)}"
+            )
+
+            # Verify filtered query results
+            filtered_doc_ids = set()
+            for doc in filtered_result:
+                assert doc.id is not None, (
+                    f"Filtered query result document should have an ID"
+                )
+                assert doc.id in ["1", "2"], (
+                    f"Filtered query result document ID should be one of ['1', '2'], but got {doc.id}"
+                )
+                filtered_doc_ids.add(doc.id)
+
+                # Verify filter condition is satisfied
+                doc_id = int(doc.id)
+                assert doc_id >= 1, (
+                    f"Document {doc.id} should satisfy filter condition id >= 1"
+                )
+
+                # Verify document structure
+                assert doc.field("id") is not None, (
+                    f"Document {doc.id} should have id field"
+                )
+                assert doc.field("name") is not None, (
+                    f"Document {doc.id} should have name field"
+                )
+                assert doc.field("weight") is not None, (
+                    f"Document {doc.id} should have weight field"
+                )
+
+                # Verify field values
+                assert doc.field("id") == doc_id, (
+                    f"Document {doc.id} id field mismatch. Expected: {doc_id}, Actual: {doc.field('id')}"
+                )
+                assert doc.field("name") == f"test_{doc_id}", (
+                    f"Document {doc.id} name field mismatch. Expected: test_{doc_id}, Actual: {doc.field('name')}"
+                )
+                assert doc.field("weight") == float(doc_id * 10), (
+                    f"Document {doc.id} weight field mismatch. Expected: {float(doc_id * 10)}, Actual: {doc.field('weight')}"
+                )
+
+                # Verify vector access
+                assert doc.vector("dense") is not None, (
+                    f"Document {doc.id} should have dense vector"
+                )
+                assert doc.vector("sparse") is not None, (
+                    f"Document {doc.id} should have sparse vector"
+                )
+
+                # Verify score attribute exists
+                assert hasattr(doc, "score"), (
+                    f"Document {doc.id} should have a score attribute"
+                )
+                assert isinstance(doc.score, (int, float)), (
+                    f"Document {doc.id} score should be numeric, got {type(doc.score)}"
+                )
+
+            # Verify filtered documents
+            expected_filtered_ids = {"1", "2"}
+            assert filtered_doc_ids == expected_filtered_ids, (
+                f"Filtered query should return expected documents. Expected: {expected_filtered_ids}, Actual: {filtered_doc_ids}"
+            )
+
+            # Test vector query functionality for dense vectors
+            query_vector_dense = [0.1] * 128
+            vector_query_result = opened_coll.query(
+                Query(field_name="dense", vector=query_vector_dense)
+            )
+            assert len(vector_query_result) > 0, (
+                f"Expected at least 1 vector query result, but got {len(vector_query_result)}"
+            )
+
+            # Verify vector query results structure
+            for doc in vector_query_result[:3]:  # Check first 3 results
+                assert doc.id is not None, (
+                    f"Vector query result document should have an ID"
+                )
+                assert doc.id in ["0", "1", "2"], (
+                    f"Vector query result document ID should be one of ['0', '1', '2'], but got {doc.id}"
+                )
+
+                # Verify document structure
+                assert doc.field("id") is not None, (
+                    f"Document {doc.id} should have id field"
+                )
+                assert doc.field("name") is not None, (
+                    f"Document {doc.id} should have name field"
+                )
+                assert doc.field("weight") is not None, (
+                    f"Document {doc.id} should have weight field"
+                )
+
+                # Verify vector access
+                assert doc.vector("dense") is not None, (
+                    f"Document {doc.id} should have dense vector"
+                )
+                assert doc.vector("sparse") is not None, (
+                    f"Document {doc.id} should have sparse vector"
+                )
+
+                # Verify score attribute exists and is numeric
+                assert hasattr(doc, "score"), (
+                    f"Document {doc.id} should have a score attribute"
+                )
+                assert isinstance(doc.score, (int, float)), (
+                    f"Document {doc.id} score should be numeric, got {type(doc.score)}"
+                )
+
+                # For dense vector queries, score should typically be non-negative (depending on metric)
+                # Note: This may vary based on the metric type used
+                assert doc.score >= 0 or doc.score < 0, (
+                    f"Document {doc.id} score should be a valid number"
+                )
+
+            # Test vector query functionality for sparse vectors
+            query_vector_sparse = {1: 1.0, 2: 2.0, 3: 3.0}
+            sparse_vector_query_result = opened_coll.query(
+                Query(field_name="sparse", vector=query_vector_sparse)
+            )
+            assert len(sparse_vector_query_result) > 0, (
+                f"Expected at least 1 sparse vector query result, but got {len(sparse_vector_query_result)}"
+            )
+
+            # Verify sparse vector query results structure
+            for doc in sparse_vector_query_result[:3]:  # Check first 3 results
+                assert doc.id is not None, (
+                    f"Sparse vector query result document should have an ID"
+                )
+                assert doc.id in ["0", "1", "2"], (
+                    f"Sparse vector query result document ID should be one of ['0', '1', '2'], but got {doc.id}"
+                )
+
+                # Verify document structure
+                assert doc.field("id") is not None, (
+                    f"Document {doc.id} should have id field"
+                )
+                assert doc.field("name") is not None, (
+                    f"Document {doc.id} should have name field"
+                )
+                assert doc.field("weight") is not None, (
+                    f"Document {doc.id} should have weight field"
+                )
+
+                # Verify vector access
+                assert doc.vector("dense") is not None, (
+                    f"Document {doc.id} should have dense vector"
+                )
+                assert doc.vector("sparse") is not None, (
+                    f"Document {doc.id} should have sparse vector"
+                )
+
+                # Verify score attribute exists and is numeric
+                assert hasattr(doc, "score"), (
+                    f"Document {doc.id} should have a score attribute"
+                )
+                assert isinstance(doc.score, (int, float)), (
+                    f"Document {doc.id} score should be numeric, got {type(doc.score)}"
+                )
+
+            # Clean up
+            if hasattr(opened_coll, "destroy") and opened_coll is not None:
+                opened_coll.destroy()
+                print("DEBUG: Opened collection destroyed successfully")
+
+        except Exception as e:
+            logging.error("Exception occurred: [{}]".format(e))
+            raise e
+
+    @pytest.mark.parametrize(
+        "read_only,enable_mmap,description", COLLECTION_OPTION_TEST_CASES_VALID
+    )
+    @pytest.mark.parametrize("createAndopen_enable_mmap", [True, False])
+    def test_open_with_different_collection_options_valid(
+        self,
+        tmp_path_factory,
+        createAndopen_enable_mmap,
+        read_only,
+        enable_mmap,
+        description,
+        collection_schema,
+    ):
+        # Create collection with initial option
+        temp_dir = tmp_path_factory.mktemp("zvec")
+        collection_path = temp_dir / "test_collection"
+
+        initial_option = CollectionOption(
+            read_only=False, enable_mmap=createAndopen_enable_mmap
+        )
+
+        # Create and open collection first
+        created_coll = zvec.create_and_open(
+            path=str(collection_path), schema=collection_schema, option=initial_option
+        )
+
+        assert created_coll is not None, "Failed to create collection"
+
+        # Clean up the created collection reference
+        del created_coll
+
+        # Now open with different options
+        collection_option = CollectionOption(
+            read_only=read_only, enable_mmap=enable_mmap
+        )
+
+        try:
+            opened_coll = zvec.open(path=str(collection_path), option=collection_option)
+
+            assert opened_coll is not None, (
+                f"Failed to open collection with option: {description}. Returned None instead of valid Collection object. Path: {collection_path}"
+            )
+            assert opened_coll.path == str(collection_path), (
+                f"Opened collection path mismatch. Expected: {collection_path}, Actual: {opened_coll.path}"
+            )
+            assert opened_coll.schema.name == collection_schema.name, (
+                f"Opened collection schema name mismatch. Expected: {collection_schema.name}, Actual: {opened_coll.schema.name}"
+            )
+            assert opened_coll.option.read_only == read_only, (
+                f"Opened collection read_only option mismatch. Expected: {read_only}, Actual: {opened_coll.option.read_only}"
+            )
+            assert opened_coll.option.enable_mmap == createAndopen_enable_mmap, (
+                f"Opened collection mmap option mismatch. Expected: {createAndopen_enable_mmap}, Actual: {opened_coll.option.enable_mmap}"
+            )
+
+            # Clean up
+            if (
+                hasattr(opened_coll, "destroy")
+                and opened_coll is not None
+                and read_only == False
+            ):
+                opened_coll.destroy()
+
+        except Exception as e:
+            logging.error("Exception occurred: [{}]".format(e))
+            pytest.fail(f"Failed to open collection with different options: {e}")
+
+    def test_open_with_none_option(self, tmp_path_factory, collection_schema):
+        # Create collection
+        temp_dir = tmp_path_factory.mktemp("zvec")
+        collection_path = temp_dir / "test_collection"
+
+        initial_option = CollectionOption(read_only=False, enable_mmap=True)
+
+        # Create and open collection first
+        created_coll = zvec.create_and_open(
+            path=str(collection_path), schema=collection_schema, option=initial_option
+        )
+
+        assert created_coll is not None, (
+            f"Failed to create collection. Returned None instead of valid Collection object. Path: {collection_path}"
+        )
+
+        # Clean up the created collection reference
+        del created_coll
+
+        # Now open with None option
+        with pytest.raises(Exception) as exc_info:
+            zvec.open(path=str(collection_path), option=None)
+
+        assert "incompatible function arguments" in str(exc_info.value), (
+            f"Expected 'incompatible function arguments' error, but got: {exc_info.value}"
+        )
+
+    def test_reopen_collection(self, tmp_path_factory):
+        # Prepare schema
+        collection_schema = zvec.CollectionSchema(
+            name="test_collection",
+            fields=[
+                FieldSchema(
+                    "id",
+                    DataType.INT64,
+                    nullable=False,
+                    index_param=InvertIndexParam(enable_range_optimization=True),
+                ),
+                FieldSchema(
+                    "name",
+                    DataType.STRING,
+                    nullable=False,
+                    index_param=InvertIndexParam(),
+                ),
+                FieldSchema(
+                    "description",
+                    DataType.STRING,
+                    nullable=True,
+                    index_param=InvertIndexParam(),
+                ),
+            ],
+            vectors=[
+                VectorSchema(
+                    "dense",
+                    DataType.VECTOR_FP32,
+                    dimension=128,
+                    index_param=HnswIndexParam(),
+                )
+            ],
+        )
+
+        collection_option = CollectionOption(read_only=False, enable_mmap=True)
+
+        # Create collection
+        temp_dir = tmp_path_factory.mktemp("zvec")
+        collection_path = temp_dir / "test_collection"
+
+        # Create and open collection
+        coll1 = zvec.create_and_open(
+            path=str(collection_path),
+            schema=collection_schema,
+            option=collection_option,
+        )
+
+        assert coll1 is not None, "Failed to create and open collection"
+
+        # Insert some data
+        doc = Doc(
+            id="1",
+            fields={"id": 1, "name": "test", "description": "这是一个中文描述。"},
+            vectors={"dense": np.random.random(128).tolist()},
+        )
+
+        result = coll1.insert(doc)
+        assert result.ok()
+
+        # Close the first collection (delete reference)
+        del coll1
+
+        # Reopen the collection
+        coll2 = zvec.open(path=str(collection_path), option=collection_option)
+
+        assert coll2 is not None, "Failed to reopen collection"
+        assert coll2.path == str(collection_path)
+        assert coll2.schema.name == collection_schema.name
+
+        # Verify data is still there
+        fetched_docs = coll2.fetch(["1"])
+        assert "1" in fetched_docs
+        fetched_doc = fetched_docs["1"]
+        assert fetched_doc.id == "1"
+        assert fetched_doc.field("name") == "test"
+        assert fetched_doc.field("description") == "这是一个中文描述。"
+
+        # Clean up
+        if hasattr(coll2, "destroy") and coll2 is not None:
+            try:
+                coll2.destroy()
+            except Exception as e:
+                print(f"Warning: failed to destroy collection: {e}")
+
+    def test_open_concurrent_same_path(self, tmp_path_factory):
+        # First create a collection
+        collection_schema = zvec.CollectionSchema(
+            name="test_collection",
+            fields=[
+                FieldSchema(
+                    "id",
+                    DataType.INT64,
+                    nullable=False,
+                    index_param=InvertIndexParam(enable_range_optimization=True),
+                ),
+                FieldSchema(
+                    "name",
+                    DataType.STRING,
+                    nullable=False,
+                    index_param=InvertIndexParam(),
+                ),
+            ],
+            vectors=[
+                VectorSchema(
+                    "dense",
+                    DataType.VECTOR_FP32,
+                    dimension=128,
+                    index_param=HnswIndexParam(),
+                )
+            ],
+        )
+
+        collection_option = CollectionOption(read_only=False, enable_mmap=True)
+
+        # Create collection path
+        temp_dir = tmp_path_factory.mktemp("zvec")
+        collection_path = temp_dir / "test_collection"
+
+        # First create the collection
+        created_coll = zvec.create_and_open(
+            path=str(collection_path),
+            schema=collection_schema,
+            option=collection_option,
+        )
+
+        assert created_coll is not None, "Failed to create collection"
+
+        # Close the collection so we can test concurrent opening
+        if hasattr(created_coll, "close") and created_coll is not None:
+            created_coll.close()
+
+        # Shared variables to collect results from threads
+        results = []
+        errors = []
+
+        # Lock for thread-safe operations
+        lock = threading.Lock()
+        # Clean up the created collection reference
+        del created_coll
+
+        # Function to be executed by each thread
+        def open_collection_thread(thread_id):
+            try:
+                coll = zvec.open(path=str(collection_path), option=collection_option)
+                with lock:
+                    results.append((thread_id, coll))
+                # Close the collection if opened successfully
+                if hasattr(coll, "close") and coll is not None:
+                    coll.close()
+            except Exception as e:
+                with lock:
+                    errors.append((thread_id, str(e)))
+
+        # Create 5 threads to call open concurrently
+        threads = []
+        for i in range(5):
+            thread = threading.Thread(target=open_collection_thread, args=(i,))
+            threads.append(thread)
+            thread.start()
+
+        # Wait for all threads to complete
+        for thread in threads:
+            thread.join()
+
+        # Verify concurrency safety: only one should succeed, others should fail
+        assert len(results) == 1, (
+            f"Expected exactly one successful open, but got {len(results)}"
+        )
+        assert len(errors) == 4, (
+            f"Expected exactly four failures, but got {len(errors)}"
+        )
+
+        # Additional verification: check that the successful open has a valid collection
+        successful_thread_id, successful_collection = results[0]
+        assert successful_collection is not None, (
+            "Successful open should return a valid collection"
+        )
+        assert successful_collection.path == str(collection_path), (
+            "Collection path mismatch"
+        )
+
+        # Clean up the successfully opened collection
+        if (
+            hasattr(successful_collection, "destroy")
+            and successful_collection is not None
+        ):
+            try:
+                successful_collection.destroy()
+            except Exception as e:
+                print(f"Warning: failed to destroy collection: {e}")
+
+    def test_open_with_corrupted_files(self, tmp_path_factory):
+        # First create a collection
+        collection_schema = zvec.CollectionSchema(
+            name="test_collection",
+            fields=[
+                FieldSchema(
+                    "id",
+                    DataType.INT64,
+                    nullable=False,
+                    index_param=InvertIndexParam(enable_range_optimization=True),
+                ),
+                FieldSchema(
+                    "name",
+                    DataType.STRING,
+                    nullable=False,
+                    index_param=InvertIndexParam(),
+                ),
+            ],
+            vectors=[
+                VectorSchema(
+                    "dense",
+                    DataType.VECTOR_FP32,
+                    dimension=128,
+                    index_param=HnswIndexParam(),
+                )
+            ],
+        )
+
+        collection_option = CollectionOption(read_only=False, enable_mmap=True)
+
+        # Create collection path
+        temp_dir = tmp_path_factory.mktemp("zvec")
+        collection_path = temp_dir / "test_collection"
+
+        # First create the collection
+        created_coll = zvec.create_and_open(
+            path=str(collection_path),
+            schema=collection_schema,
+            option=collection_option,
+        )
+
+        assert created_coll is not None, "Failed to create collection"
+
+        # Close the collection so we can manipulate its files
+        if hasattr(created_coll, "close") and created_coll is not None:
+            created_coll.close()
+
+        # Test case 1: Delete some files in the collection directory (simulate partial corruption)
+        import os
+        import shutil
+        import random
+
+        # Get the collection directory path
+        collection_dir = str(collection_path)
+
+        # List all files in the collection directory
+        files_in_dir = []
+        for root, dirs, files in os.walk(collection_dir):
+            for file in files:
+                files_in_dir.append(os.path.join(root, file))
+
+        # Randomly delete approximately half of the files to simulate partial corruption
+        if files_in_dir:
+            # Shuffle the list to randomly select files
+            random.shuffle(files_in_dir)
+            files_to_delete = files_in_dir[: len(files_in_dir) // 2]
+            for file_path in files_to_delete:
+                try:
+                    os.remove(file_path)
+                except Exception as e:
+                    pass  # Ignore errors during deletion
+
+        # Try to open the collection with missing files - should raise an exception
+        with pytest.raises(Exception):
+            zvec.open(path=str(collection_path), option=collection_option)
+
+        # Test case 2: Delete all files in the collection directory (simulate complete corruption)
+        # Recreate the collection
+        recreated_coll = zvec.create_and_open(
+            path=str(collection_path) + "_all",
+            schema=collection_schema,
+            option=collection_option,
+        )
+
+        assert recreated_coll is not None, "Failed to recreate collection"
+
+        # Close the collection so we can manipulate its files
+        if hasattr(recreated_coll, "close") and recreated_coll is not None:
+            recreated_coll.close()
+
+        # Delete all files in the collection directory
+        try:
+            shutil.rmtree(collection_dir)
+            os.makedirs(collection_dir)  # Recreate empty directory
+        except Exception as e:
+            pass  # Ignore errors during deletion
+
+        # Try to open the collection with missing files - should raise an exception
+        with pytest.raises(Exception):
+            zvec.open(path=str(collection_path), option=collection_option)

python/tests/detail/test_collection_recall.py

@@ -0,0 +1,740 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import pytest
+
+from zvec.typing import DataType, StatusCode, MetricType, QuantizeType
+from zvec.model import Collection, Doc, Query
+from zvec.model.param import (
+    CollectionOption,
+    InvertIndexParam,
+    HnswIndexParam,
+    FlatIndexParam,
+    IVFIndexParam,
+    DiskAnnIndexParam,
+    HnswQueryParam,
+    IVFQueryParam,
+    DiskAnnQueryParam,
+)
+
+from zvec.model.schema import FieldSchema, VectorSchema
+from zvec.extension import RrfReRanker, WeightedReRanker, QwenReRanker
+from distance_helper import *
+
+from zvec import StatusCode
+from distance_helper import *
+from fixture_helper import *
+from doc_helper import *
+from params_helper import *
+
+import time
+
+
+# ==================== helper ====================
+def batchdoc_and_check(collection: Collection, multiple_docs, operator="insert"):
+    if operator == "insert":
+        result = collection.insert(multiple_docs)
+    elif operator == "upsert":
+        result = collection.upsert(multiple_docs)
+
+    elif operator == "update":
+        result = collection.update(multiple_docs)
+    else:
+        logging.error("operator value is error!")
+
+    assert len(result) == len(multiple_docs)
+    for item in result:
+        assert item.ok(), (
+            f"result={result},Insert operation failed with code {item.code()}"
+        )
+
+    stats = collection.stats
+    assert stats is not None, "Collection stats should not be None"
+    """assert stats.doc_count == len(multiple_docs), (
+        f"Document count should be {len(multiple_docs)} after insert, but got {stats.doc_count}"
+    )"""
+
+    doc_ids = [doc.id for doc in multiple_docs]
+    fetched_docs = collection.fetch(doc_ids)
+    assert len(fetched_docs) == len(multiple_docs), (
+        f"fetched_docs={fetched_docs},Expected {len(multiple_docs)} fetched documents, but got {len(fetched_docs)}"
+    )
+
+    for original_doc in multiple_docs:
+        assert original_doc.id in fetched_docs, (
+            f"Expected document ID {original_doc.id} in fetched documents"
+        )
+        fetched_doc = fetched_docs[original_doc.id]
+
+        assert is_doc_equal(fetched_doc, original_doc, collection.schema)
+
+        assert hasattr(fetched_doc, "score"), "Document should have a score attribute"
+        assert fetched_doc.score == 0.0, (
+            "Fetch operation should return default score of 0.0"
+        )
+
+
+def compute_exact_similarity_scores(
+    vectors_a,
+    vectors_b,
+    metric_type=MetricType.IP,
+    DataType=DataType.VECTOR_FP32,
+    QuantizeType=QuantizeType.UNDEFINED,
+):
+    similarities = []
+    for i, vec_a in enumerate(vectors_a):
+        for j, vec_b in enumerate(vectors_b):
+            similarity = distance_recall(vec_a, vec_b, metric_type, DataType)
+            similarities.append((j, similarity))
+
+    # For L2,COSINE metric, smaller distances mean higher similarity, so sort in ascending order
+    if (
+        metric_type in [MetricType.L2]
+        and DataType
+        in [DataType.VECTOR_FP32, DataType.VECTOR_FP16, DataType.VECTOR_INT8]
+    ) or (
+        metric_type in [MetricType.COSINE]
+        and DataType in [DataType.VECTOR_FP32, DataType.VECTOR_FP16]
+    ):
+        similarities.sort(key=lambda x: x[1], reverse=False)  # Ascending order for L2
+
+    else:
+        similarities.sort(
+            key=lambda x: x[1], reverse=True
+        )  # Descending order for others
+
+    # Special handling for COSINE in FP16 to address precision issues
+    if metric_type == MetricType.COSINE and DataType == DataType.VECTOR_FP16:
+        # Clamp values to valid cosine distance range [0, 2] and handle floating point errors
+        similarities = [(idx, max(0.0, min(2.0, score))) for idx, score in similarities]
+
+    return similarities
+
+
+def get_ground_truth_for_vector_query(
+    collection,
+    query_vector,
+    field_name,
+    all_docs,
+    query_idx,
+    metric_type,
+    k,
+    use_exact_computation=False,
+):
+    if use_exact_computation:
+        all_vectors = [doc.vectors[field_name] for doc in all_docs]
+
+        for d, f in DEFAULT_VECTOR_FIELD_NAME.items():
+            if field_name == f:
+                DataType = d
+                break
+        similarities = compute_exact_similarity_scores(
+            [query_vector],
+            all_vectors,
+            metric_type,
+            DataType=DataType,
+            QuantizeType=QuantizeType,
+        )
+
+        if metric_type == MetricType.COSINE and DataType == DataType.VECTOR_FP16:
+            # Filter out tiny non-zero values that may be caused by precision errors
+            similarities = [
+                (idx, max(0.0, min(2.0, score))) for idx, score in similarities
+            ]
+
+        ground_truth_ids_scores = similarities[:k]
+        print("Get the most similar k document IDs k:,ground_truth_ids_scores")
+        print(k, ground_truth_ids_scores)
+        return ground_truth_ids_scores
+
+    else:
+        full_result = collection.query(
+            Query(field_name=field_name, vector=query_vector),
+            topk=min(len(all_docs), 1024),
+            include_vector=True,
+        )
+
+        ground_truth_ids_scores = [
+            (result.id, result.score) for result in full_result[:k]
+        ]
+
+        if not ground_truth_ids_scores:
+            ground_truth_ids_scores = [(all_docs[query_idx].id, 0)]
+
+        return ground_truth_ids_scores
+
+
+def get_ground_truth_map(collection, test_docs, query_vectors_map, metric_type, k):
+    ground_truth_map = {}
+
+    for field_name, query_vectors in query_vectors_map.items():
+        ground_truth_map[field_name] = {}
+
+        # Support per-field metric type: metric_type can be a dict mapping
+        # field_name -> MetricType, or a single MetricType applied to all fields.
+        if isinstance(metric_type, dict):
+            field_metric = metric_type.get(field_name, MetricType.IP)
+        else:
+            field_metric = metric_type
+
+        for i, query_vector in enumerate(query_vectors):
+            # Get the ground truth for this query
+            relevant_doc_ids_scores = get_ground_truth_for_vector_query(
+                collection,
+                query_vector,
+                field_name,
+                test_docs,
+                i,
+                field_metric,
+                k,
+                True,
+            )
+            ground_truth_map[field_name][i] = relevant_doc_ids_scores
+
+    print("ground_truth_map:\n")
+    print(ground_truth_map)
+    return ground_truth_map
+
+
+def calculate_recall_at_k(
+    collection: Collection,
+    test_docs,
+    query_vectors_map,
+    schema,
+    k=1,
+    expected_doc_ids_scores_map=None,
+    tolerance=0.01,
+):
+    recall_stats = {}
+
+    for field_name, query_vectors in query_vectors_map.items():
+        recall_stats[field_name] = {
+            "relevant_retrieved_count": 0,
+            "total_relevant_count": 0,
+            "retrieved_count": 0,
+            "recall_at_k": 0.0,
+        }
+
+        for i, query_vector in enumerate(query_vectors):
+            print("Starting %dth query" % i)
+
+            query_result_list = collection.query(
+                Query(field_name=field_name, vector=query_vector),
+                topk=1024,
+                include_vector=True,
+            )
+            retrieved_count = len(query_result_list)
+
+            query_result_ids_scores = []
+            for word in query_result_list:
+                query_result_ids_scores.append((word.id, word.score))
+
+            recall_stats[field_name]["retrieved_count"] += retrieved_count
+
+            print("expected_doc_ids_scores_map:\n")
+            print(expected_doc_ids_scores_map)
+            if i in (expected_doc_ids_scores_map[field_name]):
+                expected_relevant_ids_scores = expected_doc_ids_scores_map[field_name][
+                    i
+                ]
+            print(
+                "field_name,i,expected_relevant_ids_scores, query_result_ids_scores:\n"
+            )
+            print(
+                field_name,
+                i,
+                "\n",
+                expected_relevant_ids_scores,
+                "\n",
+                len(query_result_ids_scores),
+                query_result_ids_scores,
+            )
+
+            # Update total relevant documents count
+            recall_stats[field_name]["total_relevant_count"] += len(
+                expected_relevant_ids_scores
+            )
+
+            relevant_found_count = 0
+            for ids_scores_except in expected_relevant_ids_scores:
+                for ids_scores_result in query_result_ids_scores[:k]:
+                    if int(ids_scores_result[0]) == int(ids_scores_except[0]):
+                        relevant_found_count += 1
+                        break
+                    elif (
+                        int(ids_scores_result[0]) != int(ids_scores_except[0])
+                        and abs(ids_scores_result[1] - ids_scores_except[1])
+                        <= tolerance
+                    ):
+                        print("IDs are not equal, but the error is small, tolerance")
+                        print(
+                            ids_scores_result[0],
+                            ids_scores_except[0],
+                            ids_scores_result[1],
+                            ids_scores_except[1],
+                            tolerance,
+                        )
+                        relevant_found_count += 1
+                        break
+                    else:
+                        continue
+
+            recall_stats[field_name]["relevant_retrieved_count"] += relevant_found_count
+
+        # Calculate Recall@K
+        if recall_stats[field_name]["total_relevant_count"] > 0:
+            recall_stats[field_name]["recall_at_k"] = (
+                recall_stats[field_name]["relevant_retrieved_count"]
+                / recall_stats[field_name]["total_relevant_count"]
+            )
+
+    return recall_stats
+
+
+class TestRecall:
+    @pytest.mark.parametrize(
+        "full_schema_new",
+        [
+            (True, True, HnswIndexParam()),
+            (False, True, IVFIndexParam()),
+            (False, True, DiskAnnIndexParam()),
+            (False, True, FlatIndexParam()),  # ——ok
+            (
+                True,
+                True,
+                HnswIndexParam(
+                    metric_type=MetricType.IP,
+                    m=16,
+                    ef_construction=100,
+                ),
+            ),
+            (
+                True,
+                True,
+                HnswIndexParam(
+                    metric_type=MetricType.COSINE,
+                    m=24,
+                    ef_construction=150,
+                ),
+            ),
+            (
+                True,
+                True,
+                HnswIndexParam(
+                    metric_type=MetricType.L2,
+                    m=32,
+                    ef_construction=200,
+                ),
+            ),
+            (
+                False,
+                True,
+                FlatIndexParam(
+                    metric_type=MetricType.IP,
+                ),
+            ),
+            (
+                True,
+                True,
+                FlatIndexParam(
+                    metric_type=MetricType.COSINE,
+                ),
+            ),
+            (
+                True,
+                True,
+                FlatIndexParam(
+                    metric_type=MetricType.L2,
+                ),
+            ),
+            (
+                True,
+                True,
+                IVFIndexParam(
+                    metric_type=MetricType.IP,
+                    n_list=100,
+                    n_iters=10,
+                    use_soar=False,
+                ),
+            ),
+            (
+                True,
+                True,
+                IVFIndexParam(
+                    metric_type=MetricType.L2,
+                    n_list=200,
+                    n_iters=20,
+                    use_soar=True,
+                ),
+            ),
+            (
+                True,
+                True,
+                IVFIndexParam(
+                    metric_type=MetricType.COSINE,
+                    n_list=150,
+                    n_iters=15,
+                    use_soar=False,
+                ),
+            ),
+            (
+                True,
+                True,
+                DiskAnnIndexParam(
+                    metric_type=MetricType.IP,
+                    max_degree=32,
+                ),
+            ),
+            (
+                True,
+                True,
+                DiskAnnIndexParam(metric_type=MetricType.L2, max_degree=32),
+            ),
+        ],
+        indirect=True,
+    )
+    @pytest.mark.parametrize("doc_num", [500])
+    @pytest.mark.parametrize("query_num", [10])
+    @pytest.mark.parametrize("top_k", [1])
+    def test_recall_with_single_vector_valid_500(
+        self,
+        full_collection_new: Collection,
+        doc_num,
+        query_num,
+        top_k,
+        full_schema_new,
+        request,
+    ):
+        full_schema_params = request.getfixturevalue("full_schema_new")
+
+        # Build per-field metric type map so ground truth uses each field's
+        # actual index metric (fields may fall back to HnswIndexParam/IP).
+        field_metric_map = {}
+        for vector_para in full_schema_params.vectors:
+            if vector_para.index_param is not None:
+                field_metric_map[vector_para.name] = vector_para.index_param.metric_type
+            else:
+                field_metric_map[vector_para.name] = MetricType.IP
+
+        metric_type = field_metric_map.get("vector_fp32_field", MetricType.IP)
+
+        multiple_docs = [
+            generate_doc_recall(i, full_collection_new.schema) for i in range(doc_num)
+        ]
+        print("len(multiple_docs):\n")
+        print(len(multiple_docs))
+        # print(multiple_docs)
+
+        for i in range(10):
+            if i != 0:
+                pass
+                # print(multiple_docs[i * 1000:1000 * (i + 1)])
+            batchdoc_and_check(
+                full_collection_new,
+                multiple_docs[i * 1000 : 1000 * (i + 1)],
+                operator="insert",
+            )
+
+        stats = full_collection_new.stats
+        assert stats.doc_count == len(multiple_docs)
+
+        doc_ids = ["0", "1"]
+        fetched_docs = full_collection_new.fetch(doc_ids)
+        print("fetched_docs,multiple_docs")
+        print(
+            fetched_docs[doc_ids[0]].vectors["sparse_vector_fp32_field"],
+            fetched_docs[doc_ids[0]].vectors["sparse_vector_fp16_field"],
+            fetched_docs[doc_ids[1]].vectors["sparse_vector_fp32_field"],
+            fetched_docs[doc_ids[1]].vectors["sparse_vector_fp16_field"],
+            "\n",
+            multiple_docs[0].vectors["sparse_vector_fp32_field"],
+            multiple_docs[0].vectors["sparse_vector_fp32_field"],
+            multiple_docs[1].vectors["sparse_vector_fp32_field"],
+            multiple_docs[1].vectors["sparse_vector_fp16_field"],
+        )
+
+        full_collection_new.optimize(option=OptimizeOption())
+
+        time.sleep(2)
+
+        query_vectors_map = {}
+        for field_name in DEFAULT_VECTOR_FIELD_NAME.values():
+            query_vectors_map[field_name] = [
+                multiple_docs[i].vectors[field_name] for i in range(query_num)
+            ]
+
+        # Get ground truth mapping (pass per-field metric map)
+        ground_truth_map = get_ground_truth_map(
+            full_collection_new,
+            multiple_docs,
+            query_vectors_map,
+            field_metric_map,
+            top_k,
+        )
+
+        # Validate ground truth mapping structure
+        for field_name in DEFAULT_VECTOR_FIELD_NAME.values():
+            assert field_name in ground_truth_map
+            field_gt = ground_truth_map[field_name]
+            assert len(field_gt) == query_num
+
+            for query_idx in range(query_num):
+                assert query_idx in field_gt
+                relevant_ids = field_gt[query_idx]
+                assert isinstance(relevant_ids, list)
+                assert len(relevant_ids) <= top_k
+
+        # Print ground truth statistics
+        print(f"Ground Truth for Top-{top_k} Retrieval:")
+        for field_name, field_gt in ground_truth_map.items():
+            print(f"  {field_name}:")
+            for query_idx, relevant_ids in field_gt.items():
+                print(
+                    f" Query {query_idx}: {len(relevant_ids)} relevant docs - {relevant_ids[:5]}{'...' if len(relevant_ids) > 5 else ''}"
+                )
+
+        # Calculate Recall@K using ground truth
+        recall_at_k_stats = calculate_recall_at_k(
+            full_collection_new,
+            multiple_docs,
+            query_vectors_map,
+            full_schema_new,
+            k=top_k,
+            expected_doc_ids_scores_map=ground_truth_map,
+            tolerance=0.01,
+        )
+        print("ground_truth_map:\n")
+        print(ground_truth_map)
+
+        print("(recall_at_k_stats:\n")
+        print(recall_at_k_stats)
+        print("field_metric_map:")
+        print(field_metric_map)
+        # Print Recall@K statistics
+        print(f"Recall@{top_k} using Ground Truth:")
+        for field_name, stats in recall_at_k_stats.items():
+            print(f"  {field_name}:")
+            print(
+                f"    Relevant Retrieved: {stats['relevant_retrieved_count']}/{stats['total_relevant_count']}"
+            )
+            print(f"    Recall@{top_k}: {stats['recall_at_k']:.4f}")
+        for k, v in recall_at_k_stats.items():
+            assert v["recall_at_k"] == 1.0
+
+    @pytest.mark.parametrize(
+        "full_schema_new",
+        [
+            (True, True, HnswIndexParam()),
+            (False, True, IVFIndexParam()),
+            (False, True, FlatIndexParam()),  # ——ok
+            (
+                True,
+                True,
+                HnswIndexParam(
+                    metric_type=MetricType.IP,
+                    m=16,
+                    ef_construction=100,
+                ),
+            ),
+            (
+                True,
+                True,
+                HnswIndexParam(
+                    metric_type=MetricType.COSINE,
+                    m=24,
+                    ef_construction=150,
+                ),
+            ),
+            # (True, True, HnswIndexParam(metric_type=MetricType.L2, m=32, ef_construction=200, )),
+            (
+                False,
+                True,
+                FlatIndexParam(
+                    metric_type=MetricType.IP,
+                ),
+            ),
+            (
+                True,
+                True,
+                FlatIndexParam(
+                    metric_type=MetricType.COSINE,
+                ),
+            ),
+            # (True, True, FlatIndexParam(metric_type=MetricType.L2, )),
+            (
+                True,
+                True,
+                IVFIndexParam(
+                    metric_type=MetricType.IP,
+                    n_list=100,
+                    n_iters=10,
+                    use_soar=False,
+                ),
+            ),
+            (
+                True,
+                True,
+                IVFIndexParam(
+                    metric_type=MetricType.L2,
+                    n_list=200,
+                    n_iters=20,
+                    use_soar=True,
+                ),
+            ),
+            (
+                True,
+                True,
+                DiskAnnIndexParam(metric_type=MetricType.IP, max_degree=32),
+            ),
+            (
+                True,
+                True,
+                DiskAnnIndexParam(metric_type=MetricType.L2, max_degree=32),
+            ),
+            (
+                True,
+                True,
+                DiskAnnIndexParam(metric_type=MetricType.COSINE, max_degree=32),
+            ),
+        ],
+        indirect=True,
+    )
+    @pytest.mark.parametrize("doc_num", [2000])
+    @pytest.mark.parametrize("query_num", [2])
+    @pytest.mark.parametrize("top_k", [1])
+    @pytest.mark.skip(reason="known bug")
+    def test_recall_with_single_vector_valid_2000(
+        self,
+        full_collection_new: Collection,
+        doc_num,
+        query_num,
+        top_k,
+        full_schema_new,
+        request,
+    ):
+        full_schema_params = request.getfixturevalue("full_schema_new")
+
+        # Build per-field metric type map so ground truth uses each field's
+        # actual index metric (fields may fall back to HnswIndexParam/IP).
+        field_metric_map = {}
+        for vector_para in full_schema_params.vectors:
+            if vector_para.index_param is not None:
+                field_metric_map[vector_para.name] = vector_para.index_param.metric_type
+            else:
+                field_metric_map[vector_para.name] = MetricType.IP
+
+        metric_type = field_metric_map.get("vector_fp32_field", MetricType.IP)
+
+        multiple_docs = [
+            generate_doc_recall(i, full_collection_new.schema) for i in range(doc_num)
+        ]
+        print("len(multiple_docs):\n")
+        print(len(multiple_docs))
+        # print(multiple_docs)
+
+        for i in range(10):
+            if i != 0:
+                pass
+                # print(multiple_docs[i * 1000:1000 * (i + 1)])
+            batchdoc_and_check(
+                full_collection_new,
+                multiple_docs[i * 1000 : 1000 * (i + 1)],
+                operator="insert",
+            )
+
+        stats = full_collection_new.stats
+        assert stats.doc_count == len(multiple_docs)
+
+        doc_ids = ["0", "1"]
+        fetched_docs = full_collection_new.fetch(doc_ids)
+        print("fetched_docs,multiple_docs")
+        print(
+            fetched_docs[doc_ids[0]].vectors["sparse_vector_fp32_field"],
+            fetched_docs[doc_ids[0]].vectors["sparse_vector_fp16_field"],
+            fetched_docs[doc_ids[1]].vectors["sparse_vector_fp32_field"],
+            fetched_docs[doc_ids[1]].vectors["sparse_vector_fp16_field"],
+            "\n",
+            multiple_docs[0].vectors["sparse_vector_fp32_field"],
+            multiple_docs[0].vectors["sparse_vector_fp32_field"],
+            multiple_docs[1].vectors["sparse_vector_fp32_field"],
+            multiple_docs[1].vectors["sparse_vector_fp16_field"],
+        )
+
+        full_collection_new.optimize(option=OptimizeOption())
+
+        time.sleep(2)
+
+        query_vectors_map = {}
+        for field_name in DEFAULT_VECTOR_FIELD_NAME.values():
+            query_vectors_map[field_name] = [
+                multiple_docs[i].vectors[field_name] for i in range(query_num)
+            ]
+
+        # Get ground truth mapping (pass per-field metric map)
+        ground_truth_map = get_ground_truth_map(
+            full_collection_new,
+            multiple_docs,
+            query_vectors_map,
+            field_metric_map,
+            top_k,
+        )
+
+        # Validate ground truth mapping structure
+        for field_name in DEFAULT_VECTOR_FIELD_NAME.values():
+            assert field_name in ground_truth_map
+            field_gt = ground_truth_map[field_name]
+            assert len(field_gt) == query_num
+
+            for query_idx in range(query_num):
+                assert query_idx in field_gt
+                relevant_ids = field_gt[query_idx]
+                assert isinstance(relevant_ids, list)
+                assert len(relevant_ids) <= top_k
+
+        # Print ground truth statistics
+        print(f"Ground Truth for Top-{top_k} Retrieval:")
+        for field_name, field_gt in ground_truth_map.items():
+            print(f"  {field_name}:")
+            for query_idx, relevant_ids in field_gt.items():
+                print(
+                    f" Query {query_idx}: {len(relevant_ids)} relevant docs - {relevant_ids[:5]}{'...' if len(relevant_ids) > 5 else ''}"
+                )
+
+        # Calculate Recall@K using ground truth
+        recall_at_k_stats = calculate_recall_at_k(
+            full_collection_new,
+            multiple_docs,
+            query_vectors_map,
+            full_schema_new,
+            k=top_k,
+            expected_doc_ids_scores_map=ground_truth_map,
+            tolerance=0.01,
+        )
+        print("ground_truth_map:\n")
+        print(ground_truth_map)
+
+        print("(recall_at_k_stats:\n")
+        print(recall_at_k_stats)
+        print("field_metric_map:")
+        print(field_metric_map)
+        # Print Recall@K statistics
+        print(f"Recall@{top_k} using Ground Truth:")
+        for field_name, stats in recall_at_k_stats.items():
+            print(f"  {field_name}:")
+            print(
+                f"    Relevant Retrieved: {stats['relevant_retrieved_count']}/{stats['total_relevant_count']}"
+            )
+            print(f"    Recall@{top_k}: {stats['recall_at_k']:.4f}")
+        for k, v in recall_at_k_stats.items():
+            assert v["recall_at_k"] == 1.0

python/tests/detail/test_db_config.py

@@ -0,0 +1,307 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+import pytest
+import tempfile
+import os
+import sys
+import subprocess
+
+import zvec
+import zvec
+from zvec import LogType, LogLevel
+
+# Error messages
+INITIALIZATION_ERROR_MSG = "initialization failed"
+RUNTIME_ERROR_MSG = "RuntimeError"
+VALUE_ERROR_MSG = "ValueError"
+TYPE_ERROR_MSG = "TypeError"
+
+
+# ==================== helper ====================
+def run_in_subprocess(func):
+    def wrapper(*args, **kwargs):
+        if os.getenv("RUNNING_IN_SUBPROCESS"):
+            return func(*args, **kwargs)
+
+        env = os.environ.copy()
+        env["RUNNING_IN_SUBPROCESS"] = "1"
+        env["PYTEST_CURRENT_TEST"] = func.__name__
+
+        import inspect
+
+        filepath = inspect.getfile(func)
+        qualname = func.__qualname__.replace(".", "::")
+        test_id = f"{filepath}::{qualname}"
+
+        project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        env["PYTHONPATH"] = project_root + ":" + env.get("PYTHONPATH", "")
+
+        cmd = [sys.executable, "-m", "pytest", "-v", "-s", test_id]
+
+        result = subprocess.run(cmd, env=env, capture_output=True, text=True)
+        if result.returncode != 0:
+            pytest.fail(
+                f"Subprocess test {func.__name__} failed with code {result.returncode}\n"
+                f"STDOUT:\n{result.stdout}\nSTDERR:\n{result.stderr}"
+            )
+
+    return wrapper
+
+
+# ==================== Fixtures ====================
+@pytest.fixture(scope="function")
+def temp_log_dir(tmp_path_factory):
+    return tmp_path_factory.mktemp("logs")
+
+
+# ==================== Tests ====================
+class TestDbConfigInitialization:
+    @run_in_subprocess
+    def test_init_default(self):
+        # default config
+        # log_type: Optional[LogType] = LogType.CONSOLE,
+        # log_level: Optional[LogLevel] = LogLevel.WARN,
+        # log_dir: Optional[str] = "./logs",
+        # log_basename: Optional[str] = "zvec.log",
+        # log_file_size: Optional[int] = 2048,
+        # log_overdue_days: Optional[int] = 7,
+        zvec.init()
+
+    @run_in_subprocess
+    def test_init_file_logger(self):
+        from pathlib import Path
+        import shutil
+
+        zvec.init(
+            log_level=LogLevel.DEBUG,
+            log_type=LogType.FILE,
+        )
+        # assert logdir exist
+        log_dir = Path("./logs")
+        assert log_dir.exists()
+
+        # validate write log
+        col = zvec.create_and_open(
+            "/tmp/test/1",
+            zvec.CollectionSchema(
+                name="test",
+                vectors=zvec.VectorSchema(
+                    dimension=4,
+                    data_type=zvec.DataType.VECTOR_FP32,
+                    name="image",
+                ),
+            ),
+        )
+        col.insert(docs=[zvec.Doc(id="1", vectors={"image": [1.0, 2.0, 3.0, 4.0]})])
+        assert any(log_dir.glob("zvec.log.*"))
+
+        # clear
+        col.destroy()
+        shutil.rmtree(log_dir, ignore_errors=True)
+
+    @run_in_subprocess
+    def test_init_with_mixed_config(self):
+        zvec.init(
+            memory_limit_mb=128,
+            log_type=LogType.FILE,
+            query_threads=1,
+            log_level=LogLevel.WARN,
+        )
+
+    @run_in_subprocess
+    def test_repeated_initialization(self):
+        # Calling init() repeatedly is allowed:
+        # it succeeds but becomes a no-op after the first successful init()
+        zvec.init()
+
+
+class TestDbConfigMemoryLimitValidation:
+    @run_in_subprocess
+    def test_memory_limit_min_valid(self):
+        # MIN_MEMORY_LIMIT_BYTES is 100M
+        with pytest.raises(RuntimeError):
+            zvec.init(memory_limit_mb=99)
+
+    @run_in_subprocess
+    def test_memory_limit_invalid_value(self):
+        # memory_limit_mb must >= 0 and must be int and if None, set default value
+        with pytest.raises(ValueError):
+            zvec.init(memory_limit_mb=0)
+        with pytest.raises(ValueError):
+            zvec.init(memory_limit_mb=-1)
+        with pytest.raises(TypeError):
+            zvec.init(memory_limit_mb="512")
+        with pytest.raises(TypeError):
+            zvec.init(memory_limit_mb=512.5)
+
+
+class TestDbConfigThreadValidation:
+    @run_in_subprocess
+    def test_query_threads(self):
+        zvec.init(query_threads=1)
+
+    @run_in_subprocess
+    def test_query_threads_invalid(self):
+        # query_threads must >= 0 and must be int and if None, set default value
+        with pytest.raises(ValueError):
+            zvec.init(query_threads=0)
+        with pytest.raises(ValueError):
+            zvec.init(query_threads=-1)
+        with pytest.raises(TypeError):
+            zvec.init(query_threads="value")
+        with pytest.raises(TypeError):
+            zvec.init(query_threads=512.5)
+        with pytest.raises(TypeError):
+            zvec.init(query_threads="512")
+
+    @run_in_subprocess
+    def test_optimize_threads(self):
+        zvec.init(optimize_threads=1)
+
+    @run_in_subprocess
+    def test_optimize_threads_invalid(self):
+        # optimize_threads must >= 0 and must be int and if None, set default value
+        with pytest.raises(ValueError):
+            zvec.init(optimize_threads=0)
+        with pytest.raises(ValueError):
+            zvec.init(optimize_threads=-1)
+        with pytest.raises(TypeError):
+            zvec.init(optimize_threads="value")
+        with pytest.raises(TypeError):
+            zvec.init(optimize_threads=512.5)
+        with pytest.raises(TypeError):
+            zvec.init(optimize_threads="512")
+
+
+class TestDbConfigRatioValidation:
+    @run_in_subprocess
+    def test_init_invert_to_forward_scan_ratio(self):
+        # must be in [0,1]
+        zvec.init(invert_to_forward_scan_ratio=0.8)
+
+    @run_in_subprocess
+    def test_init_invert_to_forward_scan_ratio_invalid(self):
+        with pytest.raises(ValueError):
+            zvec.init(invert_to_forward_scan_ratio=1.1)
+        with pytest.raises(ValueError):
+            zvec.init(invert_to_forward_scan_ratio=-0.1)
+        with pytest.raises(TypeError):
+            zvec.init(invert_to_forward_scan_ratio="0.8")
+
+    @run_in_subprocess
+    def test_init_brute_force_by_keys_ratio(self):
+        zvec.init(brute_force_by_keys_ratio=0.8)
+
+    @run_in_subprocess
+    def test_init_brute_force_by_keys_ratio_invalid(self):
+        with pytest.raises(ValueError):
+            zvec.init(brute_force_by_keys_ratio=1.1)
+        with pytest.raises(ValueError):
+            zvec.init(brute_force_by_keys_ratio=-0.1)
+        with pytest.raises(TypeError):
+            zvec.init(brute_force_by_keys_ratio="0.8")
+
+
+class TestDbConfigLogValidation:
+    @run_in_subprocess
+    def test_log_type_valid(self):
+        zvec.init(log_type=LogType.CONSOLE)
+
+    @run_in_subprocess
+    def test_log_type_invalid(self):
+        with pytest.raises(TypeError):
+            zvec.init(log_type="FILE")
+        with pytest.raises(TypeError):
+            zvec.init(log_type="")
+        with pytest.raises(TypeError):
+            zvec.init(log_type="invalid")
+        with pytest.raises(TypeError):
+            zvec.init(log_type=123)
+
+    @run_in_subprocess
+    def test_log_level_valid(self):
+        zvec.init(log_level=LogLevel.ERROR)
+
+    @run_in_subprocess
+    def test_log_level_invalid(self):
+        with pytest.raises(TypeError):
+            zvec.init(log_level="WARN")
+        with pytest.raises(TypeError):
+            zvec.init(log_level="")
+        with pytest.raises(TypeError):
+            zvec.init(log_level="invalid")
+        with pytest.raises(TypeError):
+            zvec.init(log_level=123)
+
+    @run_in_subprocess
+    def test_init_file_logger(self):
+        from pathlib import Path
+        import shutil
+
+        temp_dir = tempfile.mkdtemp(prefix="log_test_")
+        abs_temp_dir = os.path.abspath(temp_dir)
+
+        zvec.init(
+            log_level=LogLevel.DEBUG,
+            log_type=LogType.FILE,
+            log_dir=abs_temp_dir,
+            log_basename="test",
+        )
+
+        # assert logdir exist
+        log_dir = Path(abs_temp_dir)
+        assert log_dir.exists()
+
+        # validate write log
+        col = zvec.create_and_open(
+            "/tmp/test/1",
+            zvec.CollectionSchema(
+                name="test",
+                vectors=zvec.VectorSchema(
+                    dimension=4,
+                    data_type=zvec.DataType.VECTOR_FP32,
+                    name="image",
+                ),
+            ),
+        )
+        col.insert(docs=[zvec.Doc(id="1", vectors={"image": [1.0, 2.0, 3.0, 4.0]})])
+        assert any(log_dir.glob("test.*"))
+
+        # clear
+        col.destroy()
+        shutil.rmtree(log_dir, ignore_errors=True)
+
+    @run_in_subprocess
+    def test_log_file_size_invalid(self):
+        with pytest.raises(TypeError):
+            zvec.init(log_type=LogType.FILE, log_file_size="df")
+
+        with pytest.raises(ValueError):
+            zvec.init(log_type=LogType.FILE, log_file_size=0)
+
+        with pytest.raises(ValueError):
+            zvec.init(log_type=LogType.FILE, log_file_size=-1)
+
+    @run_in_subprocess
+    def test_log_overdue_days_invalid(self):
+        with pytest.raises(TypeError):
+            zvec.init(log_type=LogType.FILE, log_overdue_days="df")
+
+        with pytest.raises(ValueError):
+            zvec.init(log_type=LogType.FILE, log_overdue_days=0)
+
+        with pytest.raises(ValueError):
+            zvec.init(log_type=LogType.FILE, log_overdue_days=-1)

python/tests/test_collection_diskann.py

@@ -0,0 +1,600 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""End-to-end collection tests for the DiskAnn index.
+
+Mirrors ``test_collection_hnsw_rabitq.py`` but targets the DiskAnn plugin.
+
+Two platform-level prerequisites are enforced at module import time:
+
+1. DiskAnn is currently built only for Linux x86_64 — other platforms are
+   skipped wholesale.
+2. The DiskAnn backend lives in a *runtime-loaded* plugin
+   (``libzvec_diskann_plugin.so``). It must be loaded with ``RTLD_GLOBAL |
+   RTLD_NOW`` BEFORE ``import zvec`` so that the plugin's ``IndexFactory``
+   singleton is unified with the one inside ``_zvec.so``. After ``import
+   zvec`` we must also call ``zvec.load_diskann_plugin()`` exactly once.
+
+If either prerequisite fails the whole module is skipped so the rest of the
+test-suite is not affected.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import platform
+import sys
+
+import pytest
+
+# --------------------------------------------------------------------------- #
+# Platform gating (must happen BEFORE we touch zvec).
+# --------------------------------------------------------------------------- #
+pytestmark = pytest.mark.skipif(
+    not (sys.platform == "linux" and platform.machine() in ("x86_64", "AMD64")),
+    reason="DiskAnn plugin is only supported on Linux x86_64",
+)
+
+# Promote all symbols in subsequently-loaded DSOs to the global namespace and
+# resolve relocations eagerly. This is REQUIRED so the DiskAnn plugin can see
+# the ``IndexFactory`` singleton that lives in ``_zvec.so`` and vice versa.
+# See: DiskAnn RTLD_GLOBAL + RTLD_NOW Requirement.
+if sys.platform == "linux":
+    sys.setdlopenflags(sys.getdlopenflags() | os.RTLD_GLOBAL | os.RTLD_NOW)
+
+import zvec  # noqa: E402
+
+from zvec import (  # noqa: E402
+    Collection,
+    CollectionOption,
+    DataType,
+    DiskAnnIndexParam,
+    DiskAnnQueryParam,
+    Doc,
+    FieldSchema,
+    MetricType,
+    Query,
+    VectorSchema,
+)
+from zvec.typing import QuantizeType  # noqa: E402
+
+
+@pytest.fixture(scope="session")
+def diskann_collection_schema():
+    """Create a collection schema with a DiskAnn index."""
+    return zvec.CollectionSchema(
+        name="test_diskann_collection",
+        fields=[
+            FieldSchema("id", DataType.INT64, nullable=False),
+            FieldSchema("name", DataType.STRING, nullable=False),
+        ],
+        vectors=[
+            VectorSchema(
+                "embedding",
+                DataType.VECTOR_FP32,
+                dimension=128,
+                index_param=DiskAnnIndexParam(
+                    metric_type=MetricType.L2,
+                    max_degree=64,
+                    list_size=100,
+                    pq_chunk_num=0,
+                    quantize_type=QuantizeType.UNDEFINED,
+                ),
+            ),
+        ],
+    )
+
+
+@pytest.fixture(scope="session")
+def collection_option():
+    """Create collection options."""
+    return CollectionOption(read_only=False, enable_mmap=True)
+
+
+@pytest.fixture
+def single_doc():
+    """Create a single document for testing."""
+    return Doc(
+        id="0",
+        fields={"id": 0, "name": "test_doc_0"},
+        vectors={"embedding": [0.1 + i * 0.01 for i in range(128)]},
+    )
+
+
+@pytest.fixture
+def multiple_docs():
+    """Create multiple documents for testing."""
+    return [
+        Doc(
+            id=f"{i}",
+            fields={"id": i, "name": f"test_doc_{i}"},
+            vectors={"embedding": [i * 0.1 + j * 0.01 for j in range(128)]},
+        )
+        for i in range(1, 101)
+    ]
+
+
+@pytest.fixture(scope="function")
+def diskann_collection(
+    tmp_path_factory, diskann_collection_schema, collection_option
+) -> Collection:
+    """
+    Function-scoped fixture: creates and opens a collection with DiskAnn index.
+    """
+    temp_dir = tmp_path_factory.mktemp("zvec_diskann")
+    collection_path = temp_dir / "test_diskann_collection"
+
+    coll = zvec.create_and_open(
+        path=str(collection_path),
+        schema=diskann_collection_schema,
+        option=collection_option,
+    )
+
+    assert coll is not None, "Failed to create and open DiskAnn collection"
+    assert coll.path == str(collection_path)
+    assert coll.schema.name == diskann_collection_schema.name
+
+    try:
+        yield coll
+    finally:
+        if hasattr(coll, "destroy") and coll is not None:
+            try:
+                coll.destroy()
+            except Exception as e:
+                print(f"Warning: failed to destroy collection: {e}")
+
+
+@pytest.fixture
+def collection_with_single_doc(
+    diskann_collection: Collection, single_doc: Doc
+) -> Collection:
+    """Setup: insert single doc into collection."""
+    assert diskann_collection.stats.doc_count == 0
+    result = diskann_collection.insert(single_doc)
+    assert bool(result)
+    assert result.ok()
+    assert diskann_collection.stats.doc_count == 1
+
+    yield diskann_collection
+
+    # Teardown: delete single doc
+    diskann_collection.delete(single_doc.id)
+    assert diskann_collection.stats.doc_count == 0
+
+
+@pytest.fixture
+def collection_with_multiple_docs(
+    diskann_collection: Collection, multiple_docs: list[Doc]
+) -> Collection:
+    """Setup: insert multiple docs into collection."""
+    assert diskann_collection.stats.doc_count == 0
+    result = diskann_collection.insert(multiple_docs)
+    assert len(result) == len(multiple_docs)
+    for item in result:
+        assert item.ok()
+    assert diskann_collection.stats.doc_count == len(multiple_docs)
+
+    yield diskann_collection
+
+    # Teardown: delete multiple docs
+    diskann_collection.delete([doc.id for doc in multiple_docs])
+
+
+# ==================== Tests ====================
+
+
+@pytest.mark.usefixtures("diskann_collection")
+class TestDiskAnnCollectionCreation:
+    """Test DiskAnn collection creation and schema validation."""
+
+    def test_collection_creation(
+        self, diskann_collection: Collection, diskann_collection_schema
+    ):
+        """Test that collection is created with correct schema."""
+        assert diskann_collection is not None
+        assert diskann_collection.schema.name == diskann_collection_schema.name
+        assert len(diskann_collection.schema.fields) == len(
+            diskann_collection_schema.fields
+        )
+        assert len(diskann_collection.schema.vectors) == len(
+            diskann_collection_schema.vectors
+        )
+
+    def test_vector_schema_validation(self, diskann_collection: Collection):
+        """Test that vector schema has correct DiskAnn configuration."""
+        vector_schema = diskann_collection.schema.vector("embedding")
+        assert vector_schema is not None
+        assert vector_schema.name == "embedding"
+        assert vector_schema.data_type == DataType.VECTOR_FP32
+        assert vector_schema.dimension == 128
+
+        index_param = vector_schema.index_param
+        assert index_param is not None
+        assert index_param.metric_type == MetricType.L2
+        assert index_param.max_degree == 64
+        assert index_param.list_size == 100
+        assert index_param.pq_chunk_num == 0
+
+    def test_collection_stats(self, diskann_collection: Collection):
+        """Test initial collection statistics."""
+        stats = diskann_collection.stats
+        assert stats is not None
+        assert stats.doc_count == 0
+        assert len(stats.index_completeness) == 1
+        assert stats.index_completeness["embedding"] == 1
+
+
+@pytest.mark.usefixtures("diskann_collection")
+class TestDiskAnnCollectionInsert:
+    """Test document insertion into DiskAnn collection."""
+
+    def test_insert_single_doc(self, diskann_collection: Collection, single_doc: Doc):
+        """Test inserting a single document."""
+        result = diskann_collection.insert(single_doc)
+        assert bool(result)
+        assert result.ok()
+
+        stats = diskann_collection.stats
+        assert stats is not None
+        assert stats.doc_count == 1
+
+    def test_insert_multiple_docs(
+        self, diskann_collection: Collection, multiple_docs: list[Doc]
+    ):
+        """Test inserting multiple documents."""
+        result = diskann_collection.insert(multiple_docs)
+        assert len(result) == len(multiple_docs)
+        for item in result:
+            assert item.ok()
+
+        stats = diskann_collection.stats
+        assert stats is not None
+        assert stats.doc_count == len(multiple_docs)
+
+
+@pytest.mark.usefixtures("diskann_collection")
+class TestDiskAnnCollectionFetch:
+    """Test document fetching from DiskAnn collection."""
+
+    def test_fetch_single_doc(
+        self, collection_with_single_doc: Collection, single_doc: Doc
+    ):
+        """Test fetching a single document by ID."""
+        result = collection_with_single_doc.fetch(ids=[single_doc.id])
+        assert bool(result)
+        assert single_doc.id in result.keys()
+
+        doc = result[single_doc.id]
+        assert doc is not None
+        assert doc.id == single_doc.id
+        assert doc.field("id") == single_doc.field("id")
+        assert doc.field("name") == single_doc.field("name")
+
+    def test_fetch_multiple_docs(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test fetching multiple documents by IDs."""
+        ids = [doc.id for doc in multiple_docs[:10]]
+        result = collection_with_multiple_docs.fetch(ids=ids)
+        assert bool(result)
+        assert len(result) == len(ids)
+
+        for doc_id in ids:
+            assert doc_id in result
+            doc = result[doc_id]
+            assert doc is not None
+            assert doc.id == doc_id
+
+    def test_fetch_nonexistent_doc(self, collection_with_single_doc: Collection):
+        """Test fetching a non-existent document."""
+        result = collection_with_single_doc.fetch(ids=["nonexistent_id"])
+        assert len(result) == 0
+
+
+@pytest.mark.usefixtures("diskann_collection")
+class TestDiskAnnCollectionQuery:
+    """Test vector search queries on DiskAnn collection."""
+
+    def test_query_by_vector(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test querying by vector with DiskAnn index."""
+        query_vector = multiple_docs[0].vector("embedding")
+        query = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=DiskAnnQueryParam(list_size=100),
+        )
+
+        result = collection_with_multiple_docs.query(queries=query, topk=10)
+        assert len(result) > 0
+        assert len(result) <= 10
+
+        # First result should be the query document itself (or very close)
+        first_doc = result[0]
+        assert first_doc is not None
+        assert first_doc.id is not None
+
+    def test_query_by_id(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test querying by document ID with DiskAnn index."""
+        query = Query(
+            field_name="embedding",
+            id=multiple_docs[0].id,
+            param=DiskAnnQueryParam(list_size=100),
+        )
+
+        result = collection_with_multiple_docs.query(queries=query, topk=10)
+        assert len(result) > 0
+        assert len(result) <= 10
+
+    def test_query_with_different_list_size(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test querying with different list_size parameter values."""
+        query_vector = multiple_docs[0].vector("embedding")
+
+        # Test with list_size=50
+        query_small = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=DiskAnnQueryParam(list_size=50),
+        )
+        result_small = collection_with_multiple_docs.query(queries=query_small, topk=10)
+        assert len(result_small) > 0
+
+        # Test with list_size=200
+        query_large = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=DiskAnnQueryParam(list_size=200),
+        )
+        result_large = collection_with_multiple_docs.query(queries=query_large, topk=10)
+        assert len(result_large) > 0
+
+    def test_query_with_topk(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test querying with different topk values."""
+        query_vector = multiple_docs[0].vector("embedding")
+        query = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=DiskAnnQueryParam(list_size=100),
+        )
+
+        # Test topk=5
+        result_5 = collection_with_multiple_docs.query(queries=query, topk=5)
+        assert len(result_5) <= 5
+
+        # Test topk=20
+        result_20 = collection_with_multiple_docs.query(queries=query, topk=20)
+        assert len(result_20) <= 20
+
+    def test_query_with_filter(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test querying with filter conditions."""
+        query_vector = multiple_docs[0].vector("embedding")
+        query = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=DiskAnnQueryParam(list_size=100),
+        )
+
+        # Query with id filter
+        result = collection_with_multiple_docs.query(
+            queries=query, topk=10, filter="id < 50"
+        )
+        assert len(result) > 0
+        for doc in result:
+            assert doc.field("id") < 50
+
+    def test_query_with_output_fields(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test querying with specific output fields."""
+        query_vector = multiple_docs[0].vector("embedding")
+        query = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=DiskAnnQueryParam(list_size=100),
+        )
+
+        result = collection_with_multiple_docs.query(
+            queries=query, topk=10, output_fields=["id", "name"]
+        )
+        assert len(result) > 0
+
+        first_doc = result[0]
+        assert "id" in first_doc.field_names()
+        assert "name" in first_doc.field_names()
+
+    def test_query_with_include_vector(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test querying with vector data included in results."""
+        query_vector = multiple_docs[0].vector("embedding")
+        query = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=DiskAnnQueryParam(list_size=100),
+        )
+
+        result = collection_with_multiple_docs.query(
+            queries=query, topk=10, include_vector=True
+        )
+        assert len(result) > 0
+
+        first_doc = result[0]
+        assert first_doc.vector("embedding") is not None
+        assert len(first_doc.vector("embedding")) == 128
+
+
+@pytest.mark.usefixtures("diskann_collection")
+class TestDiskAnnCollectionUpdate:
+    """Test document update in DiskAnn collection."""
+
+    def test_update_doc_fields(
+        self, collection_with_single_doc: Collection, single_doc: Doc
+    ):
+        """Test updating document fields."""
+        updated_doc = Doc(
+            id=single_doc.id,
+            fields={"id": single_doc.field("id"), "name": "updated_name"},
+        )
+
+        result = collection_with_single_doc.update(updated_doc)
+        assert bool(result)
+        assert result.ok()
+
+        # Verify update
+        fetched = collection_with_single_doc.fetch(ids=[single_doc.id])
+        assert single_doc.id in fetched
+        doc = fetched[single_doc.id]
+        assert doc.field("name") == "updated_name"
+
+    def test_update_doc_vector(
+        self, collection_with_single_doc: Collection, single_doc: Doc
+    ):
+        """Test updating document vector."""
+        new_vector = [0.5 + i * 0.01 for i in range(128)]
+        updated_doc = Doc(
+            id=single_doc.id,
+            vectors={"embedding": new_vector},
+        )
+
+        result = collection_with_single_doc.update(updated_doc)
+        assert bool(result)
+        assert result.ok()
+
+        # Verify update
+        fetched = collection_with_single_doc.fetch(
+            ids=[single_doc.id],
+        )
+        assert single_doc.id in fetched
+        doc = fetched[single_doc.id]
+        assert doc.vector("embedding") is not None
+        embedding = doc.vector("embedding")
+        assert len(embedding) == 128
+        # Verify vector values are approximately equal (float comparison)
+        for i in range(128):
+            assert math.isclose(embedding[i], new_vector[i], rel_tol=1e-5)
+
+
+@pytest.mark.usefixtures("diskann_collection")
+class TestDiskAnnCollectionDelete:
+    """Test document deletion from DiskAnn collection."""
+
+    def test_delete_single_doc(
+        self, collection_with_single_doc: Collection, single_doc: Doc
+    ):
+        """Test deleting a single document."""
+        result = collection_with_single_doc.delete(single_doc.id)
+        assert bool(result)
+        assert result.ok()
+
+        stats = collection_with_single_doc.stats
+        assert stats.doc_count == 0
+
+    def test_delete_multiple_docs(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test deleting multiple documents."""
+        ids_to_delete = [doc.id for doc in multiple_docs[:10]]
+        result = collection_with_multiple_docs.delete(ids_to_delete)
+        assert len(result) == len(ids_to_delete)
+        for item in result:
+            assert item.ok()
+
+        stats = collection_with_multiple_docs.stats
+        assert stats.doc_count == len(multiple_docs) - len(ids_to_delete)
+
+
+@pytest.mark.usefixtures("diskann_collection")
+class TestDiskAnnCollectionOptimizeAndReopen:
+    """Test collection optimize and reopen functionality."""
+
+    def test_optimize_close_reopen_and_query(
+        self,
+        tmp_path_factory,
+        diskann_collection_schema,
+        collection_option,
+        multiple_docs: list[Doc],
+    ):
+        """Test inserting 100 docs, optimize, close, reopen and query."""
+        # Create collection and insert 100 documents
+        temp_dir = tmp_path_factory.mktemp("zvec_diskann_optimize")
+        collection_path = temp_dir / "test_optimize_collection"
+
+        coll = zvec.create_and_open(
+            path=str(collection_path),
+            schema=diskann_collection_schema,
+            option=collection_option,
+        )
+
+        assert coll is not None
+        assert coll.stats.doc_count == 0
+
+        # Insert 100 documents
+        result = coll.insert(multiple_docs)
+        assert len(result) == len(multiple_docs)
+        for item in result:
+            assert item.ok()
+        assert coll.stats.doc_count == len(multiple_docs)
+
+        # Call optimize
+        from zvec import OptimizeOption
+
+        coll.optimize(option=OptimizeOption())
+
+        # Verify data is still accessible after optimize
+        query_vector = multiple_docs[0].vector("embedding")
+        query = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=DiskAnnQueryParam(list_size=100),
+        )
+        result_before_close = coll.query(queries=query, topk=10)
+        assert len(result_before_close) > 0
+
+        # Close collection (destroy will close it)
+        collection_path_str = str(collection_path)
+        del coll
+
+        # Reopen collection
+        reopened_coll = zvec.open(path=collection_path_str, option=collection_option)
+        assert reopened_coll is not None
+        assert reopened_coll.stats.doc_count == len(multiple_docs)
+
+        # Execute query on reopened collection
+        query_after_reopen = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=DiskAnnQueryParam(list_size=100),
+        )
+        result_after_reopen = reopened_coll.query(queries=query_after_reopen, topk=10)
+        assert len(result_after_reopen) > 0
+        assert len(result_after_reopen) <= 10
+
+        # Verify query results are valid
+        first_doc = result_after_reopen[0]
+        assert first_doc is not None
+        assert first_doc.id is not None
+        assert first_doc.field("id") is not None
+        assert first_doc.field("name") is not None
+
+        # Cleanup
+        reopened_coll.destroy()

python/tests/test_collection_fts.py

@@ -0,0 +1,188 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""End-to-end tests for FTS-only collections (no vector field).
+
+The schema validation rule "must have at least one vector field" has been
+lifted; these tests pin the new behavior so insert / query / delete /
+optimize all work on a vector-less collection.
+"""
+
+from __future__ import annotations
+
+import pytest
+import zvec
+from zvec import (
+    Collection,
+    CollectionOption,
+    DataType,
+    Doc,
+    FieldSchema,
+    FtsIndexParam,
+    OptimizeOption,
+)
+from zvec.model.param.query import Fts, Query
+
+
+# ==================== Fixtures ====================
+
+
+@pytest.fixture(scope="function")
+def fts_collection(tmp_path_factory) -> Collection:
+    """FTS-only collection: a STRING field for forward + an FTS-indexed STRING."""
+    temp_dir = tmp_path_factory.mktemp("zvec_fts_only")
+    collection_path = temp_dir / "fts_collection"
+
+    schema = zvec.CollectionSchema(
+        name="fts_only",
+        fields=[
+            FieldSchema("title", DataType.STRING, nullable=False),
+            FieldSchema(
+                "content",
+                DataType.STRING,
+                nullable=False,
+                index_param=FtsIndexParam(
+                    tokenizer_name="standard",
+                    filters=["lowercase"],
+                ),
+            ),
+        ],
+        # vectors omitted on purpose — schema validation must accept this.
+    )
+
+    coll = zvec.create_and_open(
+        path=str(collection_path),
+        schema=schema,
+        option=CollectionOption(read_only=False, enable_mmap=True),
+    )
+    assert coll is not None
+
+    try:
+        yield coll
+    finally:
+        try:
+            coll.destroy()
+        except Exception as e:
+            print(f"Warning: failed to destroy collection: {e}")
+
+
+def _make_docs() -> list[Doc]:
+    """5-doc corpus where 4 contain 'hello' and doc 4 is the only outlier."""
+    return [
+        Doc(id="pk_0", fields={"title": "intro", "content": "hello world"}),
+        Doc(id="pk_1", fields={"title": "guide", "content": "hello foo bar"}),
+        Doc(id="pk_2", fields={"title": "tips", "content": "hello baz"}),
+        Doc(id="pk_3", fields={"title": "more", "content": "hello hello"}),
+        Doc(id="pk_4", fields={"title": "other", "content": "nothing relevant"}),
+    ]
+
+
+def _fts_query(coll: Collection, term: str) -> list[Doc]:
+    """Run a single-term FTS match query against the `content` field."""
+    return coll.query(
+        queries=Query(field_name="content", fts=Fts(match_string=term)),
+        topk=10,
+    )
+
+
+# ==================== Tests ====================
+
+
+class TestFtsOnlyCollectionSchema:
+    def test_create_and_open_without_vectors(self, fts_collection: Collection):
+        """Schema with zero vector fields must be accepted by validate()."""
+        assert fts_collection.schema.name == "fts_only"
+        assert {f.name for f in fts_collection.schema.fields} == {"title", "content"}
+        # Empty vectors is the whole point of the test.
+        assert list(fts_collection.schema.vectors) == []
+        assert fts_collection.stats.doc_count == 0
+
+    def test_create_schema_omitting_vectors_kwarg(self):
+        """Constructing CollectionSchema without `vectors=` argument is valid."""
+        schema = zvec.CollectionSchema(
+            name="bare_fts",
+            fields=[
+                FieldSchema(
+                    "content",
+                    DataType.STRING,
+                    nullable=False,
+                    index_param=FtsIndexParam(),
+                ),
+            ],
+        )
+        assert list(schema.vectors) == []
+        assert {f.name for f in schema.fields} == {"content"}
+
+
+class TestFtsOnlyCollectionLifecycle:
+    def test_insert_and_fts_query(self, fts_collection: Collection):
+        """FTS-only collection supports insert + FTS query end-to-end."""
+        results = fts_collection.insert(_make_docs())
+        assert all(r.ok() for r in results)
+        assert fts_collection.stats.doc_count == 5
+
+        hits = _fts_query(fts_collection, "hello")
+        assert len(hits) == 4
+        assert {doc.id for doc in hits} == {"pk_0", "pk_1", "pk_2", "pk_3"}
+
+        # Term that nothing in the surviving corpus contains.
+        assert _fts_query(fts_collection, "missing_term_xyz") == []
+
+    def test_delete_then_query(self, fts_collection: Collection):
+        """Tombstone filter must drop deleted docs from FTS results."""
+        fts_collection.insert(_make_docs())
+        statuses = fts_collection.delete(["pk_0", "pk_4"])
+        assert all(s.ok() for s in statuses)
+        assert fts_collection.stats.doc_count == 3
+
+        hits = _fts_query(fts_collection, "hello")
+        assert len(hits) == 3
+        assert {doc.id for doc in hits} == {"pk_1", "pk_2", "pk_3"}
+        # pk_4's unique term is filtered out post-delete.
+        assert _fts_query(fts_collection, "nothing") == []
+
+    def test_optimize_rebuilds_fts(self, fts_collection: Collection):
+        """Optimize with >30% deletes triggers ReduceFts; recall unchanged."""
+        fts_collection.insert(_make_docs())
+        # 40% delete ratio — above COMPACT_DELETE_RATIO_THRESHOLD=0.3, so
+        # build_compact_task picks the rebuild path and ReduceFts runs.
+        fts_collection.delete(["pk_0", "pk_4"])
+
+        before = {doc.id for doc in _fts_query(fts_collection, "hello")}
+        assert before == {"pk_1", "pk_2", "pk_3"}
+
+        fts_collection.optimize(option=OptimizeOption())
+        assert fts_collection.stats.doc_count == 3
+
+        after = {doc.id for doc in _fts_query(fts_collection, "hello")}
+        assert after == before
+        assert _fts_query(fts_collection, "nothing") == []
+
+
+class TestFtsOnlyCollectionQueryValidation:
+    def test_vector_query_rejected(self, fts_collection: Collection):
+        """Vector query on a no-vector collection must raise."""
+        with pytest.raises(ValueError, match="No vector field found"):
+            fts_collection.query(
+                queries=Query(field_name="content", vector=[0.1, 0.2, 0.3]),
+                topk=5,
+            )
+
+    def test_id_query_rejected(self, fts_collection: Collection):
+        """ID-based query on a no-vector collection must raise."""
+        fts_collection.insert(_make_docs()[:1])
+        with pytest.raises(ValueError, match="No vector field found"):
+            fts_collection.query(
+                queries=Query(field_name="content", id="pk_0"),
+                topk=5,
+            )

python/tests/test_collection_fts_vector_hybrid.py

@@ -0,0 +1,391 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Tests for FTS + vector hybrid retrieval via multi-query with reranker."""
+
+from __future__ import annotations
+
+import pytest
+import zvec
+from zvec import (
+    Collection,
+    CollectionOption,
+    DataType,
+    Doc,
+    FieldSchema,
+    FtsIndexParam,
+    HnswIndexParam,
+    VectorSchema,
+)
+from zvec.extension.multi_vector_reranker import RrfReRanker, WeightedReRanker
+from zvec.model.param.query import Fts, Query
+
+
+DIM = 16
+
+
+# ==================== Fixtures ====================
+
+
+@pytest.fixture(scope="function")
+def hybrid_collection(tmp_path_factory) -> Collection:
+    """Collection with one vector field + one FTS field."""
+    temp_dir = tmp_path_factory.mktemp("zvec_hybrid")
+    collection_path = temp_dir / "hybrid_collection"
+
+    schema = zvec.CollectionSchema(
+        name="hybrid_test",
+        fields=[
+            FieldSchema("title", DataType.STRING, nullable=False),
+            FieldSchema(
+                "content",
+                DataType.STRING,
+                nullable=False,
+                index_param=FtsIndexParam(
+                    tokenizer_name="standard",
+                    filters=["lowercase"],
+                ),
+            ),
+        ],
+        vectors=[
+            VectorSchema(
+                "embedding",
+                DataType.VECTOR_FP32,
+                dimension=DIM,
+                index_param=HnswIndexParam(),
+            ),
+        ],
+    )
+
+    coll = zvec.create_and_open(
+        path=str(collection_path),
+        schema=schema,
+        option=CollectionOption(read_only=False, enable_mmap=True),
+    )
+    assert coll is not None
+
+    try:
+        yield coll
+    finally:
+        try:
+            coll.destroy()
+        except Exception as e:
+            print(f"Warning: failed to destroy collection: {e}")
+
+
+def _make_docs() -> list[Doc]:
+    """Corpus with both text content and vectors.
+
+    Docs 0-2: AI/ML topic, vectors clustered in one region.
+    Docs 3-4: retrieval topic, vectors clustered in another region.
+    Doc 5: unrelated topic.
+    """
+    # AI cluster vectors
+    ai_vec = [1.0] * 8 + [0.0] * 8
+    # Retrieval cluster vectors
+    ret_vec = [0.0] * 8 + [1.0] * 8
+    # Unrelated vector
+    other_vec = [0.5] * 16
+
+    return [
+        Doc(
+            id="pk_0",
+            fields={
+                "title": "ML Intro",
+                "content": "machine learning is a branch of artificial intelligence",
+            },
+            vectors={"embedding": ai_vec},
+        ),
+        Doc(
+            id="pk_1",
+            fields={
+                "title": "Deep Learning",
+                "content": "deep learning uses neural networks for pattern recognition",
+            },
+            vectors={"embedding": [0.9] * 8 + [0.1] * 8},
+        ),
+        Doc(
+            id="pk_2",
+            fields={
+                "title": "NLP",
+                "content": "natural language processing handles text with artificial intelligence",
+            },
+            vectors={"embedding": [0.8] * 8 + [0.2] * 8},
+        ),
+        Doc(
+            id="pk_3",
+            fields={
+                "title": "Search Engine",
+                "content": "search engine uses inverted index for text retrieval",
+            },
+            vectors={"embedding": ret_vec},
+        ),
+        Doc(
+            id="pk_4",
+            fields={
+                "title": "Vector DB",
+                "content": "vector database enables similarity retrieval and search",
+            },
+            vectors={"embedding": [0.1] * 8 + [0.9] * 8},
+        ),
+        Doc(
+            id="pk_5",
+            fields={
+                "title": "Cooking",
+                "content": "baking bread requires flour water yeast and salt",
+            },
+            vectors={"embedding": other_vec},
+        ),
+    ]
+
+
+@pytest.fixture(scope="function")
+def hybrid_collection_with_docs(hybrid_collection: Collection) -> Collection:
+    """Hybrid collection pre-populated with test documents."""
+    results = hybrid_collection.insert(_make_docs())
+    assert all(r.ok() for r in results)
+    return hybrid_collection
+
+
+# ==================== Tests ====================
+
+
+class TestFtsVectorHybridQuery:
+    """Test FTS + vector hybrid retrieval using multi-query with RRF reranker."""
+
+    def test_hybrid_fts_and_vector_basic(self, hybrid_collection_with_docs: Collection):
+        """FTS + vector multi-query with RRF reranker returns results."""
+        reranker = RrfReRanker(rank_constant=60)
+        result = hybrid_collection_with_docs.query(
+            queries=[
+                Query(field_name="content", fts=Fts(match_string="retrieval")),
+                Query(field_name="embedding", vector=[0.0] * 8 + [1.0] * 8),
+            ],
+            topk=5,
+            reranker=reranker,
+        )
+        assert len(result) > 0
+        assert len(result) <= 5
+        # Results should have scores
+        for doc in result:
+            assert doc.score > 0
+
+    def test_hybrid_fts_and_vector_ranking(
+        self, hybrid_collection_with_docs: Collection
+    ):
+        """Docs relevant in both FTS and vector should rank higher."""
+        reranker = RrfReRanker(rank_constant=60)
+        # FTS: "retrieval search" matches pk_3, pk_4
+        # Vector: ret_vec cluster matches pk_3, pk_4
+        # Both signals agree: pk_3 and pk_4 should rank top
+        result = hybrid_collection_with_docs.query(
+            queries=[
+                Query(field_name="content", fts=Fts(match_string="retrieval search")),
+                Query(field_name="embedding", vector=[0.0] * 8 + [1.0] * 8),
+            ],
+            topk=5,
+            reranker=reranker,
+        )
+        top_ids = {doc.id for doc in result[:3]}
+        assert "pk_3" in top_ids or "pk_4" in top_ids
+
+    def test_hybrid_scores_descending(self, hybrid_collection_with_docs: Collection):
+        """Hybrid query results must be sorted by score descending."""
+        reranker = RrfReRanker(rank_constant=60)
+        result = hybrid_collection_with_docs.query(
+            queries=[
+                Query(field_name="content", fts=Fts(match_string="intelligence")),
+                Query(field_name="embedding", vector=[1.0] * 8 + [0.0] * 8),
+            ],
+            topk=6,
+            reranker=reranker,
+        )
+        assert len(result) >= 2
+        scores = [doc.score for doc in result]
+        assert scores == sorted(scores, reverse=True)
+
+    def test_hybrid_with_filter(self, hybrid_collection_with_docs: Collection):
+        """Hybrid query respects SQL filter."""
+        reranker = RrfReRanker(rank_constant=60)
+        result = hybrid_collection_with_docs.query(
+            queries=[
+                Query(field_name="content", fts=Fts(match_string="learning")),
+                Query(field_name="embedding", vector=[1.0] * 8 + [0.0] * 8),
+            ],
+            topk=10,
+            reranker=reranker,
+            filter="title like '%Learning%'",
+        )
+        for doc in result:
+            assert "Learning" in doc.fields["title"]
+
+    def test_hybrid_fts_no_match_still_returns_vector_results(
+        self, hybrid_collection_with_docs: Collection
+    ):
+        """When FTS matches nothing, vector results still appear."""
+        reranker = RrfReRanker(rank_constant=60)
+        result = hybrid_collection_with_docs.query(
+            queries=[
+                Query(
+                    field_name="content",
+                    fts=Fts(match_string="nonexistent_term_xyz"),
+                ),
+                Query(field_name="embedding", vector=[1.0] * 8 + [0.0] * 8),
+            ],
+            topk=5,
+            reranker=reranker,
+        )
+        # Vector query alone should still produce results
+        assert len(result) > 0
+
+    def test_hybrid_query_string_syntax(self, hybrid_collection_with_docs: Collection):
+        """Hybrid query works with FTS query_string (advanced syntax)."""
+        reranker = RrfReRanker(rank_constant=60)
+        result = hybrid_collection_with_docs.query(
+            queries=[
+                Query(
+                    field_name="content",
+                    fts=Fts(query_string="artificial AND intelligence"),
+                ),
+                Query(field_name="embedding", vector=[1.0] * 8 + [0.0] * 8),
+            ],
+            topk=5,
+            reranker=reranker,
+        )
+        assert len(result) > 0
+        # pk_0 and pk_2 contain "artificial intelligence"
+        hit_ids = {doc.id for doc in result}
+        assert "pk_0" in hit_ids or "pk_2" in hit_ids
+
+
+class TestFtsVectorHybridValidation:
+    """Test validation rules for FTS + vector hybrid queries."""
+
+    def test_hybrid_requires_reranker(self, hybrid_collection_with_docs: Collection):
+        """Multi-query with FTS + vector without reranker should raise."""
+        with pytest.raises(ValueError, match="[Rr]eranker"):
+            hybrid_collection_with_docs.query(
+                queries=[
+                    Query(field_name="content", fts=Fts(match_string="learning")),
+                    Query(field_name="embedding", vector=[1.0] * DIM),
+                ],
+                topk=5,
+            )
+
+    def test_duplicate_field_name_allowed(
+        self, hybrid_collection_with_docs: Collection
+    ):
+        """Multi-query with duplicate field names is allowed and returns results."""
+        reranker = RrfReRanker(rank_constant=60)
+        result = hybrid_collection_with_docs.query(
+            queries=[
+                Query(field_name="content", fts=Fts(match_string="learning")),
+                Query(field_name="content", fts=Fts(match_string="intelligence")),
+            ],
+            topk=5,
+            reranker=reranker,
+        )
+        assert len(result) > 0
+        assert len(result) <= 5
+
+    def test_multiple_vectors_allowed(self, hybrid_collection_with_docs: Collection):
+        """Two vector queries on the same field are allowed with a reranker."""
+        reranker = RrfReRanker(rank_constant=60)
+        result = hybrid_collection_with_docs.query(
+            queries=[
+                Query(field_name="embedding", vector=[1.0] * DIM),
+                Query(field_name="embedding", vector=[0.5] * DIM),
+            ],
+            topk=5,
+            reranker=reranker,
+        )
+        assert len(result) > 0
+        assert len(result) <= 5
+
+
+class TestFtsVectorHybridWeightedReranker:
+    """Test FTS + vector hybrid retrieval using WeightedReranker."""
+
+    def test_weighted_reranker_fts_and_vector(
+        self, hybrid_collection_with_docs: Collection
+    ):
+        """WeightedReranker correctly normalizes FTS scores alongside vector scores."""
+        weights = [0.5, 0.5]
+        reranker = WeightedReRanker(weights=weights)
+        result = hybrid_collection_with_docs.query(
+            queries=[
+                Query(field_name="content", fts=Fts(match_string="retrieval search")),
+                Query(field_name="embedding", vector=[0.0] * 8 + [1.0] * 8),
+            ],
+            topk=5,
+            reranker=reranker,
+        )
+        assert len(result) > 0
+        assert len(result) <= 5
+        for doc in result:
+            assert doc.score > 0
+
+    def test_weighted_reranker_scores_descending(
+        self, hybrid_collection_with_docs: Collection
+    ):
+        """WeightedReranker hybrid results are sorted by score descending."""
+        weights = [0.4, 0.6]
+        reranker = WeightedReRanker(weights=weights)
+        result = hybrid_collection_with_docs.query(
+            queries=[
+                Query(field_name="content", fts=Fts(match_string="intelligence")),
+                Query(field_name="embedding", vector=[1.0] * 8 + [0.0] * 8),
+            ],
+            topk=6,
+            reranker=reranker,
+        )
+        assert len(result) >= 2
+        scores = [doc.score for doc in result]
+        assert scores == sorted(scores, reverse=True)
+
+    def test_weighted_reranker_fts_weight_influence(
+        self, hybrid_collection_with_docs: Collection
+    ):
+        """Higher FTS weight should boost FTS-relevant docs in ranking."""
+        # High FTS weight: FTS signal dominates
+        weights_fts_heavy = [0.9, 0.1]
+        reranker_fts = WeightedReRanker(weights=weights_fts_heavy)
+        result_fts = hybrid_collection_with_docs.query(
+            queries=[
+                Query(field_name="content", fts=Fts(match_string="retrieval")),
+                Query(field_name="embedding", vector=[1.0] * 8 + [0.0] * 8),
+            ],
+            topk=5,
+            reranker=reranker_fts,
+        )
+
+        # High vector weight: vector signal dominates
+        weights_vec_heavy = [0.1, 0.9]
+        reranker_vec = WeightedReRanker(weights=weights_vec_heavy)
+        result_vec = hybrid_collection_with_docs.query(
+            queries=[
+                Query(field_name="content", fts=Fts(match_string="retrieval")),
+                Query(field_name="embedding", vector=[1.0] * 8 + [0.0] * 8),
+            ],
+            topk=5,
+            reranker=reranker_vec,
+        )
+
+        # Both should return results
+        assert len(result_fts) > 0
+        assert len(result_vec) > 0
+        # With FTS-heavy weight, FTS-relevant docs (pk_3, pk_4) should rank higher
+        fts_top = [doc.id for doc in result_fts[:2]]
+        vec_top = [doc.id for doc in result_vec[:2]]
+        # The rankings should differ due to weight difference
+        assert fts_top != vec_top or len(result_fts) == len(result_vec) == 1

python/tests/test_collection_hnsw_rabitq.py

@@ -0,0 +1,574 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+import platform
+import sys
+
+import pytest
+import math
+import zvec
+
+pytestmark = pytest.mark.skipif(
+    not (sys.platform == "linux" and platform.machine() in ("x86_64", "AMD64")),
+    reason="HNSW RaBitQ only supported on Linux x86_64",
+)
+from zvec import (
+    Collection,
+    CollectionOption,
+    DataType,
+    Doc,
+    FieldSchema,
+    HnswRabitqIndexParam,
+    HnswRabitqQueryParam,
+    MetricType,
+    VectorSchema,
+    Query,
+)
+
+
+# ==================== Fixtures ====================
+
+
+@pytest.fixture(scope="session")
+def hnsw_rabitq_collection_schema():
+    """Create a collection schema with HNSW RaBitQ index."""
+    return zvec.CollectionSchema(
+        name="test_hnsw_rabitq_collection",
+        fields=[
+            FieldSchema("id", DataType.INT64, nullable=False),
+            FieldSchema("name", DataType.STRING, nullable=False),
+        ],
+        vectors=[
+            VectorSchema(
+                "embedding",
+                DataType.VECTOR_FP32,
+                dimension=128,
+                index_param=HnswRabitqIndexParam(
+                    metric_type=MetricType.L2,
+                    m=16,
+                    ef_construction=200,
+                    total_bits=7,
+                    num_clusters=64,
+                ),
+            ),
+        ],
+    )
+
+
+@pytest.fixture(scope="session")
+def collection_option():
+    """Create collection options."""
+    return CollectionOption(read_only=False, enable_mmap=True)
+
+
+@pytest.fixture
+def single_doc():
+    """Create a single document for testing."""
+    return Doc(
+        id="0",
+        fields={"id": 0, "name": "test_doc_0"},
+        vectors={"embedding": [0.1 + i * 0.01 for i in range(128)]},
+    )
+
+
+@pytest.fixture
+def multiple_docs():
+    """Create multiple documents for testing."""
+    return [
+        Doc(
+            id=f"{i}",
+            fields={"id": i, "name": f"test_doc_{i}"},
+            vectors={"embedding": [i * 0.1 + j * 0.01 for j in range(128)]},
+        )
+        for i in range(1, 101)
+    ]
+
+
+@pytest.fixture(scope="function")
+def hnsw_rabitq_collection(
+    tmp_path_factory, hnsw_rabitq_collection_schema, collection_option
+) -> Collection:
+    """
+    Function-scoped fixture: creates and opens a collection with HNSW RaBitQ index.
+    """
+    temp_dir = tmp_path_factory.mktemp("zvec_hnsw_rabitq")
+    collection_path = temp_dir / "test_hnsw_rabitq_collection"
+
+    coll = zvec.create_and_open(
+        path=str(collection_path),
+        schema=hnsw_rabitq_collection_schema,
+        option=collection_option,
+    )
+
+    assert coll is not None, "Failed to create and open HNSW RaBitQ collection"
+    assert coll.path == str(collection_path)
+    assert coll.schema.name == hnsw_rabitq_collection_schema.name
+
+    try:
+        yield coll
+    finally:
+        if hasattr(coll, "destroy") and coll is not None:
+            try:
+                coll.destroy()
+            except Exception as e:
+                print(f"Warning: failed to destroy collection: {e}")
+
+
+@pytest.fixture
+def collection_with_single_doc(
+    hnsw_rabitq_collection: Collection, single_doc: Doc
+) -> Collection:
+    """Setup: insert single doc into collection."""
+    assert hnsw_rabitq_collection.stats.doc_count == 0
+    result = hnsw_rabitq_collection.insert(single_doc)
+    assert bool(result)
+    assert result.ok()
+    assert hnsw_rabitq_collection.stats.doc_count == 1
+
+    yield hnsw_rabitq_collection
+
+    # Teardown: delete single doc
+    hnsw_rabitq_collection.delete(single_doc.id)
+    assert hnsw_rabitq_collection.stats.doc_count == 0
+
+
+@pytest.fixture
+def collection_with_multiple_docs(
+    hnsw_rabitq_collection: Collection, multiple_docs: list[Doc]
+) -> Collection:
+    """Setup: insert multiple docs into collection."""
+    assert hnsw_rabitq_collection.stats.doc_count == 0
+    result = hnsw_rabitq_collection.insert(multiple_docs)
+    assert len(result) == len(multiple_docs)
+    for item in result:
+        assert item.ok()
+    assert hnsw_rabitq_collection.stats.doc_count == len(multiple_docs)
+
+    yield hnsw_rabitq_collection
+
+    # Teardown: delete multiple docs
+    hnsw_rabitq_collection.delete([doc.id for doc in multiple_docs])
+
+
+# ==================== Tests ====================
+
+
+@pytest.mark.usefixtures("hnsw_rabitq_collection")
+class TestHnswRabitqCollectionCreation:
+    """Test HNSW RaBitQ collection creation and schema validation."""
+
+    def test_collection_creation(
+        self, hnsw_rabitq_collection: Collection, hnsw_rabitq_collection_schema
+    ):
+        """Test that collection is created with correct schema."""
+        assert hnsw_rabitq_collection is not None
+        assert hnsw_rabitq_collection.schema.name == hnsw_rabitq_collection_schema.name
+        assert len(hnsw_rabitq_collection.schema.fields) == len(
+            hnsw_rabitq_collection_schema.fields
+        )
+        assert len(hnsw_rabitq_collection.schema.vectors) == len(
+            hnsw_rabitq_collection_schema.vectors
+        )
+
+    def test_vector_schema_validation(self, hnsw_rabitq_collection: Collection):
+        """Test that vector schema has correct HNSW RaBitQ configuration."""
+        vector_schema = hnsw_rabitq_collection.schema.vector("embedding")
+        assert vector_schema is not None
+        assert vector_schema.name == "embedding"
+        assert vector_schema.data_type == DataType.VECTOR_FP32
+        assert vector_schema.dimension == 128
+
+        index_param = vector_schema.index_param
+        assert index_param is not None
+        assert index_param.metric_type == MetricType.L2
+        assert index_param.m == 16
+        assert index_param.ef_construction == 200
+        assert index_param.total_bits == 7
+        assert index_param.num_clusters == 64
+
+    def test_collection_stats(self, hnsw_rabitq_collection: Collection):
+        """Test initial collection statistics."""
+        stats = hnsw_rabitq_collection.stats
+        assert stats is not None
+        assert stats.doc_count == 0
+        assert len(stats.index_completeness) == 1
+        assert stats.index_completeness["embedding"] == 1
+
+
+@pytest.mark.usefixtures("hnsw_rabitq_collection")
+class TestHnswRabitqCollectionInsert:
+    """Test document insertion into HNSW RaBitQ collection."""
+
+    def test_insert_single_doc(
+        self, hnsw_rabitq_collection: Collection, single_doc: Doc
+    ):
+        """Test inserting a single document."""
+        result = hnsw_rabitq_collection.insert(single_doc)
+        assert bool(result)
+        assert result.ok()
+
+        stats = hnsw_rabitq_collection.stats
+        assert stats is not None
+        assert stats.doc_count == 1
+
+    def test_insert_multiple_docs(
+        self, hnsw_rabitq_collection: Collection, multiple_docs: list[Doc]
+    ):
+        """Test inserting multiple documents."""
+        result = hnsw_rabitq_collection.insert(multiple_docs)
+        assert len(result) == len(multiple_docs)
+        for item in result:
+            assert item.ok()
+
+        stats = hnsw_rabitq_collection.stats
+        assert stats is not None
+        assert stats.doc_count == len(multiple_docs)
+
+
+@pytest.mark.usefixtures("hnsw_rabitq_collection")
+class TestHnswRabitqCollectionFetch:
+    """Test document fetching from HNSW RaBitQ collection."""
+
+    def test_fetch_single_doc(
+        self, collection_with_single_doc: Collection, single_doc: Doc
+    ):
+        """Test fetching a single document by ID."""
+        result = collection_with_single_doc.fetch(ids=[single_doc.id])
+        assert bool(result)
+        assert single_doc.id in result.keys()
+
+        doc = result[single_doc.id]
+        assert doc is not None
+        assert doc.id == single_doc.id
+        assert doc.field("id") == single_doc.field("id")
+        assert doc.field("name") == single_doc.field("name")
+
+    def test_fetch_multiple_docs(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test fetching multiple documents by IDs."""
+        ids = [doc.id for doc in multiple_docs[:10]]
+        result = collection_with_multiple_docs.fetch(ids=ids)
+        assert bool(result)
+        assert len(result) == len(ids)
+
+        for doc_id in ids:
+            assert doc_id in result
+            doc = result[doc_id]
+            assert doc is not None
+            assert doc.id == doc_id
+
+    def test_fetch_nonexistent_doc(self, collection_with_single_doc: Collection):
+        """Test fetching a non-existent document."""
+        result = collection_with_single_doc.fetch(ids=["nonexistent_id"])
+        assert len(result) == 0
+
+
+@pytest.mark.usefixtures("hnsw_rabitq_collection")
+class TestHnswRabitqCollectionQuery:
+    """Test vector search queries on HNSW RaBitQ collection."""
+
+    def test_query_by_vector(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test querying by vector with HNSW RaBitQ index."""
+        query_vector = multiple_docs[0].vector("embedding")
+        query = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=HnswRabitqQueryParam(ef=300),
+        )
+
+        result = collection_with_multiple_docs.query(queries=query, topk=10)
+        assert len(result) > 0
+        assert len(result) <= 10
+
+        # First result should be the query document itself (or very close)
+        first_doc = result[0]
+        assert first_doc is not None
+        assert first_doc.id is not None
+
+    def test_query_by_id(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test querying by document ID with HNSW RaBitQ index."""
+        query = Query(
+            field_name="embedding",
+            id=multiple_docs[0].id,
+            param=HnswRabitqQueryParam(ef=300),
+        )
+
+        result = collection_with_multiple_docs.query(queries=query, topk=10)
+        assert len(result) > 0
+        assert len(result) <= 10
+
+    def test_query_with_different_ef_values(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test querying with different ef parameter values."""
+        query_vector = multiple_docs[0].vector("embedding")
+
+        # Test with ef=100
+        query_100 = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=HnswRabitqQueryParam(ef=100),
+        )
+        result_100 = collection_with_multiple_docs.query(queries=query_100, topk=10)
+        assert len(result_100) > 0
+
+        # Test with ef=500
+        query_500 = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=HnswRabitqQueryParam(ef=500),
+        )
+        result_500 = collection_with_multiple_docs.query(queries=query_500, topk=10)
+        assert len(result_500) > 0
+
+    def test_query_with_topk(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test querying with different topk values."""
+        query_vector = multiple_docs[0].vector("embedding")
+        query = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=HnswRabitqQueryParam(ef=300),
+        )
+
+        # Test topk=5
+        result_5 = collection_with_multiple_docs.query(queries=query, topk=5)
+        assert len(result_5) <= 5
+
+        # Test topk=20
+        result_20 = collection_with_multiple_docs.query(queries=query, topk=20)
+        assert len(result_20) <= 20
+
+    def test_query_with_filter(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test querying with filter conditions."""
+        query_vector = multiple_docs[0].vector("embedding")
+        query = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=HnswRabitqQueryParam(ef=300),
+        )
+
+        # Query with id filter
+        result = collection_with_multiple_docs.query(
+            queries=query, topk=10, filter="id < 50"
+        )
+        assert len(result) > 0
+        for doc in result:
+            assert doc.field("id") < 50
+
+    def test_query_with_output_fields(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test querying with specific output fields."""
+        query_vector = multiple_docs[0].vector("embedding")
+        query = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=HnswRabitqQueryParam(ef=300),
+        )
+
+        result = collection_with_multiple_docs.query(
+            queries=query, topk=10, output_fields=["id", "name"]
+        )
+        assert len(result) > 0
+
+        first_doc = result[0]
+        assert "id" in first_doc.field_names()
+        assert "name" in first_doc.field_names()
+
+    def test_query_with_include_vector(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test querying with vector data included in results."""
+        query_vector = multiple_docs[0].vector("embedding")
+        query = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=HnswRabitqQueryParam(ef=300),
+        )
+
+        result = collection_with_multiple_docs.query(
+            queries=query, topk=10, include_vector=True
+        )
+        assert len(result) > 0
+
+        first_doc = result[0]
+        assert first_doc.vector("embedding") is not None
+        assert len(first_doc.vector("embedding")) == 128
+
+
+@pytest.mark.usefixtures("hnsw_rabitq_collection")
+class TestHnswRabitqCollectionUpdate:
+    """Test document update in HNSW RaBitQ collection."""
+
+    def test_update_doc_fields(
+        self, collection_with_single_doc: Collection, single_doc: Doc
+    ):
+        """Test updating document fields."""
+        updated_doc = Doc(
+            id=single_doc.id,
+            fields={"id": single_doc.field("id"), "name": "updated_name"},
+        )
+
+        result = collection_with_single_doc.update(updated_doc)
+        assert bool(result)
+        assert result.ok()
+
+        # Verify update
+        fetched = collection_with_single_doc.fetch(ids=[single_doc.id])
+        assert single_doc.id in fetched
+        doc = fetched[single_doc.id]
+        assert doc.field("name") == "updated_name"
+
+    def test_update_doc_vector(
+        self, collection_with_single_doc: Collection, single_doc: Doc
+    ):
+        """Test updating document vector."""
+        new_vector = [0.5 + i * 0.01 for i in range(128)]
+        updated_doc = Doc(
+            id=single_doc.id,
+            vectors={"embedding": new_vector},
+        )
+
+        result = collection_with_single_doc.update(updated_doc)
+        assert bool(result)
+        assert result.ok()
+
+        # Verify update
+        fetched = collection_with_single_doc.fetch(
+            ids=[single_doc.id],
+        )
+        assert single_doc.id in fetched
+        doc = fetched[single_doc.id]
+        assert doc.vector("embedding") is not None
+        embedding = doc.vector("embedding")
+        assert len(embedding) == 128
+        # Verify vector values are approximately equal (float comparison)
+        for i in range(128):
+            assert math.isclose(embedding[i], new_vector[i], rel_tol=1e-5)
+
+
+@pytest.mark.usefixtures("hnsw_rabitq_collection")
+class TestHnswRabitqCollectionDelete:
+    """Test document deletion from HNSW RaBitQ collection."""
+
+    def test_delete_single_doc(
+        self, collection_with_single_doc: Collection, single_doc: Doc
+    ):
+        """Test deleting a single document."""
+        result = collection_with_single_doc.delete(single_doc.id)
+        assert bool(result)
+        assert result.ok()
+
+        stats = collection_with_single_doc.stats
+        assert stats.doc_count == 0
+
+    def test_delete_multiple_docs(
+        self, collection_with_multiple_docs: Collection, multiple_docs: list[Doc]
+    ):
+        """Test deleting multiple documents."""
+        ids_to_delete = [doc.id for doc in multiple_docs[:10]]
+        result = collection_with_multiple_docs.delete(ids_to_delete)
+        assert len(result) == len(ids_to_delete)
+        for item in result:
+            assert item.ok()
+
+        stats = collection_with_multiple_docs.stats
+        assert stats.doc_count == len(multiple_docs) - len(ids_to_delete)
+
+
+@pytest.mark.usefixtures("hnsw_rabitq_collection")
+class TestHnswRabitqCollectionOptimizeAndReopen:
+    """Test collection optimize and reopen functionality."""
+
+    def test_optimize_close_reopen_and_query(
+        self,
+        tmp_path_factory,
+        hnsw_rabitq_collection_schema,
+        collection_option,
+        multiple_docs: list[Doc],
+    ):
+        """Test inserting 100 docs, optimize, close, reopen and query."""
+        # Create collection and insert 100 documents
+        temp_dir = tmp_path_factory.mktemp("zvec_hnsw_rabitq_optimize")
+        collection_path = temp_dir / "test_optimize_collection"
+
+        coll = zvec.create_and_open(
+            path=str(collection_path),
+            schema=hnsw_rabitq_collection_schema,
+            option=collection_option,
+        )
+
+        assert coll is not None
+        assert coll.stats.doc_count == 0
+
+        # Insert 100 documents
+        result = coll.insert(multiple_docs)
+        assert len(result) == len(multiple_docs)
+        for item in result:
+            assert item.ok()
+        assert coll.stats.doc_count == len(multiple_docs)
+
+        # Call optimize
+        from zvec import OptimizeOption
+
+        coll.optimize(option=OptimizeOption())
+
+        # Verify data is still accessible after optimize
+        query_vector = multiple_docs[0].vector("embedding")
+        query = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=HnswRabitqQueryParam(ef=300),
+        )
+        result_before_close = coll.query(query, topk=10)
+        assert len(result_before_close) > 0
+
+        # Close collection (destroy will close it)
+        collection_path_str = str(collection_path)
+        del coll
+
+        # Reopen collection
+        reopened_coll = zvec.open(path=collection_path_str, option=collection_option)
+        assert reopened_coll is not None
+        assert reopened_coll.stats.doc_count == len(multiple_docs)
+
+        # Execute query on reopened collection
+        query_after_reopen = Query(
+            field_name="embedding",
+            vector=query_vector,
+            param=HnswRabitqQueryParam(ef=300),
+        )
+        result_after_reopen = reopened_coll.query(query_after_reopen, topk=10)
+        assert len(result_after_reopen) > 0
+        assert len(result_after_reopen) <= 10
+
+        # Verify query results are valid
+        first_doc = result_after_reopen[0]
+        assert first_doc is not None
+        assert first_doc.id is not None
+        assert first_doc.field("id") is not None
+        assert first_doc.field("name") is not None
+
+        # Cleanup
+        reopened_coll.destroy()

python/tests/test_convert.py

@@ -0,0 +1,584 @@
+from __future__ import annotations
+
+import math
+
+import pytest
+from zvec._zvec import _Doc
+from zvec.model.convert import convert_to_py_doc, convert_to_cpp_doc
+from zvec import Doc, CollectionSchema, DataType, FieldSchema, VectorSchema
+
+
+# ----------------------------
+# Convert Cpp Doc Test Case
+# ----------------------------
+class TestConvertCppDoc:
+    def test_default(self):
+        doc = Doc(id="1")
+        schema = CollectionSchema(
+            name="test_collection",
+            fields=FieldSchema("name", DataType.STRING),
+        )
+
+        cpp_doc = convert_to_cpp_doc(doc, collection_schema=schema)
+
+        assert cpp_doc is not None
+        assert cpp_doc.pk() == doc.id
+
+    def test_with_field_notin_schema(self):
+        doc = Doc(id="1", fields={"name": "Tom"})
+        schema = CollectionSchema(
+            name="test_collection",
+            fields=[
+                FieldSchema("id", DataType.UINT64),
+                FieldSchema("salary", DataType.UINT32),
+                FieldSchema("age", DataType.INT32),
+                FieldSchema("create_at", DataType.INT64),
+                FieldSchema("author", DataType.STRING),
+                FieldSchema("weight", DataType.FLOAT),
+            ],
+        )
+        with pytest.raises(ValueError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+    def test_with_scalar_fields(self):
+        schema = CollectionSchema(
+            name="test_collection",
+            fields=[
+                FieldSchema("id", DataType.UINT64),
+                FieldSchema("salary", DataType.UINT32),
+                FieldSchema("age", DataType.INT32),
+                FieldSchema("create_at", DataType.INT64),
+                FieldSchema("author", DataType.STRING),
+                FieldSchema("weight", DataType.FLOAT),
+                FieldSchema("bmi", DataType.DOUBLE),
+                FieldSchema("is_male", DataType.BOOL),
+            ],
+        )
+        doc = Doc(
+            id="1",
+            fields={
+                "id": 1,
+                "salary": 1000,
+                "age": 18,
+                "create_at": 1640995200,
+                "bmi": 80.0 / 200.0,
+                "author": "Tom",
+                "weight": 80.0,
+                "is_male": True,
+            },
+        )
+        cpp_doc = convert_to_cpp_doc(doc, collection_schema=schema)
+        assert cpp_doc is not None
+        assert cpp_doc.pk() == doc.id
+        assert cpp_doc.get_any("id", DataType.UINT64) == 1
+        assert cpp_doc.get_any("salary", DataType.UINT32) == 1000
+        assert cpp_doc.get_any("age", DataType.INT32) == 18
+        assert cpp_doc.get_any("create_at", DataType.INT64) == 1640995200
+        assert cpp_doc.get_any("author", DataType.STRING) == "Tom"
+        assert math.isclose(
+            cpp_doc.get_any("weight", DataType.FLOAT), 80.0, rel_tol=1e-6
+        )
+        assert math.isclose(
+            cpp_doc.get_any("bmi", DataType.DOUBLE), 80.0 / 200.0, rel_tol=1e-6
+        )
+        assert cpp_doc.get_any("is_male", DataType.BOOL) == True
+
+    def test_with_array_fields(self):
+        schema = CollectionSchema(
+            name="test_collection",
+            fields=[
+                FieldSchema("tags", DataType.ARRAY_STRING),
+                FieldSchema("ids", DataType.ARRAY_UINT64),
+                FieldSchema("marks", DataType.ARRAY_UINT32),
+                FieldSchema("x", DataType.ARRAY_INT32),
+                FieldSchema("y", DataType.ARRAY_INT64),
+                FieldSchema("scores", DataType.ARRAY_FLOAT),
+                FieldSchema("ratios", DataType.ARRAY_DOUBLE),
+                FieldSchema("results", DataType.ARRAY_BOOL),
+            ],
+        )
+
+        doc = Doc(
+            id="1",
+            fields={
+                "tags": ["tag1", "tag2", "tag3"],
+                "ids": [111111111111, 222222222222, 333333333333],
+                "marks": [100, 200, 300],
+                "x": [1, 2, 3],
+                "y": [100, 200, 300],
+                "scores": [1.1, 2.2, 3.3],
+                "ratios": [0.1, 0.2, 0.3],
+                "results": [True, False, True],
+            },
+        )
+        cpp_doc = convert_to_cpp_doc(doc, collection_schema=schema)
+
+        assert cpp_doc is not None
+        assert cpp_doc.pk() == doc.id
+        assert cpp_doc.get_any("tags", DataType.ARRAY_STRING) == doc.field("tags")
+        assert cpp_doc.get_any("ids", DataType.ARRAY_UINT64) == doc.field("ids")
+        assert cpp_doc.get_any("marks", DataType.ARRAY_UINT32) == doc.field("marks")
+        assert cpp_doc.get_any("x", DataType.ARRAY_INT32) == doc.field("x")
+        assert cpp_doc.get_any("y", DataType.ARRAY_INT64) == doc.field("y")
+        scores = cpp_doc.get_any("scores", DataType.ARRAY_FLOAT)
+        for i in range(len(doc.field("scores"))):
+            assert math.isclose(scores[i], doc.field("scores")[i], rel_tol=1e-1)
+        ratios = cpp_doc.get_any("ratios", DataType.ARRAY_DOUBLE)
+        for i in range(len(doc.field("ratios"))):
+            assert math.isclose(ratios[i], doc.field("ratios")[i], rel_tol=1e-1)
+        results = cpp_doc.get_any("results", DataType.ARRAY_BOOL)
+        for i in range(len(doc.field("results"))):
+            assert results[i] == doc.field("results")[i]
+
+    def test_with_dense_vector_fields(self):
+        schema = CollectionSchema(
+            name="test_collection",
+            vectors=[
+                VectorSchema(
+                    name="embedding",
+                    data_type=DataType.VECTOR_FP16,
+                    dimension=4,
+                ),
+                VectorSchema(
+                    name="image",
+                    data_type=DataType.VECTOR_FP32,
+                    dimension=8,
+                ),
+                VectorSchema(
+                    name="text",
+                    data_type=DataType.VECTOR_INT8,
+                    dimension=32,
+                ),
+            ],
+        )
+
+        doc = Doc(
+            id="1",
+            vectors={
+                "embedding": [1.1] * 4,
+                "image": [2.2] * 8,
+                "text": [4] * 32,
+            },
+        )
+        cpp_doc = convert_to_cpp_doc(doc, collection_schema=schema)
+        assert cpp_doc is not None
+        assert cpp_doc.pk() == doc.id
+
+        embedding_vector = cpp_doc.get_any("embedding", DataType.VECTOR_FP16)
+        assert len(embedding_vector) == 4
+        for i in range(4):
+            assert math.isclose(
+                embedding_vector[i], doc.vector("embedding")[i], rel_tol=1e-1
+            )
+
+        image_vector = cpp_doc.get_any("image", DataType.VECTOR_FP32)
+        assert len(image_vector) == 8
+        for i in range(8):
+            assert math.isclose(image_vector[i], doc.vector("image")[i], rel_tol=1e-1)
+
+        text_vector = cpp_doc.get_any("text", DataType.VECTOR_INT8)
+        assert len(text_vector) == 32
+        for i in range(32):
+            assert text_vector[i] == doc.vectors["text"][i]
+
+    def test_with_sparse_vector_fields(self):
+        schema = CollectionSchema(
+            name="test_collection",
+            vectors=[
+                VectorSchema(
+                    name="author",
+                    data_type=DataType.SPARSE_VECTOR_FP32,
+                ),
+                VectorSchema(
+                    name="content",
+                    data_type=DataType.SPARSE_VECTOR_FP16,
+                ),
+            ],
+        )
+        doc = Doc(
+            id="1",
+            vectors={
+                "author": {1: 1.1, 2: 2.2, 3: 3.3},
+                "content": {4: 4.4, 5: 5.5, 6: 6.6},
+            },
+        )
+
+        cpp_doc = convert_to_cpp_doc(doc, collection_schema=schema)
+        assert cpp_doc is not None
+        assert cpp_doc.pk() == doc.id
+
+        author_vector = cpp_doc.get_any("author", DataType.SPARSE_VECTOR_FP32)
+        assert isinstance(author_vector, dict)
+        for key, value in doc.vector("author").items():
+            assert math.isclose(author_vector[key], value, rel_tol=1e-1)
+
+        content_vector = cpp_doc.get_any("content", DataType.SPARSE_VECTOR_FP16)
+        assert isinstance(content_vector, dict)
+        for key, value in doc.vector("content").items():
+            assert math.isclose(content_vector[key], value, rel_tol=1e-1)
+
+    def test_with_scalar_fields_error_datatype(self):
+        schema = CollectionSchema(
+            name="test_collection",
+            fields=[
+                FieldSchema("id", DataType.UINT64),
+                FieldSchema("salary", DataType.UINT32),
+                FieldSchema("age", DataType.INT32),
+                FieldSchema("create_at", DataType.INT64),
+                FieldSchema("author", DataType.STRING),
+                FieldSchema("weight", DataType.FLOAT),
+                FieldSchema("bmi", DataType.DOUBLE),
+                FieldSchema("is_male", DataType.BOOL),
+            ],
+        )
+        doc = Doc(
+            id="1",
+            fields={
+                "id": "1",
+            },
+        )
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(id="1", fields={"salary": "1000"})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(id="1", fields={"age": "18"})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(id="1", fields={"create_at": "2021-01-01"})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(id="1", fields={"author": 1})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(id="1", fields={"weight": "80.5"})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(id="1", fields={"bmi": "25.0"})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(id="1", fields={"is_male": "true"})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+    def test_with_array_fields_error_datatype(self):
+        schema = CollectionSchema(
+            name="test_collection",
+            fields=[
+                FieldSchema("tags", DataType.ARRAY_STRING),
+                FieldSchema("ids", DataType.ARRAY_UINT64),
+                FieldSchema("marks", DataType.ARRAY_UINT32),
+                FieldSchema("x", DataType.ARRAY_INT32),
+                FieldSchema("y", DataType.ARRAY_INT64),
+                FieldSchema("scores", DataType.ARRAY_FLOAT),
+                FieldSchema("ratios", DataType.ARRAY_DOUBLE),
+                FieldSchema("results", DataType.ARRAY_BOOL),
+            ],
+        )
+
+        doc = Doc(id="1", fields={"tags": [1, 2, 3]})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(id="1", fields={"ids": ["1", "2", "3"]})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(id="1", fields={"marks": [1.1, 2.2, 3.3]})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(id="1", fields={"x": [1.1, 2.2, 3.3]})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(id="1", fields={"y": [1.1, 2.2, 3.3]})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(id="1", fields={"scores": ["1", "2", "3"]})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(id="1", fields={"ratios": ["1", "2", "3"]})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(id="1", fields={"results": ["1", "2", "3"]})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+    def test_with_vector_fields_error_datatype(self):
+        schema = CollectionSchema(
+            name="test_collection",
+            vectors=[
+                VectorSchema(
+                    name="embedding",
+                    data_type=DataType.VECTOR_FP16,
+                    dimension=4,
+                ),
+                VectorSchema(
+                    name="image",
+                    data_type=DataType.VECTOR_FP32,
+                    dimension=8,
+                ),
+                VectorSchema(
+                    name="text",
+                    data_type=DataType.VECTOR_INT8,
+                    dimension=32,
+                ),
+            ],
+        )
+
+        doc = Doc(id="1", vectors={"image": ["1.1"] * 4})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(id="1", vectors={"text": ["1"] * 4})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(id="1", vectors={"embedding": ["1"] * 4})
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+    def test_with_sparse_vector_error_datatype(self):
+        schema = CollectionSchema(
+            name="test_collection",
+            vectors=[
+                VectorSchema(
+                    name="author",
+                    data_type=DataType.SPARSE_VECTOR_FP32,
+                ),
+                VectorSchema(
+                    name="content",
+                    data_type=DataType.SPARSE_VECTOR_FP16,
+                ),
+            ],
+        )
+        doc = Doc(
+            id="1",
+            vectors={
+                "author": {"1": 1.1, "2": 2.2, "3": 3.3},
+            },
+        )
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(
+            id="1",
+            vectors={
+                "content": {"1": 1.1, "2": 2.2, "3": 3.3},
+            },
+        )
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+        doc = Doc(
+            id="1",
+            vectors={
+                "author": {1: "1", 2: "2", 3: "3"},
+            },
+        )
+        with pytest.raises(TypeError):
+            convert_to_cpp_doc(doc, collection_schema=schema)
+
+
+# ----------------------------
+# Convert Py Doc Test Case
+# ----------------------------
+class TestConvertPyDoc:
+    def test_default(self):
+        doc = _Doc()
+        doc.set_pk("1")
+        doc.set_score(1.0)
+
+        schema = CollectionSchema(
+            name="test_collection",
+            fields=FieldSchema("name", DataType.STRING),
+        )
+
+        py_doc = convert_to_py_doc(doc, schema)
+        assert py_doc.id == "1"
+        assert py_doc.score == 1.0
+
+    def test_with_scalar_fields(self):
+        schema = CollectionSchema(
+            name="test_collection",
+            fields=[
+                FieldSchema("id", DataType.UINT64),
+                FieldSchema("salary", DataType.UINT32),
+                FieldSchema("age", DataType.INT32),
+                FieldSchema("create_at", DataType.INT64),
+                FieldSchema("author", DataType.STRING),
+                FieldSchema("weight", DataType.FLOAT),
+                FieldSchema("bmi", DataType.DOUBLE),
+                FieldSchema("is_male", DataType.BOOL),
+            ],
+        )
+        doc = _Doc()
+        doc.set_pk("1")
+        doc.set_any("id", schema.field("id")._get_object(), 1111111111111111)
+        doc.set_any("salary", schema.field("salary")._get_object(), 1000)
+        doc.set_any("age", schema.field("age")._get_object(), 18)
+        doc.set_any("create_at", schema.field("create_at")._get_object(), 1640995200)
+        doc.set_any("author", schema.field("author")._get_object(), "Tom")
+        doc.set_any("weight", schema.field("weight")._get_object(), 80.0)
+        doc.set_any("bmi", schema.field("bmi")._get_object(), 80.0 / 200.0)
+        doc.set_any("is_male", schema.field("is_male")._get_object(), True)
+
+        py_doc = convert_to_py_doc(doc, schema)
+        assert py_doc.id == "1"
+        assert py_doc.field("id") == 1111111111111111
+        assert py_doc.field("salary") == 1000
+        assert py_doc.field("age") == 18
+        assert py_doc.field("create_at") == 1640995200
+        assert py_doc.field("author") == "Tom"
+        assert py_doc.field("weight") == 80.0
+        assert py_doc.field("bmi") == 80.0 / 200.0
+        assert py_doc.field("is_male") == True
+
+    def test_with_array_fields(self):
+        schema = CollectionSchema(
+            name="test_collection",
+            fields=[
+                FieldSchema("tags", DataType.ARRAY_STRING),
+                FieldSchema("ids", DataType.ARRAY_UINT64),
+                FieldSchema("marks", DataType.ARRAY_UINT32),
+                FieldSchema("x", DataType.ARRAY_INT32),
+                FieldSchema("y", DataType.ARRAY_INT64),
+                FieldSchema("scores", DataType.ARRAY_FLOAT),
+                FieldSchema("ratios", DataType.ARRAY_DOUBLE),
+                FieldSchema("results", DataType.ARRAY_BOOL),
+            ],
+        )
+
+        doc = _Doc()
+        doc.set_pk("1")
+        doc.set_any(
+            "tags", schema.field("tags")._get_object(), ["tag1", "tag2", "tag3"]
+        )
+        doc.set_any(
+            "ids",
+            schema.field("ids")._get_object(),
+            [111111111111, 222222222222, 3333333333333],
+        )
+        doc.set_any("marks", schema.field("marks")._get_object(), [1000, 2000, 3000])
+        doc.set_any("x", schema.field("x")._get_object(), [1, 2, 3])
+        doc.set_any("y", schema.field("y")._get_object(), [100, 200, 300])
+        doc.set_any("scores", schema.field("scores")._get_object(), [0.1, 0.2, 0.3])
+        doc.set_any("ratios", schema.field("ratios")._get_object(), [0.1, 0.2, 0.3])
+        doc.set_any(
+            "results", schema.field("results")._get_object(), [True, False, True]
+        )
+
+        py_doc = convert_to_py_doc(doc, schema)
+        assert py_doc.field("tags") == ["tag1", "tag2", "tag3"]
+        assert py_doc.field("ids") == [111111111111, 222222222222, 3333333333333]
+        assert py_doc.field("marks") == [1000, 2000, 3000]
+        assert py_doc.field("x") == [1, 2, 3]
+        assert py_doc.field("y") == [100, 200, 300]
+
+        scores = doc.get_any("scores", DataType.ARRAY_FLOAT)
+        for i in range(len(scores)):
+            assert math.isclose(scores[i], py_doc.field("scores")[i], rel_tol=1e-1)
+        ratios = doc.get_any("ratios", DataType.ARRAY_DOUBLE)
+        for i in range(len(ratios)):
+            assert math.isclose(ratios[i], py_doc.field("ratios")[i], rel_tol=1e-1)
+        results = doc.get_any("results", DataType.ARRAY_BOOL)
+        for i in range(len(results)):
+            assert results[i] == py_doc.field("results")[i]
+
+    def test_with_dense_vector_fields(self):
+        schema = CollectionSchema(
+            name="test_collection",
+            vectors=[
+                VectorSchema(
+                    name="embedding",
+                    data_type=DataType.VECTOR_FP16,
+                    dimension=4,
+                ),
+                VectorSchema(
+                    name="image",
+                    data_type=DataType.VECTOR_FP32,
+                    dimension=8,
+                ),
+                VectorSchema(
+                    name="text",
+                    data_type=DataType.VECTOR_INT8,
+                    dimension=32,
+                ),
+            ],
+        )
+
+        doc = _Doc()
+        doc.set_pk("1")
+        doc.set_any("embedding", schema.vector("embedding")._get_object(), [1.1] * 4)
+        doc.set_any("image", schema.vector("image")._get_object(), [2.2] * 8)
+        doc.set_any("text", schema.vector("text")._get_object(), [4] * 32)
+
+        py_doc = convert_to_py_doc(doc, schema)
+        assert py_doc.id == "1"
+
+        embedding_vector = py_doc.vector("embedding")
+        assert len(embedding_vector) == 4
+        for i in range(4):
+            assert math.isclose(
+                py_doc.vector("embedding")[i], embedding_vector[i], rel_tol=1e-1
+            )
+
+        image_vector = py_doc.vector("image")
+        assert len(image_vector) == 8
+        for i in range(8):
+            assert math.isclose(
+                py_doc.vector("image")[i], image_vector[i], rel_tol=1e-1
+            )
+
+        text_vector = py_doc.vector("text")
+        assert len(text_vector) == 32
+        for i in range(32):
+            assert py_doc.vector("text")[i] == text_vector[i]
+
+    def test_with_sparse_vector_fields(self):
+        schema = CollectionSchema(
+            name="test_collection",
+            vectors=[
+                VectorSchema(
+                    name="author",
+                    data_type=DataType.SPARSE_VECTOR_FP32,
+                ),
+                VectorSchema(
+                    name="content",
+                    data_type=DataType.SPARSE_VECTOR_FP16,
+                ),
+            ],
+        )
+
+        doc = _Doc()
+        doc.set_pk("1")
+        doc.set_any(
+            "author", schema.vector("author")._get_object(), {1: 1.1, 2: 2.2, 3: 3.3}
+        )
+        doc.set_any(
+            "content", schema.vector("content")._get_object(), {4: 4.4, 5: 5.5, 6: 6.6}
+        )
+
+        py_doc = convert_to_py_doc(doc, schema)
+        assert py_doc.id == "1"
+
+        author_vector = py_doc.vector("author")
+        assert isinstance(author_vector, dict)
+        for key, value in doc.get_any("author", DataType.SPARSE_VECTOR_FP32).items():
+            assert math.isclose(author_vector[key], value, rel_tol=1e-1)
+
+        content_vector = py_doc.vector("content")
+        assert isinstance(content_vector, dict)
+        for key, value in doc.get_any("content", DataType.SPARSE_VECTOR_FP16).items():
+            assert math.isclose(content_vector[key], value, rel_tol=1e-1)

python/tests/test_doc.py

@@ -0,0 +1,269 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+import math
+import pytest
+
+
+from zvec._zvec import _Doc
+from zvec import FieldSchema, VectorSchema, Doc, DataType
+
+
+# ----------------------------
+# PyDoc Test Case
+# ----------------------------
+class TestPyDoc:
+    def test_default(self):
+        Doc(id="1")
+
+    def test_with_single_vector(self):
+        doc = Doc(id="1", vectors={"dense": [1, 2, 3]})
+        assert doc is not None
+        assert doc.id == "1"
+        assert doc.vector("dense") == [1, 2, 3]
+
+    def test_with_hybrid_vectors(self):
+        doc = Doc(
+            id="1", vectors={"dense": [1, 2, 3], "sparse": {1: 1.0, 2: 2.0, 3: 3.0}}
+        )
+        assert doc is not None
+        assert doc.id == "1"
+        assert doc.vector("dense") == [1, 2, 3]
+        assert doc.vector("sparse") == {1: 1.0, 2: 2.0, 3: 3.0}
+
+    def test_with_multi_vectors(self):
+        doc = Doc(
+            id="1",
+            vectors={
+                "image": [1, 2, 3],
+                "description": [4, 5, 6],
+                "keys": {1: 1.0, 2: 2.0, 3: 3.0},
+            },
+            fields={"author": "Tom", "age": 19, "is_male": True, "weight": 60.5},
+        )
+        assert doc is not None
+        assert doc.id == "1"
+        assert doc.vector("image") == [1, 2, 3]
+        assert doc.vector("description") == [4, 5, 6]
+        assert doc.vector("keys") == {1: 1.0, 2: 2.0, 3: 3.0}
+        assert doc.field("author") == "Tom"
+        assert doc.field("age") == 19
+        assert doc.field("is_male") == True
+        assert doc.field("weight") == 60.5
+
+    def test_with_numpy_array(self):
+        import numpy as np
+
+        doc = Doc._from_tuple(
+            (
+                "1",
+                0.0,
+                None,
+                {
+                    "image": np.array([1, 2, 3]),
+                    "description": np.random.random(512),
+                    "keys": {1: 1.0, 2: 2.0, 3: 3.0},
+                },
+            )
+        )
+        assert doc is not None
+        assert doc.id == "1"
+        assert doc.vector("image") == [1, 2, 3]
+        assert doc.vector("keys") == {1: 1.0, 2: 2.0, 3: 3.0}
+
+
+# ----------------------------
+# CppDoc Test Case
+# ----------------------------
+class TestCppDoc:
+    def test_default(self):
+        doc = _Doc()
+        assert doc is not None
+
+    def test_doc_set_pk(self):
+        doc = _Doc()
+        doc.set_pk("1")
+        assert doc.pk() == "1"
+
+    def test_doc_set_score(self):
+        doc = _Doc()
+        doc.set_score(0.9)
+        assert math.isclose(doc.score(), 0.9, rel_tol=1e-6)
+
+    def test_doc_get_null_field(self):
+        doc = _Doc()
+        schema = FieldSchema("author", DataType.STRING, nullable=True)
+        doc.set_any("author", schema._get_object(), None)
+        assert doc.has_field("author")
+        assert doc.get_any("author", schema.data_type) is None
+
+    def test_doc_get_set_has_null_field(self):
+        doc = _Doc()
+        schema = FieldSchema("author", DataType.STRING, nullable=False)
+        with pytest.raises(ValueError):
+            doc.set_any("author", schema._get_object(), None)
+
+    def test_doc_get_set_has_string_field(self):
+        doc = _Doc()
+        schema = FieldSchema("author", DataType.STRING)
+        doc.set_any("author", schema._get_object(), "Tom")
+        assert doc.has_field("author")
+        assert doc.get_any("author", DataType.STRING) == "Tom"
+
+    def test_doc_get_set_has_bool_field(self):
+        doc = _Doc()
+        schema = FieldSchema("is_male", DataType.BOOL)
+        doc.set_any("is_male", schema._get_object(), True)
+        assert doc.has_field("is_male")
+        assert doc.get_any("is_male", DataType.BOOL) == True
+
+    def test_doc_get_set_has_int32_field(self):
+        doc = _Doc()
+        schema = FieldSchema("age", DataType.INT32)
+        doc.set_any("age", schema._get_object(), 19)
+        assert doc.has_field("age")
+        assert doc.get_any("age", DataType.INT32) == 19
+
+    def test_doc_get_set_has_int64_field(self):
+        doc = _Doc()
+        schema = FieldSchema("id", DataType.INT64)
+        doc.set_any("id", schema._get_object(), 1111111111111111111)
+        assert doc.has_field("id")
+        assert doc.get_any("id", DataType.INT64) == 1111111111111111111
+
+    def test_doc_get_set_has_float_field(self):
+        doc = _Doc()
+        schema = FieldSchema("weight", DataType.FLOAT)
+        doc.set_any("weight", schema._get_object(), 60.5)
+        assert doc.has_field("weight")
+        assert math.isclose(doc.get_any("weight", DataType.FLOAT), 60.5, rel_tol=1e-6)
+
+    def test_doc_get_set_has_double_field(self):
+        doc = _Doc()
+        schema = FieldSchema("height", DataType.DOUBLE)
+        doc.set_any("height", schema._get_object(), 1.77777777777)
+        assert doc.has_field("height")
+        assert math.isclose(
+            doc.get_any("height", DataType.DOUBLE), 1.7777777777, rel_tol=1e-9
+        )
+
+    def test_doc_get_set_has_uint32_field(self):
+        doc = _Doc()
+        schema = FieldSchema("id", DataType.UINT32)
+        doc.set_any("id", schema._get_object(), 4294967295)
+        assert doc.has_field("id")
+        assert doc.get_any("id", DataType.UINT32) == 4294967295
+
+    def test_doc_get_set_has_uint64_field(self):
+        doc = _Doc()
+        schema = FieldSchema("id", DataType.UINT64)
+        doc.set_any("id", schema._get_object(), 18446744073709551615)
+        assert doc.has_field("id")
+        assert doc.get_any("id", DataType.UINT64) == 18446744073709551615
+
+    def test_doc_get_set_has_array_string_field(self):
+        doc = _Doc()
+        schema = FieldSchema("tags", DataType.ARRAY_STRING)
+        doc.set_any("tags", schema._get_object(), ["tag1", "tag2", "tag3"])
+        assert doc.has_field("tags")
+        assert doc.get_any("tags", DataType.ARRAY_STRING) == ["tag1", "tag2", "tag3"]
+
+    def test_doc_get_set_has_array_int32_field(self):
+        doc = _Doc()
+        schema = FieldSchema("ids", DataType.ARRAY_INT32)
+        doc.set_any("ids", schema._get_object(), [1, 2, 3])
+        assert doc.has_field("ids")
+        assert doc.get_any("ids", DataType.ARRAY_INT32) == [1, 2, 3]
+
+    def test_doc_get_set_has_array_int64_field(self):
+        doc = _Doc()
+        schema = FieldSchema("ids", DataType.ARRAY_INT64)
+        doc.set_any("ids", schema._get_object(), [1, 2, 3])
+        assert doc.has_field("ids")
+        assert doc.get_any("ids", DataType.ARRAY_INT64) == [1, 2, 3]
+
+    def test_doc_get_set_has_array_float_field(self):
+        doc = _Doc()
+        schema = FieldSchema("weights", DataType.ARRAY_FLOAT)
+        doc.set_any("weights", schema._get_object(), [1.0, 2.0, 3.0])
+        assert doc.has_field("weights")
+        assert doc.get_any("weights", DataType.ARRAY_FLOAT) == [1.0, 2.0, 3.0]
+
+    def test_doc_get_set_has_array_double_field(self):
+        doc = _Doc()
+        schema = FieldSchema("heights", DataType.ARRAY_DOUBLE)
+        doc.set_any("heights", schema._get_object(), [1.0, 2.0, 3.0])
+        assert doc.has_field("heights")
+        assert doc.get_any("heights", DataType.ARRAY_DOUBLE) == [1.0, 2.0, 3.0]
+
+    def test_doc_get_set_has_array_bool_field(self):
+        doc = _Doc()
+        schema = FieldSchema("bools", DataType.ARRAY_BOOL)
+        doc.set_any("bools", schema._get_object(), [True, False, True])
+        assert doc.has_field("bools")
+        assert doc.get_any("bools", DataType.ARRAY_BOOL) == [True, False, True]
+
+    def test_doc_get_set_has_vector_fp16(self):
+        doc = _Doc()
+        schema = VectorSchema("image", DataType.VECTOR_FP16)
+        doc.set_any("image", schema._get_object(), [1.0, 2.0, 3.0])
+        assert doc.has_field("image")
+        image_vector = doc.get_any("image", DataType.VECTOR_FP16)
+        assert image_vector is not None
+        for i in range(len(image_vector)):
+            assert math.isclose(image_vector[i], [1.0, 2.0, 3.0][i], rel_tol=1e-6)
+
+    def test_doc_get_set_has_vector_fp32(self):
+        doc = _Doc()
+        schema = VectorSchema("image", DataType.VECTOR_FP32)
+        doc.set_any("image", schema._get_object(), [1.111111, 2.222222, 3.333333])
+        assert doc.has_field("image")
+        vector = doc.get_any("image", DataType.VECTOR_FP32)
+        assert vector is not None
+        for i in range(len(vector)):
+            assert math.isclose(
+                vector[i], [1.111111, 2.222222, 3.333333][i], rel_tol=1e-6
+            )
+
+    def test_doc_get_set_has_vector_int8(self):
+        doc = _Doc()
+        schema = VectorSchema("image", DataType.VECTOR_INT8)
+        doc.set_any("image", schema._get_object(), [1, 2, 3])
+        assert doc.has_field("image")
+        assert doc.get_any("image", DataType.VECTOR_INT8) == [1, 2, 3]
+
+    def test_doc_get_set_has_sparse_vector_fp32(self):
+        doc = _Doc()
+        sparse = {1: 1.111111, 2: 2.222222, 3: 3.333333}
+        schema = VectorSchema("key", DataType.SPARSE_VECTOR_FP32)
+        doc.set_any("key", schema._get_object(), sparse)
+        assert doc.has_field("key")
+        vector = doc.get_any("key", DataType.SPARSE_VECTOR_FP32)
+        assert vector is not None
+        assert isinstance(vector, dict)
+        for key, value in sparse.items():
+            assert math.isclose(vector[key], value, rel_tol=1e-6)
+
+    def test_doc_get_set_has_sparse_vector_fp16(self):
+        doc = _Doc()
+        sparse = {1: 1.1, 2: 2.2, 3: 3.3}
+        schema = VectorSchema("key", DataType.SPARSE_VECTOR_FP16)
+        doc.set_any("key", schema._get_object(), sparse)
+        assert doc.has_field("key")
+        vector = doc.get_any("key", DataType.SPARSE_VECTOR_FP16)
+        assert vector is not None
+        assert isinstance(vector, dict)
+        for key, value in sparse.items():
+            assert math.isclose(vector[key], value, rel_tol=1e-1)

python/tests/test_fts_query.py

@@ -0,0 +1,158 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Tests for FTS (Full-Text Search) query support in the Python SDK."""
+
+import pickle
+
+import pytest
+
+from zvec.model.param.query import Fts, Query
+
+
+class TestFtsQueryValidation:
+    """Test FTS parameter validation in Query dataclass."""
+
+    def test_fts_query_string_only(self):
+        """Query with only query_string in Fts should be valid."""
+        q = Query(
+            field_name="content", fts=Fts(query_string='+hello -world "exact phrase"')
+        )
+        q._validate()
+        assert q.fts.query_string == '+hello -world "exact phrase"'
+        assert q.fts.match_string is None
+        assert q.has_fts() is True
+
+    def test_fts_match_string_only(self):
+        """Query with only match_string in Fts should be valid."""
+        q = Query(field_name="content", fts=Fts(match_string="machine learning"))
+        q._validate()
+        assert q.fts.match_string == "machine learning"
+        assert q.fts.query_string is None
+        assert q.has_fts() is True
+
+    def test_fts_query_string_and_match_string_mutually_exclusive(self):
+        """Cannot provide both query_string and match_string in Fts."""
+        q = Query(
+            field_name="content",
+            fts=Fts(query_string="+hello", match_string="hello world"),
+        )
+        with pytest.raises(ValueError, match="mutually exclusive"):
+            q._validate()
+
+    def test_no_fts(self):
+        """Query without FTS fields should have has_fts() == False."""
+        q = Query(field_name="embedding", vector=[0.1, 0.2, 0.3])
+        assert q.has_fts() is False
+
+    def test_vector_and_fts_mutually_exclusive(self):
+        """Cannot combine vector search with FTS in a single Query."""
+        q = Query(
+            field_name="embedding",
+            vector=[0.1, 0.2, 0.3],
+            fts=Fts(match_string="deep learning"),
+        )
+        with pytest.raises(ValueError, match="Cannot combine fts with vector search"):
+            q._validate()
+
+    def test_fts_without_vector_or_id(self):
+        """Query with only FTS (no vector, no id) should be valid."""
+        q = Query(field_name="content", fts=Fts(query_string="hello"))
+        q._validate()
+        assert q.has_vector() is False
+        assert q.has_id() is False
+        assert q.has_fts() is True
+
+
+class TestFtsQueryBinding:
+    """Test FTS binding layer (_Fts)."""
+
+    def test_import_fts_query(self):
+        """_Fts should be importable from _zvec.param."""
+        from zvec._zvec.param import _Fts
+
+        fts = _Fts()
+        assert fts.query_string == ""
+        assert fts.match_string == ""
+
+    def test_fts_query_set_fields(self):
+        """Setting fields on _Fts should work."""
+        from zvec._zvec.param import _Fts
+
+        fts = _Fts()
+        fts.query_string = "+hello -world"
+        assert fts.query_string == "+hello -world"
+
+        fts2 = _Fts()
+        fts2.match_string = "machine learning"
+        assert fts2.match_string == "machine learning"
+
+    def test_fts_query_pickle(self):
+        """_Fts should support pickling."""
+        from zvec._zvec.param import _Fts
+
+        fts = _Fts()
+        fts.query_string = "+vector search"
+        fts.match_string = ""
+
+        data = pickle.dumps(fts)
+        restored = pickle.loads(data)
+        assert restored.query_string == "+vector search"
+        assert restored.match_string == ""
+
+    def test_search_query_fts_field(self):
+        """_SearchQuery should have fts field."""
+        from zvec._zvec.param import _Fts, _SearchQuery
+
+        vq = _SearchQuery()
+        # fts should be None by default (optional)
+        assert vq.fts is None
+
+        # set fts
+        fts = _Fts()
+        fts.query_string = "hello"
+        vq.fts = fts
+        assert vq.fts is not None
+        assert vq.fts.query_string == "hello"
+
+    def test_search_query_pickle_with_fts(self):
+        """_SearchQuery with fts should survive pickling."""
+        from zvec._zvec.param import _Fts, _SearchQuery
+
+        vq = _SearchQuery()
+        vq.topk = 10
+        vq.field_name = "embedding"
+        fts = _Fts()
+        fts.match_string = "test query"
+        vq.fts = fts
+
+        data = pickle.dumps(vq)
+        restored = pickle.loads(data)
+        assert restored.topk == 10
+        assert restored.field_name == "embedding"
+        assert restored.fts is not None
+        assert restored.fts.match_string == "test query"
+
+    def test_search_query_pickle_without_fts(self):
+        """_SearchQuery without fts should survive pickling."""
+        from zvec._zvec.param import _SearchQuery
+
+        vq = _SearchQuery()
+        vq.topk = 5
+        vq.field_name = "vec"
+
+        data = pickle.dumps(vq)
+        restored = pickle.loads(data)
+        assert restored.topk == 5
+        assert restored.field_name == "vec"
+        assert restored.fts is None

python/tests/test_gil_release.py

@@ -0,0 +1,273 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Tests to verify that the GIL is released during native C++ query calls,
+enabling true thread-level concurrency for multi-threaded Python applications."""
+
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+import pytest
+import zvec
+from zvec import (
+    Collection,
+    CollectionOption,
+    DataType,
+    Doc,
+    FieldSchema,
+    HnswIndexParam,
+    Query,
+    VectorSchema,
+)
+
+
+@pytest.fixture(scope="module")
+def gil_test_collection(tmp_path_factory) -> Collection:
+    """Create a collection with enough data to make queries take measurable time."""
+    schema = zvec.CollectionSchema(
+        name="gil_test",
+        fields=[
+            FieldSchema("id", DataType.INT64, nullable=False),
+        ],
+        vectors=[
+            VectorSchema(
+                "vec",
+                DataType.VECTOR_FP32,
+                dimension=128,
+                index_param=HnswIndexParam(),
+            ),
+        ],
+    )
+    option = CollectionOption(read_only=False, enable_mmap=True)
+    temp_dir = tmp_path_factory.mktemp("zvec_gil_test")
+    collection_path = temp_dir / "gil_test_collection"
+
+    coll = zvec.create_and_open(path=str(collection_path), schema=schema, option=option)
+
+    # Insert enough docs to make queries non-trivial
+    docs = [
+        Doc(
+            id=str(i),
+            fields={"id": i},
+            vectors={"vec": [float(i % 100) + 0.1 * j for j in range(128)]},
+        )
+        for i in range(500)
+    ]
+    result = coll.insert(docs)
+    for r in result:
+        assert r.ok()
+
+    yield coll
+
+    try:
+        coll.destroy()
+    except Exception:
+        pass
+
+
+class TestGILRelease:
+    """Verify that C++ query calls release the GIL, allowing true thread concurrency."""
+
+    def test_gil_released_during_query(self, gil_test_collection: Collection):
+        """Prove the GIL is explicitly released during C++ Query calls.
+
+        Strategy:
+        - Calibrate per-query latency on the current platform (slow archs like
+          RISC-V can be 10x slower than x86), then dynamically pick a query count
+          whose total runtime fits comfortably inside switch_interval.
+        - Set switch_interval well above the projected total query time so that
+          CPython's involuntary GIL switching will NOT trigger during the run.
+        - A background thread (using time.sleep(0) to avoid deadlock) counts how
+          many times it got to run.
+        - Since total query time < switch_interval, the bg thread can ONLY run if
+          the C++ code explicitly releases the GIL.
+        - Reset counter just before queries; check counter > 0 after queries.
+        """
+        query_vec = [1.0] * 128
+
+        def run_query():
+            gil_test_collection.query(
+                Query(field_name="vec", vector=query_vec),
+                topk=100,
+            )
+
+        # --- Calibrate: estimate per-query latency on this platform ---
+        # Warm up to avoid first-call overhead skewing the measurement.
+        for _ in range(3):
+            run_query()
+
+        calib_iters = 10
+        calib_start = time.monotonic()
+        for _ in range(calib_iters):
+            run_query()
+        per_query = max((time.monotonic() - calib_start) / calib_iters, 1e-6)
+
+        # Target total query window ~200ms, capped to a sane range so the test
+        # remains meaningful on both fast and slow archs.
+        target_total = 0.2
+        num_iters = max(1, min(500, int(target_total / per_query)))
+        projected_total = per_query * num_iters
+        # Pick switch_interval with a large safety margin (>=10x, >=2s) to absorb
+        # GC pauses, CPU throttling, and noisy-neighbor effects on CI / shared VMs.
+        switch_interval = max(2.0, projected_total * 10.0)
+
+        old_interval = sys.getswitchinterval()
+        sys.setswitchinterval(switch_interval)
+
+        try:
+            counter = {"value": 0}
+            stop_event = threading.Event()
+
+            def background_counter():
+                while not stop_event.is_set():
+                    counter["value"] += 1
+                    time.sleep(0)  # Yield GIL to prevent deadlock
+
+            bg_thread = threading.Thread(target=background_counter, daemon=True)
+            bg_thread.start()
+
+            # Let bg thread start (sleep releases GIL)
+            time.sleep(0.05)
+
+            # --- Critical section: reset counter, run queries, capture counter ---
+            counter["value"] = 0
+
+            start = time.monotonic()
+            for _ in range(num_iters):
+                run_query()
+            elapsed = time.monotonic() - start
+
+            count_during_queries = counter["value"]
+            # --- End critical section ---
+
+            stop_event.set()
+            time.sleep(0.01)
+            bg_thread.join(timeout=5)
+
+            print(
+                f"\nPer-query: {per_query * 1000:.2f}ms, iters: {num_iters}, "
+                f"elapsed: {elapsed:.4f}s, switch_interval: {switch_interval:.2f}s"
+            )
+            print(f"Counter during queries: {count_during_queries}")
+
+            # Verify queries completed within the switch_interval window.
+            # If they did NOT, the run was contaminated by external jitter (GC,
+            # throttling, noisy neighbor) rather than a real GIL-release defect,
+            # so skip instead of failing to avoid flaky CI noise.
+            if elapsed >= switch_interval:
+                pytest.skip(
+                    f"Queries took {elapsed:.3f}s >= switch_interval "
+                    f"({switch_interval:.3f}s); calibration was outpaced by "
+                    "runtime jitter, result is inconclusive."
+                )
+            # If elapsed < switch_interval, the ONLY way bg thread could run is
+            # via explicit GIL release.
+            assert count_during_queries > 0, (
+                "Background thread could not run during C++ execution despite "
+                "query time < switch_interval. GIL was NOT released."
+            )
+        finally:
+            sys.setswitchinterval(old_interval)
+
+    def test_parallel_queries_correctness(self, gil_test_collection: Collection):
+        """Verify parallel queries return correct results and print timing info.
+
+        NOTE: The definitive proof of GIL release is test_gil_released_during_query
+        (counter + setswitchinterval). This test focuses on parallel correctness and
+        logs timing for manual inspection, since CI timing is too noisy for assertions.
+        """
+        num_queries = 1000
+        query_vec = [1.0] * 128
+
+        def do_query():
+            return gil_test_collection.query(
+                Query(field_name="vec", vector=query_vec),
+                topk=100,
+            )
+
+        # Serial execution (baseline)
+        start_serial = time.monotonic()
+        for _ in range(num_queries):
+            do_query()
+        serial_time = time.monotonic() - start_serial
+
+        # Parallel execution
+        num_workers = os.cpu_count() or 2
+        start_parallel = time.monotonic()
+        with ThreadPoolExecutor(max_workers=num_workers) as executor:
+            futures = [executor.submit(do_query) for _ in range(num_queries)]
+            for future in as_completed(futures):
+                result = future.result()
+                assert len(result) > 0
+        parallel_time = time.monotonic() - start_parallel
+
+        print(f"\nSerial time: {serial_time:.4f}s, Parallel time: {parallel_time:.4f}s")
+        print(
+            f"Speedup ratio: {serial_time / parallel_time:.2f}x (workers={num_workers})"
+        )
+
+    def test_thread_safety_concurrent_queries(self, gil_test_collection: Collection):
+        """Verify no crashes or data corruption under concurrent query load."""
+        num_threads = 8
+        queries_per_thread = 10
+        errors = []
+
+        def worker(thread_id):
+            try:
+                for i in range(queries_per_thread):
+                    vec = [float(thread_id + i) + 0.1 * j for j in range(128)]
+                    result = gil_test_collection.query(
+                        Query(field_name="vec", vector=vec),
+                        topk=10,
+                    )
+                    assert len(result) > 0
+            except Exception as e:
+                errors.append((thread_id, e))
+
+        threads = [
+            threading.Thread(target=worker, args=(tid,)) for tid in range(num_threads)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join(timeout=60)
+
+        assert len(errors) == 0, f"Errors in threads: {errors}"
+
+    def test_concurrent_fetch_release_gil(self, gil_test_collection: Collection):
+        """Verify Fetch operations also release the GIL correctly."""
+        num_threads = 4
+        errors = []
+
+        def worker(thread_id):
+            try:
+                ids = [str(i) for i in range(thread_id * 10, thread_id * 10 + 10)]
+                result = gil_test_collection.fetch(ids)
+                assert len(result) > 0
+            except Exception as e:
+                errors.append((thread_id, e))
+
+        threads = [
+            threading.Thread(target=worker, args=(tid,)) for tid in range(num_threads)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join(timeout=30)
+
+        assert len(errors) == 0, f"Errors in threads: {errors}"

python/tests/test_hnsw_contiguous_memory.py

@@ -0,0 +1,415 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Tests for the ``use_contiguous_memory`` optimization on ``HnswIndexParam``.
+
+The HNSW streamer supports two allocation strategies for graph nodes:
+
+* ``use_contiguous_memory=False`` (default): each node allocates its own
+  linked buffer. Lower peak memory usage, worse cache locality.
+* ``use_contiguous_memory=True``: a single contiguous arena holds every
+  node. Higher peak memory usage, better cache locality and search
+  throughput.
+
+These tests exercise the Python surface end-to-end and make sure that
+when a collection is created / reopened with ``use_contiguous_memory=True``
+the underlying HNSW streamer entity is constructed correctly and serves
+search traffic.
+"""
+
+from __future__ import annotations
+
+import pickle
+import sys
+
+import numpy as np
+import pytest
+
+import zvec
+from zvec import (
+    Collection,
+    CollectionOption,
+    CollectionSchema,
+    Doc,
+    FieldSchema,
+    HnswIndexParam,
+    HnswQueryParam,
+    InvertIndexParam,
+    Query,
+    VectorSchema,
+)
+from zvec.typing import DataType, IndexType, MetricType, QuantizeType
+
+
+DIMENSION = 32
+NUM_DOCS = 128
+TOPK = 5
+
+# ---------------------------------------------------------------------------
+
+
+def _debug_hnsw_storage_mode(coll: Collection, column: str = "dense") -> str:
+    """Return the internal HNSW entity storage mode for ``column``.
+
+    Exposes the debug-only introspection hook on the pybind11 ``_Collection``.
+    Only meaningful after ``optimize()`` has built a persisted HNSW index; on
+    a pure writing segment it will raise ``KeyError``.
+    """
+    underlying = coll._obj  # type: ignore[attr-defined]
+    return underlying._debug_hnsw_storage_mode(column)
+
+
+def _build_schema(name: str, *, use_contiguous_memory: bool) -> CollectionSchema:
+    """Create a simple schema with a single FP32 HNSW vector column."""
+    return CollectionSchema(
+        name=name,
+        fields=[
+            FieldSchema(
+                "id",
+                DataType.INT64,
+                nullable=False,
+                index_param=InvertIndexParam(enable_range_optimization=True),
+            ),
+        ],
+        vectors=[
+            VectorSchema(
+                "dense",
+                DataType.VECTOR_FP32,
+                dimension=DIMENSION,
+                index_param=HnswIndexParam(
+                    metric_type=MetricType.IP,
+                    m=16,
+                    ef_construction=100,
+                    use_contiguous_memory=use_contiguous_memory,
+                ),
+            ),
+        ],
+    )
+
+
+def _generate_docs(rng: np.random.Generator, num: int = NUM_DOCS) -> list[Doc]:
+    """Produce deterministic documents for insertion."""
+    docs: list[Doc] = []
+    for i in range(num):
+        vec = rng.standard_normal(DIMENSION).astype(np.float32)
+        docs.append(
+            Doc(
+                id=str(i),
+                fields={"id": i},
+                vectors={"dense": vec.tolist()},
+            )
+        )
+    return docs
+
+
+def _assert_query_matches(coll: Collection, query_vec: list[float]) -> list[str]:
+    """Run a top-k vector query and return the returned ids in order."""
+    vector_query = Query(
+        field_name="dense",
+        vector=query_vec,
+        param=HnswQueryParam(ef=128),
+    )
+    hits = coll.query(vector_query, topk=TOPK)
+    # Expect a single result group for the single vector query.
+    assert hits is not None, "query returned None"
+    assert len(hits) >= 1, f"expected at least one hit, got {hits!r}"
+    return [doc.id for doc in hits]
+
+
+# ---------------------------------------------------------------------------
+# 1) Pure Python surface: construction / property / to_dict / repr / pickle
+# ---------------------------------------------------------------------------
+
+
+class TestHnswIndexParamContiguousMemorySurface:
+    """Verify the Python binding exposes ``use_contiguous_memory`` correctly."""
+
+    def test_default_is_false(self):
+        param = HnswIndexParam()
+        assert param.use_contiguous_memory is False
+
+    def test_custom_true(self):
+        param = HnswIndexParam(use_contiguous_memory=True)
+        assert param.use_contiguous_memory is True
+        assert param.type == IndexType.HNSW
+        # other fields keep their default values
+        assert param.m == 50
+        assert param.ef_construction == 500
+
+    def test_to_dict_includes_use_contiguous_memory(self):
+        param = HnswIndexParam(
+            metric_type=MetricType.L2,
+            m=16,
+            ef_construction=100,
+            quantize_type=QuantizeType.FP16,
+            use_contiguous_memory=True,
+        )
+        data = param.to_dict()
+        assert data["use_contiguous_memory"] is True
+        # Make sure existing fields are still present.
+        assert data["metric_type"] == "L2"
+        assert data["m"] == 16
+        assert data["ef_construction"] == 100
+        assert data["quantize_type"] == "FP16"
+
+    def test_repr_contains_flag(self):
+        on = repr(HnswIndexParam(use_contiguous_memory=True))
+        off = repr(HnswIndexParam(use_contiguous_memory=False))
+        assert "use_contiguous_memory" in on
+        assert "use_contiguous_memory" in off
+        assert "true" in on
+        assert "false" in off
+
+    def test_readonly_property(self):
+        param = HnswIndexParam(use_contiguous_memory=True)
+        if sys.version_info >= (3, 11):
+            match_pattern = r"(can't set attribute|has no setter|readonly attribute)"
+        else:
+            match_pattern = r"can't set attribute"
+        with pytest.raises(AttributeError, match=match_pattern):
+            param.use_contiguous_memory = False  # type: ignore[misc]
+
+    def test_pickle_roundtrip(self):
+        original = HnswIndexParam(
+            metric_type=MetricType.COSINE,
+            m=24,
+            ef_construction=150,
+            quantize_type=QuantizeType.INT8,
+            use_contiguous_memory=True,
+        )
+        restored = pickle.loads(pickle.dumps(original))
+        assert restored.use_contiguous_memory is True
+        assert restored.metric_type == MetricType.COSINE
+        assert restored.m == 24
+        assert restored.ef_construction == 150
+        assert restored.quantize_type == QuantizeType.INT8
+
+
+# ---------------------------------------------------------------------------
+# 2) End-to-end: create collection, insert, query with contiguous memory on
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def rng() -> np.random.Generator:
+    return np.random.default_rng(seed=42)
+
+
+# NOTE: the ``enable_mmap=False`` (BufferPool) variant is intentionally
+# omitted from this fixture. Building a persisted HNSW index via
+# ``optimize()`` / ``create_vector_index`` / ``drop_vector_index``
+# currently requires mmap-backed storage, because the BufferPool backend
+# has not implemented the ``create_new`` semantics yet and the guard in
+# ``SegmentImpl::merge_vector_indexer`` rejects that combination. Once
+# BufferPool gains write support, re-add ``False`` to ``params`` (and
+# drop the guard in segment.cc) so these end-to-end tests cover both
+# storage modes again.
+@pytest.fixture(params=[True], ids=["mmap_on"])
+def collection_option(request) -> CollectionOption:
+    return CollectionOption(read_only=False, enable_mmap=request.param)
+
+
+# Building a new persisted HNSW index currently requires mmap-backed storage
+# because the BufferPool backend has not implemented `create_new` semantics
+# yet. Collections opened with ``enable_mmap=False`` therefore cannot run
+# optimize()/create_vector_index/drop_vector_index. Tests use this fixture
+# to know which behaviour to assert, and once BufferPool gains write support
+# the guard in segment.cc (and these branches) can be removed together.
+@pytest.fixture
+def build_index_supported(collection_option: CollectionOption) -> bool:
+    return bool(collection_option.enable_mmap)
+
+
+# Error message fragments emitted by the NotSupported guard in
+# SegmentImpl::merge_vector_indexer / drop_vector_index. If the C++ message
+# changes, update these together.
+_BUILD_NOT_SUPPORTED_FRAGMENTS = ("not yet supported", "enable_mmap=false")
+
+
+class TestHnswContiguousMemoryEndToEnd:
+    """End-to-end: schema -> create_and_open -> insert -> query works."""
+
+    def test_create_with_contiguous_memory_and_query(
+        self,
+        tmp_path_factory,
+        collection_option,
+        rng,
+    ):
+        """With the flag on, the schema round-trips and search works end-to-end.
+
+        After ``optimize()`` the writing segment is compacted into a persisted
+        segment backed by the configured HNSW entity. We assert both the
+        user-observable behaviour (schema + search) and, via the debug hook,
+        that the entity type actually honours ``use_contiguous_memory``.
+        """
+        schema = _build_schema("hnsw_contig_create", use_contiguous_memory=True)
+
+        path = tmp_path_factory.mktemp("zvec") / "hnsw_contig_create"
+        coll = zvec.create_and_open(
+            path=str(path), schema=schema, option=collection_option
+        )
+        try:
+            # Schema round-trips with the flag set.
+            vec_schema = coll.schema.vectors[0]
+            assert vec_schema.index_param.use_contiguous_memory is True
+
+            docs = _generate_docs(rng)
+            insert_result = coll.insert(docs=docs)
+            for r in insert_result:
+                assert r.ok(), f"insert failed: code={r.code()}"
+            assert coll.stats.doc_count == NUM_DOCS
+
+            # Build persisted HNSW index; this is where the contiguous entity
+            # is actually instantiated.
+            coll.optimize()
+            assert _debug_hnsw_storage_mode(coll) == "contiguous", (
+                "use_contiguous_memory=True should produce a contiguous entity"
+            )
+
+            # Pick an existing vector as the query; top-1 must be itself.
+            query_vec = docs[0].vector("dense")
+            ids = _assert_query_matches(coll, query_vec)
+            assert ids[0] == "0", f"expected self-recall, got top-1 id={ids[0]}"
+        finally:
+            coll.destroy()
+
+    def test_create_without_contiguous_memory_uses_mmap_entity(
+        self,
+        tmp_path_factory,
+        collection_option,
+        rng,
+    ):
+        """Baseline: when the flag is omitted the default (mmap) entity is used."""
+        schema = _build_schema("hnsw_contig_default", use_contiguous_memory=False)
+        path = tmp_path_factory.mktemp("zvec") / "hnsw_contig_default"
+        coll = zvec.create_and_open(
+            path=str(path), schema=schema, option=collection_option
+        )
+        try:
+            vec_schema = coll.schema.vectors[0]
+            assert vec_schema.index_param.use_contiguous_memory is False
+
+            docs = _generate_docs(rng)
+            for r in coll.insert(docs=docs):
+                assert r.ok()
+            assert coll.stats.doc_count == NUM_DOCS
+
+            coll.optimize()
+            # With the flag off and mmap on, the persisted entity must be the
+            # default mmap layout — specifically, not the contiguous arena.
+            assert _debug_hnsw_storage_mode(coll) == "mmap", (
+                "use_contiguous_memory=False + enable_mmap=True should "
+                "produce the mmap entity"
+            )
+
+            # Search still functions with the default entity backing.
+            query_vec = docs[0].vector("dense")
+            ids = _assert_query_matches(coll, query_vec)
+            assert ids[0] == "0"
+        finally:
+            coll.destroy()
+
+    def test_close_and_reopen_with_contiguous_memory(
+        self,
+        tmp_path_factory,
+        collection_option,
+        rng,
+    ):
+        """Reopening a collection must preserve the ``use_contiguous_memory`` flag.
+
+        The core property: the flag survives the schema persist/reload
+        round-trip so the HNSW streamer entity — constructed lazily on first
+        persisted-segment build — honours the user's choice. We run
+        ``optimize()`` after reopen and confirm the contiguous entity was
+        materialized.
+        """
+        schema = _build_schema("hnsw_contig_reopen", use_contiguous_memory=True)
+        path = tmp_path_factory.mktemp("zvec") / "hnsw_contig_reopen"
+        path_str = str(path)
+
+        created = zvec.create_and_open(
+            path=path_str, schema=schema, option=collection_option
+        )
+        docs = _generate_docs(rng)
+        for r in created.insert(docs=docs):
+            assert r.ok()
+        assert created.stats.doc_count == NUM_DOCS
+        # Persist pending writes so that reopen reconstructs state from disk.
+        created.flush()
+        del created  # close the handle
+
+        reopened = zvec.open(path=path_str, option=collection_option)
+        try:
+            assert reopened is not None
+            assert reopened.stats.doc_count == NUM_DOCS
+
+            # Schema persisted the flag across the reopen boundary.
+            vec_schema = reopened.schema.vectors[0]
+            assert vec_schema.index_param.use_contiguous_memory is True
+
+            reopened.optimize()
+            assert _debug_hnsw_storage_mode(reopened) == "contiguous"
+
+            # Entity actually works: exact self-recall + fetch parity.
+            query_vec = docs[7].vector("dense")
+            ids = _assert_query_matches(reopened, query_vec)
+            assert ids[0] == "7"
+
+            fetched = reopened.fetch([d.id for d in docs[:10]])
+            assert len(fetched) == 10
+        finally:
+            reopened.destroy()
+
+    def test_result_parity_with_and_without_contiguous_memory(
+        self,
+        tmp_path_factory,
+        rng,
+    ):
+        """
+        Two collections built from the same documents must return the same
+        top-k neighbors regardless of whether contiguous memory is enabled:
+        the flag is a memory-layout optimization and must not alter recall
+        for identical graph construction parameters on the same data.
+        """
+        docs = _generate_docs(rng)
+        query_vec = docs[3].vector("dense")
+
+        def _build_and_query(tag: str, flag: bool) -> list[str]:
+            schema = _build_schema(f"hnsw_parity_{tag}", use_contiguous_memory=flag)
+            option = CollectionOption(read_only=False, enable_mmap=True)
+            path = tmp_path_factory.mktemp("zvec") / f"hnsw_parity_{tag}"
+            coll = zvec.create_and_open(path=str(path), schema=schema, option=option)
+            try:
+                for r in coll.insert(docs=docs):
+                    assert r.ok()
+                coll.optimize()
+                expected_mode = "contiguous" if flag else "mmap"
+                assert _debug_hnsw_storage_mode(coll) == expected_mode, (
+                    f"{tag}: unexpected entity type"
+                )
+                return _assert_query_matches(coll, query_vec)
+            finally:
+                coll.destroy()
+
+        ids_off = _build_and_query("off", flag=False)
+        ids_on = _build_and_query("on", flag=True)
+
+        # The graph is built with the same (m, ef_construction, data, order),
+        # so top-k results must match exactly.
+        assert ids_on == ids_off, (
+            f"top-{TOPK} results diverged between use_contiguous_memory modes: "
+            f"on={ids_on}, off={ids_off}"
+        )
+        # Sanity: self-recall is still perfect.
+        assert ids_on[0] == "3"

python/tests/test_jieba_default_dict.py

@@ -0,0 +1,201 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""End-to-end: jieba FTS works without any user configuration.
+
+`import zvec` is supposed to register the wheel-bundled jieba dict
+directory via `set_default_jieba_dict_dir`. With that in place a user can
+declare an FTS field with `tokenizer_name="jieba"`, leave `extra_params`
+empty, and Chinese full-text search just works.
+
+Falls back to GTEST_SKIP-equivalent when running against a build that did
+not bundle the dict (e.g., source-tree dev install without the install
+step). In that case CI will rely on the C++ unit tests instead.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import pytest
+import zvec
+from zvec import (
+    Collection,
+    CollectionOption,
+    DataType,
+    Doc,
+    FieldSchema,
+    FtsIndexParam,
+)
+from zvec.model.param.query import Fts, Query
+
+
+def _bundled_dict_dir() -> str:
+    """Path zvec.__init__ would have registered; empty when not bundled."""
+    return zvec.get_default_jieba_dict_dir()
+
+
+def _bundled_dict_files_exist() -> bool:
+    """Whether the registered default actually contains the dict files.
+
+    `importlib.resources` happily returns a path even when the data dir was
+    not installed (e.g. source-tree dev runs); only an installed wheel has
+    the files on disk.
+    """
+    import os
+
+    base = _bundled_dict_dir()
+    if not base:
+        return False
+    return os.path.isfile(os.path.join(base, "jieba.dict.utf8")) and os.path.isfile(
+        os.path.join(base, "hmm_model.utf8")
+    )
+
+
+@pytest.fixture(scope="module", autouse=True)
+def _require_bundled_dict():
+    if not _bundled_dict_files_exist():
+        pytest.skip(
+            "Bundled jieba dict not found at zvec/data/jieba_dict/ — "
+            "this test requires an installed wheel (not a source-tree dev "
+            "build without the install step).",
+        )
+
+
+@pytest.fixture(scope="function")
+def jieba_collection(tmp_path_factory) -> Collection:
+    """FTS-only collection using jieba tokenizer and no explicit dict path."""
+    # env-var shadows GlobalConfig in the priority chain.
+    if os.environ.get("ZVEC_JIEBA_DICT_DIR"):
+        pytest.skip("ZVEC_JIEBA_DICT_DIR shadows the bundled default")
+    temp_dir = tmp_path_factory.mktemp("zvec_jieba_default")
+    collection_path = temp_dir / "fts_jieba"
+
+    schema = zvec.CollectionSchema(
+        name="fts_jieba_default",
+        fields=[
+            FieldSchema("title", DataType.STRING, nullable=False),
+            FieldSchema(
+                "content",
+                DataType.STRING,
+                nullable=False,
+                # Deliberately omit extra_params — the bundled default must
+                # be picked up via GlobalConfig.jieba_dict_dir.
+                index_param=FtsIndexParam(
+                    tokenizer_name="jieba",
+                    filters=["lowercase"],
+                ),
+            ),
+        ],
+    )
+
+    coll = zvec.create_and_open(
+        path=str(collection_path),
+        schema=schema,
+        option=CollectionOption(read_only=False, enable_mmap=True),
+    )
+    assert coll is not None
+    try:
+        yield coll
+    finally:
+        try:
+            coll.destroy()
+        except Exception as e:
+            print(f"Warning: failed to destroy collection: {e}")
+
+
+def test_jieba_works_without_explicit_dict_path(jieba_collection: Collection):
+    """User opens collection, inserts CJK doc, searches — no init() / no
+    extra_params / no env var / no manual setter call. Just `import zvec`."""
+    docs = [
+        Doc(id="pk_1", fields={"title": "t1", "content": "中华人民共和国成立"}),
+        Doc(id="pk_2", fields={"title": "t2", "content": "无关文档"}),
+    ]
+    insert_results = jieba_collection.insert(docs)
+    assert all(r.ok() for r in insert_results)
+
+    hits = jieba_collection.query(
+        queries=Query(field_name="content", fts=Fts(match_string="中华")),
+        topk=10,
+    )
+    ids = {doc.id for doc in hits}
+    assert "pk_1" in ids
+    assert "pk_2" not in ids
+
+
+def test_default_dict_dir_is_registered_on_import():
+    """Sanity check: zvec.__init__ registered a non-empty default."""
+    assert _bundled_dict_dir() != ""
+
+
+def test_user_can_override_default_at_runtime():
+    """zvec.set_default_jieba_dict_dir can be called any time to override."""
+    saved = zvec.get_default_jieba_dict_dir()
+    try:
+        zvec.set_default_jieba_dict_dir("/tmp/zvec/jieba-override")
+        assert zvec.get_default_jieba_dict_dir() == "/tmp/zvec/jieba-override"
+    finally:
+        zvec.set_default_jieba_dict_dir(saved)
+
+
+@pytest.mark.skipif(
+    sys.platform == "win32",
+    reason="os.environ writes may not propagate across CRT to zvec.pyd",
+)
+def test_env_var_overrides_global_config(monkeypatch, tmp_path_factory):
+    """ZVEC_JIEBA_DICT_DIR beats GlobalConfig in jieba's resolution chain."""
+    bundled = _bundled_dict_dir()
+    monkeypatch.setenv("ZVEC_JIEBA_DICT_DIR", bundled)
+    saved_global = zvec.get_default_jieba_dict_dir()
+    try:
+        zvec.set_default_jieba_dict_dir("/zvec/intentionally/missing/global")
+
+        temp_dir = tmp_path_factory.mktemp("zvec_jieba_env")
+        schema = zvec.CollectionSchema(
+            name="fts_jieba_env",
+            fields=[
+                FieldSchema("title", DataType.STRING, nullable=False),
+                FieldSchema(
+                    "content",
+                    DataType.STRING,
+                    nullable=False,
+                    index_param=FtsIndexParam(
+                        tokenizer_name="jieba",
+                        filters=["lowercase"],
+                    ),
+                ),
+            ],
+        )
+        coll = zvec.create_and_open(
+            path=str(temp_dir / "fts_jieba_env"),
+            schema=schema,
+            option=CollectionOption(read_only=False, enable_mmap=True),
+        )
+        assert coll is not None
+        try:
+            results = coll.insert(
+                [
+                    Doc(id="pk_1", fields={"title": "t", "content": "搜索引擎技术"}),
+                ]
+            )
+            assert all(r.ok() for r in results)
+            hits = coll.query(
+                queries=Query(field_name="content", fts=Fts(match_string="搜索")),
+                topk=10,
+            )
+            assert {d.id for d in hits} == {"pk_1"}
+        finally:
+            coll.destroy()
+    finally:
+        zvec.set_default_jieba_dict_dir(saved_global)

python/tests/test_params.py

@@ -0,0 +1,540 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+import sys
+import time
+
+
+import numpy as np
+import pytest
+from zvec import (
+    AddColumnOption,
+    AlterColumnOption,
+    CollectionOption,
+    FlatIndexParam,
+    HnswIndexParam,
+    IndexOption,
+    InvertIndexParam,
+    IVFIndexParam,
+    OptimizeOption,
+    HnswQueryParam,
+    IVFQueryParam,
+    Query,
+    VectorQuery,
+    IndexType,
+    MetricType,
+    QuantizeType,
+    QuantizerParam,
+    DataType,
+    VectorSchema,
+)
+
+from zvec._zvec.param import _SearchQuery
+
+# ----------------------------
+# Invert Index Param Test Case
+# ----------------------------
+
+
+class TestInvertIndexParam:
+    def test_default(self):
+        param = InvertIndexParam()
+        assert param.enable_range_optimization is False
+        assert param.enable_extended_wildcard is False
+        assert param.type == IndexType.INVERT
+
+    def test_custom(self):
+        param = InvertIndexParam(
+            enable_range_optimization=True, enable_extended_wildcard=True
+        )
+        assert param.enable_range_optimization is True
+        assert param.enable_extended_wildcard is True
+
+    def test_readonly(self):
+        param = InvertIndexParam()
+        import sys
+
+        if sys.version_info >= (3, 11):
+            match_pattern = r"(can't set attribute|has no setter|readonly attribute)"
+        else:
+            match_pattern = r"can't set attribute"
+        with pytest.raises(AttributeError, match=match_pattern):
+            param.enable_range_optimization = False
+            param.enable_extended_wildcard = False
+
+
+# ----------------------------
+# Hnsw Index Param Test Case
+# ----------------------------
+
+
+class TestHnswIndexParam:
+    def test_default(self):
+        param = HnswIndexParam()
+        assert param.metric_type == MetricType.IP
+        assert param.m == 50
+        assert param.ef_construction == 500
+        assert param.quantize_type == QuantizeType.UNDEFINED
+        assert param.type == IndexType.HNSW
+
+    def test_custom(self):
+        param = HnswIndexParam(
+            metric_type=MetricType.L2,
+            m=10,
+            ef_construction=1000,
+            quantize_type=QuantizeType.FP16,
+        )
+        assert param.metric_type == MetricType.L2
+        assert param.m == 10
+        assert param.ef_construction == 1000
+        assert param.quantize_type == QuantizeType.FP16
+
+    @pytest.mark.parametrize(
+        "attr", ["metric_type", "m", "ef_construction", "quantize_type"]
+    )
+    def test_readonly_attributes(self, attr):
+        param = HnswIndexParam()
+        import sys
+
+        if sys.version_info >= (3, 11):
+            match_pattern = r"(can't set attribute|has no setter|readonly attribute)"
+        else:
+            match_pattern = r"can't set attribute"
+        with pytest.raises(AttributeError, match=match_pattern):
+            setattr(param, attr, getattr(param, attr))
+
+
+# ----------------------------
+# Flat Index Param Test Case
+# ----------------------------
+class TestFlatIndexParam:
+    def test_default(self):
+        param = FlatIndexParam()
+        assert param.type == IndexType.FLAT
+        assert param.quantize_type == QuantizeType.UNDEFINED
+        assert param.metric_type == MetricType.IP
+
+    def test_custom(self):
+        param = FlatIndexParam(
+            metric_type=MetricType.L2, quantize_type=QuantizeType.INT8
+        )
+        assert param.metric_type == MetricType.L2
+        assert param.quantize_type == QuantizeType.INT8
+
+    @pytest.mark.parametrize("attr", ["metric_type", "quantize_type"])
+    def test_readonly_attributes(self, attr):
+        param = FlatIndexParam()
+        import sys
+
+        if sys.version_info >= (3, 11):
+            match_pattern = r"(can't set attribute|has no setter|readonly attribute)"
+        else:
+            match_pattern = r"can't set attribute"
+        with pytest.raises(AttributeError, match=match_pattern):
+            setattr(param, attr, getattr(param, attr))
+
+
+# ----------------------------
+# Ivf Index Param Test Case
+# ----------------------------
+class TestIVFIndexParam:
+    def test_default(self):
+        param = IVFIndexParam()
+        assert param.metric_type == MetricType.IP
+        assert param.n_list == 10
+        assert param.quantize_type == QuantizeType.UNDEFINED
+        assert param.type == IndexType.IVF
+
+    def test_custom(self):
+        param = IVFIndexParam(
+            metric_type=MetricType.L2, n_list=1000, quantize_type=QuantizeType.FP16
+        )
+        assert param.metric_type == MetricType.L2
+        assert param.n_list == 1000
+        assert param.quantize_type == QuantizeType.FP16
+        assert param.type == IndexType.IVF
+
+    @pytest.mark.parametrize("attr", ["metric_type", "n_list", "quantize_type"])
+    def test_readonly_attributes(self, attr):
+        param = IVFIndexParam()
+        import sys
+
+        if sys.version_info >= (3, 11):
+            match_pattern = r"(can't set attribute|has no setter|readonly attribute)"
+        else:
+            match_pattern = r"can't set attribute"
+        with pytest.raises(AttributeError, match=match_pattern):
+            setattr(param, attr, getattr(param, attr))
+
+
+# ----------------------------
+# CollectionOption Test Case
+# ----------------------------
+class TestCollectionOption:
+    def test_default(self):
+        option = CollectionOption()
+        assert option is not None
+        assert option.read_only == False
+        assert option.enable_mmap == True
+
+    def test_custom(self):
+        option = CollectionOption(read_only=True, enable_mmap=False)
+        assert option.read_only == True
+        assert option.enable_mmap == False
+
+        option = CollectionOption(read_only=False, enable_mmap=True)
+        assert option.read_only == False
+        assert option.enable_mmap == True
+
+    @pytest.mark.parametrize("attr", ["read_only", "enable_mmap"])
+    def test_readonly_attributes(self, attr):
+        param = CollectionOption()
+        import sys
+
+        if sys.version_info >= (3, 11):
+            match_pattern = r"(can't set attribute|has no setter|readonly attribute)"
+        else:
+            match_pattern = r"can't set attribute"
+        with pytest.raises(AttributeError, match=match_pattern):
+            setattr(param, attr, getattr(param, attr))
+
+
+# ----------------------------
+# IndexOption Test Case
+# ----------------------------
+class TestIndexOption:
+    def test_default(self):
+        option = IndexOption()
+        assert option is not None
+        assert option.concurrency == 0
+
+    def test_custom(self):
+        option = IndexOption(concurrency=10)
+        assert option.concurrency == 10
+
+    @pytest.mark.parametrize("attr", ["concurrency"])
+    def test_readonly_attributes(self, attr):
+        param = IndexOption()
+        import sys
+
+        if sys.version_info >= (3, 11):
+            match_pattern = r"(can't set attribute|has no setter|readonly attribute)"
+        else:
+            match_pattern = r"can't set attribute"
+        with pytest.raises(AttributeError, match=match_pattern):
+            setattr(param, attr, getattr(param, attr))
+
+
+# ----------------------------
+# AddColumnOption Test Case
+# ----------------------------
+class TestAddColumnOption:
+    def test_default(self):
+        option = AddColumnOption()
+        assert option is not None
+        assert option.concurrency == 0
+
+    def test_custom(self):
+        option = AddColumnOption(concurrency=10)
+        assert option.concurrency == 10
+
+    @pytest.mark.parametrize("attr", ["concurrency"])
+    def test_readonly_attributes(self, attr):
+        param = AddColumnOption()
+        import sys
+
+        if sys.version_info >= (3, 11):
+            match_pattern = r"(can't set attribute|has no setter|readonly attribute)"
+        else:
+            match_pattern = r"can't set attribute"
+        with pytest.raises(AttributeError, match=match_pattern):
+            setattr(param, attr, getattr(param, attr))
+
+
+# ----------------------------
+# AlterColumnOption Test Case
+# ----------------------------
+class TestAlterColumnOption:
+    def test_default(self):
+        option = AlterColumnOption()
+        assert option is not None
+        assert option.concurrency == 0
+
+    def test_custom(self):
+        option = AlterColumnOption(concurrency=10)
+        assert option.concurrency == 10
+
+    @pytest.mark.parametrize("attr", ["concurrency"])
+    def test_readonly_attributes(self, attr):
+        param = AlterColumnOption()
+        import sys
+
+        if sys.version_info >= (3, 11):
+            match_pattern = r"(can't set attribute|has no setter|readonly attribute)"
+        else:
+            match_pattern = r"can't set attribute"
+        with pytest.raises(AttributeError, match=match_pattern):
+            setattr(param, attr, getattr(param, attr))
+
+
+# ----------------------------
+# OptimizeOption Test Case
+# ----------------------------
+class TestOptimizeOption:
+    def test_default(self):
+        option = OptimizeOption()
+        assert option is not None
+        assert option.concurrency == 0
+
+    def test_custom(self):
+        option = OptimizeOption(concurrency=10)
+        assert option.concurrency == 10
+
+    @pytest.mark.parametrize("attr", ["concurrency"])
+    def test_readonly_attributes(self, attr):
+        param = OptimizeOption()
+        import sys
+
+        if sys.version_info >= (3, 11):
+            match_pattern = r"(can't set attribute|has no setter|readonly attribute)"
+        else:
+            match_pattern = r"can't set attribute"
+        with pytest.raises(AttributeError, match=match_pattern):
+            setattr(param, attr, getattr(param, attr))
+
+
+# ----------------------------
+# HnswQueryParam Test Case
+# ----------------------------
+class TestHnswQueryParam:
+    def test_default(self):
+        param = HnswQueryParam()
+        assert param is not None
+        assert param.ef == 300
+        assert param.is_using_refiner == False
+        assert param.radius == 0
+        assert param.is_linear == False
+        assert param.prefetch_offset == 8
+        assert param.prefetch_lines == 0
+
+    def test_custom(self):
+        param = HnswQueryParam(
+            ef=10,
+            is_using_refiner=True,
+            radius=30,
+            is_linear=True,
+            extra_params={
+                "prefetch_offset": 16,
+                "prefetch_lines": 4,
+            },
+        )
+        assert param.ef == 10
+        assert param.is_using_refiner == True
+        assert param.radius == 30
+        assert param.is_linear == True
+        assert param.prefetch_offset == 16
+        assert param.prefetch_lines == 4
+
+    def test_readonly_attributes(self):
+        param = HnswQueryParam()
+        if sys.version_info >= (3, 11):
+            match_pattern = r"(can't set attribute|has no setter|readonly attribute)"
+        else:
+            match_pattern = r"can't set attribute"
+            with pytest.raises(AttributeError, match=match_pattern):
+                param.ef = 10
+                param.is_using_refiner = True
+                param.radius = 30
+                param.is_linear = True
+
+
+# # ----------------------------
+# # IVFQueryParam Test Case
+# # ----------------------------
+# class TestIVFQueryParam:
+#     def test_default(self):
+#         param = IVFQueryParam()
+#         assert param is not None
+#         assert param.nprobe == 10
+#         assert param.is_using_refiner == False
+#         assert param.radius == 0
+#         assert param.is_linear == False
+#         assert param.scale_factor == 10
+#
+#     def test_custom(self):
+#         param = IVFQueryParam(
+#             nprobe=20,
+#             is_using_refiner=True,
+#             radius=30,
+#             is_linear=True,
+#             scale_factor=40
+#         )
+#         assert param.nprobe == 20
+#         assert param.is_using_refiner == True
+#         assert param.radius == 30
+#         assert param.is_linear == True
+#         assert param.scale_factor == 40
+
+
+class TestQuery:
+    def test_init_with_valid_id(self):
+        vq = Query(field_name="embedding", id="doc123")
+        assert vq.field_name == "embedding"
+        assert vq.id == "doc123"
+        assert vq.vector is None
+        assert vq.param is None
+
+    def test_init_with_valid_vector(self):
+        vec = [0.1, 0.2, 0.3]
+        param = HnswQueryParam(ef=300)
+        vq = Query(field_name="embedding", vector=vec, param=param)
+        assert vq.field_name == "embedding"
+        assert vq.vector == vec
+        assert vq.param == param
+
+    def test_init_both_id_and_vector_raises_error(self):
+        with pytest.raises(ValueError):
+            Query(field_name="embedding", id="doc123", vector=[0.1])._validate()
+
+    def test_init_without_field_name_raises_error(self):
+        with pytest.raises(ValueError):
+            Query(field_name=None)._validate()
+
+    def test_has_id_returns_true_when_id_set(self):
+        vq = Query(field_name="embedding", id="doc123")
+        assert vq.has_id()
+
+    def test_has_id_returns_false_when_no_id(self):
+        vq = Query(field_name="embedding", vector=[0.1])
+        assert not vq.has_id()
+
+    def test_has_vector_returns_true_with_non_empty_vector(self):
+        vq = Query(field_name="embedding", vector=[0.1])
+        assert vq.has_vector()
+
+    def test_validate_fails_on_both_id_and_vector(self):
+        vq = Query(field_name="test", id="doc123", vector=[0.1])
+        with pytest.raises(ValueError):
+            vq._validate()
+
+    def test_validate_fails_on_both_id_and_numpy_vector(self):
+        vq = Query(field_name="test", id="doc123", vector=np.array([0.1]))
+        with pytest.raises(ValueError, match="Cannot provide both id and vector"):
+            vq._validate()
+
+
+class TestVectorQueryDeprecated:
+    def test_deprecation_warning(self):
+        import warnings
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            vq = VectorQuery(field_name="embedding", id="doc123")
+            assert len(w) == 1
+            assert issubclass(w[0].category, DeprecationWarning)
+            assert "Query" in str(w[0].message)
+
+    def test_isinstance_compatibility(self):
+        import warnings
+
+        with warnings.catch_warnings(record=True):
+            warnings.simplefilter("always")
+            vq = VectorQuery(field_name="embedding", id="doc123")
+        assert isinstance(vq, Query)
+
+
+# ----------------------------
+# QuantizerParam Test Case
+# ----------------------------
+
+
+class TestQuantizerParam:
+    def test_default(self):
+        qp = QuantizerParam()
+        assert qp.enable_rotate is False
+
+    def test_enable_rotate_true(self):
+        qp = QuantizerParam(enable_rotate=True)
+        assert qp.enable_rotate is True
+
+    def test_enable_rotate_false(self):
+        qp = QuantizerParam(enable_rotate=False)
+        assert qp.enable_rotate is False
+
+    def test_equality(self):
+        qp1 = QuantizerParam(enable_rotate=True)
+        qp2 = QuantizerParam(enable_rotate=True)
+        qp3 = QuantizerParam(enable_rotate=False)
+        assert qp1 == qp2
+        assert qp1 != qp3
+
+    def test_to_dict(self):
+        qp = QuantizerParam(enable_rotate=True)
+        d = qp.to_dict()
+        assert isinstance(d, dict)
+        assert d.get("enable_rotate") is True
+
+    def test_repr(self):
+        qp = QuantizerParam(enable_rotate=True)
+        r = repr(qp)
+        assert "enable_rotate" in r or "QuantizerParam" in r
+
+    def test_pickle_roundtrip(self):
+        import pickle
+
+        qp = QuantizerParam(enable_rotate=True)
+        data = pickle.dumps(qp)
+        qp2 = pickle.loads(data)
+        assert qp2.enable_rotate is True
+        assert qp == qp2
+
+
+# ----------------------------
+# HnswIndexParam with QuantizerParam
+# ----------------------------
+
+
+class TestHnswIndexParamQuantizer:
+    def test_default_quantizer_param(self):
+        param = HnswIndexParam()
+        assert param.quantizer_param is not None
+        assert param.quantizer_param.enable_rotate is False
+
+    def test_with_quantizer_param(self):
+        qp = QuantizerParam(enable_rotate=True)
+        param = HnswIndexParam(
+            metric_type=MetricType.L2,
+            quantize_type=QuantizeType.INT8,
+            quantizer_param=qp,
+        )
+        assert param.quantizer_param.enable_rotate is True
+        assert param.quantize_type == QuantizeType.INT8
+
+
+# ----------------------------
+# FlatIndexParam with QuantizerParam
+# ----------------------------
+
+
+class TestFlatIndexParamQuantizer:
+    def test_with_quantizer_param(self):
+        qp = QuantizerParam(enable_rotate=True)
+        param = FlatIndexParam(
+            metric_type=MetricType.L2,
+            quantize_type=QuantizeType.INT8,
+            quantizer_param=qp,
+        )
+        assert param.quantizer_param.enable_rotate is True
+        assert param.quantize_type == QuantizeType.INT8

python/tests/test_query_executor.py

@@ -0,0 +1,329 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from typing import Dict, Union
+from unittest.mock import MagicMock, patch
+
+import numpy as np
+import math
+from zvec._zvec.param import _SearchQuery
+
+import pytest
+from zvec.executor.query_executor import (
+    QueryContext,
+    QueryExecutor,
+)
+from zvec import (
+    RrfReRanker,
+    WeightedReRanker,
+    HnswQueryParam,
+    CollectionSchema,
+    VectorSchema,
+    DataType,
+    MetricType,
+    Query,
+    VectorQuery,
+)
+from zvec.extension.multi_vector_reranker import CallbackReRanker
+
+
+# ----------------------------
+# Mock Collection Schema
+# ----------------------------
+class MockCollectionSchema(CollectionSchema):
+    def __init__(self, vectors=Union[VectorSchema, Dict[str, VectorSchema]]):
+        self._vectors = (
+            [vectors] if not isinstance(vectors, Dict) else list(vectors.values())
+        )
+
+    @property
+    def vectors(self):
+        return self._vectors
+
+
+# ----------------------------
+# VectorQuery Test Case
+# ----------------------------
+class TestQuery:
+    def test_init(self):
+        query = Query(field_name="test_field")
+        assert query.field_name == "test_field"
+        assert query.id is None
+        assert query.vector is None
+        assert query.param is None
+
+        param = HnswQueryParam()
+        query = Query(
+            field_name="test_field", id="test_id", vector=[1, 2, 3], param=param
+        )
+        assert query.field_name == "test_field"
+        assert query.id == "test_id"
+        assert query.vector == [1, 2, 3]
+        assert query.param == param
+
+    def test_has_id(self):
+        query = Query(field_name="test_field")
+        assert not query.has_id()
+
+        query = Query(field_name="test_field", id="test_id")
+        assert query.has_id()
+
+    def test_has_vector(self):
+        query = Query(field_name="test_field")
+        assert not query.has_vector()
+
+        query = Query(field_name="test_field", vector=[])
+        assert not query.has_vector()
+
+        query = Query(field_name="test_field", vector=[1, 2, 3])
+        assert query.has_vector()
+
+    def test_validate_dense_fp16_convert(self):
+        v = _SearchQuery()
+        schema = VectorSchema(name="test", data_type=DataType.VECTOR_FP16)
+        vec = np.array([1.1, 2.1, 3.1], dtype=np.float16)
+        v.set_vector(schema._get_object(), vec)
+        ret = v.get_vector(schema._get_object())
+        assert np.array_equal(vec, ret)
+
+    def test_validate_dense_fp32_convert(self):
+        v = _SearchQuery()
+        schema = VectorSchema(name="test", data_type=DataType.VECTOR_FP32)
+        vec = np.array([1.1, 2.1, 3.1], dtype=np.float32)
+        v.set_vector(schema._get_object(), vec)
+        ret = v.get_vector(schema._get_object())
+        assert np.array_equal(vec, ret)
+
+    def test_validate_dense_fp64_convert(self):
+        v = _SearchQuery()
+        schema = VectorSchema(name="test", data_type=DataType.VECTOR_FP64)
+        vec = np.array([1.1, 2.1, 3.1], dtype=np.float64)
+        v.set_vector(schema._get_object(), vec)
+        ret = v.get_vector(schema._get_object())
+        assert np.array_equal(vec, ret)
+
+    def test_validate_dense_int8_convert(self):
+        v = _SearchQuery()
+        schema = VectorSchema(name="test", data_type=DataType.VECTOR_INT8)
+        vec = np.array([1, 2, 3], dtype=np.int8)
+        v.set_vector(schema._get_object(), vec)
+        ret = v.get_vector(schema._get_object())
+        assert np.array_equal(vec, ret)
+
+    def test_validate_sparse_fp32_convert(self):
+        v = _SearchQuery()
+        schema = VectorSchema(name="test", data_type=DataType.SPARSE_VECTOR_FP32)
+        vec = {1: 1.1, 2: 2.2, 3: 3.3}
+        v.set_vector(schema._get_object(), vec)
+        ret = v.get_vector(schema._get_object())
+        for k in vec.keys():
+            assert math.isclose(vec[k], ret[k], abs_tol=1e-6)
+
+    def test_validate_sparse_fp16_convert(self):
+        v = _SearchQuery()
+        schema = VectorSchema(name="test", data_type=DataType.SPARSE_VECTOR_FP16)
+        vec = {1: 1.1, 2: 2.2, 3: 3.3}
+        v.set_vector(schema._get_object(), vec)
+        ret = v.get_vector(schema._get_object())
+        for k in vec.keys():
+            assert math.isclose(np.float16(vec[k]), ret[k], abs_tol=1e-6)
+
+
+class TestVectorQueryDeprecated:
+    def test_deprecation_warning(self):
+        import warnings
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            vq = VectorQuery(field_name="test_field")
+            assert len(w) == 1
+            assert issubclass(w[0].category, DeprecationWarning)
+            assert "Query" in str(w[0].message)
+
+    def test_isinstance_compatibility(self):
+        import warnings
+
+        with warnings.catch_warnings(record=True):
+            warnings.simplefilter("always")
+            vq = VectorQuery(field_name="test_field")
+        assert isinstance(vq, Query)
+
+
+class TestQueryContext:
+    def test_init(self):
+        ctx = QueryContext(topk=10)
+        assert ctx.topk == 10
+        assert ctx.queries == []
+        assert ctx.filter is None
+        assert ctx.reranker is None
+        assert ctx.output_fields is None
+        assert ctx.include_vector is False
+
+    def test_properties(self):
+        queries = [Query(field_name="test")]
+        reranker = RrfReRanker()
+        output_fields = ["field1", "field2"]
+
+        ctx = QueryContext(
+            topk=5,
+            filter="test_filter",
+            include_vector=True,
+            queries=queries,
+            output_fields=output_fields,
+            reranker=reranker,
+        )
+
+        assert ctx.topk == 5
+        assert ctx.queries == queries
+        assert ctx.filter == "test_filter"
+        assert ctx.reranker == reranker
+        assert ctx.output_fields == output_fields
+        assert ctx.include_vector is True
+
+    def test_properties_with_weighted_reranker(self):
+        queries = [Query(field_name="test")]
+        reranker = WeightedReRanker(
+            weights=[1.0],
+        )
+
+        ctx = QueryContext(
+            topk=5,
+            queries=queries,
+            reranker=reranker,
+        )
+
+        assert ctx.reranker == reranker
+        assert ctx.reranker.weights == [1.0]
+
+    def test_properties_with_callback_reranker(self):
+        queries = [Query(field_name="test")]
+        cb = lambda query_results, topn: []
+        reranker = CallbackReRanker(callback=cb)
+
+        ctx = QueryContext(
+            topk=5,
+            queries=queries,
+            reranker=reranker,
+        )
+
+        assert ctx.reranker == reranker
+
+
+class TestQueryExecutor:
+    def test_init(self):
+        schema = MockCollectionSchema()
+        executor = QueryExecutor(schema)
+        assert isinstance(executor, QueryExecutor)
+
+    def test_do_build_without_queries(self):
+        # When no queries are given, build a single vector-less query.
+        schema = MockCollectionSchema()
+        executor = QueryExecutor(schema)
+        ctx = QueryContext(topk=5, filter="test_filter")
+
+        result = executor._build_queries(ctx, MagicMock())
+        assert len(result) == 1
+        assert result[0].topk == 5
+        assert result[0].filter == "test_filter"
+
+    def test_do_build_query_wo_vector(self):
+        # Vector-less core query should carry the context query params.
+        schema = MockCollectionSchema()
+        executor = QueryExecutor(schema)
+        ctx = QueryContext(topk=7, filter="f", include_vector=True)
+
+        core_vector = executor._build_base_search_query(ctx)
+        assert core_vector.topk == 7
+        assert core_vector.filter == "f"
+        assert core_vector.include_vector is True
+
+    def test_do_merge_rerank_results_single_without_reranker(self):
+        # A single result list without a reranker is returned as-is.
+        schema = MockCollectionSchema()
+        executor = QueryExecutor(schema)
+        ctx = QueryContext(topk=5)
+        docs_list = [["doc1", "doc2"]]
+
+        result = executor._merge_and_rerank(ctx, docs_list)
+        assert result == ["doc1", "doc2"]
+
+    def test_do_merge_rerank_results_empty(self):
+        # Empty results should raise an error.
+        schema = MockCollectionSchema()
+        executor = QueryExecutor(schema)
+        ctx = QueryContext(topk=5)
+
+        with pytest.raises(ValueError, match="Query results is empty"):
+            executor._merge_and_rerank(ctx, [])
+
+    def test_do_merge_rerank_results_with_reranker(self):
+        # Multiple result lists are merged through the reranker.
+        schema = MockCollectionSchema()
+        executor = QueryExecutor(schema)
+        reranker = MagicMock()
+        reranker.rerank.return_value = ["merged"]
+        ctx = QueryContext(
+            topk=5,
+            queries=[Query(field_name="test1"), Query(field_name="test2")],
+            reranker=reranker,
+        )
+        docs_list = [["d1"], ["d2"]]
+
+        result = executor._merge_and_rerank(ctx, docs_list)
+        assert result == ["merged"]
+        reranker.rerank.assert_called_once_with(docs_list, ctx.topk)
+
+    def test_execute_python_pipeline(self):
+        # Each query is executed serially and converted into a result list.
+        schema = MockCollectionSchema()
+        executor = QueryExecutor(schema)
+        collection = MagicMock()
+        collection.Query.side_effect = [["raw1"], ["raw2"]]
+        vectors = [MagicMock(), MagicMock()]
+
+        with patch(
+            "zvec.executor.query_executor.convert_to_py_doc",
+            side_effect=lambda doc, schema: doc,
+        ):
+            results = executor._execute_python_pipeline(vectors, collection)
+        assert results == [["raw1"], ["raw2"]]
+        assert collection.Query.call_count == 2
+
+    def test_build_search_query_by_missing_id_raises_value_error(self):
+        vector_schema = VectorSchema(name="test", data_type=DataType.VECTOR_FP32)
+        schema = CollectionSchema(name="test_collection", vectors=[vector_schema])
+        executor = QueryExecutor(schema)
+        ctx = QueryContext(topk=5)
+        collection = MagicMock()
+        collection.Fetch.return_value = {}
+
+        with pytest.raises(ValueError, match="Document with id 'missing' not found"):
+            executor._build_search_query(
+                ctx, Query(field_name="test", id="missing"), collection
+            )
+
+    def test_build_search_query_validates_query(self):
+        vector_schema = VectorSchema(name="test", data_type=DataType.VECTOR_FP32)
+        schema = CollectionSchema(name="test_collection", vectors=[vector_schema])
+        executor = QueryExecutor(schema)
+        ctx = QueryContext(topk=5)
+        collection = MagicMock()
+
+        with pytest.raises(ValueError, match="Cannot provide both id and vector"):
+            executor._build_search_query(
+                ctx,
+                Query(field_name="test", id="doc1", vector=np.array([0.1])),
+                collection,
+            )

python/tests/test_reranker.py

@@ -0,0 +1,948 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from unittest.mock import patch, MagicMock
+import pytest
+import os
+
+from zvec import Doc, MetricType, VectorSchema, DataType, FlatIndexParam
+from zvec.extension.multi_vector_reranker import (
+    CallbackReRanker,
+    RrfReRanker,
+    WeightedReRanker,
+)
+from zvec.extension.sentence_transformer_rerank_function import (
+    DefaultLocalReRanker,
+)
+from zvec.extension.qwen_rerank_function import QwenReRanker
+
+# Set ZVEC_RUN_INTEGRATION_TESTS=1 to run real API tests
+RUN_INTEGRATION_TESTS = os.environ.get("ZVEC_RUN_INTEGRATION_TESTS", "0") == "1"
+
+
+# ----------------------------
+# RrfReRanker Test Case
+# ----------------------------
+class TestRrfReRanker:
+    def test_init(self):
+        reranker = RrfReRanker(rank_constant=100)
+        assert reranker.rank_constant == 100
+
+    def test_default_rank_constant(self):
+        reranker = RrfReRanker()
+        assert reranker.rank_constant == 60
+
+    def test_rerank(self):
+        reranker = RrfReRanker(rank_constant=60)
+
+        doc1 = Doc(id="1", score=0.8)
+        doc2 = Doc(id="2", score=0.7)
+        doc3 = Doc(id="3", score=0.9)
+        doc4 = Doc(id="4", score=0.6)
+
+        query_results = [[doc1, doc2, doc3], [doc3, doc1, doc4]]
+
+        results = reranker.rerank(query_results, topn=3)
+
+        assert len(results) <= 3
+
+        for doc in results:
+            assert hasattr(doc, "score")
+
+        scores = [doc.score for doc in results]
+        assert scores == sorted(scores, reverse=True)
+
+
+# ----------------------------
+# WeightedReRanker Test Case
+# ----------------------------
+class TestWeightedReRanker:
+    @staticmethod
+    def _make_fields(metrics):
+        return [
+            VectorSchema(
+                name=f"vector{i}",
+                data_type=DataType.VECTOR_FP32,
+                dimension=4,
+                index_param=FlatIndexParam(metric_type=metric),
+            )
+            for i, metric in enumerate(metrics)
+        ]
+
+    def test_init(self):
+        reranker = WeightedReRanker([0.7, 0.3])
+        assert reranker.weights == [0.7, 0.3]
+
+    def test_rerank(self):
+        reranker = WeightedReRanker([0.7, 0.3])
+
+        doc1 = Doc(id="1", score=0.8)
+        doc2 = Doc(id="2", score=0.7)
+        doc3 = Doc(id="3", score=0.9)
+
+        query_results = [[doc1, doc2], [doc2, doc3]]
+        fields = self._make_fields([MetricType.L2, MetricType.L2])
+
+        results = reranker.rerank(query_results, topn=3, fields=fields)
+
+        assert len(results) <= 3
+
+        for doc in results:
+            assert hasattr(doc, "score")
+
+
+# ----------------------------
+# CallbackReRanker Test Case
+# ----------------------------
+class TestCallbackReRanker:
+    def test_rerank(self):
+        def my_callback(query_results, fields, topn):
+            all_docs = []
+            for docs in query_results:
+                all_docs.extend(docs)
+            all_docs.sort(key=lambda d: d.score, reverse=True)
+            return all_docs[:topn]
+
+        reranker = CallbackReRanker(my_callback)
+
+        doc1 = Doc(id="1", score=0.8)
+        doc2 = Doc(id="2", score=0.9)
+        doc3 = Doc(id="3", score=0.7)
+        doc4 = Doc(id="4", score=0.6)
+
+        query_results = [[doc1, doc2], [doc3, doc4]]
+
+        results = reranker.rerank(query_results, topn=3)
+
+        assert len(results) == 3
+        scores = [doc.score for doc in results]
+        assert scores == sorted(scores, reverse=True)
+
+    def test_callback_with_topn(self):
+        received_topn = []
+
+        def my_callback(query_results, fields, topn):
+            received_topn.append(topn)
+            return []
+
+        reranker = CallbackReRanker(my_callback)
+        reranker.rerank([[Doc(id="1", score=0.5)]], topn=7)
+
+        assert received_topn == [7]
+
+
+# ----------------------------
+# QwenReRanker Test Case
+# ----------------------------
+class TestQwenReRanker:
+    def test_init_without_query(self):
+        with pytest.raises(ValueError, match="Query is required for QwenReRanker"):
+            QwenReRanker(api_key="test_key")
+
+    def test_init_without_api_key(self):
+        with patch.dict(os.environ, {}, clear=True):
+            with pytest.raises(ValueError, match="DashScope API key is required"):
+                QwenReRanker(query="test")
+
+    @patch.dict(os.environ, {"DASHSCOPE_API_KEY": "test_key"})
+    def test_init_with_env_api_key(self):
+        reranker = QwenReRanker(query="test", rerank_field="content")
+        assert reranker.query == "test"
+        assert reranker._api_key == "test_key"
+        assert reranker.rerank_field == "content"
+
+    def test_init_with_explicit_api_key(self):
+        reranker = QwenReRanker(
+            query="test", api_key="explicit_key", rerank_field="content"
+        )
+        assert reranker.query == "test"
+        assert reranker._api_key == "explicit_key"
+
+    def test_model_property(self):
+        reranker = QwenReRanker(
+            query="test", api_key="test_key", rerank_field="content"
+        )
+        assert reranker.model == "gte-rerank-v2"
+
+        reranker = QwenReRanker(
+            query="test",
+            model="custom-model",
+            api_key="test_key",
+            rerank_field="content",
+        )
+        assert reranker.model == "custom-model"
+
+    def test_query_property(self):
+        reranker = QwenReRanker(
+            query="test query", api_key="test_key", rerank_field="content"
+        )
+        assert reranker.query == "test query"
+
+    def test_rerank_field_property(self):
+        reranker = QwenReRanker(query="test", api_key="test_key", rerank_field="title")
+        assert reranker.rerank_field == "title"
+
+    def test_rerank_empty_results(self):
+        reranker = QwenReRanker(
+            query="test", api_key="test_key", rerank_field="content"
+        )
+        results = reranker.rerank({})
+        assert results == []
+
+    def test_rerank_no_valid_documents(self):
+        reranker = QwenReRanker(
+            query="test", api_key="test_key", rerank_field="content"
+        )
+        # Document without the rerank_field
+        query_results = {"vector1": [Doc(id="1")]}
+        with pytest.raises(ValueError, match="No documents to rerank"):
+            reranker.rerank(query_results)
+
+    def test_rerank_skip_empty_content(self):
+        reranker = QwenReRanker(
+            query="test", api_key="test_key", rerank_field="content"
+        )
+        query_results = {
+            "vector1": [
+                Doc(id="1", fields={"content": ""}),
+                Doc(id="2", fields={"content": "   "}),
+            ]
+        }
+        with pytest.raises(ValueError, match="No documents to rerank"):
+            reranker.rerank(query_results)
+
+    @patch("zvec.extension.qwen_function.require_module")
+    def test_rerank_success(self, mock_require_module):
+        # Mock dashscope module
+        mock_dashscope = MagicMock()
+        mock_require_module.return_value = mock_dashscope
+
+        # Mock API response
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.output = {
+            "results": [
+                {"index": 0, "relevance_score": 0.95},
+                {"index": 1, "relevance_score": 0.85},
+            ]
+        }
+        mock_dashscope.TextReRank.call.return_value = mock_response
+
+        reranker = QwenReRanker(
+            query="test query", api_key="test_key", rerank_field="content"
+        )
+
+        query_results = {
+            "vector1": [
+                Doc(id="1", fields={"content": "Document 1"}),
+                Doc(id="2", fields={"content": "Document 2"}),
+            ]
+        }
+
+        results = reranker.rerank(query_results, topn=2)
+
+        assert len(results) == 2
+        assert results[0].id == "1"
+        assert results[0].score == 0.95
+        assert results[1].id == "2"
+        assert results[1].score == 0.85
+
+        # Verify API call
+        mock_dashscope.TextReRank.call.assert_called_once_with(
+            model="gte-rerank-v2",
+            query="test query",
+            documents=["Document 1", "Document 2"],
+            top_n=2,
+            return_documents=False,
+        )
+
+    @patch("zvec.extension.qwen_function.require_module")
+    def test_rerank_deduplicate_documents(self, mock_require_module):
+        # Mock dashscope module
+        mock_dashscope = MagicMock()
+        mock_require_module.return_value = mock_dashscope
+
+        # Mock API response
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.output = {
+            "results": [
+                {"index": 0, "relevance_score": 0.9},
+            ]
+        }
+        mock_dashscope.TextReRank.call.return_value = mock_response
+
+        reranker = QwenReRanker(
+            query="test", api_key="test_key", rerank_field="content"
+        )
+
+        # Same document in multiple vector results
+        doc1 = Doc(id="1", fields={"content": "Document 1"})
+        query_results = {"vector1": [doc1], "vector2": [doc1]}
+
+        results = reranker.rerank(query_results, topn=5)
+
+        # Should only call API with document once
+        call_args = mock_dashscope.TextReRank.call.call_args
+        assert len(call_args[1]["documents"]) == 1
+
+    @patch("zvec.extension.qwen_function.require_module")
+    def test_rerank_api_error(self, mock_require_module):
+        # Mock dashscope module
+        mock_dashscope = MagicMock()
+        mock_require_module.return_value = mock_dashscope
+
+        # Mock API error response
+        mock_response = MagicMock()
+        mock_response.status_code = 400
+        mock_response.message = "Invalid request"
+        mock_response.code = "InvalidParameter"
+        mock_dashscope.TextReRank.call.return_value = mock_response
+
+        reranker = QwenReRanker(
+            query="test", api_key="test_key", rerank_field="content"
+        )
+
+        query_results = {"vector1": [Doc(id="1", fields={"content": "Document 1"})]}
+
+        with pytest.raises(ValueError, match="DashScope API error"):
+            reranker.rerank(query_results)
+
+    @patch("zvec.extension.qwen_function.require_module")
+    def test_rerank_runtime_error(self, mock_require_module):
+        # Mock dashscope module that raises exception
+        mock_dashscope = MagicMock()
+        mock_require_module.return_value = mock_dashscope
+        mock_dashscope.TextReRank.call.side_effect = Exception("Network error")
+
+        reranker = QwenReRanker(
+            query="test", api_key="test_key", rerank_field="content"
+        )
+
+        query_results = {"vector1": [Doc(id="1", fields={"content": "Document 1"})]}
+
+        with pytest.raises(RuntimeError, match="Failed to call DashScope API"):
+            reranker.rerank(query_results)
+
+    @pytest.mark.skipif(
+        not RUN_INTEGRATION_TESTS,
+        reason="Integration test skipped. Set ZVEC_RUN_INTEGRATION_TESTS=1 to run.",
+    )
+    def test_real_qwen_rerank(self):
+        """Integration test with real DashScope TextReRank API.
+
+        To run this test, set environment variables:
+            export ZVEC_RUN_INTEGRATION_TESTS=1
+            export DASHSCOPE_API_KEY=your-api-key
+        """
+        # Create reranker with real API
+        reranker = QwenReRanker(
+            query="What is machine learning?",
+            rerank_field="content",
+            model="gte-rerank-v2",
+        )
+
+        # Prepare test documents
+        query_results = {
+            "vector1": [
+                Doc(
+                    id="1",
+                    score=0.8,
+                    fields={
+                        "content": "Machine learning is a subset of artificial intelligence that focuses on building systems that can learn from data."
+                    },
+                ),
+                Doc(
+                    id="2",
+                    score=0.7,
+                    fields={
+                        "content": "The weather is nice today with clear skies and sunshine."
+                    },
+                ),
+                Doc(
+                    id="3",
+                    score=0.75,
+                    fields={
+                        "content": "Deep learning is a specialized branch of machine learning using neural networks with multiple layers."
+                    },
+                ),
+            ],
+            "vector2": [
+                Doc(
+                    id="4",
+                    score=0.6,
+                    fields={
+                        "content": "Python is a popular programming language for data science and machine learning applications."
+                    },
+                ),
+                Doc(
+                    id="5",
+                    score=0.65,
+                    fields={
+                        "content": "A recipe for chocolate cake includes flour, sugar, eggs, and cocoa powder."
+                    },
+                ),
+            ],
+        }
+
+        # Call real API
+        results = reranker.rerank(query_results, topn=3)
+
+        # Verify results
+        assert len(results) <= 3, "Should return at most topn documents"
+        assert len(results) > 0, "Should return at least one document"
+
+        # All results should have valid scores
+        for doc in results:
+            assert hasattr(doc, "score"), "Each document should have a score"
+            assert isinstance(doc.score, (int, float)), "Score should be numeric"
+            assert doc.score > 0, "Score should be positive"
+
+        # Verify scores are in descending order
+        scores = [doc.score for doc in results]
+        assert scores == sorted(scores, reverse=True), (
+            "Results should be sorted by score in descending order"
+        )
+
+        # Verify relevant documents are ranked higher
+        # Document 1 and 3 are about machine learning, should rank higher than weather/recipe docs
+        result_ids = [doc.id for doc in results]
+
+        # At least one of the ML-related documents should be in top results
+        ml_related_docs = {"1", "3", "4"}
+        assert any(doc_id in ml_related_docs for doc_id in result_ids[:2]), (
+            "ML-related documents should rank higher"
+        )
+
+        # Print results for manual verification (useful during development)
+        print("\nReranking results:")
+        for i, doc in enumerate(results, 1):
+            print(f"{i}. ID={doc.id}, Score={doc.score:.4f}")
+            if doc.fields:
+                content = doc.field("content")
+                if content:
+                    print(f"   Content: {content[:80]}...")
+
+
+# ----------------------------
+# DefaultLocalReRanker Test Case
+# ----------------------------
+class TestDefaultLocalReRanker:
+    """Test cases for DefaultLocalReRanker."""
+
+    def test_init_without_query(self):
+        """Test initialization fails without query."""
+        with pytest.raises(
+            ValueError, match="Query is required for DefaultLocalReRanker"
+        ):
+            DefaultLocalReRanker(rerank_field="content")
+
+    def test_init_with_empty_query(self):
+        """Test initialization fails with empty query."""
+        with pytest.raises(
+            ValueError, match="Query is required for DefaultLocalReRanker"
+        ):
+            DefaultLocalReRanker(query="", rerank_field="content")
+
+    @patch("zvec.extension.sentence_transformer_rerank_function.require_module")
+    def test_init_success(self, mock_require_module):
+        """Test successful initialization with mocked model."""
+        # Mock sentence_transformers module
+        mock_st = MagicMock()
+        mock_model = MagicMock()
+        mock_model.predict = MagicMock()  # Cross-encoder has predict method
+        mock_model.device = "cpu"
+        mock_st.CrossEncoder.return_value = mock_model
+        mock_require_module.return_value = mock_st
+
+        reranker = DefaultLocalReRanker(
+            query="test query",
+            rerank_field="content",
+            model_name="cross-encoder/ms-marco-MiniLM-L6-v2",
+        )
+
+        assert reranker.query == "test query"
+        assert reranker.rerank_field == "content"
+        assert reranker.model_name == "cross-encoder/ms-marco-MiniLM-L6-v2"
+        assert reranker.model_source == "huggingface"
+        assert reranker.batch_size == 32
+
+    @pytest.mark.skipif(
+        not RUN_INTEGRATION_TESTS,
+        reason="Integration test skipped. Set ZVEC_RUN_INTEGRATION_TESTS=1 to run.",
+    )
+    @patch("zvec.extension.sentence_transformer_rerank_function.require_module")
+    def test_init_with_custom_params(self, mock_require_module):
+        """Test initialization with custom parameters."""
+        mock_st = MagicMock()
+        mock_model = MagicMock()
+        mock_model.predict = MagicMock()
+        mock_model.device = "cuda"
+        mock_st.CrossEncoder.return_value = mock_model
+        mock_require_module.return_value = mock_st
+
+        reranker = DefaultLocalReRanker(
+            query="custom query",
+            rerank_field="title",
+            model_name="cross-encoder/ms-marco-MiniLM-L12-v2",
+            model_source="modelscope",
+            device="cuda",
+            batch_size=64,
+        )
+
+        assert reranker.query == "custom query"
+        assert reranker.rerank_field == "title"
+        assert reranker.model_name == "cross-encoder/ms-marco-MiniLM-L12-v2"
+        assert reranker.model_source == "modelscope"
+        assert reranker.batch_size == 64
+
+    @patch("zvec.extension.sentence_transformer_rerank_function.require_module")
+    def test_init_invalid_model(self, mock_require_module):
+        """Test initialization fails with non-cross-encoder model."""
+        # Mock a model without predict method (not a cross-encoder)
+        mock_st = MagicMock()
+        mock_model = MagicMock(spec=[])  # No predict method
+        mock_st.CrossEncoder.return_value = mock_model
+        mock_require_module.return_value = mock_st
+
+        with pytest.raises(ValueError, match="does not appear to be a cross-encoder"):
+            DefaultLocalReRanker(query="test", rerank_field="content")
+
+    def test_query_property(self):
+        """Test query property."""
+        mock_model = MagicMock()
+        mock_model.predict = MagicMock()
+
+        mock_st = MagicMock()
+        mock_st.CrossEncoder.return_value = mock_model
+
+        with patch(
+            "zvec.extension.sentence_transformer_rerank_function.require_module",
+            return_value=mock_st,
+        ):
+            reranker = DefaultLocalReRanker(query="test query", rerank_field="content")
+            assert reranker.query == "test query"
+
+    def test_rerank_field_property(self):
+        """Test rerank_field property."""
+        mock_model = MagicMock()
+        mock_model.predict = MagicMock()
+
+        mock_st = MagicMock()
+        mock_st.CrossEncoder.return_value = mock_model
+
+        with patch(
+            "zvec.extension.sentence_transformer_rerank_function.require_module",
+            return_value=mock_st,
+        ):
+            reranker = DefaultLocalReRanker(query="test", rerank_field="title")
+            assert reranker.rerank_field == "title"
+
+    def test_batch_size_property(self):
+        """Test batch_size property."""
+        mock_model = MagicMock()
+        mock_model.predict = MagicMock()
+
+        mock_st = MagicMock()
+        mock_st.CrossEncoder.return_value = mock_model
+
+        with patch(
+            "zvec.extension.sentence_transformer_rerank_function.require_module",
+            return_value=mock_st,
+        ):
+            reranker = DefaultLocalReRanker(
+                query="test", rerank_field="content", batch_size=128
+            )
+            assert reranker.batch_size == 128
+
+    def test_rerank_empty_results(self):
+        """Test rerank with empty query_results."""
+        mock_model = MagicMock()
+        mock_model.predict = MagicMock()
+
+        mock_st = MagicMock()
+        mock_st.CrossEncoder.return_value = mock_model
+
+        with patch(
+            "zvec.extension.sentence_transformer_rerank_function.require_module",
+            return_value=mock_st,
+        ):
+            reranker = DefaultLocalReRanker(query="test", rerank_field="content")
+            results = reranker.rerank({})
+            assert results == []
+
+    def test_rerank_no_valid_documents(self):
+        """Test rerank with documents missing rerank_field."""
+        mock_model = MagicMock()
+        mock_model.predict = MagicMock()
+
+        mock_st = MagicMock()
+        mock_st.CrossEncoder.return_value = mock_model
+
+        with patch(
+            "zvec.extension.sentence_transformer_rerank_function.require_module",
+            return_value=mock_st,
+        ):
+            reranker = DefaultLocalReRanker(query="test", rerank_field="content")
+
+            # Document without the rerank_field
+            query_results = {"vector1": [Doc(id="1")]}
+            with pytest.raises(ValueError, match="No documents to rerank"):
+                reranker.rerank(query_results)
+
+    def test_rerank_skip_empty_content(self):
+        """Test rerank skips documents with empty content."""
+        mock_model = MagicMock()
+        mock_model.predict = MagicMock()
+
+        mock_st = MagicMock()
+        mock_st.CrossEncoder.return_value = mock_model
+
+        with patch(
+            "zvec.extension.sentence_transformer_rerank_function.require_module",
+            return_value=mock_st,
+        ):
+            reranker = DefaultLocalReRanker(query="test", rerank_field="content")
+
+            query_results = {
+                "vector1": [
+                    Doc(id="1", fields={"content": ""}),
+                    Doc(id="2", fields={"content": "   "}),
+                ]
+            }
+            with pytest.raises(ValueError, match="No documents to rerank"):
+                reranker.rerank(query_results)
+
+    def test_rerank_success(self):
+        """Test successful rerank with mocked model."""
+        # Mock standard cross-encoder model
+        mock_model = MagicMock()
+
+        # Mock predict method to return scores
+        import numpy as np
+
+        mock_scores = np.array([0.95, 0.85, 0.75])
+        mock_model.predict.return_value = mock_scores
+        mock_model.device = "cpu"
+
+        # Mock sentence_transformers module
+        mock_st = MagicMock()
+        mock_st.CrossEncoder.return_value = mock_model
+
+        with patch(
+            "zvec.extension.sentence_transformer_rerank_function.require_module",
+            return_value=mock_st,
+        ):
+            reranker = DefaultLocalReRanker(query="test query", rerank_field="content")
+
+            query_results = {
+                "vector1": [
+                    Doc(id="1", score=0.8, fields={"content": "Document 1"}),
+                    Doc(id="2", score=0.7, fields={"content": "Document 2"}),
+                    Doc(id="3", score=0.6, fields={"content": "Document 3"}),
+                ]
+            }
+
+            results = reranker.rerank(query_results, topn=3)
+
+            # Verify results
+            assert len(results) == 3
+            assert results[0].id == "1"
+            assert results[0].score == 0.95
+            assert results[1].id == "2"
+            assert results[1].score == 0.85
+            assert results[2].id == "3"
+            assert results[2].score == 0.75
+
+            # Verify model.predict was called correctly
+            assert mock_model.predict.called
+            call_args = mock_model.predict.call_args
+            pairs = call_args[0][0]
+            assert len(pairs) == 3
+            assert pairs[0] == ["test query", "Document 1"]
+            assert pairs[1] == ["test query", "Document 2"]
+            assert pairs[2] == ["test query", "Document 3"]
+            assert call_args[1]["batch_size"] == 32
+            assert call_args[1]["show_progress_bar"] is False
+
+    def test_rerank_with_topn_limit(self):
+        """Test rerank respects topn limit."""
+        mock_model = MagicMock()
+
+        import numpy as np
+
+        mock_scores = np.array([0.9, 0.8, 0.7, 0.6, 0.5])
+        mock_model.predict.return_value = mock_scores
+
+        # Mock sentence_transformers module
+        mock_st = MagicMock()
+        mock_st.CrossEncoder.return_value = mock_model
+
+        with patch(
+            "zvec.extension.sentence_transformer_rerank_function.require_module",
+            return_value=mock_st,
+        ):
+            reranker = DefaultLocalReRanker(query="test", rerank_field="content")
+
+            query_results = {
+                "vector1": [
+                    Doc(id="1", fields={"content": "Doc 1"}),
+                    Doc(id="2", fields={"content": "Doc 2"}),
+                    Doc(id="3", fields={"content": "Doc 3"}),
+                    Doc(id="4", fields={"content": "Doc 4"}),
+                    Doc(id="5", fields={"content": "Doc 5"}),
+                ]
+            }
+
+            results = reranker.rerank(query_results, topn=2)
+
+            # Should only return top 2
+            assert len(results) == 2
+            assert results[0].id == "1"
+            assert results[0].score == 0.9
+            assert results[1].id == "2"
+            assert results[1].score == 0.8
+
+    def test_rerank_deduplicate_documents(self):
+        """Test rerank deduplicates documents across multiple vectors."""
+        mock_model = MagicMock()
+
+        import numpy as np
+
+        mock_scores = np.array([0.95, 0.85])
+        mock_model.predict.return_value = mock_scores
+
+        # Mock sentence_transformers module
+        mock_st = MagicMock()
+        mock_st.CrossEncoder.return_value = mock_model
+
+        with patch(
+            "zvec.extension.sentence_transformer_rerank_function.require_module",
+            return_value=mock_st,
+        ):
+            reranker = DefaultLocalReRanker(query="test", rerank_field="content")
+
+            # Same document in multiple vector results
+            doc1 = Doc(id="1", fields={"content": "Document 1"})
+            doc2 = Doc(id="2", fields={"content": "Document 2"})
+
+            query_results = {
+                "vector1": [doc1, doc2],
+                "vector2": [doc1],  # doc1 appears in both
+            }
+
+            results = reranker.rerank(query_results, topn=5)
+
+            # Should only process each document once
+            assert len(results) == 2
+            assert mock_model.predict.call_count == 1
+
+            call_args = mock_model.predict.call_args
+            pairs = call_args[0][0]
+            assert len(pairs) == 2  # Only 2 unique documents
+
+    def test_rerank_sorting(self):
+        """Test rerank sorts documents by score in descending order."""
+        mock_model = MagicMock()
+
+        import numpy as np
+
+        # Return scores in non-sorted order
+        mock_scores = np.array([0.6, 0.9, 0.7])
+        mock_model.predict.return_value = mock_scores
+
+        # Mock sentence_transformers module
+        mock_st = MagicMock()
+        mock_st.CrossEncoder.return_value = mock_model
+
+        with patch(
+            "zvec.extension.sentence_transformer_rerank_function.require_module",
+            return_value=mock_st,
+        ):
+            reranker = DefaultLocalReRanker(query="test", rerank_field="content")
+
+            query_results = {
+                "vector1": [
+                    Doc(id="1", fields={"content": "Doc 1"}),
+                    Doc(id="2", fields={"content": "Doc 2"}),
+                    Doc(id="3", fields={"content": "Doc 3"}),
+                ]
+            }
+
+            results = reranker.rerank(query_results, topn=3)
+
+            # Should be sorted by score (descending)
+            assert len(results) == 3
+            assert results[0].id == "2"  # score 0.9
+            assert results[0].score == 0.9
+            assert results[1].id == "3"  # score 0.7
+            assert results[1].score == 0.7
+            assert results[2].id == "1"  # score 0.6
+            assert results[2].score == 0.6
+
+    def test_rerank_model_error(self):
+        """Test rerank handles model prediction errors."""
+        mock_model = MagicMock()
+
+        # Mock predict to raise exception
+        mock_model.predict.side_effect = Exception("Model inference error")
+
+        # Mock sentence_transformers module
+        mock_st = MagicMock()
+        mock_st.CrossEncoder.return_value = mock_model
+
+        with patch(
+            "zvec.extension.sentence_transformer_rerank_function.require_module",
+            return_value=mock_st,
+        ):
+            reranker = DefaultLocalReRanker(query="test", rerank_field="content")
+
+            query_results = {"vector1": [Doc(id="1", fields={"content": "Document 1"})]}
+
+            with pytest.raises(RuntimeError, match="Failed to compute rerank scores"):
+                reranker.rerank(query_results)
+
+    def test_rerank_with_custom_batch_size(self):
+        """Test rerank uses custom batch_size."""
+        mock_model = MagicMock()
+
+        import numpy as np
+
+        mock_scores = np.array([0.9, 0.8])
+        mock_model.predict.return_value = mock_scores
+
+        # Mock sentence_transformers module
+        mock_st = MagicMock()
+        mock_st.CrossEncoder.return_value = mock_model
+
+        with patch(
+            "zvec.extension.sentence_transformer_rerank_function.require_module",
+            return_value=mock_st,
+        ):
+            reranker = DefaultLocalReRanker(
+                query="test", rerank_field="content", batch_size=64
+            )
+
+            query_results = {
+                "vector1": [
+                    Doc(id="1", fields={"content": "Doc 1"}),
+                    Doc(id="2", fields={"content": "Doc 2"}),
+                ]
+            }
+
+            reranker.rerank(query_results)
+
+            # Verify batch_size is passed to predict
+            call_args = mock_model.predict.call_args
+            assert call_args[1]["batch_size"] == 64
+
+    @pytest.mark.skipif(
+        not RUN_INTEGRATION_TESTS,
+        reason="Integration test skipped. Set ZVEC_RUN_INTEGRATION_TESTS=1 to run.",
+    )
+    def test_real_sentence_transformer_rerank(self):
+        """Integration test with real SentenceTransformer cross-encoder model.
+
+        To run this test, set environment variable:
+            export ZVEC_RUN_INTEGRATION_TESTS=1
+
+        Note: This test requires sentence-transformers package and will
+        download the MS MARCO MiniLM model (~80MB) on first run.
+        """
+        # Create reranker with real model (using default lightweight model)
+        reranker = DefaultLocalReRanker(
+            query="What is machine learning?",
+            rerank_field="content",
+        )
+
+        # Prepare test documents
+        query_results = {
+            "vector1": [
+                Doc(
+                    id="1",
+                    score=0.8,
+                    fields={
+                        "content": "Machine learning is a subset of artificial intelligence that focuses on building systems that can learn from data."
+                    },
+                ),
+                Doc(
+                    id="2",
+                    score=0.7,
+                    fields={
+                        "content": "The weather is nice today with clear skies and sunshine."
+                    },
+                ),
+                Doc(
+                    id="3",
+                    score=0.75,
+                    fields={
+                        "content": "Deep learning is a specialized branch of machine learning using neural networks with multiple layers."
+                    },
+                ),
+            ],
+            "vector2": [
+                Doc(
+                    id="4",
+                    score=0.6,
+                    fields={
+                        "content": "Python is a popular programming language for data science and machine learning applications."
+                    },
+                ),
+                Doc(
+                    id="5",
+                    score=0.65,
+                    fields={
+                        "content": "A recipe for chocolate cake includes flour, sugar, eggs, and cocoa powder."
+                    },
+                ),
+            ],
+        }
+
+        # Call real model
+        results = reranker.rerank(query_results, topn=3)
+
+        # Verify results
+        assert len(results) <= 3, "Should return at most topn documents"
+        assert len(results) > 0, "Should return at least one document"
+
+        # All results should have valid scores
+        for doc in results:
+            assert hasattr(doc, "score"), "Each document should have a score"
+            assert isinstance(doc.score, (int, float)), "Score should be numeric"
+
+        # Verify scores are in descending order
+        scores = [doc.score for doc in results]
+        assert scores == sorted(scores, reverse=True), (
+            "Results should be sorted by score in descending order"
+        )
+
+        # Verify relevant documents are ranked higher
+        # Documents 1, 3, and 4 are about machine learning, should rank higher
+        result_ids = [doc.id for doc in results]
+
+        # At least one of the ML-related documents should be in top results
+        ml_related_docs = {"1", "3", "4"}
+        assert any(doc_id in ml_related_docs for doc_id in result_ids[:2]), (
+            "ML-related documents should rank higher"
+        )
+
+        # Print results for manual verification (useful during development)
+        print("\nSentenceTransformer Reranking results:")
+        for i, doc in enumerate(results, 1):
+            print(f"{i}. ID={doc.id}, Score={doc.score:.4f}")
+            if doc.fields:
+                content = doc.field("content")
+                if content:
+                    print(f"   Content: {content[:80]}...")

python/tests/test_schema.py

@@ -0,0 +1,246 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+import pytest
+from zvec import (
+    CollectionSchema,
+    CollectionStats,
+    FieldSchema,
+    VectorSchema,
+    HnswIndexParam,
+    InvertIndexParam,
+    DataType,
+    IndexType,
+    MetricType,
+)
+
+# ----------------------------
+# FieldSchema Test Case
+# ----------------------------
+
+
+class TestFieldSchema:
+    def test_default(self):
+        field = FieldSchema("field", data_type=DataType.FLOAT)
+        assert field.name == "field"
+        assert field.data_type == DataType.FLOAT
+        assert field.nullable is False
+        assert field.index_param is None
+
+    def test_custom(self):
+        field_1 = FieldSchema(
+            name="float",
+            data_type=DataType.FLOAT,
+            nullable=True,
+            index_param=InvertIndexParam(),
+        )
+        assert field_1.name == "float"
+        assert field_1.data_type == DataType.FLOAT
+        assert field_1.nullable is True
+        assert field_1.index_param.enable_range_optimization is False
+
+        field_2 = FieldSchema(
+            name="str",
+            data_type=DataType.STRING,
+            nullable=True,
+            index_param=InvertIndexParam(enable_range_optimization=True),
+        )
+        assert field_2.name == "str"
+        assert field_2.data_type == DataType.STRING
+        assert field_2.nullable is True
+        assert field_2.index_param.enable_range_optimization is True
+
+    def test_readonly(self):
+        field = FieldSchema(
+            name="float",
+            data_type=DataType.FLOAT,
+            nullable=True,
+            index_param=InvertIndexParam(),
+        )
+
+        import sys
+
+        if sys.version_info >= (3, 11):
+            match_pattern = r"(can't set attribute|has no setter|readonly attribute)"
+        else:
+            match_pattern = r"can't set attribute"
+        with pytest.raises(AttributeError, match=match_pattern):
+            field.index_param = InvertIndexParam(enable_range_optimization=True)
+
+
+# ----------------------------
+# VectorSchema Test Case
+# ----------------------------
+class TestVectorSchema:
+    def test_default(self):
+        field = VectorSchema("vector", data_type=DataType.VECTOR_FP32, dimension=128)
+        assert field.name == "vector"
+        assert field.data_type == DataType.VECTOR_FP32
+        assert field.dimension == 128
+        assert field.index_param is not None
+        assert field.index_param.type == IndexType.FLAT
+        assert field.index_param.metric_type == MetricType.IP
+
+    def test_custom(self):
+        field = VectorSchema(
+            name="vector",
+            data_type=DataType.VECTOR_INT8,
+            dimension=512,
+            index_param=HnswIndexParam(
+                metric_type=MetricType.COSINE, m=15, ef_construction=300
+            ),
+        )
+        assert field.name == "vector"
+        assert field.data_type == DataType.VECTOR_INT8
+        assert field.index_param.metric_type == MetricType.COSINE
+        assert field.index_param.m == 15
+        assert field.index_param.ef_construction == 300
+
+    def test_readonly(self):
+        field = VectorSchema(
+            name="vector",
+            dimension=128,
+            data_type=DataType.VECTOR_INT8,
+        )
+
+        import sys
+
+        if sys.version_info >= (3, 11):
+            match_pattern = r"(can't set attribute|has no setter|readonly attribute)"
+        else:
+            match_pattern = r"can't set attribute"
+        with pytest.raises(AttributeError, match=match_pattern):
+            field.dimension = 4
+
+
+# ----------------------------
+# CollectionSchema Test Case
+# ----------------------------
+class TestCollectionSchema:
+    def test_collection_schema_with_single_field(self):
+        collection_schema = CollectionSchema(
+            name="test_collection",
+            fields=FieldSchema(
+                name="id",
+                data_type=DataType.INT64,
+                index_param=InvertIndexParam(),
+                nullable=False,
+            ),
+            vectors=VectorSchema(
+                name="vector",
+                data_type=DataType.VECTOR_INT8,
+                dimension=128,
+                index_param=HnswIndexParam(),
+            ),
+        )
+
+        assert collection_schema is not None
+        assert collection_schema.name == "test_collection"
+        assert len(collection_schema.fields) == 1
+        assert len(collection_schema.vectors) == 1
+
+        field = collection_schema.field("id")
+        assert field is not None
+        assert field.name == "id"
+        assert field.data_type == DataType.INT64
+        assert not field.nullable
+        assert field.index_param.type == IndexType.INVERT
+        assert not field.index_param.enable_range_optimization
+
+        vector = collection_schema.vector("vector")
+        assert vector is not None
+        assert vector.name == "vector"
+        assert vector.data_type == DataType.VECTOR_INT8
+        assert vector.dimension == 128
+        assert vector.index_param.type == IndexType.HNSW
+        assert vector.index_param.m == 50
+        assert vector.index_param.ef_construction == 500
+        assert vector.index_param.metric_type == MetricType.IP
+
+    def test_collection_schema_with_multi_fields(self):
+        collection_schema = CollectionSchema(
+            name="test_collection",
+            fields=[
+                FieldSchema(
+                    "id",
+                    DataType.INT64,
+                    nullable=False,
+                    index_param=InvertIndexParam(enable_range_optimization=True),
+                ),
+                FieldSchema(
+                    "name",
+                    DataType.STRING,
+                    nullable=False,
+                    index_param=InvertIndexParam(),
+                ),
+                FieldSchema(
+                    "weight",
+                    DataType.INT32,
+                    nullable=True,
+                ),
+            ],
+            vectors=[
+                VectorSchema(
+                    "dense",
+                    DataType.VECTOR_FP32,
+                    dimension=128,
+                    index_param=HnswIndexParam(),
+                ),
+                VectorSchema(
+                    "sparse", DataType.SPARSE_VECTOR_FP32, index_param=HnswIndexParam()
+                ),
+            ],
+        )
+        assert collection_schema is not None
+        assert collection_schema.name == "test_collection"
+        assert len(collection_schema.fields) == 3
+        assert len(collection_schema.vectors) == 2
+
+        field_id = collection_schema.field("id")
+        assert field_id is not None
+        assert field_id.name == "id"
+        assert field_id.data_type == DataType.INT64
+        assert not field_id.nullable
+        assert field_id.index_param.type == IndexType.INVERT
+
+        dense = collection_schema.vector("dense")
+        assert dense is not None
+        assert dense.name == "dense"
+        assert dense.data_type == DataType.VECTOR_FP32
+        assert dense.dimension == 128
+        assert dense.index_param.type == IndexType.HNSW
+
+        sparse = collection_schema.vector("sparse")
+        assert sparse is not None
+        assert sparse.name == "sparse"
+        assert sparse.data_type == DataType.SPARSE_VECTOR_FP32
+        assert sparse.dimension == 0
+        assert sparse.index_param.type == IndexType.HNSW
+
+        assert str(collection_schema) is not None
+
+
+# ----------------------------
+# CollectionStats Test Case
+# ----------------------------
+class TestCollectionStats:
+    """
+    The constructor of CollectionStats is not provided.
+    It can only be obtained through collection.stats()
+    """
+
+    def test_collection_stats(self):
+        stats = CollectionStats()
+        assert stats is not None

python/tests/test_typing.py

@@ -0,0 +1,141 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+import pytest
+from zvec import (
+    DataType,
+    IndexType,
+    MetricType,
+    QuantizeType,
+    Status,
+    StatusCode,
+)
+
+
+# ----------------------------
+# Enum Test Case
+# ----------------------------
+@pytest.mark.parametrize(
+    "member, name",
+    [
+        (DataType.FLOAT, "FLOAT"),
+        (IndexType.HNSW, "HNSW"),
+        (MetricType.COSINE, "COSINE"),
+        (QuantizeType.INT8, "INT8"),
+        (StatusCode.OK, "OK"),
+    ],
+)
+def test_enum_names(member, name):
+    assert member.name == name
+
+
+@pytest.mark.parametrize(
+    "member, value",
+    [
+        (DataType.FLOAT, 8),
+        (IndexType.HNSW, 1),
+        (MetricType.COSINE, 3),
+        (QuantizeType.INT8, 2),
+        (StatusCode.OK, 0),
+    ],
+)
+def test_enum_values(member, value):
+    assert member.value == value
+
+
+@pytest.mark.parametrize("member", ["L2", "IP", "COSINE"])
+def test_metric_type_has_member(member):
+    assert member in MetricType.__members__
+
+
+@pytest.mark.parametrize(
+    "member",
+    [
+        "STRING",
+        "BOOL",
+        "INT32",
+        "INT64",
+        "FLOAT",
+        "DOUBLE",
+        "UINT32",
+        "UINT64",
+        "VECTOR_FP16",
+        "VECTOR_FP32",
+        "VECTOR_FP64",
+        "VECTOR_INT8",
+        "SPARSE_VECTOR_FP32",
+        "SPARSE_VECTOR_FP16",
+        "ARRAY_STRING",
+        "ARRAY_INT32",
+        "ARRAY_INT64",
+        "ARRAY_FLOAT",
+        "ARRAY_DOUBLE",
+        "ARRAY_BOOL",
+        "ARRAY_UINT32",
+        "ARRAY_UINT64",
+    ],
+)
+def test_data_type_has_member(member):
+    assert member in DataType.__members__
+
+
+@pytest.mark.parametrize("member", ["HNSW", "IVF", "FLAT", "INVERT"])
+def test_index_type_has_member(member):
+    assert member in IndexType.__members__
+
+
+@pytest.mark.parametrize("member", ["FP16", "INT8", "INT4", "UNDEFINED"])
+def test_quantize_type_has_member(member):
+    assert member in QuantizeType.__members__
+
+
+@pytest.mark.parametrize(
+    "member",
+    [
+        "OK",
+        "UNKNOWN",
+        "NOT_FOUND",
+        "ALREADY_EXISTS",
+        "INVALID_ARGUMENT",
+        "PERMISSION_DENIED",
+        "FAILED_PRECONDITION",
+        "RESOURCE_EXHAUSTED",
+        "UNAVAILABLE",
+        "INTERNAL_ERROR",
+        "NOT_SUPPORTED",
+    ],
+)
+def test_status_code_has_member(member):
+    assert member in StatusCode.__members__
+
+
+# ----------------------------
+# Status Test Case
+# ----------------------------
+class TestStatus:
+    def test_status_code(self):
+        status = Status(StatusCode.OK)
+        assert status.code() == StatusCode.OK
+
+    def test_status_message(self):
+        status = Status(StatusCode.OK, "OK")
+        assert status.message() == "OK"
+
+        status = Status(StatusCode.NOT_FOUND, "Not Found")
+        assert status.message() == "Not Found"
+
+    def test_status_ok(self):
+        status = Status(StatusCode.OK)
+        assert status.ok()

python/tests/test_util.py

@@ -0,0 +1,89 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+from zvec import require_module
+
+
+# ----------------------------
+# require_module func Test Case
+# ----------------------------
+def test_require_module_success():
+    module = require_module("os")
+    assert module is not None
+    assert hasattr(module, "path")
+
+
+def test_require_module_with_submodule_success():
+    module = require_module("os.path")
+    assert module is not None
+    assert hasattr(module, "join")
+
+
+def test_require_module_import_error():
+    with pytest.raises(ImportError) as exc_info:
+        require_module("nonexistent_module")
+
+    exception_msg = str(exc_info.value)
+    assert "Required package 'nonexistent_module' is not installed." in exception_msg
+
+
+def test_require_module_with_mitigation_import_error():
+    with pytest.raises(ImportError) as exc_info:
+        require_module("nonexistent_module.submodule", mitigation="custom_package")
+
+    exception_msg = str(exc_info.value)
+    assert "Required package 'custom_package' is not installed." in exception_msg
+    assert (
+        "Module 'nonexistent_module.submodule' is part of 'nonexistent_module'"
+        in exception_msg
+    )
+    assert "please pip install 'custom_package'." in exception_msg
+
+
+def test_require_module_submodule_import_error():
+    with pytest.raises(ImportError) as exc_info:
+        require_module("os.nonexistent_submodule")
+
+    exception_msg = str(exc_info.value)
+    assert (
+        "Required package 'os.nonexistent_submodule' is not installed." in exception_msg
+    )
+    assert "Module 'os.nonexistent_submodule' is part of 'os'" in exception_msg
+    assert "please pip install 'os'." in exception_msg
+
+
+@patch("importlib.import_module")
+def test_require_module_wraps_original_exception(mock_import_module):
+    original_exception = ImportError("Original error")
+    mock_import_module.side_effect = original_exception
+
+    with pytest.raises(ImportError) as exc_info:
+        require_module("some_module")
+
+    assert exc_info.value.__cause__ is original_exception
+
+
+@patch("importlib.import_module")
+def test_require_module_calls_importlib(mock_import_module):
+    mock_module = MagicMock()
+    mock_import_module.return_value = mock_module
+
+    result = require_module("test_module")
+
+    mock_import_module.assert_called_once_with("test_module")
+    assert result is mock_module

python/tests/test_vamana.py

@@ -0,0 +1,501 @@
+# Copyright 2025-present the zvec project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Tests for the Python entry point of the Vamana (DiskANN) dense vector index.
+
+Mirrors the structure of ``test_hnsw_contiguous_memory.py`` (the closest
+hnsw dense reference), and is split into two parts:
+
+1. **Surface tests** — verify that ``VamanaIndexParam`` / ``VamanaQueryParam``
+   are correctly bound: construction defaults, readonly properties,
+   ``to_dict``, ``__repr__``, pickle round-trip, and that they appear in the
+   public ``zvec`` namespace with the expected ``IndexType.VAMANA`` value.
+
+2. **End-to-end tests** — build a collection that uses Vamana on a dense
+   FP32 column, insert deterministic documents, then run a top-k query
+   through ``VamanaQueryParam`` on both the writer segment and the
+   persisted (post-``optimize()``) segment.
+"""
+
+from __future__ import annotations
+
+import pickle
+import sys
+
+import numpy as np
+import pytest
+
+import zvec
+from zvec import (
+    Collection,
+    CollectionOption,
+    CollectionSchema,
+    Doc,
+    FieldSchema,
+    InvertIndexParam,
+    VamanaIndexParam,
+    VamanaQueryParam,
+    Query,
+    VectorSchema,
+)
+from zvec.typing import DataType, IndexType, MetricType, QuantizeType
+
+DIMENSION = 32
+NUM_DOCS = 128
+TOPK = 5
+
+# Defaults pulled from src/include/zvec/core/interface/constants.h. Keep
+# in sync with kDefaultVamana* if the engine defaults ever change.
+DEFAULT_MAX_DEGREE = 64
+DEFAULT_SEARCH_LIST_SIZE = 100
+DEFAULT_ALPHA = 1.2
+DEFAULT_EF_SEARCH = 200
+DEFAULT_SATURATE_GRAPH = False
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _build_schema(
+    name: str,
+    *,
+    metric_type: MetricType = MetricType.IP,
+    max_degree: int = 32,
+    search_list_size: int = 64,
+    alpha: float = 1.2,
+    use_contiguous_memory: bool = False,
+) -> CollectionSchema:
+    """Create a simple schema with a single FP32 Vamana vector column."""
+    return CollectionSchema(
+        name=name,
+        fields=[
+            FieldSchema(
+                "id",
+                DataType.INT64,
+                nullable=False,
+                index_param=InvertIndexParam(enable_range_optimization=True),
+            ),
+        ],
+        vectors=[
+            VectorSchema(
+                "dense",
+                DataType.VECTOR_FP32,
+                dimension=DIMENSION,
+                index_param=VamanaIndexParam(
+                    metric_type=metric_type,
+                    max_degree=max_degree,
+                    search_list_size=search_list_size,
+                    alpha=alpha,
+                    use_contiguous_memory=use_contiguous_memory,
+                ),
+            ),
+        ],
+    )
+
+
+def _generate_docs(rng: np.random.Generator, num: int = NUM_DOCS) -> list[Doc]:
+    """Produce deterministic documents for insertion."""
+    docs: list[Doc] = []
+    for i in range(num):
+        vec = rng.standard_normal(DIMENSION).astype(np.float32)
+        docs.append(
+            Doc(
+                id=str(i),
+                fields={"id": i},
+                vectors={"dense": vec.tolist()},
+            )
+        )
+    return docs
+
+
+def _query_topk(
+    coll: Collection, query_vec: list[float], *, ef_search: int = 64
+) -> list[str]:
+    """Run a top-k vector query and return the returned ids in order."""
+    vector_query = Query(
+        field_name="dense",
+        vector=query_vec,
+        param=VamanaQueryParam(ef_search=ef_search),
+    )
+    hits = coll.query(vector_query, topk=TOPK)
+    assert hits is not None, "query returned None"
+    assert len(hits) >= 1, f"expected at least one hit, got {hits!r}"
+    return [doc.id for doc in hits]
+
+
+# ---------------------------------------------------------------------------
+# 1) Surface: construction / property / to_dict / repr / pickle / namespace
+# ---------------------------------------------------------------------------
+
+
+class TestVamanaIndexParamSurface:
+    """Verify the Python binding for ``VamanaIndexParam``."""
+
+    def test_defaults(self):
+        param = VamanaIndexParam()
+        assert param.type == IndexType.VAMANA
+        assert param.metric_type == MetricType.IP
+        assert param.max_degree == DEFAULT_MAX_DEGREE
+        assert param.search_list_size == DEFAULT_SEARCH_LIST_SIZE
+        assert param.alpha == pytest.approx(DEFAULT_ALPHA)
+        assert param.saturate_graph is DEFAULT_SATURATE_GRAPH
+        assert param.use_contiguous_memory is False
+        assert param.use_id_map is False
+        assert param.quantize_type == QuantizeType.UNDEFINED
+
+    def test_custom_construction(self):
+        param = VamanaIndexParam(
+            metric_type=MetricType.COSINE,
+            max_degree=48,
+            search_list_size=128,
+            alpha=1.5,
+            saturate_graph=True,
+            use_contiguous_memory=True,
+            use_id_map=False,
+            quantize_type=QuantizeType.INT8,
+        )
+        assert param.type == IndexType.VAMANA
+        assert param.metric_type == MetricType.COSINE
+        assert param.max_degree == 48
+        assert param.search_list_size == 128
+        assert param.alpha == pytest.approx(1.5)
+        assert param.saturate_graph is True
+        assert param.use_contiguous_memory is True
+        assert param.use_id_map is False
+        assert param.quantize_type == QuantizeType.INT8
+
+    def test_to_dict_includes_all_fields(self):
+        param = VamanaIndexParam(
+            metric_type=MetricType.L2,
+            max_degree=32,
+            search_list_size=80,
+            alpha=1.3,
+            saturate_graph=True,
+            use_contiguous_memory=True,
+            use_id_map=False,
+            quantize_type=QuantizeType.FP16,
+        )
+        data = param.to_dict()
+        assert data["type"] == "VAMANA"
+        assert data["metric_type"] == "L2"
+        assert data["max_degree"] == 32
+        assert data["search_list_size"] == 80
+        assert data["alpha"] == pytest.approx(1.3)
+        assert data["saturate_graph"] is True
+        assert data["use_contiguous_memory"] is True
+        assert data["use_id_map"] is False
+        assert data["quantize_type"] == "FP16"
+
+    def test_repr_contains_key_fields(self):
+        text = repr(
+            VamanaIndexParam(
+                metric_type=MetricType.COSINE,
+                max_degree=24,
+                search_list_size=72,
+                alpha=1.4,
+                saturate_graph=True,
+                use_contiguous_memory=True,
+            )
+        )
+        # Spot-check the most diagnostic fields are rendered.
+        assert "VAMANA" in text
+        assert "COSINE" in text
+        assert "max_degree" in text and "24" in text
+        assert "search_list_size" in text and "72" in text
+        assert "alpha" in text
+        assert "saturate_graph" in text and "true" in text
+        assert "use_contiguous_memory" in text and "true" in text
+
+    @pytest.mark.parametrize(
+        "field, kwargs",
+        [
+            ("max_degree", dict(max_degree=99)),
+            ("search_list_size", dict(search_list_size=99)),
+            ("alpha", dict(alpha=1.7)),
+            ("saturate_graph", dict(saturate_graph=True)),
+            ("use_contiguous_memory", dict(use_contiguous_memory=True)),
+            ("use_id_map", dict(use_id_map=True)),
+        ],
+    )
+    def test_readonly_properties(self, field, kwargs):
+        param = VamanaIndexParam(**kwargs)
+        if sys.version_info >= (3, 11):
+            match_pattern = r"(can't set attribute|has no setter|readonly attribute)"
+        else:
+            match_pattern = r"can't set attribute"
+        with pytest.raises(AttributeError, match=match_pattern):
+            setattr(param, field, getattr(param, field))
+
+    def test_pickle_roundtrip(self):
+        original = VamanaIndexParam(
+            metric_type=MetricType.COSINE,
+            max_degree=48,
+            search_list_size=120,
+            alpha=1.4,
+            saturate_graph=True,
+            use_contiguous_memory=True,
+            use_id_map=False,
+            quantize_type=QuantizeType.INT8,
+        )
+        restored = pickle.loads(pickle.dumps(original))
+        assert restored.type == IndexType.VAMANA
+        assert restored.metric_type == MetricType.COSINE
+        assert restored.max_degree == 48
+        assert restored.search_list_size == 120
+        assert restored.alpha == pytest.approx(1.4)
+        assert restored.saturate_graph is True
+        assert restored.use_contiguous_memory is True
+        assert restored.use_id_map is False
+        assert restored.quantize_type == QuantizeType.INT8
+        # to_dict equality is the strongest end-to-end equivalence we have.
+        assert restored.to_dict() == original.to_dict()
+
+
+class TestVamanaQueryParamSurface:
+    """Verify the Python binding for ``VamanaQueryParam``."""
+
+    def test_defaults(self):
+        q = VamanaQueryParam()
+        assert q.type == IndexType.VAMANA
+        assert q.ef_search == DEFAULT_EF_SEARCH
+        assert q.radius == pytest.approx(0.0)
+        assert q.is_linear is False
+        assert q.is_using_refiner is False
+        assert q.prefetch_offset == 8
+        assert q.prefetch_lines == 0
+
+    def test_custom_construction(self):
+        q = VamanaQueryParam(
+            ef_search=300,
+            radius=0.5,
+            is_linear=True,
+            is_using_refiner=True,
+            extra_params={
+                "prefetch_offset": 8,
+                "prefetch_lines": 2,
+            },
+        )
+        assert q.type == IndexType.VAMANA
+        assert q.ef_search == 300
+        assert q.radius == pytest.approx(0.5)
+        assert q.is_linear is True
+        assert q.is_using_refiner is True
+        assert q.prefetch_offset == 8
+        assert q.prefetch_lines == 2
+
+    def test_repr_contains_key_fields(self):
+        text = repr(VamanaQueryParam(ef_search=128, radius=0.25))
+        assert "VAMANA" in text
+        assert "ef_search" in text and "128" in text
+        assert "radius" in text
+
+    def test_readonly_ef_search(self):
+        q = VamanaQueryParam(ef_search=100)
+        if sys.version_info >= (3, 11):
+            match_pattern = r"(can't set attribute|has no setter|readonly attribute)"
+        else:
+            match_pattern = r"can't set attribute"
+        with pytest.raises(AttributeError, match=match_pattern):
+            q.ef_search = 200  # type: ignore[misc]
+
+    def test_pickle_roundtrip(self):
+        original = VamanaQueryParam(
+            ef_search=256,
+            radius=0.3,
+            is_linear=False,
+            is_using_refiner=True,
+            extra_params={
+                "prefetch_offset": 4,
+                "prefetch_lines": 3,
+            },
+        )
+        restored = pickle.loads(pickle.dumps(original))
+        assert restored.type == IndexType.VAMANA
+        assert restored.ef_search == 256
+        assert restored.radius == pytest.approx(0.3)
+        assert restored.is_linear is False
+        assert restored.is_using_refiner is True
+        assert restored.prefetch_offset == 4
+        assert restored.prefetch_lines == 3
+
+
+class TestVamanaPublicNamespace:
+    """The Vamana entry points must be importable from the top-level ``zvec``."""
+
+    def test_top_level_exports(self):
+        assert zvec.VamanaIndexParam is VamanaIndexParam
+        assert zvec.VamanaQueryParam is VamanaQueryParam
+        assert "VamanaIndexParam" in zvec.__all__
+        assert "VamanaQueryParam" in zvec.__all__
+
+    def test_index_type_enum_member(self):
+        # Sanity: the IndexType enum exposes VAMANA and it is what the
+        # bound params advertise.
+        assert IndexType.VAMANA is not None
+        assert VamanaIndexParam().type == IndexType.VAMANA
+        assert VamanaQueryParam().type == IndexType.VAMANA
+
+
+# ---------------------------------------------------------------------------
+# 2) End-to-end: create collection, insert, query through the writer segment
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def rng() -> np.random.Generator:
+    return np.random.default_rng(seed=42)
+
+
+# Mirror the hnsw dense test fixture: only the mmap-backed variant is
+# currently usable for vector index construction. BufferPool (enable_mmap=
+# False) is intentionally omitted because the same write-path guard in
+# ``SegmentImpl::merge_vector_indexer`` rejects that combination.
+@pytest.fixture(params=[True], ids=["mmap_on"])
+def collection_option(request) -> CollectionOption:
+    return CollectionOption(read_only=False, enable_mmap=request.param)
+
+
+class TestVamanaEndToEnd:
+    """End-to-end: schema -> create_and_open -> insert -> query works."""
+
+    def test_schema_round_trip(self, tmp_path_factory, collection_option):
+        """The Vamana index params survive the schema persist path."""
+        schema = _build_schema(
+            "vamana_schema_rt",
+            metric_type=MetricType.COSINE,
+            max_degree=32,
+            search_list_size=80,
+            alpha=1.3,
+            use_contiguous_memory=True,
+        )
+        path = tmp_path_factory.mktemp("zvec") / "vamana_schema_rt"
+        coll = zvec.create_and_open(
+            path=str(path), schema=schema, option=collection_option
+        )
+        try:
+            vec_schema = coll.schema.vectors[0]
+            ip = vec_schema.index_param
+            assert ip.type == IndexType.VAMANA
+            assert ip.metric_type == MetricType.COSINE
+            assert ip.max_degree == 32
+            assert ip.search_list_size == 80
+            assert ip.alpha == pytest.approx(1.3)
+            assert ip.use_contiguous_memory is True
+        finally:
+            coll.destroy()
+
+    def test_insert_and_query_self_recall(
+        self, tmp_path_factory, collection_option, rng
+    ):
+        """Top-1 of a query equal to an inserted vector must be that vector.
+
+        Exercises the writer-segment Vamana streamer end-to-end through the
+        Python entry point: ``VamanaIndexParam`` for build and
+        ``VamanaQueryParam`` for search.
+        """
+        schema = _build_schema("vamana_e2e_recall")
+        path = tmp_path_factory.mktemp("zvec") / "vamana_e2e_recall"
+        coll = zvec.create_and_open(
+            path=str(path), schema=schema, option=collection_option
+        )
+        try:
+            docs = _generate_docs(rng)
+            for r in coll.insert(docs=docs):
+                assert r.ok(), f"insert failed: code={r.code()}"
+            assert coll.stats.doc_count == NUM_DOCS
+
+            # Self-recall: query with the i-th inserted vector, expect id i
+            # to be the top result.
+            for probe in (0, 7, 42, NUM_DOCS - 1):
+                query_vec = docs[probe].vector("dense")
+                ids = _query_topk(coll, query_vec)
+                assert ids[0] == str(probe), (
+                    f"expected self-recall at probe={probe}, got top-1 id={ids[0]} "
+                    f"(top-{TOPK}={ids})"
+                )
+        finally:
+            coll.destroy()
+
+    def test_query_param_ef_search_affects_only_quality(
+        self, tmp_path_factory, collection_option, rng
+    ):
+        """``ef_search`` is a search-time knob and must not crash for any
+        sensible value. Larger ``ef_search`` should be at least as good as
+        smaller for self-recall."""
+        schema = _build_schema("vamana_e2e_ef")
+        path = tmp_path_factory.mktemp("zvec") / "vamana_e2e_ef"
+        coll = zvec.create_and_open(
+            path=str(path), schema=schema, option=collection_option
+        )
+        try:
+            docs = _generate_docs(rng)
+            for r in coll.insert(docs=docs):
+                assert r.ok()
+
+            query_vec = docs[3].vector("dense")
+            ids_small = _query_topk(coll, query_vec, ef_search=16)
+            ids_large = _query_topk(coll, query_vec, ef_search=256)
+
+            # Both should self-recall the probe vector at top-1.
+            assert ids_small[0] == "3"
+            assert ids_large[0] == "3"
+            assert len(ids_small) == TOPK
+            assert len(ids_large) == TOPK
+        finally:
+            coll.destroy()
+
+    def test_optimize_then_query(self, tmp_path_factory, collection_option, rng):
+        """The persisted Vamana segment built by ``optimize()`` must serve
+        queries correctly.
+
+        Until the cmake fix to force-load ``core_knn_vamana_static`` into the
+        ``_zvec`` pybind module, this path failed at ``VamanaStreamer``
+        creation because the global factory registration in
+        ``vamana_streamer.cc`` was never linked in. This test pins down the
+        regression.
+        """
+        schema = _build_schema("vamana_e2e_optimize")
+        path = tmp_path_factory.mktemp("zvec") / "vamana_e2e_optimize"
+        coll = zvec.create_and_open(
+            path=str(path), schema=schema, option=collection_option
+        )
+        try:
+            docs = _generate_docs(rng)
+            for r in coll.insert(docs=docs):
+                assert r.ok()
+            assert coll.stats.doc_count == NUM_DOCS
+
+            # Snapshot the writer-segment top-k for a probe vector.
+            query_vec = docs[5].vector("dense")
+            ids_pre = _query_topk(coll, query_vec)
+            assert ids_pre[0] == "5"
+
+            # Trigger persisted segment build. Pre-fix this raised
+            # RuntimeError("Failed to create index").
+            coll.optimize()
+
+            # Persisted segment must still serve queries with the same
+            # top-1 self-recall guarantee. We do not assert full top-k
+            # equality with the writer segment because the persisted
+            # streamer may visit nodes in a different order; top-1 self-
+            # recall is the strong invariant.
+            ids_post = _query_topk(coll, query_vec)
+            assert ids_post[0] == "5", (
+                f"post-optimize top-1 should still be probe id, got {ids_post}"
+            )
+            assert len(ids_post) == TOPK
+        finally:
+            coll.destroy()