Implement synonym support in Java search applications with 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 you’ll learn how to create a synonym dictionary, import or export it, manage synonym groups, and run 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 first step to add synonyms? Create an
Indexinstance and work with theSynonymDictionaryAPI. - Can I import a ready‑made synonym dictionary? Yes – call
importDictionary(path)with the file location. - How do I turn on synonym‑aware searching? Enable
SearchOptions.setUseSynonymSearch(true). - Is it possible to edit synonym groups at runtime? Absolutely – you can clear, add, or retrieve groups via the dictionary API.
- What should I monitor when scaling the index? Regularly prune unused entries and tune the JVM heap for large synonym files.
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?
Enabling synonym support lets the engine automatically broaden queries to include equivalent terms, which improves result relevance, increases user satisfaction, and can raise conversion rates for e‑commerce or content‑driven sites. It also centralizes terminology management, reducing maintenance overhead across multiple applications.
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 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 the 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
Feature 1: creating and indexing an index
The Index class represents a searchable collection of documents stored on disk or in memory.
// 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
SynonymDictionary manages synonym groups and provides methods to query synonyms for a term.
String[] synonyms = index.getDictionaries().getSynonymDictionary().getSynonyms("make");
Feature 3: retrieving synonym groups
SynonymDictionary.getGroups() returns a list of all defined synonym groups with their identifiers.
String[][] synonymGroups = index.getDictionaries().getSynonymDictionary().getSynonymGroups("make");
Feature 4: managing synonym dictionary entries
add(word, synonym) inserts a new synonym relationship into the dictionary. clear() removes all entries, and remove(word) deletes a specific term from the dictionary.
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
exportDictionary(path) writes the current synonym dictionary to a binary .dat file at the specified location.
String exportFilePath = "YOUR_OUTPUT_DIRECTORY/AdvancedUsage/ManagingDictionaries/SynonymDictionary/Synonyms.dat";
index.getDictionaries().getSynonymDictionary().exportDictionary(exportFilePath);
Feature 6: importing synonyms from a file
importDictionary(path) loads a previously exported .dat file into the synonym dictionary.
index.getDictionaries().getSynonymDictionary().importDictionary(exportFilePath);
Feature 7: performing search with synonym support
SearchOptions configures query behavior, including whether synonym expansion is enabled. setUseSynonymSearch(true) turns on synonym‑aware searching for the upcoming query.
String query = "better";
SearchOptions options = new SearchOptions();
options.setUseSynonymSearch(true);
SearchResult result = index.search(query, options);
How to search with synonyms
Load your Index, enable synonym search, and execute a query. The engine automatically expands the query using the synonym dictionary you built or imported, returning matches for all related terms.
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; increase the
-Xmxparameter accordingly. - Keep the library up‑to‑date: New releases contain performance improvements and bug fixes.
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, improving discoverability for professionals.
Performance considerations
- Optimize index storage: Periodically rebuild the index to remove stale data.
- Manage memory usage: Monitor heap consumption when loading large synonym files; a 500 MB dictionary typically requires a 2 GB heap on a 64‑bit JVM.
- 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
- Documentation
- API Reference
- Download GroupDocs.Search for Java
- GitHub Repository
- Free Support Forum
- Temporary License Acquisition
Last Updated: 2026-10-17
Tested With: GroupDocs.Search 25.4 for Java
Author: GroupDocs