Skip to main content

Synonyms API

Synonyms allow you to define equivalent terms for search queries, improving search relevance by matching documents even when users use different terminology.

Overview​

Synonyms help users find relevant documents even when they use different words. For example, "laptop" and "notebook" can be treated as synonyms.

List Synonyms​

Get all synonyms for a collection.

Endpoint: GET /collections/{name}/synonyms

Example Request:

curl http://localhost:9200/collections/products/synonyms

Example Response:

{
  "synonyms": [
    {
      "id": "syn1",
      "synonyms": ["laptop", "notebook", "computer"]
    },
    {
      "id": "syn2",
      "synonyms": ["phone", "mobile", "smartphone"]
    }
  ]
}

List All Synonyms​

List all synonym records known to the server.

Endpoint: GET /synonyms

curl http://localhost:9200/synonyms

This endpoint is useful for administration and inventory views. Use /synonyms/global when you only need global synonym sets.

Global Synonyms​

Global synonyms apply to all collections. They are merged with collection-specific synonyms at query time.

List global synonyms

GET /synonyms/global

curl http://localhost:9200/synonyms/global

Create or update a global synonym set

POST /synonyms/global/{id} or PUT /synonyms/global/{id}

curl -X POST http://localhost:9200/synonyms/global/tech_terms \
  -H "Content-Type: application/json" \
  -d '{
    "root": "laptop",
    "synonyms": ["notebook", "portable computer"]
  }'

Get a global synonym set

GET /synonyms/global/{id}

Delete a global synonym set

DELETE /synonyms/global/{id}

Create Synonym​

Create a new synonym set.

Endpoint: POST /collections/{name}/synonyms/{id}

Request Body:

{
  "root": "term1",
  "synonyms": ["term2", "term3"]
}

Example Request:

curl -X POST http://localhost:9200/collections/products/synonyms/laptop_synonyms \
  -H "Content-Type: application/json" \
  -d '{
    "root": "laptop",
    "synonyms": ["notebook", "portable computer"]
  }'

Example Response:

{
  "message": "Synonym created successfully",
  "id": "laptop_synonyms"
}

Get Synonym​

Get details about a specific synonym set.

Endpoint: GET /collections/{name}/synonyms/{id}

Example Request:

curl http://localhost:9200/collections/products/synonyms/laptop_synonyms

Example Response:

{
  "id": "laptop_synonyms",
  "synonyms": ["laptop", "notebook", "portable computer"]
}

Update Synonym​

Update an existing synonym set (same as create - upsert behavior).

Endpoint: POST /collections/{name}/synonyms/{id} or PUT /collections/{name}/synonyms/{id}

Example Request:

curl -X POST http://localhost:9200/collections/products/synonyms/laptop_synonyms \
  -H "Content-Type: application/json" \
  -d '{
    "root": "laptop",
    "synonyms": ["notebook", "portable computer", "laptop computer"]
  }'

Delete Synonym​

Delete a synonym set.

Endpoint: DELETE /collections/{name}/synonyms/{id}

Example Request:

curl -X DELETE http://localhost:9200/collections/products/synonyms/laptop_synonyms

Example Response:

{
  "message": "Synonym deleted successfully",
  "id": "laptop_synonyms"
}

Local vs Global Synonyms​

  • Local (collection) synonyms: stored under /collections/{name}/synonyms and only affect that collection.
  • Global synonyms: stored under /synonyms/global and apply to every collection.
  • Scope preference: controlled by query_settings.lexical_scope_preference in hlquery.conf.

Scope Preference​

When global and local synonym sets contain the same normalized term, hlquery uses the lexical_scope_preference setting to decide how to build the query expansion graph:

<query_settings
     enable_synonyms="true"
     lexical_scope_preference="merge">
ValueBehavior
mergeDefault. Global and local synonyms are combined. Overlapping terms expand to the union of both sets.
localCollection synonyms override matching global synonym terms. Global synonyms still apply for terms not defined locally.
globalGlobal synonyms override matching collection synonym terms. Local synonyms still apply for terms not defined globally.

Example:

  • Global synonym: phone -> mobile, smartphone
  • Collection synonym: phone -> handset, device

With merge, searching phone can expand to mobile, smartphone, handset, and device.

With local, searching phone uses the collection set: handset, device.

With global, searching phone uses the global set: mobile, smartphone.

How Synonyms Work​

Synonyms are applied to lexical and hybrid searches. Vector-only searches do not use synonyms.

When a user searches for any term in a synonym set, hlquery will also match documents containing other terms in the same set.

Example:

  • Synonym set: ["laptop", "notebook", "portable computer"]
  • User searches: "laptop"
  • Matches documents containing: "laptop", "notebook", or "portable computer"

Best Practices​

  1. Use relevant terms: Include all common variations of a term
  2. Keep sets focused: Don't mix unrelated terms
  3. Test thoroughly: Verify synonyms improve search results
  4. Update regularly: Add new synonyms as language evolves
  5. Consider context: Some synonyms may be context-specific

Use Cases​

  • Product names: "iPhone" = "Apple iPhone" = "iPhone 15"
  • Technical terms: "RAM" = "memory" = "random access memory"
  • Regional variations: "elevator" = "lift", "truck" = "lorry"
  • Abbreviations: "TV" = "television", "PC" = "personal computer"

Next Steps​