{"record":{"id":"50b1daf3fa1fd09e","repo":"pathwaycom/pathway","slug":"either-dimensions-or-embedder-must-be-provided","errorCode":null,"errorMessage":"Either `dimensions` or `embedder` must be provided to index factory.","messagePattern":"Either `dimensions` or `embedder` must be provided to index factory\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/pathway/stdlib/indexing/nearest_neighbors.py","lineNumber":426,"sourceCode":"    dimensions: int | None = None\n    embedder: pw.UDF | None = None\n\n    def _get_embed_dimensions(self) -> int:\n        # import is here to prevent cyclical imports\n        from pathway.xpacks.llm.embedders import BaseEmbedder\n\n        if isinstance(self.embedder, BaseEmbedder):\n            return self.embedder.get_embedding_dimension()\n        elif isinstance(self.embedder, pw.UDF):\n            return len(_coerce_sync(self.embedder.__wrapped__)(\".\"))\n        else:\n            raise TypeError(\"Embedder is not a valid `pw.UDF`.\")\n\n    def __post_init__(self):\n        if self.dimensions is None and self.embedder is not None:\n            self.dimensions: int = self._get_embed_dimensions()\n        elif self.dimensions is None and self.embedder is None:\n            raise ValueError(\n                \"Either `dimensions` or `embedder` must be provided to index factory.\"\n            )\n\n\n@dataclass(kw_only=True)\nclass UsearchKnnFactory(KnnIndexFactory):\n    \"\"\"\n    Factory for creating UsearchKNN indices.\n\n    Args:\n        dimensions (int): number of dimensions of vectors that are used by the index and\n            queries. This is only needed if the `embedder` is not provided.\n        reserved_space (int): initial capacity (in the number of entries) of the index\n        metric (USearchMetricKind): metric kind that is used to determine distance.\n            Defaults to cosine similarity.\n        connectivity (int): maximum number of edges for a node in the HNSW index, setting\n            this value to 0 tells usearch to configure it on its own\n        expansion_add (int): indicates amount of work spent while adding elements to the index","sourceCodeStart":408,"sourceCodeEnd":444,"githubUrl":"https://github.com/pathwaycom/pathway/blob/fa2f74a4649b7c5908690cf60137263d8d80de5f/python/pathway/stdlib/indexing/nearest_neighbors.py#L408-L444","documentation":"KNN index factories in pathway.stdlib.indexing.nearest_neighbors need to know the vector dimensionality to allocate and configure the underlying index (USearch reserves space per vector, brute force allocates accordingly). The dimension is either stated explicitly via `dimensions` or inferred from an `embedder`; __post_init__ raises this ValueError when both are absent, i.e. dimensions is None and embedder is None.","triggerScenarios":"Constructing UsearchKnnFactory() or BruteForceKnnFactory() with neither dimensions nor embedder — e.g. when indexing precomputed vector columns the author assumes the dimension is read from the data, which it is not.","commonSituations":"Switching a pipeline from text embedding to precomputed vectors and deleting the embedder argument; copy-pasting a factory constructor and trimming arguments; defaults picked up from a config dict where both keys are missing.","solutions":["Pass the exact vector size if vectors are precomputed: UsearchKnnFactory(dimensions=1536).","Or pass an embedder (a pw.UDF or BaseEmbedder) so the dimension is inferred by embedding a probe string.","Centralize the dimension in one constant shared with your embedding model config to avoid drift."],"exampleFix":"# before\nfactory = BruteForceKnnFactory()  # vectors already in the table\n\n# after\nfactory = BruteForceKnnFactory(dimensions=384)","handlingStrategy":"validation","validationCode":"def make_knn_factory(cls, *, dimensions=None, embedder=None, **kw):\n    if dimensions is None and embedder is None:\n        raise ValueError(\"provide dimensions (precomputed vectors) or an embedder\")\n    return cls(dimensions=dimensions, embedder=embedder, **kw)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep the embedding model and its dimension in one config record so factories are always constructed with one of the two.","For precomputed-vector pipelines, assert len(first_vector) == dimensions at startup as a cross-check."],"tags":["pathway","knn","configuration","embeddings"],"backgroundTag":null,"analyzedSha":"fa2f74a4649b7c5908690cf60137263d8d80de5f","analyzedAt":"2026-08-15T01:48:17.006Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}