Add Documents to Index for Case‑Insensitive Search in Java

When you need case insensitive search java that reliably finds information regardless of how users type it, the key is to add documents to an index while normalizing the text. In this tutorial we walk through configuring GroupDocs.Search for Java so that every document you index is automatically lower‑cased (or otherwise transformed) during indexing, guaranteeing case‑insensitive results without extra query‑time logic.

Quick Answers

  • What does “add documents to index” mean? It means loading source files into a searchable data structure so they can be queried later.
  • Why use character replacement? It normalizes every character—typically to lower‑case—so searches ignore case differences automatically.
  • Do I need a license? A free trial works for development; a full license is required for production deployments.
  • Which Java version is required? Java 8 or newer; the library targets Java 11+ for optimal performance.
  • Can I switch to case‑sensitive search when needed? Yes—search options let you toggle case‑sensitivity per query.

What is “add documents to index” in GroupDocs.Search?

Load your source files (PDF, DOCX, TXT, etc.) into a searchable index so the engine can retrieve them quickly. Adding documents to an index parses each file, extracts plain text, and stores it in an optimized data structure that enables fast look‑ups.

Why enable character replacement during indexing?

Character replacement converts each character to a predefined equivalent—most commonly lower‑case—while the index is built. This ensures that variations in capitalization, diacritics, or locale‑specific symbols do not affect search results. By normalizing text at indexing time, the engine can match queries against a consistent token set, providing fast, reliable case‑insensitive behavior without additional processing during each search.

Prerequisites

  • GroupDocs.Search for Java version 25.4 or newer (the library supports 30+ file formats and can index multi‑hundred‑page documents without loading the whole file into memory).
  • Java Development Kit (JDK) 8 or later installed.
  • Basic familiarity with Maven (or ability to add JARs manually).

Setting Up GroupDocs.Search for Java

Maven Setup

Add the GroupDocs 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

If you prefer not to use Maven, grab the latest JAR from the official site: GroupDocs.Search for Java releases.

License Acquisition

  • Free Trial – download a trial license to start experimenting.
  • Temporary License – request an extended testing license from the GroupDocs portal.
  • Full License – purchase a production license when you’re ready to go live.

Basic Initialization (Create the index)

The following snippet creates an index folder and enables character replacements:

import com.groupdocs.search.Index;
import com.groupdocs.search.IndexSettings;

String indexFolder = "YOUR_OUTPUT_DIRECTORY/AdvancedUsage/Indexing/CharacterReplacementDuringIndexing";
IndexSettings settings = new IndexSettings();
settings.setUseCharacterReplacements(true);
Index index = new Index(indexFolder, settings);

Implementation Guide

Enable Character Replacement in Index Settings

Activating this feature tells the engine to replace characters while indexing, which is the core step for case‑insensitive behavior.

Step 1: Configure IndexSettings

IndexSettings is the configuration object that controls how the index stores and processes text. By setting useCharacterReplacements to true, you turn on automatic lower‑casing (or any custom mapping you provide).

import com.groupdocs.search.Index;
import com.groupdocs.search.IndexSettings;

String indexFolder = "YOUR_OUTPUT_DIRECTORY/AdvancedUsage/Indexing/CharacterReplacementDuringIndexing";

// Create an instance of IndexSettings and enable character replacement.
IndexSettings settings = new IndexSettings();
settings.setUseCharacterReplacements(true);

// Initialize the index with these settings.
Index index = new Index(indexFolder, settings);

Configure Character Replacements

Map each character to its lower‑case counterpart (or any custom mapping you need).

Step 2: Define and Add Replacement Pairs

The replacement dictionary holds pairs such as 'A' → 'a', 'É' → 'e', etc. Adding these pairs before indexing ensures every token is normalized.

import com.groupdocs.search.dictionaries.CharacterReplacementPair;

// Access existing replacements and clear them.
index.getDictionaries().getCharacterReplacements().clear();

