Expand description
§smeltery-prospect
Prospect, the full-text search of the Smeltery framework: a model declares
which columns are searched (with weights), filtered and sorted; a search returns a page of hits that hold real
models, ranked, with highlights. The database driver uses the database’s own full-text search (SQLite FTS5,
PostgreSQL tsvector + GIN, MySQL / MariaDB FULLTEXT), which the database keeps current itself; no extra server.
Apps use it through the facade, as smeltery::prospect:
use smeltery::db::prelude::*;
use smeltery::prospect::{IndexSpec, Searchable, Weight};
#[sea_orm::model]
#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Serialize, Deserialize)]
#[sea_orm(table_name = "posts")]
pub struct Model {
#[sea_orm(primary_key)]
pub id: i64,
pub title: String,
pub body: String,
pub team_id: i64,
pub published: bool,
}
impl ActiveModelBehavior for ActiveModel {}
impl Searchable for Model {
fn index(i: &mut IndexSpec) {
i.text("title").weight(Weight::A);
i.text("body");
i.only_when("published");
i.scoped_by("team_id");
}
}
use smeltery::db::{Page, PageQuery};
use smeltery::prelude::*;
use smeltery::prospect::{Hit, Prospect, ProspectExt as _};
#[derive(serde::Deserialize)]
struct Search {
#[serde(default)]
q: String,
}
async fn index(prospect: Prospect, Query(s): Query<Search>, page: PageQuery) -> Result<Json<Page<Hit<Post>>>> {
let team = 1; // the signed-in user's team
Ok(Json(
Post::search(&prospect, &s.q)
.within(team)
.highlight(["title", "body"])
.paginate(page)
.await?,
))
}
fn build(app: AppBuilder) -> AppBuilder {
app.prospect(|p| {
p.model::<Post>();
})
.routes(|r| {
r.get("/posts", index).middleware("throttle:60,1");
})
}The index comes from a migration (smeltery::prospect::migration::SearchIndex), and user text is reduced to
letters-and-digits terms before it reaches any search grammar. The full guide, with the driver differences, is the
“Search” section of the Smeltery README.
§Licence
MIT OR Apache-2.0.
Modules§
- migration
SearchIndex: the migration helper that creates and drops a table’s full-text index for the database driver.- testing
- Test helpers: switch an app to the recording memory engine and assert what was indexed.
Structs§
- Highlight
- A highlighted text: segments in order. It never holds markup; a template renders each segment escaped and wraps
the matched ones in
<mark>. A Mold view gets the segments in a field of its struct (h.segments().to_vec(), aVec<Segment>namedtitlehere), since release builds compile field access: - Highlights
- The highlights of one hit, by column.
- Hit
- One search result: the model loaded from the database, its relevance score and its highlights.
- Index
Spec - What a model makes searchable; filled in
Searchable::index. - Models
- The registration of searchable models, inside
ProspectExt::prospect. - Prospect
- The search service: a handler argument (
prospect: Prospect), orProspect::ofelsewhere. Cheap to clone. - Prospect
Settings - Prospect’s settings: read from
.envbyProspectSettings::from_env, changed with the builder methods. - Search
- A search of the model
M, fromSearchable::search. Every method checks its input against the model’sIndexSpec; a mistake (an undeclared column, a value of the wrong type, a bound passed) is returned by the call that runs the search, before any query. - Search
Text - Search text parsed into terms.
- Segment
- One piece of a highlighted text: plain text, or a match.
- Text
Column - A text column being declared:
IndexSpec::textreturns it.
Enums§
- Direction
- A sort direction.
- Driver
- Which engine answers searches.
- Filter
Value - A filter value: an integer, a bool, a string or a date-time, of the type of its column.
- Language
- How words are compared.
Simple(the default) compares words as they are (lower-cased, and on SQLite without diacritics);Englishalso reduces English words to their stem (forgingfindsforge) on SQLite (theportertokenizer) and PostgreSQL (theenglishconfiguration). MySQL has no stemming. - Prospect
Error - What went wrong in a search, a registration or a migration helper.
- Weight
- A text column’s weight:
Aranks highest. SQLite uses them asbm25column weights (10, 5, 2, 1), PostgreSQL as its foursetweightclasses; MySQL’s relevance has no column weights.
Constants§
- MAX_
TERMS - The most terms a search uses; the rest are dropped.
- MIN_
PREFIX - The shortest last term that matches as a prefix (search-as-you-type).
- MYSQL_
STOPWORDS - InnoDB’s default full-text stopwords (
INFORMATION_SCHEMA.INNODB_FT_DEFAULT_STOPWORD, MySQL 8.4 “Full-Text Stopwords”): the MySQL driver drops these terms from a search.
Traits§
- Prospect
Ext - Installs Prospect on an
AppBuilder(bootstrap/app.rs). - Searchable
- A model that can be searched: implement it next to the model’s entity (
app/models/post.rs) and register the model with.prospect(|p| { p.model::<Post>(); }).