Skip to main content

Crate smeltery_prospect

Crate smeltery_prospect 

Source
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(), a Vec<Segment> named title here), 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.
IndexSpec
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), or Prospect::of elsewhere. Cheap to clone.
ProspectSettings
Prospect’s settings: read from .env by ProspectSettings::from_env, changed with the builder methods.
Search
A search of the model M, from Searchable::search. Every method checks its input against the model’s IndexSpec; 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.
SearchText
Search text parsed into terms.
Segment
One piece of a highlighted text: plain text, or a match.
TextColumn
A text column being declared: IndexSpec::text returns it.

Enums§

Direction
A sort direction.
Driver
Which engine answers searches.
FilterValue
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); English also reduces English words to their stem (forging finds forge) on SQLite (the porter tokenizer) and PostgreSQL (the english configuration). MySQL has no stemming.
ProspectError
What went wrong in a search, a registration or a migration helper.
Weight
A text column’s weight: A ranks highest. SQLite uses them as bm25 column weights (10, 5, 2, 1), PostgreSQL as its four setweight classes; 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§

ProspectExt
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>(); }).