feat: full-text and faceted search API for samples

[brightpixel-dev]

Difficulty: Hard · Priority: Critical

Overview

listSamples() only supports exact-match genre/uploader filters and one fixed sort order — no text search, no price/BPM range, no relevance ranking. Add real search to the samples API.

Acceptance Criteria

• Query param for free-text search across title/genre with relevance ranking
• BPM range and price range filters, combinable with text search
• Sort options: relevance, newest, price asc/desc, most sold
• Stays performant as the table grows (indexed, not a full scan)

Technical Approach

Add a generated tsvector column + GIN index, rank with ts_rank/websearch_to_tsquery, combine with existing/extended range filters in one query. Layer onto the existing list endpoint rather than a new API surface.

Combining relevance ranking with multiple structured filters and pagination in one indexed query (without falling off the GIN index) is the hard part — every write path also has to keep the index in sync.

[mxrtins04]

Hi maintainer, can i be assigned this issue pleasee?

[Fabiana1504]

Hi! I’d like to take this issue. I have experience building backend APIs with PostgreSQL and search features, and I’d implement the full-text search on top of the existing endpoint while keeping it performant. I’ll combine relevance ranking, BPM and price range filters, sorting, pagination, and proper indexing with regression tests to ensure the query remains efficient as the dataset grows.

[grantfox-oss]

🦊 GrantFox — @Fabiana1504 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #21)
2. Your PR will be reviewed by the Crate-Protocol maintainers

Good luck! Track your progress on GrantFox.