Fuzzy-Matcher

To perform fuzzy matching, you must structure your data into Document and Element objects using their respective builders.

// Example of building a Document with Elements
List<Document> documentList = Arrays.asList(input).stream().map(contact -> {
    return new Document.Builder(contact[0]) // contact[0] is the unique Key
            .addElement(new Element.Builder<String>()
                    .setValue(contact[1])
                    .setType(NAME)
                    .createElement())
            .addElement(new Element.Builder<String>()
                    .setValue(contact[2])
                    .setType(ADDRESS)
                    .createElement())
            .createDocument();
}).collect(Collectors.toList());

Fuzzy-Matcher is a Java library designed to identify and group similar entities within a collection of documents. It operates by breaking down data through a hierarchical structure:

1. Document: The top-level entity (e.g., a Contact).
2. Element: Attributes within a document (e.g., name, address, email).
3. Token: The smallest unit of data derived from an Element via Tokenization.

The library then compares these tokens using a MatchType and calculates a similarity score through Scoring. The entire process is highly customizable through four stages: Pre-Processing, Tokenization, Match Type, and Scoring.

Fuzzy-Matcher supports several strategies for matching different data formats:

• Exact Word Match: Uses Word tokenization and Equality matching. Good for names where word order might vary (e.g., "Wayne Grace Jr." vs "Grace Hilton Wayne").
• Soundex Match: Uses Word-Soundex tokenization. Useful for phonetic similarities (e.g., "Steven" vs "Stephen").
• NGram Match: Uses N-Gram tokenization. Ideal for strings that aren't easily split by words, like emails.
• Nearest Neighbors Match: Uses Value tokenization and Nearest Neighbor matching. Best for continuous values like numeric amounts or dates where closeness matters more than exact equality.

Performance varies based on the MatchType used for your elements:

• EQUALITY: Linear performance O(N), where N is the number of Elements in all documents. This is the default for most types.
• NEAREST_NEIGHBOR: Performance is O(N logN). This is the default for NUMBER and DATE types. Performance is also influenced by the NeighborhoodRange setting; higher values generally perform better.

Tip: To guarantee linear performance for numeric/date types, override the MatchType to EQUALITY instead of using a NeighborhoodRange of 1.0.

Add the following dependency to your pom.xml to use Fuzzy-Matcher. Note that version 1.2.1 requires Java 11. If you are using Java 8, you must use version 1.1.x.

<dependency>
    <groupId>com.intuit.fuzzymatcher</groupId>
    <artifactId>fuzzy-matcher</artifactId>
    <version>1.2.1</version>
</dependency>

The MatchService returns a Map<String, List<Match<Document>>> where the key is the Document.key. Each Match<Document> object contains the following information:

// Accessing match details
match.getData();        // The source Document on which the match is applied
match.getMatchedWith();  // The target Document that the data matched with
match.getScore().getResult(); // The probability score between 0.0 - 1.0

The MatchService is the primary entry point for executing matches. It supports three distinct matching patterns depending on your use case.

MatchService matchService = new MatchService();

// 1. Match a list of Documents (De-duplication use case)
matchService.applyMatchByDocId(List<Document> documents);

// 2. Match a new list of Documents against an existing list (Bulk import use case)
matchService.applyMatchByDocId(List<Document> documents, List<Document> matchWith);

// 3. Match a single Document against an existing list (Single creation use case)
matchService.applyMatchByDocId(Document document, List<Document> matchWith);

When constructing a Document, the following configuration fields are available:

* __Key__: Required field indicating unique primary key of the document
* __Elements__: Set of elements for each document
* __Threshold__: A double value between 0.0 - 1.0, above which the document is considered as match.