From 381cc730e1f13bbf9b1d2d685dda0440afa2ccdc Mon Sep 17 00:00:00 2001
From: liunux4odoo <41217877+liunux4odoo@users.noreply.github.com>
Date: Tue, 7 May 2024 08:58:22 +0800
Subject: [PATCH 1/3] add `include_rank` parameter to `Table.search`

---
 sqlite_utils/db.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/sqlite_utils/db.py b/sqlite_utils/db.py
index 6332dc26e..27099d0c7 100644
--- a/sqlite_utils/db.py
+++ b/sqlite_utils/db.py
@@ -2641,6 +2641,7 @@ def search(
         offset: Optional[int] = None,
         where: Optional[str] = None,
         where_args: Optional[Union[Iterable, dict]] = None,
+        include_rank: bool = False,
         quote: bool = False,
     ) -> Generator[dict, None, None]:
         """
@@ -2654,6 +2655,7 @@ def search(
         :param offset: Optional integer SQL offset.
         :param where: Extra SQL fragment for the WHERE clause
         :param where_args: Arguments to use for :param placeholders in the extra WHERE clause
+        :param include_rank: Select the search rank column in the final query
         :param quote: Apply quoting to disable any special characters in the search query
 
         See :ref:`python_api_fts_search`.
@@ -2673,6 +2675,7 @@ def search(
                 limit=limit,
                 offset=offset,
                 where=where,
+                include_rank=include_rank,
             ),
             args,
         )

From 9a5256e2261b64bad41b0d1e3871fd3019deb073 Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Sat, 23 Nov 2024 12:27:08 -0800
Subject: [PATCH 2/3] Test for .search(include_rank)

Refs https://github.com/simonw/sqlite-utils/pull/628#issuecomment-2495644255
---
 tests/test_fts.py | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/tests/test_fts.py b/tests/test_fts.py
index ecfcff9db..a35b9eef1 100644
--- a/tests/test_fts.py
+++ b/tests/test_fts.py
@@ -1,6 +1,7 @@
 import pytest
 from sqlite_utils import Database
 from sqlite_utils.utils import sqlite3
+from unittest.mock import ANY
 
 search_records = [
     {
@@ -126,6 +127,32 @@ def test_search_where_args_disallows_query(fresh_db):
     )
 
 
+def test_search_include_rank(fresh_db):
+    table = fresh_db["t"]
+    table.insert_all(search_records)
+    table.enable_fts(["text", "country"], fts_version="FTS5")
+    results = list(table.search("are", include_rank=True))
+    assert results == [
+        {
+            "rowid": 1,
+            "text": "tanuki are running tricksters",
+            "country": "Japan",
+            "not_searchable": "foo",
+            "rank": ANY,
+        },
+        {
+            "rowid": 2,
+            "text": "racoons are biting trash pandas",
+            "country": "USA",
+            "not_searchable": "bar",
+            "rank": ANY,
+        },
+    ]
+    assert isinstance(results[0]["rank"], float)
+    assert isinstance(results[1]["rank"], float)
+    assert results[0]["rank"] < results[1]["rank"]
+
+
 def test_enable_fts_table_names_containing_spaces(fresh_db):
     table = fresh_db["test"]
     table.insert({"column with spaces": "in its name"})

From 513f22851f677264d66213adcdd74e4992aae17f Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Sat, 23 Nov 2024 12:29:57 -0800
Subject: [PATCH 3/3] Docs for table.search(include_rank)

Refs https://github.com/simonw/sqlite-utils/pull/628#issuecomment-2495644255
---
 docs/python-api.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/python-api.rst b/docs/python-api.rst
index 4b446bb74..2333d7f47 100644
--- a/docs/python-api.rst
+++ b/docs/python-api.rst
@@ -2308,6 +2308,9 @@ The ``.search()`` method also accepts the following optional parameters:
 ``where_args`` dictionary
     Arguments to use for ``:param`` placeholders in the extra WHERE clause
 
+``include_rank`` bool
+    If set a ``rank`` column will be included with the BM25 ranking score - for FTS5 tables only.
+
 ``quote`` bool
     Apply :ref:`FTS quoting rules <python_api_quote_fts>` to the search query, disabling advanced query syntax in a way that avoids surprising errors.