Merge branch 'main' into custom-functions

Author: stephencelis

Sources/StructuredQueriesCore/QueryFragment.swift

@@ -150,6 +150,7 @@ extension QueryFragment: ExpressibleByStringInterpolation {
     }
 
     public mutating func appendLiteral(_ literal: String) {
+      guard !literal.isEmpty else { return }
       segments.append(.sql(literal))
     }
 
@@ -183,7 +184,7 @@ extension QueryFragment: ExpressibleByStringInterpolation {
     ///
     /// - Parameter sql: A raw query string.
     public mutating func appendInterpolation(raw sql: String) {
-      segments.append(.sql(sql))
+      appendLiteral(sql)
     }
 
     /// Append a raw lossless string to the interpolation.
@@ -200,7 +201,7 @@ extension QueryFragment: ExpressibleByStringInterpolation {
     ///
     /// - Parameter sql: A raw query string.
     public mutating func appendInterpolation(raw sql: some LosslessStringConvertible) {
-      segments.append(.sql(sql.description))
+      appendLiteral(sql.description)
     }
 
     /// Append a query binding to the interpolation.

Sources/StructuredQueriesCore/SQLite/FTS5.swift

@@ -2,17 +2,73 @@ import IssueReporting
 
 /// A virtual table using the FTS5 extension.
 ///
-/// Apply this protocol to a `@Table` declaration to introduce FTS5 helpers.
+/// Apply this protocol to a `@Table` declaration to introduce [FTS5] helpers.
+///
+/// [FTS5]: https://www.sqlite.org/fts5.html
 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
   /// ReminderText.where { $0.match("get") }
   /// // SELECT … FROM "reminderTexts" WHERE ("reminderTexts" MATCH 'get')
   /// ```
   ///
+  /// > Important: Avoid passing a string entered by the user directly to this operator. FTS5
+  /// > queries have a distinct [syntax] that can specify particular columns and refine a search in
+  /// > various ways. If FTS5 is given a query with invalid syntax, it can even throw SQL errors at
+  /// > runtime.
+  /// >
+  /// > Instead, consider transforming the user's input into a query by quoting, prefixing, and/or
+  /// > combining inputs from your UI into a valid query before handing it off to SQLite.
+  ///
+  /// [syntax]: https://www.sqlite.org/fts5.html#full_text_query_syntax
+  ///
   /// - Parameter pattern: A string expression describing the `MATCH` pattern.
   /// - Returns: A predicate expression.
   public func match(_ pattern: some StringProtocol) -> some QueryExpression<Bool> {
@@ -60,7 +116,7 @@ extension TableColumnExpression where Root: FTS5 {
   ///
   /// ```swift
   /// ReminderText.where { $0.title.match("get") }
-  /// // SELECT … FROM "reminderTexts" WHERE ("reminderTexts"."title" MATCH '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: ""                     │
+        │ )                              │
+        └────────────────────────────────┘
+        """
+      }
+    }
   }
 }