Add indexed_only and quantization support to search parameters

Author: srimon12

docs/search.md

@@ -17,7 +17,7 @@ SEARCH <collection_name> SIMILAR TO '<query_text>' LIMIT <n> USING HYBRID
 SEARCH <collection_name> SIMILAR TO '<query_text>' LIMIT <n> USING HYBRID [FUSION 'rrf|dbsf'] [DENSE MODEL '<model>'] [SPARSE MODEL '<model>'] [WHERE <filter>]
 SEARCH <collection_name> SIMILAR TO '<query_text>' LIMIT <n> USING SPARSE [MODEL '<sparse_model>']
 SEARCH <collection_name> SIMILAR TO '<query_text>' LIMIT <n> EXACT
-SEARCH <collection_name> SIMILAR TO '<query_text>' LIMIT <n> [USING ...] [WHERE <filter>] [RERANK] WITH { hnsw_ef: <n>, exact: true|false, acorn: true|false, mmr_diversity: <0..1>, mmr_candidates: <n> }
+SEARCH <collection_name> SIMILAR TO '<query_text>' LIMIT <n> [USING ...] [WHERE <filter>] [RERANK] WITH { hnsw_ef: <n>, exact: true|false, acorn: true|false, indexed_only: true|false, quantization: { ignore: true|false, rescore: true|false, oversampling: <n> }, mmr_diversity: <0..1>, mmr_candidates: <n> }
 SEARCH <collection_name> SIMILAR TO '<query_text>' LIMIT <n> [USING ...] [WHERE <filter>] RERANK [MODEL '<reranker_model>']
 ```
 
@@ -107,11 +107,12 @@ Use these when you want to debug retrieval quality or tune recall without changi
 | `WITH { hnsw_ef: 128 }` | Increase HNSW exploration at query time |
 | `WITH { exact: true }` | Force exact KNN explicitly |
 | `WITH { acorn: true }` | Enable ACORN for filtered queries |
+| `WITH { indexed_only: true, quantization: { rescore: true } }` | Prefer indexed vectors and apply quantization controls |
 | `WITH { mmr_diversity: 0.5, mmr_candidates: 50 }` | Apply native MMR diversification after nearest-neighbor retrieval |
 
 - `EXACT` can appear after `LIMIT` or after `RERANK`
 - `WITH { ... }` can appear after `WHERE` and/or `RERANK`
-- Supported `WITH` keys are `hnsw_ef`, `exact`, `acorn`, `mmr_diversity`, and `mmr_candidates`
+- Supported `WITH` keys are `hnsw_ef`, `exact`, `acorn`, `indexed_only`, `quantization`, `mmr_diversity`, and `mmr_candidates`
 - MMR is currently supported for dense `SEARCH` and dense `SEARCH ... GROUP BY`
 - MMR is not yet supported with `USING HYBRID`, `USING SPARSE`, or `RECOMMEND`
 

src/qql/ast_nodes.py

@@ -27,10 +27,19 @@ class SearchWith:
     hnsw_ef: int | None = None
     exact: bool = False
     acorn: bool = False
+    indexed_only: bool = False
+    quantization: "QuantizationSearchWith | None" = None
     mmr_diversity: float | None = None
     mmr_candidates: int | None = None
 
 
+@dataclass(frozen=True)
+class QuantizationSearchWith:
+    ignore: bool | None = None
+    rescore: bool | None = None
+    oversampling: float | None = None
+
+
 # ── Filter expression leaf nodes ──────────────────────────────────────────────
 
 @dataclass(frozen=True)

src/qql/cli.py

@@ -70,7 +70,7 @@
       Optional: [yellow]WHERE[/yellow] <filter>   (e.g. WHERE year > 2020 AND status = 'ok')
       Optional: [yellow]RERANK[/yellow] [MODEL '<model>']   rerank results with a cross-encoder
       Optional: [yellow]EXACT[/yellow]   bypass HNSW and perform exact search
-      Optional: [yellow]WITH[/yellow] { hnsw_ef: <int>, exact: <bool>, acorn: <bool>, mmr_diversity: <0..1>, mmr_candidates: <int> }   search parameters
+    Optional: [yellow]WITH[/yellow] { hnsw_ef: <int>, exact: <bool>, acorn: <bool>, indexed_only: <bool>, quantization: { ignore: <bool>, rescore: <bool>, oversampling: <n> }, mmr_diversity: <0..1>, mmr_candidates: <int> }   search parameters
       Optional: [yellow]GROUP BY[/yellow] <field> [[yellow]GROUP_SIZE[/yellow] <n>]
                   Group results by a payload field value (default GROUP_SIZE: 3).
                   Field must be keyword or integer type. RERANK and GROUP BY cannot be combined.

src/qql/executor.py

@@ -37,6 +37,7 @@
     Prefetch,
     ProductQuantization,
     ProductQuantizationConfig,
+    QuantizationSearchParams,
     Range,
     RecommendInput,
     RecommendQuery,
@@ -830,9 +831,18 @@ def _execute_recommend(self, node: RecommendStmt) -> ExecutionResult:
     def _build_search_params(self, with_clause: SearchWith | None) -> SearchParams | None:
         if with_clause is None:
             return None
+        quantization = None
+        if with_clause.quantization is not None:
+            quantization = QuantizationSearchParams(
+                ignore=with_clause.quantization.ignore,
+                rescore=with_clause.quantization.rescore,
+                oversampling=with_clause.quantization.oversampling,
+            )
         return SearchParams(
             hnsw_ef=with_clause.hnsw_ef,
             exact=with_clause.exact,
+            quantization=quantization,
+            indexed_only=True if with_clause.indexed_only else None,
             acorn=AcornSearchParams(enable=True) if with_clause.acorn else None,
         )
 

src/qql/parser.py

@@ -25,6 +25,7 @@
     OrExpr,
     QuantizationConfig,
     QuantizationType,
+    QuantizationSearchWith,
     RecommendStmt,
     SelectStmt,
     ScrollStmt,
@@ -414,6 +415,8 @@ def _parse_search(self) -> SearchStmt:
                     hnsw_ef=with_clause.hnsw_ef,
                     exact=True,
                     acorn=with_clause.acorn,
+                    indexed_only=with_clause.indexed_only,
+                    quantization=with_clause.quantization,
                     mmr_diversity=with_clause.mmr_diversity,
                     mmr_candidates=with_clause.mmr_candidates,
                 )
@@ -427,6 +430,8 @@ def _parse_search(self) -> SearchStmt:
                     hnsw_ef=parsed_with.hnsw_ef or with_clause.hnsw_ef,
                     exact=parsed_with.exact or with_clause.exact,
                     acorn=parsed_with.acorn or with_clause.acorn,
+                    indexed_only=parsed_with.indexed_only or with_clause.indexed_only,
+                    quantization=parsed_with.quantization or with_clause.quantization,
                     mmr_diversity=(
                         parsed_with.mmr_diversity
                         if parsed_with.mmr_diversity is not None
@@ -957,6 +962,8 @@ def _parse_with_clause(self) -> SearchWith:
         hnsw_ef: int | None = None
         exact: bool = False
         acorn: bool = False
+        indexed_only: bool = False
+        quantization: QuantizationSearchWith | None = None
         mmr_diversity: float | None = None
         mmr_candidates: int | None = None
         while self._peek().kind != TokenKind.RBRACE:
@@ -979,6 +986,10 @@ def _parse_with_clause(self) -> SearchWith:
                 exact = self._parse_bool()
             elif key == "acorn":
                 acorn = self._parse_bool()
+            elif key == "indexed_only":
+                indexed_only = self._parse_bool()
+            elif key == "quantization":
+                quantization = self._parse_quantization_search_with()
             elif key == "mmr_diversity":
                 mmr_diversity = float(self._parse_number())
                 if not 0.0 <= mmr_diversity <= 1.0:
@@ -996,7 +1007,7 @@ def _parse_with_clause(self) -> SearchWith:
             else:
                 raise QQLSyntaxError(
                     "Unknown WITH parameter "
-                    f"'{key}'. Expected: hnsw_ef, exact, acorn, mmr_diversity, mmr_candidates",
+                    f"'{key}'. Expected: hnsw_ef, exact, acorn, indexed_only, quantization, mmr_diversity, mmr_candidates",
                     key_tok.pos,
                 )
             if self._peek().kind == TokenKind.COMMA:
@@ -1010,10 +1021,48 @@ def _parse_with_clause(self) -> SearchWith:
             hnsw_ef=hnsw_ef,
             exact=exact,
             acorn=acorn,
+            indexed_only=indexed_only,
+            quantization=quantization,
             mmr_diversity=mmr_diversity,
             mmr_candidates=mmr_candidates,
         )
 
+    def _parse_quantization_search_with(self) -> QuantizationSearchWith:
+        self._expect(TokenKind.LBRACE)
+        ignore: bool | None = None
+        rescore: bool | None = None
+        oversampling: float | None = None
+
+        while self._peek().kind != TokenKind.RBRACE:
+            key_tok = self._expect(TokenKind.IDENTIFIER)
+            key = key_tok.value.lower()
+            self._expect(TokenKind.COLON)
+            if key == "ignore":
+                ignore = self._parse_bool()
+            elif key == "rescore":
+                rescore = self._parse_bool()
+            elif key == "oversampling":
+                oversampling = float(self._parse_number())
+            else:
+                raise QQLSyntaxError(
+                    "Unknown QUANTIZATION parameter "
+                    f"'{key}'. Expected: ignore, rescore, oversampling",
+                    key_tok.pos,
+                )
+            if self._peek().kind == TokenKind.COMMA:
+                self._advance()
+                if self._peek().kind == TokenKind.RBRACE:
+                    break
+            else:
+                break
+
+        self._expect(TokenKind.RBRACE)
+        return QuantizationSearchWith(
+            ignore=ignore,
+            rescore=rescore,
+            oversampling=oversampling,
+        )
+
     def _parse_bool(self) -> bool:
         tok = self._peek()
         if tok.kind == TokenKind.IDENTIFIER:

tests/test_executor.py

@@ -8,6 +8,7 @@
     InsertBulkStmt,
     InsertStmt,
     QuantizationConfig,
+    QuantizationSearchWith,
     QuantizationType,
     RecommendStmt,
     SelectStmt,
@@ -728,6 +729,37 @@ def test_search_with_acorn_forwards_search_params(
         assert search_params.hnsw_ef == 128
         assert search_params.acorn.enable is True
 
+    def test_search_with_indexed_only_and_quantization_forwards_search_params(
+        self, executor, mock_client, mocker
+    ):
+        mock_client.collection_exists.return_value = True
+        mock_response = mocker.MagicMock()
+        mock_response.points = []
+        mock_client.query_points.return_value = mock_response
+
+        node = SearchStmt(
+            collection="notes",
+            query_text="hello",
+            limit=5,
+            model=None,
+            with_clause=SearchWith(
+                indexed_only=True,
+                quantization=QuantizationSearchWith(
+                    ignore=True,
+                    rescore=False,
+                    oversampling=2.5,
+                ),
+            ),
+        )
+        executor.execute(node)
+
+        search_params = mock_client.query_points.call_args.kwargs["search_params"]
+        assert search_params.indexed_only is True
+        assert search_params.quantization is not None
+        assert search_params.quantization.ignore is True
+        assert search_params.quantization.rescore is False
+        assert search_params.quantization.oversampling == pytest.approx(2.5)
+
     def test_dense_search_against_hybrid_collection_uses_dense_vector_name(
         self, executor, mock_client, mocker
     ):
@@ -989,6 +1021,30 @@ def test_recommend_forwards_search_params(self, executor, mock_client, mocker):
         assert search_params.exact is True
         assert search_params.hnsw_ef == 128
 
+    def test_recommend_forwards_indexed_only_and_quantization(
+        self, executor, mock_client, mocker
+    ):
+        mock_client.collection_exists.return_value = True
+        mock_response = mocker.MagicMock()
+        mock_response.points = []
+        mock_client.query_points.return_value = mock_response
+
+        node = RecommendStmt(
+            collection="notes",
+            positive_ids=("a",),
+            limit=5,
+            with_clause=SearchWith(
+                indexed_only=True,
+                quantization=QuantizationSearchWith(rescore=True),
+            ),
+        )
+        executor.execute(node)
+
+        search_params = mock_client.query_points.call_args.kwargs["search_params"]
+        assert search_params.indexed_only is True
+        assert search_params.quantization is not None
+        assert search_params.quantization.rescore is True
+
     def test_recommend_with_mmr_raises(self, executor, mock_client):
         mock_client.collection_exists.return_value = True
         node = RecommendStmt(

tests/test_parser.py

@@ -22,6 +22,7 @@
     NotInExpr,
     OrExpr,
     QuantizationType,
+    QuantizationSearchWith,
     RecommendStmt,
     SelectStmt,
     ScrollStmt,
@@ -892,6 +893,22 @@ def test_with_acorn(self):
         assert node.with_clause is not None
         assert node.with_clause.acorn is True
 
+    def test_with_indexed_only(self):
+        node = parse("SEARCH col SIMILAR TO 'q' LIMIT 5 WITH { indexed_only: true }")
+        assert node.with_clause is not None
+        assert node.with_clause.indexed_only is True
+
+    def test_with_quantization(self):
+        node = parse(
+            "SEARCH col SIMILAR TO 'q' LIMIT 5 "
+            "WITH { quantization: { ignore: true, rescore: false, oversampling: 2 } }"
+        )
+        assert node.with_clause is not None
+        assert node.with_clause.quantization is not None
+        assert node.with_clause.quantization.ignore is True
+        assert node.with_clause.quantization.rescore is False
+        assert node.with_clause.quantization.oversampling == pytest.approx(2.0)
+
     def test_with_multiple_params(self):
         node = parse(
             "SEARCH col SIMILAR TO 'q' LIMIT 5 WITH { hnsw_ef: 256, acorn: true }"
@@ -946,6 +963,10 @@ def test_with_mmr_candidates_non_positive_raises(self):
         with pytest.raises(QQLSyntaxError, match="mmr_candidates must be a positive integer"):
             parse("SEARCH col SIMILAR TO 'q' LIMIT 5 WITH { mmr_candidates: 0 }")
 
+    def test_with_quantization_unknown_key_raises(self):
+        with pytest.raises(QQLSyntaxError):
+            parse("SEARCH col SIMILAR TO 'q' LIMIT 5 WITH { quantization: { unknown: true } }")
+
     def test_with_trailing_comma(self):
         node = parse("SEARCH col SIMILAR TO 'q' LIMIT 5 WITH { hnsw_ef: 256, }")
         assert node.with_clause.hnsw_ef == 256