Services Integration Framework Guide

10.4 HotFix 3

Back Next

SearchMatch

A SearchMatch request generates a list of search results by identifying matching records in a package or base object using MDM Hub match columns and, optionally, match rule sets. For information on configuring match columns and match rule sets, see the

Multidomain MDM Configuration Guide

Records must be tokenized or the records cannot be returned as match results. Use the

Tokenize

API or batch job to tokenize records.

SearchMatch

returns a list of matching records. This is unlike the Hub match batch process, which creates a list of match candidates in the Operational Reference Store that you retrieve using

GetMatchedRecords

When you perform an extended search, the default match rule set must have fuzzy match keys. If fuzzy match keys are absent, the

SearchMatch

API does not return search results.

For information about performing exact matches on fuzzy base objects, see Exact Matches on Fuzzy Base Objects.

Required Parameters

The required SearchMatch Request parameters are described in the following table:

Parameter	Description
RecordsToReturn	Number of records to return.
MatchColumnField or RecordsToMatch	Specifies which match columns or match rules are used for matching: MatchColumnField: The name of a single match column or a list of match columns to use in matching. RecordsToMatch: The Hub uses all possible match columns configured for the record or records listed in RecordsToMatch. The Hub does not use the match columns that are based on fields for which the records have no value. Use MatchColumnUid to restrict match columns further. The match columns that result from using the RecordsToMatch parameter override the match columns specified by MatchColumnField.
SiperianObjectUid	Package or base object to search.
MatchType	Specifies how match rules are used in the search. If you do not specify the MatchType, SearchMatch uses the default MatchType of NONE . You can specify one of the following match types: BOTH . Uses the automatic and the manual merge match rules. AUTO . Uses the automatic merge match rules. NONE . Uses the automatic and the manual merge match rules. If you selected exact-match columns in the Selected Match Columns list, and a selected record contains a value for that exact-match column, the match process identifies duplicate records based on the exact-match column plus the match rules. DBFILTERED . Increases performance when a fuzzy search is based on a nonselective term.

Undermatching when using MatchType AUTO and BOTH

The

AUTO

and

BOTH

MatchType may result in undermatching if the search request contains empty fields. Users may not provide data for every field when performing a search from a custom client application. If an empty field is configured as an exact match column in the match rules, any potential search result containing data in these fields is excluded from the search results returned by

SearchMatch

MatchType NONE

A SearchMatch with MatchType

NONE

can be performed in one of two ways:

Without using match rules. The match is performed by giving all columns equal weight, with no required fields. Undermatching is avoided because empty fields in the search request are ignored, which prevents relevant records from being excluded from the search results. However, overmatching and misleading match scores can occur because nonselective fields, such as Gender, are given the same weight as selective fields, such as Customer ID.

Using a match rule set that has Enable Search by Rules enabled in the Hub. The undermatching that can occur when using MatchType

AUTO

and

BOTH

is avoided because empty fields provided by the search request are ignored and not used to exclude search results. Overmatching and misleading match scores are avoided because the match rules give the columns an appropriate weight.

MatchType DBFILTERED

The DBFILTERED MatchType increases performance when a fuzzy search based on a nonselective term, such as Name="JOHN", also provides values for exact match columns. Nonselective fuzzy search terms provide excessive search results which cause

SearchMatch

to take longer than expected to complete. When the MatchType is DBFILTERED,

SearchMatch

performs in one of two ways:

If the fuzzy search term is selective, for example, JONATHAN LIVINGSTONE, SearchMatch functions as it does when MatchType is set to

BOTH

. Initial filtering is performed using the match key ranges generated by the Hub, and then additional filtering is performed by the Process Server using the exact match columns. This type of filtering reduces the number of database joins required and provides optimal SearchMatch performance for selective fuzzy search terms.

If the fuzzy search term is nonselective, for example, JOHN, initial filtering is done in the database on the exact match columns and match key ranges. This results in fewer records being returned to the Process Server for matching than would occur using the MatchType

AUTO

BOTH

. This type of filtering provides optimal SearchMatch performance for nonselective fuzzy search terms.

Consider the following when using the DBFILTERED MatchType:

A DBFILTERED match cannot be performed using the following types of exact match columns:

Exact match columns that have match subtype, non-equal matching, null matching, or segment matching enabled.

Exact match columns that are based on a concatenation of base object columns.

Ensure the lock on the schema has been released. API performance decreases when the schema is locked.

DBFILTERED

SearchMatch

performance decreases as the number of fuzzy match rules increases. Create a match rule set to use specifically for DBFILTERED SearchMatch that is limited to the match rules essential for database filtering.

Ensure low cardinality (preferably 1:1) between the base object providing the match key and the exact match columns used for filtering to increase database filtering performance.

Add custom column indexes to some of the exact match columns used for filtering to improve database filtering performance. Use as few custom column indexes as possible to avoid decreasing batch job performance.

Optional Parameters

