FTS5: Add bm25 function (#147)

* Add type-safe bm25 function

* wip

* wip

* wip

* Fix docs

Author: stephencelis

Sources/StructuredQueriesCore/SQLite/FTS5.swift

@@ -8,6 +8,50 @@ import IssueReporting
 public protocol FTS5: Table {}
 
 extension TableDefinition where QueryValue: FTS5 {
+  /// A BM25 ranking function for the given column-accuracy mapping.
+  ///
+  /// - Parameter rankings: A dictionary mapping columns to accuracy of a match.
+  /// - Returns: A BM25 ranking function.
+  public func bm25(
+    _ rankings: KeyValuePairs<PartialKeyPath<Self>, Double> = [:]
+  ) -> some QueryExpression<Double> {
+    var queryFragments: [QueryFragment] = ["\(QueryValue.self)"]
+    if !rankings.isEmpty {
+      var columnNameToRanking: QueryFragment = """
+        CASE "name"
+        """
+      for (keyPath, ranking) in rankings {
+        guard let column = self[keyPath: keyPath] as? any WritableTableColumnExpression
+        else {
+          reportIssue(
+            """
+            Key path cannot be used in 'bm25' function: \(keyPath)
+
+            Must be a key path to a table column on '\(QueryValue.self)'.
+            """
+          )
+          continue
+        }
+        columnNameToRanking.append(
+          """
+           WHEN \(bind: column.name) THEN \(ranking)
+          """
+        )
+      }
+      columnNameToRanking.append(" ELSE 1 END")
+      for offset in Self.writableColumns.indices {
+        queryFragments.append(
+          """
+          (SELECT \(columnNameToRanking) \
+          FROM pragma_table_info(\(quote: QueryValue.tableName, delimiter: .text)) \
+          WHERE "cid" = \(offset))
+          """
+        )
+      }
+    }
+    return SQLQueryExpression("bm25(\(queryFragments.joined(separator: ", ")))")
+  }
+
   /// A predicate expression from this table matched against another _via_ the `MATCH` operator.
   ///
   /// ```swift
@@ -72,7 +116,7 @@ extension TableColumnExpression where Root: FTS5 {
   ///
   /// ```swift
   /// ReminderText.where { $0.title.match("get") }
-  /// // SELECT … FROM "reminderTexts" WHERE ("reminderTexts" MATCH 'title:\"get\"')
+  /// // SELECT … FROM "reminderTexts" WHERE ("reminderTexts" MATCH 'title:"get"')
   /// ```
   ///
   /// - Parameter pattern: A string expression describing the `MATCH` pattern.

Tests/StructuredQueriesTests/FTSTests.swift

@@ -87,5 +87,57 @@ extension SnapshotTests {
       }
     }
 
+    @Test func bm25() {
+      assertQuery(
+        ReminderText
+          .where { $0.match("Week") }
+          .order { $0.bm25([\.title: 10, \.notes: 5, \.tags: 2]) }
+      ) {
+        """
+        SELECT "reminderTexts"."reminderID", "reminderTexts"."title", "reminderTexts"."notes", "reminderTexts"."listID", "reminderTexts"."listTitle", "reminderTexts"."tags"
+        FROM "reminderTexts"
+        WHERE ("reminderTexts" MATCH 'Week')
+        ORDER BY bm25("reminderTexts", (SELECT CASE "name" WHEN 'title' THEN 10.0 WHEN 'notes' THEN 5.0 WHEN 'tags' THEN 2.0 ELSE 1 END FROM pragma_table_info('reminderTexts') WHERE "cid" = 0), (SELECT CASE "name" WHEN 'title' THEN 10.0 WHEN 'notes' THEN 5.0 WHEN 'tags' THEN 2.0 ELSE 1 END FROM pragma_table_info('reminderTexts') WHERE "cid" = 1), (SELECT CASE "name" WHEN 'title' THEN 10.0 WHEN 'notes' THEN 5.0 WHEN 'tags' THEN 2.0 ELSE 1 END FROM pragma_table_info('reminderTexts') WHERE "cid" = 2), (SELECT CASE "name" WHEN 'title' THEN 10.0 WHEN 'notes' THEN 5.0 WHEN 'tags' THEN 2.0 ELSE 1 END FROM pragma_table_info('reminderTexts') WHERE "cid" = 3), (SELECT CASE "name" WHEN 'title' THEN 10.0 WHEN 'notes' THEN 5.0 WHEN 'tags' THEN 2.0 ELSE 1 END FROM pragma_table_info('reminderTexts') WHERE "cid" = 4), (SELECT CASE "name" WHEN 'title' THEN 10.0 WHEN 'notes' THEN 5.0 WHEN 'tags' THEN 2.0 ELSE 1 END FROM pragma_table_info('reminderTexts') WHERE "cid" = 5))
+        """
+      } results: {
+        """
+        ┌────────────────────────────────┐
+        │ ReminderText(                  │
+        │   reminderID: 10,              │
+        │   title: "Send weekly emails", │
+        │   notes: "",                   │
+        │   listID: 3,                   │
+        │   listTitle: "Business",       │
+        │   tags: ""                     │
+        │ )                              │
+        └────────────────────────────────┘
+        """
+      }
+      assertQuery(
+        ReminderText
+          .where { $0.match("Week") }
+          .order { $0.bm25() }
+      ) {
+        """
+        SELECT "reminderTexts"."reminderID", "reminderTexts"."title", "reminderTexts"."notes", "reminderTexts"."listID", "reminderTexts"."listTitle", "reminderTexts"."tags"
+        FROM "reminderTexts"
+        WHERE ("reminderTexts" MATCH 'Week')
+        ORDER BY bm25("reminderTexts")
+        """
+      } results: {
+        """
+        ┌────────────────────────────────┐
+        │ ReminderText(                  │
+        │   reminderID: 10,              │
+        │   title: "Send weekly emails", │
+        │   notes: "",                   │
+        │   listID: 3,                   │
+        │   listTitle: "Business",       │
+        │   tags: ""                     │
+        │ )                              │
+        └────────────────────────────────┘
+        """
+      }
+    }
   }
 }