How to Search with Synonyms in Java Using GroupDocs.Search

If you want your users to find the right content even when they type different words, search with synonyms is the answer. In this guide we’ll walk through everything you need to know—creating a synonym dictionary, importing/exporting it, managing synonym groups, and finally running a search that automatically expands queries using those synonyms. Whether you’re building a CMS, an e‑commerce catalog, or a legal document repository, adding synonym support can dramatically boost relevance and conversion rates.

Quick Answers

What is the primary step to add synonyms? Initialize an Index and use the SynonymDictionary API.
Can I import a synonym dictionary? Yes – use importDictionary(path) to load a pre‑built file.
How do I enable search with synonyms? Set SearchOptions.setUseSynonymSearch(true).
Is it possible to manage synonym groups? Absolutely – you can clear, add, or retrieve groups via the dictionary API.
What should I consider when optimizing the search index? Regularly prune unused entries and tune JVM heap for large datasets.

What Is Search with Synonyms?

“Search with synonyms” means the engine treats a set of words or phrases as interchangeable. When a user types “better”, the engine also looks for “improve”, “enhance”, or any other term you’ve defined in the same synonym group, delivering richer results without changing the user’s query.

Why Enable Synonym Support in GroupDocs.Search?

Better user experience: Visitors find relevant documents even if they use different terminology.
Higher conversion rates: E‑commerce platforms capture more sales by matching varied product terms.
Simplified maintenance: One central dictionary can serve multiple applications, making updates painless.

Prerequisites

GroupDocs.Search for Java version 25.4 or newer.
A Java IDE (IntelliJ IDEA, Eclipse, etc.) with Maven support.
Basic Java knowledge and familiarity with Maven project structure.

Required Libraries and Versions

GroupDocs.Search for Java version 25.4 or higher.

Environment Setup

IDE of your choice (IntelliJ IDEA, Eclipse, etc.).
Maven for dependency management.

Knowledge Requirements

Object‑oriented programming in Java.
Basic file I/O operations.

Setting Up GroupDocs.Search for Java

Installation Information

Add the repository and dependency to your pom.xml:

<repositories>
   <repository>
      <id>repository.groupdocs.com</id>
      <name>GroupDocs Repository</name>
      <url>https://releases.groupdocs.com/search/java/</url>
   </repository>
</repositories>

<dependencies>
   <dependency>
      <groupId>com.groupdocs</groupId>
      <artifactId>groupdocs-search</artifactId>
      <version>25.4</version>
   </dependency>
</dependencies>

Direct Download – you can also download the latest JAR from GroupDocs.Search for Java releases.

License Acquisition

Free Trial: Test core features without a license.
Temporary License: Extend trial capabilities during evaluation.
Purchase: Required for production use and full feature set.

Basic Initialization and Setup

Create an Index instance, then add documents to be searchable:

import com.groupdocs.search.*;

String indexFolder = "YOUR_DOCUMENT_DIRECTORY/AdvancedUsage/ManagingDictionaries/SynonymDictionary/Index";
String documentsFolder = "YOUR_DOCUMENT_DIRECTORY/DocumentsPath2";

// Creating an index in the specified folder
Index index = new Index(indexFolder);

// Adding documents from a specific folder to the index
index.add(documentsFolder);

How to Add Synonyms to Your Search Index

Creating an index is the foundation. Below we walk through the essential steps, each paired with the exact code you need.

Feature 1: Creating and Indexing an Index

// Create an index in the specified folder
Index index = new Index(indexFolder);

// Add documents from the given folder to the index
index.add(documentsFolder);

Feature 2: Retrieving Synonyms for a Word

String[] synonyms = index.getDictionaries().getSynonymDictionary().getSynonyms("make");

Feature 3: Retrieving Synonym Groups

String[][] synonymGroups = index.getDictionaries().getSynonymDictionary().getSynonymGroups("make");

Feature 4: Managing Synonym Dictionary Entries

if (index.getDictionaries().getSynonymDictionary().getCount() > 0) {
    index.getDictionaries().getSynonymDictionary().clear();
}

String[][] newSynonymGroups = new String[][]{
    new String[] { "achieve", "accomplish", "attain", "reach" },
    new String[] { "accept", "take", "have" },
    new String[] { "improve", "better" }
};

index.getDictionaries().getSynonymDictionary().addRange(newSynonymGroups);

Feature 5: Exporting Synonyms to a File

String exportFilePath = "YOUR_OUTPUT_DIRECTORY/AdvancedUsage/ManagingDictionaries/SynonymDictionary/Synonyms.dat";
index.getDictionaries().getSynonymDictionary().exportDictionary(exportFilePath);

Feature 6: Importing Synonyms from a File

index.getDictionaries().getSynonymDictionary().importDictionary(exportFilePath);

Feature 7: Performing Search with Synonym Support

String query = "better";
SearchOptions options = new SearchOptions();
options.setUseSynonymSearch(true);

SearchResult result = index.search(query, options);

How to Search with Synonyms

By enabling setUseSynonymSearch(true), the engine automatically expands the query using the synonym dictionary you built or imported. This step is crucial for delivering richer results without changing the user’s search behavior.

How to Import Synonym Dictionary

If you already have a .dat file prepared by another environment, simply call importDictionary(path). This is ideal for synchronizing dictionaries across development, staging, and production servers.

How to Manage Synonym Groups

Synonym groups let you treat a set of terms as a single logical entity. Adding, clearing, or retrieving groups is done through the SynonymDictionary API, as shown in the code snippets above.

How to Optimize Search Index

Regularly prune unused entries: Use clear() before bulk updates.
Adjust JVM heap: Large dictionaries may require more memory.
Keep the library up‑to‑date: New releases contain performance improvements.

Practical Applications

Content Management Systems (CMS): Users find articles even when they use alternative terminology.
E‑commerce Platforms: Product searches become tolerant to synonyms like “laptop” vs. “notebook”.
Document Repositories: Legal or medical archives benefit from domain‑specific synonym groups.

Performance Considerations

Optimize Index Storage: Periodically rebuild the index to remove stale data.
Manage Memory Usage: Monitor heap consumption when loading large synonym files.
Regular Updates: Stay on the latest GroupDocs.Search version for bug fixes and speed gains.

Common Issues and Solutions

Issue	Likely Cause	Fix
No synonym matches appear	`setUseSynonymSearch(true)` not set or dictionary not imported	Verify the option is enabled and the dictionary file exists.
Out‑of‑memory errors during import	Very large `.dat` file exceeds JVM heap	Increase `-Xmx` heap size or import in smaller batches.
Duplicate entries in results	Same term appears in multiple synonym groups	Consolidate overlapping groups using `clear()` then `addRange()`.

Frequently Asked Questions

Q: What is the minimum system requirement for using GroupDocs.Search?
A: Any modern OS with a compatible JDK (Java 8 or newer) is sufficient.

Q: How often should I refresh my synonym dictionary?
A: Update it whenever new terminology emerges—use clear() followed by addRange() for a clean refresh.

Q: Can I run GroupDocs.Search without purchasing a license?
A: A free trial works for evaluation, but a license is required for production deployments.

Q: What are best practices for indexing large data sets?
A: Split data into logical batches, monitor heap usage, and schedule regular index maintenance.

Q: I’m not seeing expected synonym matches—what should I check?
A: Verify that the dictionary is correctly imported, that setUseSynonymSearch(true) is active, and that the terms are present in the synonym groups.

Resources

Last Updated: 2026-03-04
Tested With: GroupDocs.Search 25.4 for Java
Author: GroupDocs