The optional SearchMatch Request parameters are described in the following table:

Parameter	Description
includePending	includePending determines if SearchMatch includes pending records in the results. true : SearchMatch includes pending records in results. "Enable match on pending records" must be enabled for the base object in the Match Merge Hub setup. false : SearchMatch does not include pending records in results. The default is false . This parameter has no effect for base objects for which State Management is not enabled. See the Multidomain MDM Configuration Guide for more information on State Management.
sortCriteria	A string containing a comma-separated list of column names and a sort direction. For example, "LAST_NAME ASC, FIRST_NAME ASC" returns the search results sorted by last name and then first name, in ascending order. Use DESC to sort in descending order. The results are returned in random order if you do not specify the sort order, unless the MatchType is NONE . If the MatchType is not NONE , RecordsToReturn is specified, and sortCriteria is not specified, then the records are sorted based on the match score.
MatchRuleSetUid	A string containing the name of a match rule set. If a match rule set is not specified using this parameter, SearchMatch uses the default match rule set. You must use one of the following formats: A fully qualified SiperianObjectUid followed by the match rule set. For example, "MATCH_RULE_SET.C_PARTY\|Main". You must include the MATCH_RULE_SET prefix. Set to NULL to use the default match rule set. To set MatchRuleSetUid to NULL, omit MatchRuleSetUid from the SearchMatch request.
setDisablePaging	This parameter determines if paging is disabled. true : paging is disabled. false : paging is enabled. The default is false . Use GetSearchResults to fetch subsequent pages of search results.

Response Fields

The SearchMatch Response contains a list of matching records as well as the information described in the following table for each record:

Field	Description
DEFINITIVE_MATCH_IND	Indicates whether a match was made using a match rule enabled for automatic merging. Matches made using auto-merge match rules typically result in closer matches than those made using manual-merge match rules. 1 : Match made using an auto-merge match rule. 0 : Match made without using a manual-merge match rule.
RULESET_NAME	Indicates which match rule set was used to make the match. The value for RULESET_NAME is GENERATED SEARCH when the MatchType is NONE .
RULE_NUMBER	Indicates the rule number of the match rule that was used to make the match. The value for RULE_NUMBER is 1 when the MatchType is NONE .
MATCH_SCORE	Indicates the match score of the result. If MatchType is equal to NONE , SearchMatch returns the match score, if available, so that the search results can be ranked by the match score. The match score is ignored when sorting if you specify a sort order using the sortCriteria parameter.

Use Case

This is the common scenario for using the SearchMatch Request:

Generate and then return a list of the possible matches in a given package or base object. Use the returned list of match candidates to merge or link records using

Merge

MultiMerge

, or

Link

The user specifies search criteria in a UI and the UI calls SearchMatch to find similar records and display the results to the user for editing.

SearchMatch Request Usage Example

The code in the following example searches for a match to 'EXAMPLES CORP' in the Organization_Name match column of the PARTY_ADDRESS_READ_PKG package. The results will be sorted based on the values in the NAME column in descending order. SearchMatch will use the default MatchType of

NONE

since no MatchType is specified.

SearchMatchRequest request = new SearchMatchRequest();
request.setRecordsToReturn(5); 
request.setSiperianObjectUid("PACKAGE.PARTY_ADDRESS_READ_PKG"); 
Field orgNameField = new Field("Organization_Name"); 
orgNameField.setStringValue("EXAMPLES CORP");
request.addMatchColumnField(orgNameField);
request.setSortCriteria("NAME DESC");
SearchMatchResponse response = (SearchMatchResponse) sipClient.process(request);

SearchMatch Response Usage Example

The code in the following example shows how to print out the records returned by the SearchMatch response.

SearchMatchResponse response = new SearchMatchResponse();
int i=0;
for(Iterator iter=response.getRecords().iterator(); iter.hasNext();) { 
//iterate through matched records
  System.out.println("Printing matched record " + i);
  Record record = (Record) iter.next();
  BigDecimal definitiveMatch = 
record.getField("DEFINITIVE_MATCH_IND").getBigDecimalValue();
  if(definitiveMatch.intValue()==1) System.out.println("Matched on an 
auto-merge rule");
  Collection fields = record.getFields();
  for(Iterator fieldIter=fields.iterator(); fieldIter.hasNext();) { 
//iterate through rest of fields
    Field f = (Field) fieldIter.next();
    System.out.println(f.getName() + ": " + f.getValue());
  }
}

Related SIF Requests

Tokenize, GetMatchedRecords, GetSearchResults, SearchQuery, Merge, MultiMerge, Link

Rename Saved Search

Table of Contents

Services Integration Framework Guide

Services Integration Framework Guide

SearchMatch

SearchMatch

Required Parameters

Undermatching when using MatchType AUTO and BOTH

MatchType NONE

MatchType DBFILTERED

Optional Parameters

Response Fields

Use Case

SearchMatch Request Usage Example

SearchMatch Response Usage Example

Related SIF Requests