bookclerk_search
Tantivy full-text search over the library's works.
Host library / GUI code that builds and queries the on-disk search index. Guest plugins do not depend on this crate.
Style: docs/contributing/code-documentation.md.
| Item | Kind | Summary |
|---|---|---|
WorkHit |
struct | One work a search found. |
WorkMatches |
struct | One window of a query's matches. |
WorkSearchIndex |
struct | On-disk Tantivy index of works. |
SavedFilter |
struct | A saved filter expression (Bookclerk quick-filter parity). |
SearchError |
enum | Errors from opening, writing, or querying the Tantivy index. |
Result |
type alias | Result alias for search index and query helpers in this crate. |
pub struct WorkHit {
pub work_id: String,
pub title: String,
pub score: f32,
}
One work a search found.
Fields
work_id: The top-level work's id.title: The work's title, as indexed.score: Tantivy relevance score; higher is a better match.
Implements: Clone, Debug, PartialEq
pub struct WorkMatches {
pub ids: Vec<String>,
pub total: usize,
}
One window of a query's matches.
Fields
ids: Work ids in the window, best match first.total: How many documents the query matches in all.
Implements: Clone, Debug, Eq, PartialEq
pub struct WorkSearchIndex {
/* private fields */
}
On-disk Tantivy index of works.
pub fn open(dir: &Path) -> Result<Self>
Opens or creates the works index in dir, replacing an index of
another layout.
Returns SearchError::Index when the directory or index cannot be
opened.
pub fn open_for_search(dir: &Path) -> Result<Self>
Opens the index in dir for searching only: nothing is created or
replaced, so a search never races a writer over the directory.
Returns SearchError::NotReady when dir holds no index of the
current layout (the rebuild has not run yet), or
SearchError::Index when it cannot be opened.
pub fn is_complete(dir: &Path) -> bool
True when a full rebuild of the current layout has finished in dir.
pub fn mark_incomplete(&self) -> Result<()>
Forgets that the index was fully rebuilt, so the daemon queues a new rebuild.
Returns SearchError::Index when the marker cannot be removed.
pub async fn refresh_works(
&self,
library: &LibraryStore,
work_ids: &[String],
) -> Result<usize>
Replaces the documents of work_ids with what the library holds
now: a held work's document is written again, and an unheld or
missing work's is removed.
How many documents were written.
Returns SearchError::Busy when another writer holds the index,
or the library or index error.
pub async fn rebuild(&self, library: &LibraryStore) -> Result<usize>
Rebuilds the whole index from the library, walking every top-level work in pages, then leaves the rebuild marker.
How many documents were written.
Returns SearchError::Busy when another writer holds the index,
or the library or index error.
pub async fn rebuild_waiting(
&self,
library: &LibraryStore,
max_wait: Duration,
) -> Result<usize>
Self::rebuild, waiting while another writer holds the index.
A running daemon refreshes this index from library events, and each
refresh holds the writer for a moment. A rebuild that finds the
index busy has written nothing, so it pauses (100 ms, doubling to
2 s) and tries again until max_wait has passed.
library- The library the works are read from.max_wait- How long to keep trying while the index is busy.
How many documents were written.
Returns SearchError::Busy when the index is still busy after
max_wait, and any other error of Self::rebuild at once.
pub async fn open_and_match_ids(
dir: PathBuf,
query: String,
offset: usize,
limit: usize,
) -> Result<WorkMatches>
Opens the index in dir for searching and reads one window of a
query's matches without blocking the caller's task (see
Self::open_for_search and Self::match_ids).
Propagates open and query failures.
pub fn match_ids(
&self,
raw_query: &str,
offset: usize,
limit: usize,
) -> Result<WorkMatches>
The work ids of the limit matches of raw_query after the first
offset, best first (ties in index order), and the total match
count. Only the window's documents are read. Blocking.
Returns SearchError::Query for a query that does not parse, or
SearchError::Index when the index cannot be read.
pub fn search(&self, raw_query: &str, limit: usize) -> Result<Vec<WorkHit>>
The best limit matches of raw_query with their titles, best
first; a limit of 0 returns every match. Blocking.
Returns SearchError::Query for a query that does not parse, or
SearchError::Index when the index cannot be read.
pub struct SavedFilter {
pub name: String,
pub query: String,
}
A saved filter expression (Bookclerk quick-filter parity).
Fields
name: Operator-facing display name for this saved filter.query: Lucene-style query string (normalized before parse).
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub enum SearchError {
Index(String),
Busy,
NotReady,
Query(String),
Library(LibraryError),
}
Errors from opening, writing, or querying the Tantivy index.
Variants
Index: Index open / writer / commit failure (operator-facing detail).Busy: Another writer (a rebuild, an event refresh, or the CLI) holds the index lock; the write can be retried shortly.NotReady: The index has not been built under the current layout yet; the daemon's rebuild job is building it.Query: Query parse failure after Lucene-style normalization.Library: Failure loading library rows while rebuilding the index.
Implements: Debug, Display, Error, From<LibraryError>
pub type Result<T> = Result<T, SearchError>;
Result alias for search index and query helpers in this crate.
Generated from crates/bookclerk-search at main · View as Markdown