Control equivalent and ignored words

← FTS examples

The language tabs use earlier client interfaces. Check SDK versions and connection setup before running them.

Synonyms represent equivalent words. Stopwords are omitted by the analyzer. Configure both for the field that needs them.

Before you run it: A configuration change does not rewrite old postings. An empty stopword list disables stopwords rather than preserving the old list.

Start with a test field and a few documents containing the terms you will compare. A synonym map groups words such as tv and television; a stopword list chooses words to discard. Test both old and newly indexed documents after a change, because stored postings are not rewritten automatically.

Follow the exampleCopy Anchor Link

1. Review the current configuration.
2. Write a complete synonym map or stopword list.
3. Test searches using the changed words.
4. Reindex existing documents when analysis changes require it.

Set equivalent wordsCopy Anchor Link

The body maps each canonical term to the words that should mean the same thing. Send the complete desired map every time - there is no merge.

curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.products/description/synonyms" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "synonyms": {
      "television": ["tv", "telly"],
      "headphones": ["headset", "cans"]
    }
  }'

Check the resultCopy Anchor Link

The new configuration replaces the old one; it is not appended.

201 Created with an empty body. Both installers answer the same way; a malformed map is a 400. Nothing needs restarting - the records are read per request, so the next query already sees them:

curl -G "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.products/description" \
  -H "Authorization: Bearer $OC_TOKEN" \
  --data-urlencode "q=tv" \
  --data-urlencode "mode=bm25"

That search now ranks documents containing television as well as those containing tv, and the reverse query does the same.

Set ignored wordsCopy Anchor Link

The array is the complete stopword list for the field. When set, it is used instead of the built-in list for the analyzer language.

curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.products/description/stopwords" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "stopwords": ["the", "a", "with", "for"] }'

An empty array is not a no-op - it is how you turn stopword removal off for the field entirely:

curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/fts/shop.products/description/stopwords" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "stopwords": [] }'

Understand the behaviorCopy Anchor Link

• Synonyms work from both ends. At index time every occurrence of a canonical term also writes postings under each of its synonyms. At query time a term that appears as either a canonical or a synonym expands to the whole class. That is what makes tv and television symmetric without writing the index twice.
• Expansion is capped at 32 synonyms per class to bound query-time work - a term mapping to a thousand others would otherwise issue a thousand posting-list scans.
• Stopwords apply on the analyzer-aware path. They are consulted when a document is indexed with an analyzer block, and by the query nodes that carry an analyzer, so that both sides tokenize the same way. An index write with no analyzer uses the default tokenizer and the override does not enter into it.
• Both are configuration, not content. They silently change what every later query on the field matches and how it scores, for every reader, without touching a single document - so they are charged as a schema-level change rather than a row write, and need the corresponding privilege.
• Configuration is read on subsequent applicable requests without restarting. Reindex existing documents when their stored tokens must change.

Important limits and checksCopy Anchor Link

• Treating either call as an append. Both calls replace the stored configuration. Include every entry you want to keep, and store the complete map in version control.
• Expecting an empty stopword array to be ignored. It means "no stopwords for this field", not "leave things as they were" - which is exactly how you disable the built-in list, and exactly how you erase a list you meant to keep.
• Expecting a stopword change to rewrite existing postings. It governs analysis from the next write onward. Documents already indexed keep the postings they were given; reindex them if you need the old ones gone.
• Installing on the wrong field. Both records are keyed by (schema, field). A map installed on title does nothing at all for a query against description.
• Writing a class longer than the cap. Only the first 32 members of a class are retained. Check generated maps before submitting them.

ContinueCopy Anchor Link

Continue to make text searchable.