{"record":{"id":"caa2a3dbf5e54294","repo":"lancedb/lancedb","slug":"the-query-used-for-vector-search","errorCode":null,"errorMessage":"\n                The query used for vector search is not a string.\n                In this case, the reranker query needs to be specified explicitly.\n                ","messagePattern":"\n                The query used for vector search is not a string\\.\n                In this case, the reranker query needs to be specified explicitly\\.\n                ","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/python/lancedb/query.py","lineNumber":1954,"sourceCode":"        reranker: Reranker\n            The reranker to use.\n\n        query_string: Optional[str]\n            The query to use for reranking. This needs to be specified explicitly here\n            as the query used for vector search may already be vectorized and the\n            reranker requires a string query.\n            This is only required if the query used for vector search is not a string.\n            Note: This doesn't yet support the case where the query is multimodal or a\n            list of vectors.\n\n        Returns\n        -------\n        LanceVectorQueryBuilder\n            The LanceQueryBuilder object.\n        \"\"\"\n        self._reranker = reranker\n        if self._str_query is None and query_string is None:\n            raise ValueError(\n                \"\"\"\n                The query used for vector search is not a string.\n                In this case, the reranker query needs to be specified explicitly.\n                \"\"\"\n            )\n        if query_string is not None and not isinstance(query_string, str):\n            raise ValueError(\"Reranking currently only supports string queries\")\n        self._str_query = query_string if query_string is not None else self._str_query\n        if reranker.score == \"all\":\n            self.with_row_id(True)\n        return self\n\n    def bypass_vector_index(self) -> LanceVectorQueryBuilder:\n        \"\"\"\n        If this is called then any vector index is skipped\n\n        An exhaustive (flat) search will be performed.  The query vector will\n        be compared to every vector in the table.  At high scales this can be","sourceCodeStart":1936,"sourceCodeEnd":1972,"githubUrl":"https://github.com/lancedb/lancedb/blob/c7b051aff7039333a3f61b79217246c27676806a/python/python/lancedb/query.py#L1936-L1972","documentation":"When a reranker is attached to a LanceVectorQueryBuilder whose query is a vector (not a string), the reranker needs the original text to rerank against. If neither the vector query carried a string (self._str_query is None) nor an explicit query_string was passed, rerank() raises this ValueError. Rerankers like cross-encoders operate on text and cannot derive it from the embedding vector.","triggerScenarios":"table.search(vector).rerank(reranker) where the vector search has no associated text and no query_string argument is supplied; hybrid builders where text() was never called.","commonSituations":"Pure vector searches with a cross-encoder/RRF-style reranker that requires text; pipelines that add rerankers unconditionally; forgetting to pass query_string= after searching by raw embedding.","solutions":["Pass the text explicitly: .rerank(reranker, query_string=\"your query text\").","Perform a hybrid query (query_type=\"hybrid\") so .text() sets self._str_query before reranking.","Skip the reranker for pure vector queries or use a reranker that does not need the query string.","Wrap rerank in try/except ValueError and fall back to unranked results."],"exampleFix":"// before\ntbl.search([0.1, 0.2]).rerank(Reranker())\n\n// after\ntbl.search([0.1, 0.2]).rerank(Reranker(), query_string=\"find the docs about cats\")","handlingStrategy":"try-catch","validationCode":"def can_rerank(q, reranker, query_string=None) -> bool:\n    str_query = getattr(q, \"_str_query\", None)\n    return str_query is not None or isinstance(query_string, str)","typeGuard":"def has_query_text(q) -> bool:\n    return getattr(q, \"_str_query\", None) is not None","tryCatchPattern":"try:\n    q = q.rerank(reranker)\nexcept ValueError as e:\n    if \"query needs to be specified explicitly\" in str(e):\n        q = q.rerank(reranker, query_string=user_text)\n    else:\n        raise","preventionTips":["When reranking pure vector searches, always pass query_string=... with the original text.","Prefer hybrid queries so .text() supplies the string the reranker needs.","Check whether the chosen reranker requires query text before enabling it."],"tags":["python","value-error","reranker","vector-search"],"backgroundTag":"missing-required-argument","analyzedSha":"c7b051aff7039333a3f61b79217246c27676806a","analyzedAt":"2026-09-08T23:42:37.579Z","contentChangedAt":"2026-09-08T23:42:37.579Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}