Library Query System
Relevant source files
The following files were used as context for generating this wiki page:
The Library Query System manages the retrieval, filtering, and sorting of music tracks within the DJ Assistant application. It utilizes a hybrid execution model where complex multi-parameter filtering and sorting occur server-side in SQL, while free-text searching occurs client-side for immediate user feedback. This system ensures high performance across large music libraries by leveraging a dedicated Rust-based query builder and SQLite's Write-Ahead Logging (WAL) mode.
Sources: CHANGELOG.md:15-25, README.md:188-210
Architecture and Data Flow
The system operates across the React frontend and the Rust core. The frontend normalizes user-defined filters before sending them across the Inter-Process Communication (IPC) bridge. The Rust core receives these structured requests and builds a parameterized SQL query to prevent injection and optimize execution.
Query Processing Flow
The following diagram illustrates the path of a library query from the User Interface to the local database.
A flowchart showing the end-to-end data flow from the UI interaction to the SQLite database and back.
Sources: apps/desktop/src/App.tsx:270-300, apps/desktop/src/lib/library.ts:48-90
Filtering and Sorting Logic
The system supports structured filtering across several track attributes. Filters are grouped logically, and the system counts active filter groups to provide UI feedback.
Supported Filter Criteria
| Filter Group | Attribute | Description |
|---|---|---|
| BPM | bpmMin, bpmMax | Filters tracks within a specific tempo range. |
| Key | keyCamelot | Filters based on one or more Camelot wheel codes (e.g., 8A, 9B). |
| Status | analysisStatus | Filters by analysis state (pending, complete, failed, needs_review). |
| Genre | genre | Filters by associated genre tags found in metadata. |
| Rating | ratingMin | Filters tracks with a star rating equal to or higher than the target. |
Sources: apps/desktop/src/lib/library.ts:48-90, apps/desktop/src/App.tsx:135-250
Server-Side Sorting
The system applies sorting server-side to ensure that paginated results remain consistent. The list_tracks command accepts sortBy and sortDir parameters. By default, the system sorts by imported_at in descending order to show the newest tracks first.
A sequence diagram depicting how a sort request initiated in the UI is processed by the Rust backend.
Sources: apps/desktop/src/App.tsx:327-340, apps/desktop/src/lib/library.ts:160-165
Data Persistence and Schema
The query system operates against the tracks table. Indexing is applied to high-frequency query columns to maintain performance as the library grows.
Database Indexing Strategy
The schema includes specific indices to accelerate the Library Query System:
idx_tracks_file_hash: Optimizes deduplication checks during scans.idx_tracks_artist_title: Accelerates sorting and filtering by primary metadata.idx_tracks_analysis_status: Speeds up filtering for the analysis pipeline.
Sources: apps/desktop/src-tauri/migrations/001_initial_schema.sql:39-41
Data Structure Relationship
The system manages relationships between tracks, their associated cue points, and skill execution history.
An Entity-Relationship diagram showing how tracks relate to workspaces and secondary data structures like cue points and skill runs.
Sources: apps/desktop/src-tauri/migrations/001_initial_schema.sql:4-60
Implementation Details
Filter Normalization
Before sending a query to the backend, the frontend performs normalization via normalizeFilters. This process:
- Trims whitespace from string inputs.
- Canonicalizes Camelot keys to uppercase (e.g.,
8ato8A). - Removes non-finite numeric bounds.
- Drops empty filter lists to reduce IPC payload size.
Sources: apps/desktop/src/lib/library.ts:48-75
Client-Side Search
While heavy filtering happens in SQL, the free-text search box uses the filterTracks helper. This function performs a case-insensitive match against the title, artist, album, and filePath of the tracks already loaded in the current view. This provides sub-millisecond updates as the user types without requiring repeated database hits.
Sources: apps/desktop/src/lib/library.ts:182-195, apps/desktop/src/App.tsx:355-365
Summary
The Library Query System is a performance-critical module that balances the power of SQLite for structured data retrieval with the responsiveness of React for user interaction. By using a server-side query builder in Rust and strictly typed IPC contracts, it provides a secure and scalable foundation for DJ library management.
Sources: README.md:130-145, CHANGELOG.md:15-25