Skip to content
Optimizely CertificationOptimizely Certification Optimizely Certification

Configure Synonyms and Search Tuning

⏱ 20 minutes intermediate
📜CoreGraph

Why configure search tuning

Section titled “Why configure search tuning”

Out-of-the-box search matches content based on the exact terms users type. Real users search for “laptop” when your content says “notebook computer,” or they type “car” when your products are listed as “automobile.” Synonyms bridge this vocabulary gap. Stopwords prevent common words from diluting search relevance.

Step 1: Define synonym sets

Section titled “Step 1: Define synonym sets”

Synonyms tell Graph that certain terms should be treated as equivalent during search. Create synonym sets through the Graph admin API.

Create synonym sets
bash 
# Create a two-way synonym set
curl -X PUT \
  https://cg.optimizely.com/api/content/v3/synonyms \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic {base64(AppKey:Secret)}' \
  -d '{
    "synonyms": [
      {
        "type": "two_way",
        "terms": ["laptop", "notebook", "portable computer"]
      },
      {
        "type": "two_way",
        "terms": ["automobile", "car", "vehicle"]
      },
      {
        "type": "one_way",
        "from": "CMS",
        "to": ["content management system"]
      }
    ]
  }'

Synonym types

Section titled “Synonym types”
TypeBehaviorExample
Two-wayAll terms match each other”laptop” finds “notebook” and vice versa
One-waySource term expands to include targets”CMS” also finds “content management system,” but not the reverse

Step 2: Use synonyms in queries

Section titled “Step 2: Use synonyms in queries”

Enable synonym matching in your search queries using the synonym parameter.

Search with synonyms enabled
graphql 
query SearchWithSynonyms($term: String!) {
  ArticlePage(
    where: {
      _fulltext: {
        contains: $term
        synonym: ON
      }
    }
    orderBy: { _ranking: RELEVANCE }
    limit: 20
  ) {
    items {
      Headline
      Summary
      _score
    }
    total
  }
}

When synonyms are enabled, a search for “laptop” automatically expands to include results containing “notebook” or “portable computer.”

Step 3: Configure stopwords

Section titled “Step 3: Configure stopwords”

Stopwords are common words that add noise to search results. Words like “the,” “is,” “and,” and “of” are typically excluded from search analysis.

Configure custom stopwords
bash 
# Set custom stopwords for your Graph instance
curl -X PUT \
  https://cg.optimizely.com/api/content/v3/stopwords \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic {base64(AppKey:Secret)}' \
  -d '{
    "locale": "en",
    "words": [
      "the", "is", "at", "which", "on",
      "a", "an", "and", "or", "but",
      "in", "with", "to", "for", "of"
    ]
  }'

Graph provides sensible default stopwords for common languages. Only customize stopwords when you need to add domain-specific terms or remove defaults that are meaningful in your content domain.

Step 4: Pin important results

Section titled “Step 4: Pin important results”

Pinned results guarantee that specific content appears at the top of search results for designated queries. Use this for critical content like compliance pages, product recalls, or seasonal campaigns.

Pin results for specific queries
bash 
# Pin a specific page for a search term
curl -X PUT \
  https://cg.optimizely.com/api/content/v3/pinned \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic {base64(AppKey:Secret)}' \
  -d '{
    "rules": [
      {
        "query": "return policy",
        "contentKeys": [
          "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        ]
      },
      {
        "query": "shipping",
        "contentKeys": [
          "b2c3d4e5-f6a7-8901-bcde-f12345678901"
        ]
      }
    ]
  }'

Step 5: Test and iterate

Section titled “Step 5: Test and iterate”

After configuring synonyms and stopwords, test search quality with real user queries.

  1. Collect the top 20-30 search queries from your analytics
  2. Run each query in the Graph playground
  3. Evaluate whether the top 5 results match user intent
  4. Adjust synonym sets and stopwords based on gaps
  5. Repeat monthly as content and user behavior evolve
Verify synonym expansion
graphql 
# Search for "laptop" -- should also return "notebook" content
query TestSynonyms {
  ArticlePage(
    where: {
      _fulltext: {
        contains: "laptop"
        synonym: ON
      }
    }
    orderBy: { _ranking: RELEVANCE }
    limit: 5
  ) {
    items {
      Headline
      _score
    }
    total
  }
}

Best practices

Section titled “Best practices”
  • Start small — Add synonym sets for your top 10 search terms first. Overly broad synonym sets can reduce precision.
  • Monitor search analytics — Track zero-result searches to identify vocabulary gaps that synonyms can fill.
  • Use one-way synonyms carefully — One-way synonyms are powerful but asymmetric. “CMS” expanding to “content management system” makes sense, but the reverse would dilute specific searches.
  • Review stopwords for your domain — In medical content, “or” is a stopword. In legal content, it may be significant. Tailor stopwords to your content domain.
  • Version your configuration — Store synonym and stopword configurations in version control alongside your application code.