From 1673176f16fba92d2b49fc2b56318996924956e0 Mon Sep 17 00:00:00 2001
From: Gatefixer <313497061+lancedb-gatefixer[bot]@users.noreply.github.com>
Date: Thu, 6 Aug 2026 03:27:12 +0000
Subject: [PATCH] fix(python): type structured searches as fts

---
 python/python/lancedb/table.py             | 20 ++++-------
 python/python/typing_tests/table_search.py | 42 +++++++++++++++++++++-
 2 files changed, 47 insertions(+), 15 deletions(-)

diff --git a/python/python/lancedb/table.py b/python/python/lancedb/table.py
index adceb83a6..eac80d2c8 100644
--- a/python/python/lancedb/table.py
+++ b/python/python/lancedb/table.py
@@ -1375,7 +1375,7 @@ class Table(ABC):
         self,
         query: FullTextQuery,
         vector_column_name: Optional[str] = None,
-        query_type: Literal["auto"] = "auto",
+        query_type: QueryType = "auto",
         ordering_field_name: Optional[str] = None,
         fts_columns: Optional[Union[str, List[str]]] = None,
     ) -> LanceFtsQueryBuilder: ...
@@ -1413,9 +1413,7 @@ class Table(ABC):
     @overload
     def search(
         self,
-        query: Optional[
-            Union[VEC, str, "PIL.Image.Image", Tuple, FullTextQuery]
-        ] = None,
+        query: Optional[Union[VEC, str, "PIL.Image.Image", Tuple]] = None,
         vector_column_name: Optional[str] = None,
         query_type: Literal["hybrid"] = "hybrid",
         ordering_field_name: Optional[str] = None,
@@ -1425,9 +1423,7 @@ class Table(ABC):
     @overload
     def search(
         self,
-        query: Optional[
-            Union[VEC, str, "PIL.Image.Image", Tuple, FullTextQuery]
-        ] = None,
+        query: Optional[Union[VEC, str, "PIL.Image.Image", Tuple]] = None,
         vector_column_name: Optional[str] = None,
         query_type: QueryType = "auto",
         ordering_field_name: Optional[str] = None,
@@ -3492,7 +3488,7 @@ class LanceTable(Table):
         self,
         query: FullTextQuery,
         vector_column_name: Optional[str] = None,
-        query_type: Literal["auto"] = "auto",
+        query_type: QueryType = "auto",
         ordering_field_name: Optional[str] = None,
         fts_columns: Optional[Union[str, List[str]]] = None,
     ) -> LanceFtsQueryBuilder: ...
@@ -3530,9 +3526,7 @@ class LanceTable(Table):
     @overload
     def search(
         self,
-        query: Optional[
-            Union[VEC, str, "PIL.Image.Image", Tuple, FullTextQuery]
-        ] = None,
+        query: Optional[Union[VEC, str, "PIL.Image.Image", Tuple]] = None,
         vector_column_name: Optional[str] = None,
         query_type: Literal["hybrid"] = "hybrid",
         ordering_field_name: Optional[str] = None,
@@ -3542,9 +3536,7 @@ class LanceTable(Table):
     @overload
     def search(
         self,
-        query: Optional[
-            Union[VEC, str, "PIL.Image.Image", Tuple, FullTextQuery]
-        ] = None,
+        query: Optional[Union[VEC, str, "PIL.Image.Image", Tuple]] = None,
         vector_column_name: Optional[str] = None,
         query_type: QueryType = "auto",
         ordering_field_name: Optional[str] = None,
diff --git a/python/python/typing_tests/table_search.py b/python/python/typing_tests/table_search.py
index a21206c13..61da86cc9 100644
--- a/python/python/typing_tests/table_search.py
+++ b/python/python/typing_tests/table_search.py
@@ -5,15 +5,22 @@ from typing import assert_type
 
 from lancedb.db import DBConnection
 from lancedb.query import (
+    FullTextQuery,
     LanceEmptyQueryBuilder,
     LanceFtsQueryBuilder,
     LanceHybridQueryBuilder,
     LanceVectorQueryBuilder,
 )
 from lancedb.table import LanceTable
+from lancedb.types import QueryType
 
 
-def check_table_search_types(connection: DBConnection, lance_table: LanceTable) -> None:
+def check_table_search_types(
+    connection: DBConnection,
+    lance_table: LanceTable,
+    full_text_query: FullTextQuery,
+    query_type: QueryType,
+) -> None:
     table = connection.open_table("table")
 
     assert_type(table.search(), LanceEmptyQueryBuilder)
@@ -33,3 +40,36 @@ def check_table_search_types(connection: DBConnection, lance_table: LanceTable)
         lance_table.search("query"),
         LanceFtsQueryBuilder | LanceVectorQueryBuilder,
     )
+
+    assert_type(table.search(full_text_query), LanceFtsQueryBuilder)
+    assert_type(table.search(full_text_query, query_type="auto"), LanceFtsQueryBuilder)
+    assert_type(
+        table.search(full_text_query, query_type="vector"), LanceFtsQueryBuilder
+    )
+    assert_type(table.search(full_text_query, query_type="fts"), LanceFtsQueryBuilder)
+    assert_type(
+        table.search(full_text_query, query_type="hybrid"), LanceFtsQueryBuilder
+    )
+    assert_type(
+        table.search(full_text_query, query_type=query_type), LanceFtsQueryBuilder
+    )
+
+    assert_type(lance_table.search(full_text_query), LanceFtsQueryBuilder)
+    assert_type(
+        lance_table.search(full_text_query, query_type="auto"), LanceFtsQueryBuilder
+    )
+    assert_type(
+        lance_table.search(full_text_query, query_type="vector"),
+        LanceFtsQueryBuilder,
+    )
+    assert_type(
+        lance_table.search(full_text_query, query_type="fts"), LanceFtsQueryBuilder
+    )
+    assert_type(
+        lance_table.search(full_text_query, query_type="hybrid"),
+        LanceFtsQueryBuilder,
+    )
+    assert_type(
+        lance_table.search(full_text_query, query_type=query_type),
+        LanceFtsQueryBuilder,
+    )