DocsData
Search by meaning
Find rows by what they mean, not only the words they use, with vectors kept in SQLite and nothing to set up.
Give a collection some text, and it answers its rows ranked by how close they are in meaning. With an embeddings model, “excursion” finds the museum trip; without one, Sluurp falls back to matching words loosely. To search, pass near:
const { items } = await sluurp.collection("notes").list({ near: "museum trips" });GET /api/collections/notes/records?near=museum%20tripsFeatures include:
- Vectors in the same SQLite file as the rows, with no index to build
- A local model file, any OpenAI-compatible embeddings API, or neither
- Exact comparison, so no row is missed
- Combined with full-text search, each score returned to weigh yourself
Search
Each row gets a _score: 1 is identical, lower is less alike. Everything else about list still applies. Rules limit which rows are considered, and filter narrows them before ranking:
await sluurp.collection("tickets").list({
near: "a customer who wants their money back",
filter: `team = "support"`,
perPage: 10,
});Choose the fields
By default, Sluurp compares the fields marked "searchable": true, the same ones search= uses. If there are none, it uses the text, email and URL fields. To choose them yourself, pass on:
await sluurp.collection("posts").list({ near: "team trip", on: "title,body" });Embeddings
Embeddings come from the AI plugin (sluurp plugin add ai), set up on its AI screen in the admin. Without the plugin, Sluurp uses the word-based fallback.
- A local model file. Sluurp computes embeddings in its own process, with nothing else to run. Point it at a
.ggufembeddings model such as nomic-embed-text-v1.5 (84 MB): a model already on the machine (LM Studio’s and Hugging Face’s downloads are listed), a file path, or a Hugging Face address, which each server downloads once. BERT-style models (Nomic, MiniLM, BGE, E5) work, in F32, F16, Q8_0, Q4_K, Q5_K or Q6_K. A text takes tens of milliseconds on a laptop. - An embeddings API. Any OpenAI-compatible embeddings endpoint, such as a local Ollama or OpenAI. With Ollama:
ollama pull nomic-embed-text, base URLhttp://localhost:11434/v1, modelnomic-embed-text. Text is sent only to that server. - Neither. Sluurp builds vectors from words and three-letter pieces of them. “museum trips” still finds “Museum trip — May”, and typos are tolerated, but “excursion” won’t match. Nothing is sent anywhere.
Changing models is safe: vectors are kept per model and made again as needed.
near and search
The two combine. search= and the filter’s @@ narrow the rows, near orders them by meaning, and each part’s score comes back in _scores, for you to weigh. See Ranking.
search= | near= | |
|---|---|---|
| Matches | rows containing the words | rows about the same thing |
| Order | by sort | most alike first |
| Engine | SQLite’s full-text index | exact comparison of vectors |
| Good for | names, codes, exact phrases | questions, topics, “more like this” |
Use search when people know the exact words, and near when they know the meaning.
How it works
- Vectors are made when first needed, the first time a row is searched, and kept with a hash of the text they came from. They are made again when the text changes. Writes cost nothing extra.
- Vectors are ordinary rows in the project’s database (
__vectors_<dimensions>), backed up with everything else, and compared with sqlite-vector (Apache-2.0), compiled into the binary. - Search is exact, not approximate. Every visible row (up to 5,000 after
filter) is compared, so there is no index to tune and no row is missed. For bigger collections, narrow first withfilter, such as a team or the last year. - A page holds at most 500 rows, as with any list.
- In a swarm, a search by meaning runs on the leader, since it may keep new vectors, and its answer is passed back.
Search the social feed
With the social plugin, posts can be searched the same way, across the feeds the user can read:
const { items } = await sluurp.social.feed({ near: "lost and found" });GET /api/social/feed?near=lost%20and%20foundA search palette can show both: matches by meaning beside matches by words.