feat(subsonic): sort search3 results by relevance (#5086)

* fix(subsonic): optimize search3 for high-cardinality FTS queries

Use a two-phase query strategy for FTS5 searches to avoid the
performance penalty of expensive LEFT JOINs (annotation, bookmark,
library) on high-cardinality results like "the".

Phase 1 runs a lightweight query (main table + FTS index only) to get
sorted, paginated rowids. Phase 2 hydrates only those few rowids with
the full JOINs, making them nearly free.

For queries with complex ORDER BY expressions that reference joined
tables (e.g. artist search sorted by play count), the optimization is
skipped and the original single-query approach is used.

* fix(search): update order by clauses to include 'rank' for FTS queries

Signed-off-by: Deluan <deluan@navidrome.org>

* fix(search): reintroduce 'rank' in Phase 2 ORDER BY for FTS queries

Signed-off-by: Deluan <deluan@navidrome.org>

* fix(search): remove 'rank' from ORDER BY in non-FTS queries and adjust two-phase query handling

Signed-off-by: Deluan <deluan@navidrome.org>

* fix(search): update FTS ranking to use bm25 weights and simplify ORDER BY qualification

Signed-off-by: Deluan <deluan@navidrome.org>

* fix(search): refine FTS query handling and improve comments for clarity

Signed-off-by: Deluan <deluan@navidrome.org>

* fix(search): refactor full-text search handling to streamline query strategy selection and improve LIKE fallback logic.

Increase e2e coverage for search3

Signed-off-by: Deluan <deluan@navidrome.org>

* refactor: enhance FTS column definitions and relevance weights

Signed-off-by: Deluan <deluan@navidrome.org>

* fix(search): refactor Search method signatures to remove offset and size parameters, streamline query handling

Signed-off-by: Deluan <deluan@navidrome.org>

* fix(search): allow single-character queries in search strategies and update related tests

Signed-off-by: Deluan <deluan@navidrome.org>

* fix(search): make FTS Phase 1 treat Max=0 as no limit, reorganize tests

FTS Phase 1 unconditionally called Limit(uint64(options.Max)), which
produced LIMIT 0 when Max was zero. This diverged from applyOptions
where Max=0 means no limit. Now Phase 1 mirrors applyOptions: only add
LIMIT/OFFSET when the value is positive. Also moved legacy backend
integration tests from sql_search_fts_test.go to sql_search_like_test.go
and added regression tests for the Max=0 behavior on both backends.

* refactor: simplify callSearch function by removing variadic options and directly using QueryOptions

Signed-off-by: Deluan <deluan@navidrome.org>

* fix(search): implement ftsQueryDegraded function to detect significant content loss in FTS queries

Signed-off-by: Deluan <deluan@navidrome.org>

---------

Signed-off-by: Deluan <deluan@navidrome.org>

server/e2e/e2e_suite_test.go

@@ -115,6 +115,7 @@ func buildTestFS() storagetest.FakeFS {
 	ledZepIV := template(_t{"albumartist": "Led Zeppelin", "artist": "Led Zeppelin", "album": "IV", "year": 1971, "genre": "Rock"})
 	kindOfBlue := template(_t{"albumartist": "Miles Davis", "artist": "Miles Davis", "album": "Kind of Blue", "year": 1959, "genre": "Jazz"})
 	popTrack := template(_t{"albumartist": "Various", "artist": "Various", "album": "Pop", "year": 2020, "genre": "Pop"})
+	cowboyBebop := template(_t{"albumartist": "シートベルツ", "artist": "シートベルツ", "album": "COWBOY BEBOP", "year": 1998, "genre": "Jazz"})
 
 	return createFS(fstest.MapFS{
 		// Rock / The Beatles / Abbey Road (with MBIDs)
@@ -132,6 +133,8 @@ func buildTestFS() storagetest.FakeFS {
 		"Jazz/Miles Davis/Kind of Blue/01 - So What.mp3": kindOfBlue(track(1, "So What")),
 		// Pop (standalone track, no MBIDs)
 		"Pop/01 - Standalone Track.mp3": popTrack(track(1, "Standalone Track")),
+		// CJK / シートベルツ / COWBOY BEBOP (Japanese artist, for CJK search tests)
+		"CJK/シートベルツ/COWBOY BEBOP/01 - プラチナ・ジェット.mp3": cowboyBebop(track(1, "プラチナ・ジェット")),
 		// _empty folder (directory with no audio)
 		"_empty/.keep": &fstest.MapFile{Data: []byte{}, ModTime: time.Now()},
 	})

server/e2e/subsonic_album_lists_test.go

@@ -19,7 +19,7 @@ var _ = Describe("Album List Endpoints", func() {
 
 			Expect(resp.Status).To(Equal(responses.StatusOK))
 			Expect(resp.AlbumList).ToNot(BeNil())
-			Expect(resp.AlbumList.Album).To(HaveLen(5))
+			Expect(resp.AlbumList.Album).To(HaveLen(6))
 		})
 
 		It("type=alphabeticalByName sorts albums by name", func() {
@@ -27,13 +27,14 @@ var _ = Describe("Album List Endpoints", func() {
 
 			Expect(resp.AlbumList).ToNot(BeNil())
 			albums := resp.AlbumList.Album
-			Expect(albums).To(HaveLen(5))
-			// Verify alphabetical order: Abbey Road, Help!, IV, Kind of Blue, Pop
+			Expect(albums).To(HaveLen(6))
+			// Verify alphabetical order: Abbey Road, COWBOY BEBOP, Help!, IV, Kind of Blue, Pop
 			Expect(albums[0].Title).To(Equal("Abbey Road"))
-			Expect(albums[1].Title).To(Equal("Help!"))
-			Expect(albums[2].Title).To(Equal("IV"))
-			Expect(albums[3].Title).To(Equal("Kind of Blue"))
-			Expect(albums[4].Title).To(Equal("Pop"))
+			Expect(albums[1].Title).To(Equal("COWBOY BEBOP"))
+			Expect(albums[2].Title).To(Equal("Help!"))
+			Expect(albums[3].Title).To(Equal("IV"))
+			Expect(albums[4].Title).To(Equal("Kind of Blue"))
+			Expect(albums[5].Title).To(Equal("Pop"))
 		})
 
 		It("type=alphabeticalByArtist sorts albums by artist name", func() {
@@ -41,29 +42,32 @@ var _ = Describe("Album List Endpoints", func() {
 
 			Expect(resp.AlbumList).ToNot(BeNil())
 			albums := resp.AlbumList.Album
-			Expect(albums).To(HaveLen(5))
+			Expect(albums).To(HaveLen(6))
 			// Articles like "The" are stripped for sorting, so "The Beatles" sorts as "Beatles"
-			// Non-compilations first: Beatles (x2), Led Zeppelin, Miles Davis, then compilations: Various
+			// Non-compilations first: Beatles (x2), Led Zeppelin, Miles Davis, then compilations: Various, then CJK: シートベルツ
 			Expect(albums[0].Artist).To(Equal("The Beatles"))
 			Expect(albums[1].Artist).To(Equal("The Beatles"))
 			Expect(albums[2].Artist).To(Equal("Led Zeppelin"))
 			Expect(albums[3].Artist).To(Equal("Miles Davis"))
 			Expect(albums[4].Artist).To(Equal("Various"))
+			Expect(albums[5].Artist).To(Equal("シートベルツ"))
 		})
 
 		It("type=random returns albums", func() {
 			resp := doReq("getAlbumList", "type", "random")
 
 			Expect(resp.AlbumList).ToNot(BeNil())
-			Expect(resp.AlbumList.Album).To(HaveLen(5))
+			Expect(resp.AlbumList.Album).To(HaveLen(6))
 		})
 
 		It("type=byGenre filters by genre parameter", func() {
 			resp := doReq("getAlbumList", "type", "byGenre", "genre", "Jazz")
 
 			Expect(resp.AlbumList).ToNot(BeNil())
-			Expect(resp.AlbumList.Album).To(HaveLen(1))
-			Expect(resp.AlbumList.Album[0].Title).To(Equal("Kind of Blue"))
+			Expect(resp.AlbumList.Album).To(HaveLen(2))
+			for _, a := range resp.AlbumList.Album {
+				Expect(a.Genre).To(Equal("Jazz"))
+			}
 		})
 
 		It("type=byYear filters by fromYear/toYear range", func() {
@@ -184,7 +188,7 @@ var _ = Describe("Album List Endpoints", func() {
 			Expect(resp.Status).To(Equal(responses.StatusOK))
 			Expect(resp.AlbumList2).ToNot(BeNil())
 			albums := resp.AlbumList2.Album
-			Expect(albums).To(HaveLen(5))
+			Expect(albums).To(HaveLen(6))
 			// Verify AlbumID3 format fields
 			Expect(albums[0].Name).To(Equal("Abbey Road"))
 			Expect(albums[0].Id).ToNot(BeEmpty())
@@ -195,7 +199,7 @@ var _ = Describe("Album List Endpoints", func() {
 			resp := doReq("getAlbumList2", "type", "newest")
 
 			Expect(resp.AlbumList2).ToNot(BeNil())
-			Expect(resp.AlbumList2.Album).To(HaveLen(5))
+			Expect(resp.AlbumList2.Album).To(HaveLen(6))
 		})
 	})
 
@@ -240,7 +244,7 @@ var _ = Describe("Album List Endpoints", func() {
 			Expect(resp.Status).To(Equal(responses.StatusOK))
 			Expect(resp.RandomSongs).ToNot(BeNil())
 			Expect(resp.RandomSongs.Songs).ToNot(BeEmpty())
-			Expect(len(resp.RandomSongs.Songs)).To(BeNumerically("<=", 6))
+			Expect(resp.RandomSongs.Songs).To(HaveLen(7))
 		})
 
 		It("respects size parameter", func() {
@@ -254,8 +258,10 @@ var _ = Describe("Album List Endpoints", func() {
 			resp := doReq("getRandomSongs", "size", "500", "genre", "Jazz")
 
 			Expect(resp.RandomSongs).ToNot(BeNil())
-			Expect(resp.RandomSongs.Songs).To(HaveLen(1))
-			Expect(resp.RandomSongs.Songs[0].Genre).To(Equal("Jazz"))
+			Expect(resp.RandomSongs.Songs).To(HaveLen(2))
+			for _, s := range resp.RandomSongs.Songs {
+				Expect(s.Genre).To(Equal("Jazz"))
+			}
 		})
 	})
 

server/e2e/subsonic_browsing_test.go

@@ -327,8 +327,8 @@ var _ = Describe("Browsing Endpoints", func() {
 				}
 			}
 			Expect(jazzGenre).ToNot(BeNil())
-			Expect(jazzGenre.SongCount).To(Equal(int32(1)))
-			Expect(jazzGenre.AlbumCount).To(Equal(int32(1)))
+			Expect(jazzGenre.SongCount).To(Equal(int32(2)))
+			Expect(jazzGenre.AlbumCount).To(Equal(int32(2)))
 		})
 
 		It("reports correct song and album counts for Pop", func() {

server/e2e/subsonic_multilibrary_test.go

@@ -141,7 +141,7 @@ var _ = Describe("Multi-Library Support", Ordered, func() {
 			resp := doReqWithUser(adminWithLibs, "getAlbumList", "type", "alphabeticalByName", "musicFolderId", fmt.Sprintf("%d", lib.ID))
 
 			Expect(resp.AlbumList).ToNot(BeNil())
-			Expect(resp.AlbumList.Album).To(HaveLen(5))
+			Expect(resp.AlbumList.Album).To(HaveLen(6))
 			for _, a := range resp.AlbumList.Album {
 				Expect(a.Title).ToNot(Equal("Symphony No. 9"))
 			}
@@ -275,5 +275,21 @@ var _ = Describe("Multi-Library Support", Ordered, func() {
 			Expect(artistNames).To(ContainElements("The Beatles", "Led Zeppelin", "Miles Davis"))
 			Expect(artistNames).ToNot(ContainElement("Ludwig van Beethoven"))
 		})
+
+		It("non-admin user search returns only their library's content", func() {
+			resp := doReqWithUser(userLib1Only, "search3", "query", "Beethoven")
+
+			Expect(resp.SearchResult3).ToNot(BeNil())
+			Expect(resp.SearchResult3.Artist).To(BeEmpty(), "userLib1Only should not see Beethoven (lib2)")
+			Expect(resp.SearchResult3.Album).To(BeEmpty())
+			Expect(resp.SearchResult3.Song).To(BeEmpty())
+		})
+
+		It("non-admin user search finds content from their library", func() {
+			resp := doReqWithUser(userLib1Only, "search3", "query", "Beatles")
+
+			Expect(resp.SearchResult3).ToNot(BeNil())
+			Expect(resp.SearchResult3.Artist).ToNot(BeEmpty(), "userLib1Only should find Beatles (lib1)")
+		})
 	})
 })

server/e2e/subsonic_searching_test.go

@@ -2,6 +2,8 @@ package e2e
 
 import (
 	"github.com/google/uuid"
+	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/server/subsonic/responses"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -113,9 +115,9 @@ var _ = Describe("Search Endpoints", func() {
 
 			Expect(resp.Status).To(Equal(responses.StatusOK))
 			Expect(resp.SearchResult3).ToNot(BeNil())
-			Expect(resp.SearchResult3.Artist).To(HaveLen(4))
-			Expect(resp.SearchResult3.Album).To(HaveLen(5))
-			Expect(resp.SearchResult3.Song).To(HaveLen(6))
+			Expect(resp.SearchResult3.Artist).To(HaveLen(5))
+			Expect(resp.SearchResult3.Album).To(HaveLen(6))
+			Expect(resp.SearchResult3.Song).To(HaveLen(7))
 		})
 
 		It("finds across all entity types simultaneously", func() {
@@ -217,5 +219,56 @@ var _ = Describe("Search Endpoints", func() {
 				Expect(resp.SearchResult3.Song).To(BeEmpty())
 			})
 		})
+
+		Describe("CJK search", func() {
+			It("finds songs by CJK title", func() {
+				resp := doReq("search3", "query", "プラチナ")
+
+				Expect(resp.Status).To(Equal(responses.StatusOK))
+				Expect(resp.SearchResult3).ToNot(BeNil())
+				Expect(resp.SearchResult3.Song).To(HaveLen(1))
+				Expect(resp.SearchResult3.Song[0].Title).To(Equal("プラチナ・ジェット"))
+			})
+
+			It("finds artists by CJK name", func() {
+				resp := doReq("search3", "query", "シートベルツ")
+
+				Expect(resp.Status).To(Equal(responses.StatusOK))
+				Expect(resp.SearchResult3).ToNot(BeNil())
+				Expect(resp.SearchResult3.Artist).To(HaveLen(1))
+				Expect(resp.SearchResult3.Artist[0].Name).To(Equal("シートベルツ"))
+			})
+
+			It("finds albums by CJK artist name", func() {
+				resp := doReq("search3", "query", "シートベルツ")
+
+				Expect(resp.Status).To(Equal(responses.StatusOK))
+				Expect(resp.SearchResult3).ToNot(BeNil())
+				Expect(resp.SearchResult3.Album).To(HaveLen(1))
+				Expect(resp.SearchResult3.Album[0].Name).To(Equal("COWBOY BEBOP"))
+			})
+		})
+
+		Describe("Legacy backend", func() {
+			It("returns results using legacy LIKE-based search when configured", func() {
+				DeferCleanup(configtest.SetupConfig())
+				conf.Server.Search.Backend = "legacy"
+
+				resp := doReq("search3", "query", "Beatles")
+
+				Expect(resp.Status).To(Equal(responses.StatusOK))
+				Expect(resp.SearchResult3).ToNot(BeNil())
+				Expect(resp.SearchResult3.Artist).ToNot(BeEmpty())
+
+				found := false
+				for _, a := range resp.SearchResult3.Artist {
+					if a.Name == "The Beatles" {
+						found = true
+						break
+					}
+				}
+				Expect(found).To(BeTrue(), "expected to find artist 'The Beatles' with legacy backend")
+			})
+		})
 	})
 })

server/subsonic/searching.go

@@ -42,17 +42,17 @@ func (api *Router) getSearchParams(r *http.Request) (*searchParams, error) {
 	return sp, nil
 }
 
-type searchFunc[T any] func(q string, offset int, size int, options ...model.QueryOptions) (T, error)
+type searchFunc[T any] func(q string, options ...model.QueryOptions) (T, error)
 
-func callSearch[T any](ctx context.Context, s searchFunc[T], q string, offset, size int, result *T, options ...model.QueryOptions) func() error {
+func callSearch[T any](ctx context.Context, s searchFunc[T], q string, options model.QueryOptions, result *T) func() error {
 	return func() error {
-		if size == 0 {
+		if options.Max == 0 {
 			return nil
 		}
 		typ := strings.TrimPrefix(reflect.TypeOf(*result).String(), "model.")
 		var err error
 		start := time.Now()
-		*result, err = s(q, offset, size, options...)
+		*result, err = s(q, options)
 		if err != nil {
 			log.Error(ctx, "Error searching "+typ, "query", q, "elapsed", time.Since(start), err)
 		} else {
@@ -66,27 +66,22 @@ func (api *Router) searchAll(ctx context.Context, sp *searchParams, musicFolderI
 	start := time.Now()
 	q := sanitize.Accents(strings.ToLower(strings.TrimSuffix(sp.query, "*")))
 
-	// Create query options for library filtering
-	var options []model.QueryOptions
-	var artistOptions []model.QueryOptions
+	// Build options with offset/size/filters packed in
+	songOpts := model.QueryOptions{Max: sp.songCount, Offset: sp.songOffset}
+	albumOpts := model.QueryOptions{Max: sp.albumCount, Offset: sp.albumOffset}
+	artistOpts := model.QueryOptions{Max: sp.artistCount, Offset: sp.artistOffset}
+
 	if len(musicFolderIds) > 0 {
-		// For MediaFiles and Albums, use direct library_id filter
-		options = append(options, model.QueryOptions{
-			Filters: Eq{"library_id": musicFolderIds},
-		})
-		// For Artists, use the repository's built-in library filtering mechanism
-		// which properly handles the library_artist table joins
-		// TODO Revisit library filtering in sql_base_repository.go
-		artistOptions = append(artistOptions, model.QueryOptions{
-			Filters: Eq{"library_artist.library_id": musicFolderIds},
-		})
+		songOpts.Filters = Eq{"library_id": musicFolderIds}
+		albumOpts.Filters = Eq{"library_id": musicFolderIds}
+		artistOpts.Filters = Eq{"library_artist.library_id": musicFolderIds}
 	}
 
 	// Run searches in parallel
 	g, ctx := errgroup.WithContext(ctx)
-	g.Go(callSearch(ctx, api.ds.MediaFile(ctx).Search, q, sp.songOffset, sp.songCount, &mediaFiles, options...))
-	g.Go(callSearch(ctx, api.ds.Album(ctx).Search, q, sp.albumOffset, sp.albumCount, &albums, options...))
-	g.Go(callSearch(ctx, api.ds.Artist(ctx).Search, q, sp.artistOffset, sp.artistCount, &artists, artistOptions...))
+	g.Go(callSearch(ctx, api.ds.MediaFile(ctx).Search, q, songOpts, &mediaFiles))
+	g.Go(callSearch(ctx, api.ds.Album(ctx).Search, q, albumOpts, &albums))
+	g.Go(callSearch(ctx, api.ds.Artist(ctx).Search, q, artistOpts, &artists))
 	err := g.Wait()
 	if err == nil {
 		log.Debug(ctx, fmt.Sprintf("Search resulted in %d songs, %d albums and %d artists",