Full-text search

Search is a GET on the same path you indexed to, with the query in ?q=. mode=bm25 is what you want when you care about ranking.

curl "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.orders/notes?q=delivery&mode=bm25&k=10" \
  -H "Authorization: Bearer $OC_TOKEN"

res = db.fts.search("shop.orders", "notes", "delivery", mode="bm25", k=10)
for hit in res.hits:
    print(hit.doc_id, hit.score)

const hits = await db.ftsSearch("shop.orders", "notes", {
  q:    "delivery",
  mode: "bm25",
  k:    10,
});
// mode "bm25" returns RankedHit[]; "boolean" and "phrase" return string[].
for (const h of hits as { doc_id: string; score: number }[]) {
  console.log(h.doc_id, h.score);
}

hits, err := db.FTSSearch(ctx, "shop.orders", "notes", originchain.FTSSearchRequest{
    Q:    "delivery",
    Mode: "bm25",
    K:    10,
})
for _, h := range hits {
    fmt.Println(h.DocID, h.Score)
}

[
  { "doc_id": "01JTRX9KQ3YH8K2WMX0F5JZAB7", "score": 9.4213 },
  { "doc_id": "01JTRX9KQ3YH8K2WMX0F5JZAB9", "score": 6.1077 }
]

A bare array of { doc_id, score }, highest score first. k caps the list and defaults to 10.

This is worth being blunt about, because it is easy to assume otherwise: ?q= is not a query language. There is no parser. The string is tokenized into words — Unicode word segmentation, then lowercased — and every token becomes a term. All punctuation is discarded.

The practical consequence is that operators you might type do not work, and fail silently rather than erroring. rush AND delivery searches for three terms — rush, and, delivery. Quotes around a phrase are dropped.

How multiple terms combine — it depends on the mode.

This is the important distinction, and it is not configurable:

# mode=boolean is the DEFAULT when ?mode= is omitted.
# Every term must be present. Returns a bare array of doc_ids, unranked.
curl "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.orders/notes?q=rush+delivery" \
  -H "Authorization: Bearer $OC_TOKEN"

# The typed namespace defaults to bm25 - pass mode explicitly for boolean.
res = db.fts.search("shop.orders", "notes", "rush delivery", mode="boolean")

# The legacy method defaults to boolean already:
doc_ids = db.fts_search("shop.orders", "notes", q="rush delivery")

const docIds = await db.ftsSearch("shop.orders", "notes", {
  q:    "rush delivery",
  mode: "boolean",
}) as string[];

docIDs, err := db.FTSSearch(ctx, "shop.orders", "notes", originchain.FTSSearchRequest{
    Q:    "rush delivery",
    Mode: "boolean",
})

["01JTRX9KQ3YH8K2WMX0F5JZAB7", "01JTRX9KQ3YH8K2WMX0F5JZAC1"]

mode=phrase requires the terms to appear adjacent and in the order given. The quotes you would type in another search engine are not syntax here — the mode is the switch.

# Terms must appear adjacent, in this order. Quotes are NOT syntax -
# they would simply be discarded by the tokenizer. Use mode=phrase.
curl "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.orders/notes?q=signed+by+recipient&mode=phrase" \
  -H "Authorization: Bearer $OC_TOKEN"

doc_ids = db.fts.search(
    "shop.orders", "notes", "signed by recipient", mode="phrase",
)

const docIds = await db.ftsSearch("shop.orders", "notes", {
  q:    "signed by recipient",
  mode: "phrase",
}) as string[];

docIDs, err := db.FTSSearch(ctx, "shop.orders", "notes", originchain.FTSSearchRequest{
    Q:    "signed by recipient",
    Mode: "phrase",
})

Phrase results come back as an unranked array of doc_id strings — position matching selects the documents, but this mode does not score them. If you need ranking as well as adjacency, use the phrase clause inside the DSL, which selects on positions and then ranks with BM25.

Two ways in, both bm25-only: a whole-query budget via ?fuzzy=N, or a per-term ~N suffix. Putting a ~ anywhere in q switches the query onto the fuzzy path automatically.