// Create an array for new replacements.
CharacterReplacementPair[] characterReplacements = new CharacterReplacementPair[Character.MAX_VALUE + 1];
for (int i = 0; i < characterReplacements.length; i++) {
    char originalChar = (char) i;
    char replacementChar = Character.toLowerCase(originalChar);
    characterReplacements[i] = new CharacterReplacementPair(originalChar, replacementChar);
}

// Add these replacements to the index's dictionary.
index.getDictionaries().getCharacterReplacements().addRange(characterReplacements);

Indexing Documents

Now that the index is ready, you can add documents to index from any folder.

Step 3: Add Documents for Indexing

GroupDocs.Search scans the target directory, extracts text from each supported file type, applies the replacement map, and writes the tokens to the index storage.

import com.groupdocs.search.Index;

String documentFolder = "YOUR_DOCUMENT_DIRECTORY";

// Initialize the index and add documents.
Index index = new Index(indexFolder, settings);
index.add(documentFolder);

Perform Case‑Sensitive Search (Optional)

Step 4: Execute Case‑Sensitive Searches

SearchOptions configures query behavior, such as toggling case sensitivity, allowing fine‑grained control over how searches are performed.
SearchOptions.setUseCaseSensitiveSearch(true) forces the engine to treat upper‑ and lower‑case characters as distinct during a specific query, overriding the default case‑insensitive behavior.

import com.groupdocs.search.Index;
import com.groupdocs.search.SearchOptions;
import com.groupdocs.search.results.SearchResult;

String query = "Promotion";
SearchOptions options = new SearchOptions();
options.setUseCaseSensitiveSearch(true);

// Perform the search.
Index index = new Index(indexFolder, settings);
SearchResult result = index.search(query, options);

Practical Applications

  1. Marketing Campaigns – Normalize product names so sales teams can locate assets without worrying about case.
  2. Customer Support – Power help‑desk search boxes that return the right article whether the user types “login” or “Login”.
  3. E‑commerce Catalogs – Ensure shoppers find items regardless of how they type product titles, improving conversion rates.

Performance Considerations

  • Organize Source Files – A tidy folder hierarchy reduces the time spent scanning during the add documents to index step.
  • Monitor Memory – Indexing large corpora can consume significant RAM; processing files in batches of 500 – 1 000 items keeps heap usage under control.
  • Asynchronous Indexing – When supported, run indexing on a background thread to keep the UI responsive and avoid blocking user operations.

Common Issues & Troubleshooting

SymptomLikely CauseFix
No results returned for a known termCharacter replacements not enabledVerify settings.setUseCharacterReplacements(true) and that the replacement map contains the needed characters.
Out‑of‑memory error during indexingIndexing too many large files at onceIndex in smaller batches or increase JVM heap (-Xmx4g).
Search returns case‑sensitive results unexpectedlySearchOptions.setUseCaseSensitiveSearch(true) was setRemove or set to false for default case‑insensitive behavior.
Index load time exceeds expectationsInefficient folder layout or SSD not usedRe‑organize files, prune unused documents, and store the index on a fast SSD.
Special characters are ignoredReplacement map missing Unicode entriesAdd mappings for characters like “é”, “ß”, “ø” to their desired equivalents.

Frequently Asked Questions

Q: How do I handle special characters (e.g., “é”, “ß”) during indexing?
A: Include those characters in your replacement map, mapping them to their ASCII equivalents or keeping them unchanged based on search requirements.

Q: Can I limit character replacement to a specific language?
A: Yes. Build a custom replacement array that contains only the characters for the target language before adding it to the dictionary.

Q: What should I do if the index takes a long time to load?
A: Optimize the folder structure, remove unnecessary files, and store the index on a high‑speed SSD. Incremental indexing also reduces load overhead.

Q: Is it possible to revert the character replacements after indexing?
A: No. Replacements are baked into the indexed data; you must rebuild the index with new settings to change them.

Q: Where can I find more detailed API documentation?
A: The official docs and API reference provide exhaustive details (see Resources below).

Resources

Last Updated: 2026-07-31
Tested With: GroupDocs.Search 25.4 for Java
Author: GroupDocs