examples · fts · 4 / 6
4. Phrase search
← FTS exampleswhat this does
Returns documents whose description contains the exact phrase noise cancellation - both tokens, in that order, with nothing between them. Unlike boolean AND, position matters.
when to use it
- Branded names and product models:
"Bose QC45","Sony WH-1000XM5". - Multi-word concepts where the order carries the meaning:
"connection refused","out of memory". - Log-template matching - searching for the literal stem of an emitted log line.
the request
GET /v1/tenants/:t/fts/:schema/:field?q=...&mode=phrase
curl -G "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.products/description" \
-H "Authorization: Bearer $OC_TOKEN" \
--data-urlencode "q=noise cancellation" \
--data-urlencode "mode=phrase"# Phrase search returns a bare JSON array of doc_id strings
doc_ids = db.fts.search(
"shop.products",
"description",
q="noise cancellation",
mode="phrase",
)
for doc_id in doc_ids:
print(doc_id)// Phrase search returns a bare string[] of doc_ids
const docIds = await db.ftsSearch("shop.products", "description", {
q: "noise cancellation",
mode: "phrase",
});
for (const docId of docIds) {
console.log(docId);
}// Phrase search returns []string of doc_ids
docIDs, _ := db.FTSSearch(ctx, "shop.products", "description", originchain.FTSSearchRequest{
Q: "noise cancellation",
Mode: "phrase",
})
for _, docID := range docIDs {
fmt.Println(docID)
} what you get back
["p001"]
Same shape as boolean: a bare array of doc_id strings, no wrapper, no scores. Phrase mode just narrows which docs qualify.
how it works
- The query is tokenised the same way as the indexed text.
- The engine pulls posting lists for each token along with token positions inside each document.
- A doc matches only if the positions are consecutive: position(ti+1) = position(ti) + 1 for every adjacent token pair.
common mistakes
- Expecting stemming to bridge word forms. The API analyzer is Unicode-tokenize + lowercase only - it does not stem.
q=noise cancelwill not match a doc that says "noise cancellation"; the literal tokencancellationmust be present. - Punctuation between tokens. Most analysers strip punctuation -
"noise, cancellation"in the source text still phrase-matchesq=noise cancellation. - Expecting fuzzy behaviour. Phrase is strict - one typo and the phrase doesn't match. Use BM25 with
fuzzy=1if you need typo tolerance.