perf(core): rank search by id and fetch note text for returned rows only (#1755)

Signed-off-by: phernandez <paul@basicmachines.co>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: phernandez

src/basic_memory/repository/postgres_search_query.py

@@ -31,6 +31,7 @@
     SearchIndexKey,
     SearchIndexRow,
     capped_snippet_columns,
+    snippet_length_columns,
 )
 from basic_memory.repository.search_query import (
     PreparedSearchQuery,
@@ -48,8 +49,10 @@
 # tsquery special characters that must not reach the parser as text.
 _TSQUERY_SPECIAL_CHARS = ("&", "|", "!", "(", ")", ":")
 
-# Every FTS statement returns these columns plus a score.
-_RESULT_COLUMNS = f"""
+
+def _result_columns(text_columns: str) -> str:
+    """The columns every FTS statement returns, plus a score."""
+    return f"""
                 search_index.project_id,
                 search_index.id,
                 search_index.title,
@@ -61,7 +64,7 @@
                 search_index.to_id,
                 search_index.relation_type,
                 search_index.entity_id,
-                {capped_snippet_columns("search_index")},
+                {text_columns},
                 search_index.category,
                 search_index.created_at,
                 search_index.updated_at"""
@@ -712,6 +715,7 @@ async def search(
         session: AsyncSession | None = None,
         candidate_keys: Sequence[SearchIndexKey] | None = None,
         trace: SearchTraceCollector | None = None,
+        with_text: bool = True,
     ) -> list[SearchIndexRow]:
         """Run one tsquery page, retrying a malformed or empty strict query relaxed."""
         search_text = query.search_text
@@ -721,9 +725,14 @@ async def search(
         params = compiled.params
         params["limit"] = limit
         params["offset"] = offset
+        text_columns = (
+            capped_snippet_columns("search_index")
+            if with_text
+            else snippet_length_columns("search_index")
+        )
 
         sql = f"""
-            SELECT{_RESULT_COLUMNS},
+            SELECT{_result_columns(text_columns)},
                 {compiled.score_expression} as score
             FROM {compiled.from_clause}
             WHERE {compiled.where_clause}

src/basic_memory/repository/search_filters.py

@@ -90,7 +90,15 @@ async def search(
         session: AsyncSession | None = None,
         candidate_keys: Sequence[SearchIndexKey] | None = None,
         trace: SearchTraceCollector | None = None,
-    ) -> list[SearchIndexRow]: ...
+        with_text: bool = True,
+    ) -> list[SearchIndexRow]:
+        """Run one full-text page.
+
+        ``with_text=False`` returns rows without note text (``content_snippet`` is None,
+        ``content_snippet_length`` set), for callers that rank first and fetch the text
+        of the rows they keep.
+        """
+        ...
 
     async def count(
         self,

src/basic_memory/repository/search_index_row.py

@@ -20,6 +20,16 @@
 SNIPPET_READ_LIMIT = 4000
 
 
+def snippet_length_columns(table: str) -> str:
+    """SELECT columns carrying no note text, only the stored content_snippet's length.
+
+    Ranking reads ids and scores; the text of the rows a search returns is fetched once
+    they are known (#1746). The length still answers content_length and the small-note
+    rule before that text arrives.
+    """
+    return f"NULL AS content_snippet, length({table}.content_snippet) AS content_snippet_length"
+
+
 def capped_snippet_columns(table: str) -> str:
     """SELECT columns carrying a capped content_snippet and the stored text's length."""
     return (