Introduction
The word "Why" holds the key to many inventions and better understanding in the scientific community. Perhaps this the reason "Why and How" are also used in our technical community. This blog generally focus on the understanding and debugging endeca queries. It gives an opportunity to the developers on "Why" the result is "A" instead of "B" and "How" this can be changed. Understanding the "Why Match" feature enables the developers to interpret the root level approach to a technical solution.
1. About the Why Match feature
The Why Match functionality allows an application developer to debug queries by examining which property value of a record matched a record search query and why it matched.
With Why Match enabled in an application, records returned as part of a record search query are augmented with extra dynamically generated properties that provide information about which record properties were involved in search matching.
a.) Enabling Why Match
You enable Why Match on a per-query basis using the Nx (Navigation Search Options) query parameter.No Developer Studio configuration or Dgraph flags are required to enable this feature.
However, because Why Match applies only to record search navigation requests, dynamically-generated properties only appear in records that are the result of a record search
b.) Why Match API
The MDEX Engine returns match information for each record as a DGraph.WhyMatch property in the search results.
The following code samples show how to extract and display the DGraph.WhyMatch property from a record.
Java example
// Retrieve properties from record
PropertyMap propsMap = rec.getProperties();
// Get the WhyMatch property value
String wm = (String) propsMap.get("DGraph.WhyMatch");
// Display the WM value if one exists
if (wm != null) {
%>This record matched on <%= wm %>
<%
}
c.) Why Match performance impact
The response times for MDEX Engine requests that include Why Match properties are more expensive than requests without this feature. The performance cost increases as the number of records returned with the DGraph.WhyMatch property increases.
This feature is intended for development environments to record matching. The feature is not intended for production environments and is not particularly optimized for performance.
2. About the Word Interpretation feature
The Word Interpretation feature reports word or phrase substitutions made during text search
processing.
The Word Interpretation feature is particularly useful for highlighting variants of search keywords that appear in displayed search results. These variants may result from stemming, thesaurus expansion, or spelling correction.
a.) Implementing Word Interpretation
The --wordinterp flag to the Dgraph command must be set to enable the Word Interpretation
feature.
The Word Interpretation feature does not require any work in Developer Studio. There are no Dgidx flags necessary to enable this feature, nor are there any MDEX Engine URL query parameters.
b.) Word Interpretation API methods
The MDEX Engine returns word interpretation match information in ESearchReport objects.
This word interpretation information is useful for highlighting or informing users about query expansion.
The Java ESearchReport.getWordInterps() method return the set of word interpretations used in the current text search. Each word interpretation is a key/value pair corresponding to the original search term and its interpretation by the MDEX Engine.
Java example
// Get the Map of ESearchReport objects
Map recSrchRpts = nav.getESearchReports();
if (recSrchRpts.size() > 0) {
// Get the user’s search key
String searchKey = request.getParameter("Ntk");
if (searchKey != null) {
if (recSrchRpts.containsKey(searchKey)) {
// Get the ERecSearchReport for the search key
ESearchReport searchReport = (ESearchReport)rec¬
SrchRpts.get(searchKey);
// Get the PropertyMap of word interpretations
PropertyMap wordMap = searchReport.getWordInterps();
// Get property iterator
Iterator props = wordMap.entrySet().iterator();
// Loop over properties
while (props.hasNext()) {
// Get individual property
Property prop = (Property)props.next();
String propKey = (String)prop.getKey();
String propVal = (String)prop.getValue();
// Display word interpretation information
%><tr>
<td>Original term: <%= propKey %></td>
<td>Interpreted as: <%= propVal %></td>
</tr><%
}
}
}
}
3. About the Why Rank feature
The Why Rank feature returns information that describes which relevance ranking modules were evaluated during a query and describes how query results were ranked. This information allows an application developer to debug relevance ranking behavior.
With Why Rank enabled in an application, the MDEX Engine returns records that are augmented with additional dynamically generated properties. The MDEX Engine also a returns summary information (in a Supplement object) about relevance ranking for a query. The properties provide information that describe which relevance ranking modules ordered the results and indicate why a particular record was ranked in the way that it was.
a.) Enabling Why Rank
You enable Why Rank on a per-query basis using the Nx (Navigation Search Options) query parameter or the Dx (Dimension Search Options) query parameter. No Developer Studio configuration or Dgraph flags are required to enable this feature.
b.) Why Rank API
The MDEX Engine returns relevance ranking information as a DGraph.WhyRank property on each record in the search results. The MDEX Engine also returns summary information for all record results in a Supplement object.
Java example
// Retrieve properties from record
PropertyMap propsMap = rec.getProperties();
// Get the WhyRank property value
String wr = (String) propsMap.get("DGraph.WhyRank");
// Display the WR value if one exists
if (wr != null) {
%>This record was ranked by <%= wr %>
<%
}
Here is an example of a query and a DGraph.WhyRank property from a record in the result set.
Suppose there is a query submitted to an MDEX Engine using the following query parameters:
N=0&Ntk=NoEssay&Ntt=one+two&Ntx=rel+phrase(considerFieldRanks)&Nx=whyrank.
The query produces a result set where one of the records contains the following DGraph.WhyRank property:
<Property Key="DGraph.WhyRank" Value="[ { "phrase" : { "evaluationTime" :
"0", "stratumRank" : "20", "stratumDesc" : "phrase match", "rankedField" :
"English" }} ]">
c.) Why Rank performance impact
The response times for MDEX Engine requests that include Why Rank properties are more expensive than requests without this feature. The performance cost increases as the number of records returned with the DGraph.WhyRank property increases.
This feature is intended for development environments to troubleshoot relevance ranking. The feature is not intended for production environments and is not particularly optimized for performance.
4. About the Why Precedence Rule Fired feature
The Why Precedence Rule Fired feature returns information that explains why a precedence rule fired.This information allows an application developer to debug how dimensions are displayed using precedence rules.
With the feature enabled in an application, the root dimension values that the MDEX Engine returns are augmented with additional dynamically generated properties. The properties provide information that describe how the precedence rule was triggered (explicitly or implicitly), which dimension ID and name triggered the precedence rule, and the type of precedence rule (standard, leaf, or default).
a.) Enabling Why Precedence Rule Fired
You enable Why Precedence Rule Fired on a per-query basis using the Nx (Navigation Search Options) query parameter. No Developer Studio configuration or Dgraph flags are required to enable this feature.
b.) Why Precedence Rule Fired API
The MDEX Engine returns information about why a precedence rule fired as a DGraph.WhyPrecedenceRuleFired property on each root dimension value.
The following code samples show how to extract and display the DGraph.WhyPrecedenceRuleFired property from a root dimension value.
Java example
// Retrieve the results object.
Navigation result = results.getNavigation();
// Retrieve the refinements.
DimensionList l = result.getRefinementDimensions();
// Retrieve the dimension with ID 80000.
Dimension d = l.getDimension(800000);
// Retrieve the root dval for the dimension.
DimVal root = d.getRoot();
PropertyMap propsMap = root.getProperties();
// Get the WhyPrecedenceRuleFired property value
String wprf = (String) propsMap.get("DGraph.WhyPrecedenceRuleFired");
// Display the value if one exists
if (wprf != null) {
//Do something
}
c.) Why Precedence Rule Fired property format
The DGraph.WhyPrecedenceRuleFired property value has a multi-part format that is made up of a list of trigger reasons and trigger values that were evaluated for each precedence rule.
The DGraph.WhyPrecedenceRuleFired property is returned as a JSON object with the following format:
[
{ "triggerReason" : "<Reason>", "triggerDimensionValues" : ["<DimensionID>,
... "], "ruleType" : "<Type>", "sourceDimension" : "<DimensionName>",
"sourceDimensionValue" : "<DimensionID>" },
...
]
d.) Performance impact of Why Precedence Rule Fired
The Why Precedence Rule Fired feature is intended for a production environment.The response times for MDEX Engine requests that include DGraph.WhyPrecedenceRuleFired properties are slightly more expensive than requests without this feature. In general, the feature adds performance throughput costs that are typically observed to be less than 5%.
