arcadedb-embedded-native 26.10.2.dev1__py3-none-win_amd64.whl

arcadedb_native/vector.py

@@ -0,0 +1,800 @@
+"""
+ArcadeDB Python Bindings - Vector Search
+
+Vector index and array conversion utilities for similarity search.
+"""
+
+from arcadedb_native import _jpype_stub as jpype
+from arcadedb_native import _jpype_stub as jtypes
+from .exceptions import ArcadeDBError
+
+try:  # optional; hoisted to module scope to keep it out of per-call hot paths
+    import numpy as _np
+except ImportError:  # pragma: no cover - numpy is an optional dependency
+    _np = None
+
+
+def _quote_identifier(identifier: str) -> str:
+    if not identifier:
+        raise ArcadeDBError("SQL identifier cannot be empty")
+
+    return "`" + identifier.replace("`", "``") + "`"
+
+
+# float[] class, built on first use (it needs the JVM): jtypes.JArray(jtypes.JFloat)
+# costs about 0.6 us a call, as much as the buffer copy it is followed by.
+_FLOAT_ARRAY = None
+
+
+def _native_enabled():
+    from . import _native
+
+    return _native.enabled()
+
+
+def to_java_float_array(vector):
+    """
+    Convert a Python array-like object to a Java float array.
+
+    Accepts:
+    - Python lists: [0.1, 0.2, 0.3]
+    - NumPy arrays: np.array([0.1, 0.2, 0.3])
+    - Any array-like object with __iter__
+
+    Args:
+        vector: Array-like object containing float values
+
+    Returns:
+        Java float array compatible with ArcadeDB vector indexes
+    """
+    if _native_enabled():
+        return _np.asarray(
+            vector if hasattr(vector, "__array__") else list(vector), dtype=_np.float32
+        )
+    global _FLOAT_ARRAY
+    float_array = _FLOAT_ARRAY
+    if float_array is None:
+        float_array = _FLOAT_ARRAY = jtypes.JArray(jtypes.JFloat)
+
+    # Handle NumPy arrays
+    if _np is not None and isinstance(vector, _np.ndarray):
+        return float_array(vector)
+
+    # Convert to Python list if needed
+    if not isinstance(vector, list):
+        vector = list(vector)
+
+    # Create Java float array
+    return float_array(vector)
+
+
+def to_java_int_array(vector):
+    """
+    Convert a Python array-like object to a Java int array.
+
+    Accepts:
+    - Python lists: [3, 17, 4096]
+    - NumPy arrays of any integer dtype: np.array([3, 17], dtype=np.int32)
+    - Any array-like object with __iter__
+
+    The natural use is the token-index side of a sparse vector, whose weights
+    go through :func:`to_java_float_array`.
+
+    Prefer passing a NumPy array. JPype copies one through the buffer protocol
+    in a single crossing, while a Python list is marshalled element by element:
+    measured at 150 non-zeros, 2.6 us from an array against 6.7 us from a list,
+    2.6x, and the gap widens with length. The array's dtype does not matter --
+    int64, NumPy's default, converts as fast as int32 -- so there is no reason
+    to cast before calling this.
+
+    Args:
+        vector: Array-like object containing integer values
+
+    Returns:
+        Java int array
+    """
+    if _np is not None and isinstance(vector, _np.ndarray):
+        if vector.dtype.kind in "iu" and vector.size:
+            bounds = _np.iinfo(_np.int32)
+            if vector.min() < bounds.min or vector.max() > bounds.max:
+                # A list raises this from JPype; an int64 array used to wrap
+                # silently (2**31 became -2**31).
+                raise OverflowError(
+                    "Cannot convert value to Java int: an element does not fit in 32 bits"
+                )
+        return jtypes.JArray(jtypes.JInt)(vector)
+
+    if not isinstance(vector, list):
+        vector = list(vector)
+
+    return jtypes.JArray(jtypes.JInt)(vector)
+
+
+def to_java_byte_array(vector):
+    """
+    Convert a Python byte-like or integer array-like object to a Java byte array.
+
+    Accepts:
+    - Python lists of integers: [127, -12, 0]
+    - Python bytes / bytearray
+    - NumPy arrays
+    - Any array-like object with __iter__
+
+    Args:
+        vector: Array-like object containing byte values
+
+    Returns:
+        Java byte array compatible with INT8-encoded ArcadeDB vector indexes
+    """
+    try:
+        import numpy as np
+
+        if isinstance(vector, np.ndarray):
+            if vector.dtype in (np.int8, np.uint8):
+                return jtypes.JArray(jtypes.JByte)(vector.tobytes())
+            vector = vector.tolist()
+    except ImportError:
+        pass
+
+    if isinstance(vector, (bytes, bytearray)):
+        return jtypes.JArray(jtypes.JByte)(vector)
+    elif not isinstance(vector, list):
+        vector = list(vector)
+
+    normalized = []
+    for value in vector:
+        byte_value = int(value)
+        if byte_value < -128 or byte_value > 255:
+            raise ArcadeDBError(
+                "Byte vectors must contain values in the signed byte range "
+                "[-128, 127] or unsigned byte range [0, 255]"
+            )
+        if byte_value > 127:
+            byte_value -= 256
+        normalized.append(byte_value)
+
+    return jtypes.JArray(jtypes.JByte)(normalized)
+
+
+def to_python_array(java_vector, use_numpy=True):
+    """
+    Convert a Java array or ArrayList to a Python array.
+
+    Args:
+        java_vector: Java array or ArrayList of floats
+        use_numpy: If True and NumPy is available, return np.array.
+                   If False or NumPy unavailable, return Python list.
+
+    Returns:
+        NumPy array if use_numpy=True and NumPy is available, else Python list
+    """
+    # Convert to Python list first
+    if hasattr(java_vector, "__iter__"):
+        py_list = list(java_vector)
+    else:
+        py_list = [java_vector]
+
+    # Try to return NumPy array if requested
+    if use_numpy:
+        try:
+            import numpy as np
+
+            return np.array(py_list, dtype=np.float32)
+        except ImportError:
+            pass
+
+    return py_list
+
+
+class VectorIndex:
+    """
+    Wrapper for ArcadeDB vector index (JVector-based implementation).
+
+    This is the default and recommended implementation for vector search.
+    It uses JVector (a graph index combining HNSW hierarchy with Vamana/DiskANN
+    algorithms) which provides:
+    - No max_items limit (grows dynamically)
+    - Faster index construction
+    - Automatic indexing of existing records
+    - Concurrent construction support
+
+    Provides a Pythonic interface for creating and searching vector indexes,
+    with native support for NumPy arrays.
+
+    Distance Calculation:
+        The metric used depends on the `distance_function` parameter during index creation:
+
+        ``create_vector_index`` defaults to COSINE.
+
+        1. **EUCLIDEAN**:
+           - Returns **Squared Euclidean Distance** (Lower is better).
+           - Formula: $d^2$ where $d$ is the Euclidean distance.
+           - Range: [0.0, +inf)
+           - 0.0: Identical vectors
+           - Larger values: more distant vectors
+
+        2. **COSINE**:
+        - Returns **Cosine Distance** (Lower is better).
+        - Formula: $1 - \\cos(\\theta)$
+        - Range: [0.0, 2.0]
+            - 0.0: Identical vectors (angle 0)
+            - 1.0: Orthogonal vectors (angle 90)
+            - 2.0: Opposite vectors (angle 180)
+
+        3. **DOT_PRODUCT**:
+           - Returns **-(1 + A.B) / 2** (Lower is better).
+           - Formula: $-(1 + A \\cdot B) / 2$
+           - Range: [-1.0, 0.0] for unit-length vectors, which the engine
+             expects (it logs a warning when sampled vectors are not).
+           - Lower values indicate higher similarity (larger positive dot product).
+
+    Quantization:
+        The index supports vector quantization to reduce memory usage and speed up search:
+        - **NONE** (Default): Full precision (float32).
+        - **INT8**: 8-bit integer quantization.
+        - **BINARY**: 1-bit quantization (for high-dimensional binary vectors).
+    """
+
+    def __init__(self, java_index, database):
+        """
+        Initialize VectorIndex wrapper.
+
+        Args:
+            java_index: Java LSMVectorIndex object
+            database: Parent Database object
+        """
+        self._java_index = java_index
+        self._database = database
+        # Resolved once per wrapper: the underlying LSM indexes and the
+        # PRODUCT-quantization readiness check are stable for the lifetime of
+        # this wrapper, but were previously re-derived on every search (several
+        # JPype crossings per query).
+        self._lsm_indexes = None
+        self._pq_ready = False
+
+    def _iter_lsm_indexes(self):
+        if self._lsm_indexes is None:
+            self._lsm_indexes = self._resolve_lsm_indexes()
+        return iter(self._lsm_indexes)
+
+    def _resolve_lsm_indexes(self):
+        if "LSMVectorIndex" in self._java_index.getClass().getName():
+            return [self._java_index]
+
+        resolved = []
+        if "TypeIndex" in self._java_index.getClass().getName():
+            sub_indexes = self._java_index.getSubIndexes()
+            if sub_indexes and not sub_indexes.isEmpty():
+                for sub in sub_indexes:
+                    if "LSMVectorIndex" in sub.getClass().getName():
+                        resolved.append(sub)
+        return resolved
+
+    def _get_primary_lsm_index(self):
+        for index in self._iter_lsm_indexes():
+            return index
+        return None
+
+    def _ensure_product_quantization_ready(self):
+        # Once the check confirms enough vectors it stays valid (indexed vectors
+        # only accumulate), so don't repeat the metadata/countEntries crossings
+        # on every search. An empty PRODUCT bucket is inconclusive (data may
+        # arrive later), so it does not memoize.
+        if self._pq_ready:
+            return
+        all_confirmed = True
+        for index in self._iter_lsm_indexes():
+            meta = index.getMetadata()
+            if str(meta.quantizationType) != "PRODUCT":
+                continue
+
+            vector_count = int(index.countEntries())
+            pq_clusters = int(meta.pqClusters)
+
+            if 0 < vector_count < pq_clusters:
+                raise ArcadeDBError(
+                    "PRODUCT quantization in this ArcadeDB version requires at least "
+                    "pq_clusters indexed vectors per bucket before graph build. "
+                    f"Current bucket has {vector_count} vector(s) but "
+                    f"pq_clusters={pq_clusters}. "
+                    "Use a smaller pq_clusters value, insert more vectors, "
+                    "or use INT8/BINARY/NONE."
+                )
+            if vector_count == 0:
+                all_confirmed = False
+        self._pq_ready = all_confirmed
+
+    def _normalize_ef_search(self, ef_search):
+        if ef_search is None:
+            return None
+
+        if isinstance(ef_search, bool):
+            raise ArcadeDBError("ef_search must be a positive integer")
+
+        try:
+            normalized = int(ef_search)
+        except (TypeError, ValueError) as exc:
+            raise ArcadeDBError("ef_search must be a positive integer") from exc
+
+        if normalized < 1 or normalized != ef_search:
+            raise ArcadeDBError("ef_search must be a positive integer")
+
+        return normalized
+
+    def _get_primary_metadata(self):
+        index = self._get_primary_lsm_index()
+        if index is None:
+            raise ArcadeDBError("Underlying index does not expose vector metadata")
+        return index.getMetadata()
+
+    def _get_type_name(self):
+        index = self._get_primary_lsm_index()
+        if index is None:
+            raise ArcadeDBError("Underlying index does not expose vector type metadata")
+        return str(index.getTypeName())
+
+    def _get_vector_property_name(self):
+        index = self._get_primary_lsm_index()
+        if index is None:
+            raise ArcadeDBError(
+                "Underlying index does not expose vector property metadata"
+            )
+
+        property_names = index.getPropertyNames()
+        if hasattr(property_names, "get"):
+            return str(property_names.get(0))
+        return str(property_names[0])
+
+    def _get_id_property_name(self):
+        index = self._get_primary_lsm_index()
+        if index is None:
+            raise ArcadeDBError("Underlying index does not expose id-property metadata")
+        return str(index.getIdPropertyName())
+
+    def _lookup_query_vector_by_key(self, key):
+        vector_property = self._get_vector_property_name()
+        type_name = self._get_type_name()
+        id_property = self._get_id_property_name()
+        quoted_vector_property = _quote_identifier(vector_property)
+        quoted_type_name = _quote_identifier(type_name)
+        quoted_id_property = _quote_identifier(id_property)
+
+        result = None
+        try:
+            result = self._database.lookup_by_key(type_name, [id_property], [key])
+        except ArcadeDBError:
+            result = None
+
+        if result is None:
+            # Identifiers are quoted via _quote_identifier(); the user-supplied
+            # `key` is passed as a `?` parameter, so this is not SQL injection.
+            result = self._database.query(
+                "sql",
+                (
+                    f"SELECT {quoted_vector_property} AS `query_vector` FROM {quoted_type_name} "  # nosec B608
+                    f"WHERE {quoted_id_property} = ? LIMIT 1"
+                ),
+                key,
+            ).first()
+
+        if result is None:
+            raise ArcadeDBError(
+                f"No record found in type '{type_name}' where {id_property} = {key!r}"
+            )
+
+        query_vector = result.get("query_vector")
+        if query_vector is None:
+            raise ArcadeDBError(
+                f"Record found for {id_property} = {key!r} "
+                f"but property '{vector_property}' is null"
+            )
+
+        return query_vector
+
+    def _build_allowed_rids_set(self, allowed_rids):
+        if not allowed_rids:
+            return None
+
+        HashSet = jpype.JClass("java.util.HashSet")
+
+        allowed_rids_set = HashSet()
+        for rid_value in allowed_rids:
+            allowed_rids_set.add(self._database.to_java_rid(rid_value))
+        return allowed_rids_set
+
+    def _lookup_record_by_rid(self, rid):
+        # `rid` is already a Java RID from the search result: pass it straight
+        # through instead of stringifying and re-parsing it (previously one
+        # str() crossing + a new Java RID allocation per hit).
+        record = self._database._lookup_by_java_rid(rid)
+        if record is None:
+            raise ArcadeDBError(f"Vector search returned missing RID: {rid}")
+        return record
+
+    def _wrap_pair_results(self, pairs):
+        from .core import _wrap_java_record
+        from .graph import _graph_calls
+
+        calls = _graph_calls()
+        if calls is not None:
+            # every hit's record and score in one crossing instead of
+            # getFirst, getSecond, and the record lookup each
+            hits = calls.hits(self._database._java_db, pairs)
+            records, scores = hits[0], hits[1]
+            wrapped = []
+            for i, record in enumerate(records):
+                if record is None:
+                    # name the hit exactly as the per-hit path does
+                    self._lookup_record_by_rid(list(pairs)[i].getFirst())
+                wrapped.append(
+                    (_wrap_java_record(record, self._database), float(scores[i]))
+                )
+            return wrapped
+
+        wrapped_results = []
+        for pair in pairs:
+            rid = pair.getFirst()
+            score = pair.getSecond()
+            wrapped_results.append((self._lookup_record_by_rid(rid), float(score)))
+
+        return wrapped_results
+
+    def _find_neighbor_pairs(
+        self,
+        idx,
+        *,
+        java_vector,
+        k,
+        allowed_rids_set,
+        approximate,
+        ef_search=None,
+    ):
+        if approximate:
+            if allowed_rids_set is not None:
+                return idx.findNeighborsFromVectorApproximate(
+                    java_vector, k, allowed_rids_set
+                )
+            return idx.findNeighborsFromVectorApproximate(java_vector, k)
+
+        if allowed_rids_set is not None and ef_search is not None:
+            return idx.findNeighborsFromVector(
+                java_vector, k, ef_search, allowed_rids_set
+            )
+        if allowed_rids_set is not None:
+            return idx.findNeighborsFromVector(java_vector, k, allowed_rids_set)
+        if ef_search is not None:
+            return idx.findNeighborsFromVector(java_vector, k, ef_search)
+        return idx.findNeighborsFromVector(java_vector, k)
+
+    def _sort_results(self, results):
+        # All similarity functions are exposed as distances (lower is better) by the
+        # engine's findNeighborsFromVector, so the best matches sort ascending by score.
+        results.sort(key=lambda item: item[1])
+        return results
+
+    def _collect_search_results(
+        self,
+        *,
+        java_vector,
+        k,
+        allowed_rids_set,
+        approximate,
+        ef_search=None,
+    ):
+        all_results = []
+
+        for idx in self._iter_lsm_indexes():
+            pairs = self._find_neighbor_pairs(
+                idx,
+                java_vector=java_vector,
+                k=k,
+                allowed_rids_set=allowed_rids_set,
+                approximate=approximate,
+                ef_search=ef_search,
+            )
+
+            all_results.extend(self._wrap_pair_results(pairs))
+
+        return self._sort_results(all_results)[:k]
+
+    def _run_search(
+        self,
+        *,
+        query_vector,
+        k,
+        allowed_rids,
+        approximate,
+        ef_search=None,
+    ):
+        java_vector = to_java_float_array(query_vector)
+        allowed_rids_set = self._build_allowed_rids_set(allowed_rids)
+
+        return self._collect_search_results(
+            java_vector=java_vector,
+            k=k,
+            allowed_rids_set=allowed_rids_set,
+            approximate=approximate,
+            ef_search=ef_search,
+        )
+
+    def find_nearest(
+        self,
+        query_vector,
+        k=10,
+        ef_search=None,
+        allowed_rids=None,
+    ):
+        """
+        Find k nearest neighbors to the query vector.
+
+        Args:
+            query_vector: Query vector as Python list, NumPy array, or array-like
+            k: Number of nearest neighbors to return (final k). Default is 10.
+            ef_search: Optional search beam width override for exact graph search. None
+                uses the Java index default/adaptive behavior.
+            allowed_rids: Optional list of RID strings (e.g. ["#1:0", "#2:5"]) to
+                restrict search
+
+        Returns:
+            List of tuples: [(record, score), ...]
+            - record: The matching ArcadeDB record (Vertex, Document, or Edge)
+            - score: The similarity score/distance
+        """
+        effective_ef_search = self._normalize_ef_search(ef_search)
+
+        try:
+            self._ensure_product_quantization_ready()
+            return self._run_search(
+                query_vector=query_vector,
+                k=k,
+                allowed_rids=allowed_rids,
+                approximate=False,
+                ef_search=effective_ef_search,
+            )
+
+        except ArcadeDBError:
+            raise
+        except Exception as e:
+            raise ArcadeDBError(f"Vector search failed: {e}") from e
+
+    def get_size(self):
+        """
+        Get the current number of items in the index.
+
+        Returns:
+            int: Number of items currently indexed
+        """
+        try:
+            # Both TypeIndex and LSMVectorIndex support countEntries()
+            return self._java_index.countEntries()
+        except Exception as e:
+            raise ArcadeDBError(f"Failed to get index size: {e}") from e
+
+    def get_metadata(self):
+        """
+        Get stable metadata for the vector index.
+
+        Returns:
+            dict: Index metadata including names, dimensions, similarity function,
+            id property, quantization, and selected tuning settings.
+        """
+        try:
+            index = self._get_primary_lsm_index()
+            meta = self._get_primary_metadata()
+
+            return {
+                "index_name": str(self._java_index.getName()),
+                "bucket_index_name": str(index.getName()),
+                "type_name": str(index.getTypeName()),
+                "vector_property": self._get_vector_property_name(),
+                "dimensions": int(meta.dimensions),
+                "similarity_function": str(meta.similarityFunction),
+                "id_property": str(meta.idPropertyName),
+                "quantization": str(meta.quantizationType),
+                "max_connections": int(meta.maxConnections),
+                "beam_width": int(meta.beamWidth),
+                "ef_search": int(meta.efSearch),
+                # location_cache_size is absent on purpose: the engine dropped
+                # the field in #5559/#5568, so reading it here would raise on
+                # every get_metadata() call.
+                "graph_build_cache_size": int(meta.graphBuildCacheSize),
+                "mutations_before_rebuild": int(meta.mutationsBeforeRebuild),
+                "store_vectors_in_graph": bool(meta.storeVectorsInGraph),
+                "add_hierarchy": bool(meta.addHierarchy),
+                "build_state": str(meta.buildState),
+                "pq_subspaces": int(meta.pqSubspaces),
+                "pq_clusters": int(meta.pqClusters),
+                "pq_center_globally": bool(meta.pqCenterGlobally),
+                "pq_training_limit": int(meta.pqTrainingLimit),
+            }
+        except Exception as e:
+            raise ArcadeDBError(f"Failed to read vector index metadata: {e}") from e
+
+    def get_stats(self):
+        """
+        Get live runtime counters for the vector index.
+
+        Unlike :meth:`get_metadata`, which returns the index's stable
+        configuration, this returns counters that change as the index is
+        built and queried: graph state, cache capacities and hit/miss
+        counts, and where vectors were read from (index pages, graph, or
+        the documents themselves). Keys follow the engine and may grow
+        between releases.
+
+        Useful for sizing caches and diagnosing build cost, for example
+        ``vectorFetchFromDocuments`` being non-zero after a build means
+        the build cache did not hold the whole vector set.
+
+        Returns:
+            dict: Counter name to value, for the primary bucket index
+            (see ``get_metadata()["bucket_index_name"]``).
+
+        Examples:
+            >>> stats = index.get_stats()  # doctest: +SKIP
+            >>> stats["vectorCacheHits"], stats["vectorCacheMisses"]
+            (10399017, 1840948)
+        """
+        try:
+            raw = self._get_primary_lsm_index().getStats()
+        except Exception as e:
+            raise ArcadeDBError(f"Failed to read vector index stats: {e}") from e
+
+        stats = {}
+        for java_key in raw.keySet():
+            key = str(java_key)
+            value = raw.get(java_key)
+            if value is None:
+                stats[key] = None
+                continue
+            try:
+                kind = str(value.getClass().getSimpleName())
+            except Exception:
+                kind = ""
+            if kind in ("Long", "Integer", "Short", "Byte", "BigInteger"):
+                stats[key] = int(value)
+            elif kind in ("Double", "Float"):
+                stats[key] = float(value)
+            elif kind == "Boolean":
+                stats[key] = bool(value)
+            else:
+                stats[key] = str(value)
+        return stats
+
+    def find_nearest_by_key(
+        self,
+        key,
+        k=10,
+        ef_search=None,
+        allowed_rids=None,
+    ):
+        """
+        Find nearest neighbors using the indexed vector from an existing record.
+
+        Args:
+            key: Value of the configured id property for the source record.
+            k: Number of nearest neighbors to return (default: 10).
+            ef_search: Optional search beam width override for exact graph search.
+            allowed_rids: Optional RID whitelist to restrict the final search.
+
+        Returns:
+            List of tuples: [(record, score), ...]
+        """
+        query_vector = self._lookup_query_vector_by_key(key)
+        return self.find_nearest(
+            query_vector,
+            k=k,
+            ef_search=ef_search,
+            allowed_rids=allowed_rids,
+        )
+
+    def find_nearest_approximate(
+        self,
+        query_vector,
+        k=10,
+        allowed_rids=None,
+    ):
+        """
+        Find k nearest neighbors using Product Quantization (PQ) approximate search.
+
+        Args:
+            query_vector: Query vector as Python list, NumPy array, or array-like
+            k: Number of nearest neighbors to return (final k)
+            allowed_rids: Optional list of RID strings (e.g. ["#1:0", "#2:5"]) to restrict search
+
+        Returns:
+            List of tuples: [(record, score), ...]
+        """
+        try:
+            quantization = self.get_quantization()
+            if quantization != "PRODUCT":
+                raise ArcadeDBError(
+                    "Approximate search requires quantization=PRODUCT (PQ)"
+                )
+
+            self._ensure_product_quantization_ready()
+
+            return self._run_search(
+                query_vector=query_vector,
+                k=k,
+                allowed_rids=allowed_rids,
+                approximate=True,
+            )
+
+        except ArcadeDBError:
+            raise
+        except Exception as e:
+            raise ArcadeDBError(f"Approximate search failed: {e}") from e
+
+    def get_quantization(self):
+        """
+        Get the quantization type of the index.
+
+        Returns:
+            str: "NONE", "INT8", "BINARY", or "PRODUCT"
+        """
+        try:
+            idx_to_check = self._get_primary_lsm_index()
+
+            if idx_to_check:
+                return str(idx_to_check.getMetadata().quantizationType)
+            return "NONE"
+        except Exception:
+            return "NONE"
+
+    def warm_up(self):
+        """
+        Load the vector graph now instead of on the first search.
+
+        After a database is opened, the index loads its persisted graph lazily,
+        on the first search, and that search pays the load (ArcadeData/arcadedb#8852:
+        about 1 s at 1M 64-dimension vectors on 26.10.1, growing with the index, and
+        more on an index with deletions since its graph was saved, which still
+        re-reads every vector's document). Calling this right after
+        opening the database pays it before the first query arrives, which is
+        what a service that restarts wants. It loads the existing graph and does
+        not rebuild it; a no-op when the graph is already in memory, and safe to
+        call while other threads search. For TypeIndex wrappers, warms every
+        underlying LSMVectorIndex.
+
+        The alternative on engines before 26.10.1 is one throwaway search.
+
+        Raises:
+            ArcadeDBError: the index cannot be warmed, including on an engine
+                older than 26.10.1, which has no ``warmUp()``.
+        """
+        try:
+            warmed_any = False
+            for index in self._iter_lsm_indexes():
+                index.warmUp()
+                warmed_any = True
+            if warmed_any:
+                return
+            raise ArcadeDBError("Underlying index is not an LSM vector index")
+        except ArcadeDBError:
+            raise
+        except Exception as e:
+            raise ArcadeDBError(f"Failed to warm up vector index: {e}") from e
+
+    def build_graph_now(self):
+        """
+        Trigger an immediate rebuild of the underlying vector graph.
+
+        Useful after bulk inserts/updates to avoid waiting for a search-triggered lazy
+        build. For TypeIndex wrappers, rebuilds all underlying LSMVectorIndex instances.
+        """
+        try:
+            self._ensure_product_quantization_ready()
+
+            built_any = False
+            for index in self._iter_lsm_indexes():
+                index.buildVectorGraphNow()
+                built_any = True
+
+            if built_any:
+                return
+
+            raise ArcadeDBError(
+                "Underlying index does not support vector graph rebuild"
+            )
+        except Exception as e:
+            raise ArcadeDBError(f"Failed to rebuild vector graph: {e}") from e