# Whole-query budget via ?fuzzy= (bm25 only, 0-3)
curl "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.orders/notes?q=delivary&mode=bm25&fuzzy=1" \
  -H "Authorization: Bearer $OC_TOKEN"

# Or per-term inline with ~N. A bare ~ means distance 2.
curl "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.orders/notes?q=delivary~1+recipient&mode=bm25" \
  -H "Authorization: Bearer $OC_TOKEN"

res = db.fts.search("shop.orders", "notes", "delivary", mode="bm25", fuzzy=1)

// The TypeScript SDK does not expose fuzzy - call the endpoint directly,
// or embed the ~N operator in the query string.
const hits = await db.ftsSearch("shop.orders", "notes", {
  q:    "delivary~1",
  mode: "bm25",
});

// The Go SDK does not expose fuzzy - embed the ~N operator instead.
hits, err := db.FTSSearch(ctx, "shop.orders", "notes", originchain.FTSSearchRequest{
    Q:    "delivary~1",
    Mode: "bm25",
})

• Edit distance is capped at 3. Higher is a 400: fuzzy edit_distance 5 exceeds MAX_EDIT_DISTANCE 3.
• A bare term~ with no number means distance 2. term~0 is an exact match.
• Each term expands to at most 50 dictionary candidates.
• Distance 1 catches most real typos. Distance 2 and 3 expand aggressively and will pull in unrelated words — measure before shipping either.
• Only the Python SDK exposes a fuzzy parameter. In TypeScript and Go, put ~N in the query string.

mode=bm25 scores each document as the sum of its query terms' contributions. Each contribution combines three things:

• Inverse document frequency. A term in few documents is worth more than one in many. This is why a rare word dominates a query.
• Term frequency, with diminishing returns. The fifth occurrence adds much less than the second. k1 controls how fast that saturates.
• Length normalisation. A hit in a short document counts for more than the same hit buried in a long one. b controls how strongly.

Defaults are k1 = 1.2 and b = 0.75 — the standard Lucene values. On the ?q= surface they are fixed; they can only be overridden through the DSL's params object. Scores are relative within one result set — never compare a score across two different queries.

The explain parameter.

Add explain=true to a bm25 query to get the full arithmetic instead of the hits. This is a query parameter on the search route — there is no separate explain endpoint.

curl "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.orders/notes?q=rush+delivery&mode=bm25&k=5&explain=true" \
  -H "Authorization: Bearer $OC_TOKEN"

{
  "query_terms": ["rush", "delivery"],
  "n_total":     1204,
  "avgdl":       11.6,
  "k1":          1.2,
  "b":           0.75,
  "hits": [
    {
      "doc_id": "01JTRX9KQ3YH8K2WMX0F5JZAB7",
      "score":  9.4213,
      "terms": [
        { "term": "rush",     "df": 42,  "idf": 3.361, "tf": 1.0,
          "doc_len": 5, "contribution": 5.9102 },
        { "term": "delivery", "df": 310, "idf": 1.362, "tf": 1.0,
          "doc_len": 5, "contribution": 3.5111 }
      ]
    }
  ]
}

n_total is the corpus size and avgdl the average document length — the two corpus statistics the formula needs. Per hit, terms is sorted by contribution descending, so the first entry is the term that actually won the document its place. Length normalisation is folded into contribution; doc_len is the raw token count.

• Explain works only with mode=bm25, and overrides highlight and facets if you pass them together.
• It always reports the default k1 and b — you cannot explain a custom-tuned score, and the DSL endpoint has no explain of its own.
• Explain takes the exhaustive scoring path, so it is slower than the equivalent ranked query. It is a debugging tool, not a production one.
• No SDK exposes explain. Call the endpoint directly.

Both features need the document's text stored, which the plain index call does not do. Send it to the /doc variant instead, along with any facet values you want to aggregate on.

# Store the doc text plus per-facet values. Required before highlight=true
# or facets= will return anything.
curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.orders/notes/doc" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_id": "01JTRX9KQ3YH8K2WMX0F5JZAB7",
    "text":   "rush delivery, signed by recipient",
    "facets": { "status": ["paid"], "channel": ["web"] }
  }'

Then ask for them at query time:

curl "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.orders/notes?q=rush&mode=bm25&k=5&highlight=true&facets=status,channel" \
  -H "Authorization: Bearer $OC_TOKEN"

{
  "hits": [
    {
      "doc_id": "01JTRX9KQ3YH8K2WMX0F5JZAB7",
      "score":  9.4213,
      "highlights": { "notes": ["<em>rush</em> delivery, signed by recipient"] }
    }
  ],
  "facets": {
    "status":  [ { "value": "paid", "count": 12 }, { "value": "refunded", "count": 3 } ],
    "channel": [ { "value": "web",  "count": 11 }, { "value": "app",      "count": 4 } ]
  }
}

res = db.fts.search(
    "shop.orders", "notes", "rush",
    mode="bm25", k=5, highlight=True, facets=["status", "channel"],
)
for hit in res.hits:
    print(hit.doc_id, hit.score, hit.highlights)
for value, bucket in res.facets.items():
    print(value, [(b.value, b.count) for b in bucket])

• Highlights come back as raw <em> markup around matched terms. Escape or sanitise before rendering.
• Facets aggregate; they do not filter. facets=status tells you the distribution across the hit set — it does not narrow it. For real filtering use the DSL.
• At most 1000 distinct values are tracked per facet field.
• Only the Python SDK wraps highlight and facets; the /doc write is not wrapped by any SDK.

Everything the ?q= surface can't do — boolean composition, negation, filters, prefix and wildcard matching, multi-field search with weights, custom k1/b — lives in a JSON query DSL at POST /fts/:table/_search. Note the path takes a table only; fields are named inside the query.

curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.orders/_search" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_values_field": "notes",
    "query": {
      "bool": {
        "must":     [ { "match":  { "field": "notes", "query": "rush delivery" } } ],
        "should":   [ { "term":   { "field": "notes", "value": "signed", "boost": 2.0 } } ],
        "must_not": [ { "term":   { "field": "notes", "value": "cancelled" } } ],
        "filter":   [ { "numeric_range": { "field": "amount_cents", "gte": 10000 } } ]
      }
    },
    "top_k":  20,
    "params": { "k1": 1.2, "b": 0.75 }
  }'

{
  "total": 431,
  "hits": [
    { "doc_id": "01JTRX9KQ3YH8K2WMX0F5JZAB7", "score": 14.8802 },
    { "doc_id": "01JTRX9KQ3YH8K2WMX0F5JZAC1", "score": 11.2044 }
  ]
}

total is the match count before top_k truncation, so you can render "showing 20 of 431" without a second query. top_k defaults to 10.

Clause types.

match_all, match_none, term, terms, match, phrase, prefix, wildcard, regex, range, numeric_range, fuzzy, exists, multi_match, bool, constant_score and function_score.

• bool scores must plus any matching should. filter gates without contributing score; must_not excludes.
• match defaults to OR across its terms; pass "operator": "and" to require them all.
• Every clause takes a boost, and boosts multiply down the tree — a boost: 2.0 clause inside a boost: 3.0 bool contributes 6×.
• minimum_should_match accepts an integer, a negative integer ("all but N"), or a percentage string like "75%".
• regex supports literals, character classes, repetition, alternation and grouping — but not back-references, look-around or named groups.

Multi-field search with weights.

# Search several indexed fields at once, with per-field weights.
curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.orders/_search" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "multi_match": {
        "fields": [
          { "field": "notes",    "boost": 2.0 },
          { "field": "customer", "boost": 1.0 }
        ],
        "query": "rush delivery",
        "type":  "best_fields",
        "tie_breaker": 0.3
      }
    },
    "top_k": 20
  }'

best_fields (the default) takes the best-scoring field plus tie_breaker × each other match; most_fields sums them all. tie_breaker defaults to 0.0 — pure winner-takes-all — and must be within [0, 1]. Every field you name must be independently indexed, or the request 404s.

Two sibling endpoints share the DSL: POST /fts/:table/_aggs for aggregations and POST /fts/:table/_suggest for prefix suggestions. Because of these routes, _search, _aggs and _suggest are reserved and cannot be used as field names. No SDK wraps the DSL endpoints.