Adding custom configuration to Dimension Matchmaker

Endpoint

http://{host}:{port}/search/resources/api/v2/configuration?nodeName=dimensions&envType=auth&locale=en_US

Example

{ 

"pattern": “LWH”, 
“key”:”width” 

} 

Sample JSON configuration usage

The pattern parameter is used when no dimensions are provided by the shopper while searching for the products at the storefront. For example, the shopper used the search term, 120cm x 75cm x 80cm table, to search for a table at the storefront. Since in the search term the shopper has not provided any dimensions for the table, the search results are displayed based on the specified pattern configuration (LWH) in Zookeeper. Based on this configuration, the following dimensions are used by HCL Commerce Search to fetch the search results at the storefront:

Length: 120cm, Width: 80cm, Height: 75cm

The pattern parameter is not used when a shopper has provided the specific dimensions while searching for the products at the storefront. The search results are displayed at the storefront based on the dimensions provided by the shopper in the search term. For example, 60cm W x 80cm L x 70cm H table. Based on these shopper provided dimensions, the following dimensions are used by HCL Commerce Search to fetch the search results at the storefront:

Length: 80cm, Width: 60cm, Height: 70cm

HCL Commerce Search does not index depth(D). It only indexes Width, Length, and Height. So, the Key parameter is used to convert this D/depth/thickness into one of the Width, Length, or Height. This D/depth/thickness is converted based on the specified Key configuration (width) in Zookeeper. For example, the shopper used the search term, 10 cm H x 20 cm L x 30 cm D, to search for a food storage container at the storefront. While fetching the search results at the storefront HCL Commerce Search replaces this D with the specified Key configuration (width) in Zookeeper. The following dimensions are used by HCL Commerce Search to fetch the search results at the storefront:

Height: 10 cm, Length: 20cm, Width: 30 cm

In case of conflict between pattern and Key parameters configured in Zookeeper, the fallback WLH configuration is used for the pattern. For example, the shopper used the search term, 10cm L x 20cm W x 30cm D, to search for a food storage container at the storefront. In this case, HCL Commerce Search replaces D with the specified Key configuration (width) in Zookeeper. So, the pattern for search processing results into LWW, Length: 10cm, Width: 20cm , 30 cm Height: <Empty>. HCL Commerce Search does not consider this pattern to fetch the search result at the storefront. It neglects the pattern configuration (LWH) set in Zookeeper and fallbacks to pattern configuration, WLH. The following dimensions are used by HCL Commerce Search to fetch the search results at the storefront:

Width: 10 cm, Length: 20cm, Height: 30cm

Configure fallback unit of measurement

{

               "pattern": “LWH”,
               “key”:”width”,
                “uom”: inch

}

In the aforementioned JSON “uom”: inch indicates that inch has been configured as a fallback unit of measurement. This means when the shopper searches for the box using the search query, 5 x 5 box, then the HCL Commerce Search returns the search results using the fallback unit of measurement inch that has been configured in the aforementioned JSON.

Searching by numeric values, measurements, and dimensions

This topic describes how HCL Commerce Search parses numeric search terms, generic unit-of-measure expressions, and dimension matchmaker expressions in HCL Commerce version 9.1.21.0. Use this information to understand how shoppers can search by numbers, fractions, mixed fractions, measurements, and product dimensions, and how the generated search metadata can be used to understand parser behavior.

Search terms can contain product text together with numeric values. During query preprocessing, the search service identifies different numeric patterns and converts them into the appropriate search constraints. Product words continue to be searched as normal text, while supported numeric expressions can be searched against attribute values, measurement fields, or dimension fields.

The following numeric search behaviors are supported:

• Standard cardinal number searches, such as 15 book or 1.5 table.
• Fraction and mixed-fraction searches, such as 3/4, 12 3/5, or 12 3/5 m.
• Generic unit-of-measure searches, such as 12cm book, 12 cm book, or 12.5 in.
• Dimension matchmaker searches without direction, such as table 12x15 or table 12 x 15 in.
• Directional dimension matchmaker searches, such as 3/4ft W x 12 3/5ft L or 12ft W x 15ft L x 13ft H.
• Comma separated dimension matchmaker searches, such as 12ft W,15ft L,13ft H and 13,15,8in (that is, 13 in x 15 in x 8 in).

Supported numeric formats

Standard cardinal numbers

A standard cardinal number is a numeric value that is not directly part of a unit-of-measure expression or a dimension expression. Cardinal numbers can be integers or decimals.

15 book
1.5 table
15 5 25 30 35 book

When a search term contains cardinal numbers, the query includes those values as numeric terms. If several cardinal numbers are present, documents that contain more of the requested values are ranked higher than documents that contain fewer matching values. For example, a document that contains 15, 5, 25, 30, and 35 is scored ahead of a document that contains only some of those values.

Fractions and mixed fractions

A fraction must be entered as numerator/denominator, with no spaces around the slash. A mixed fraction must be entered as a whole number followed by a space and then a fraction.

Fraction format: 3/4
Mixed fraction format: 12 3/5

Fractions and mixed fractions are normalized before measurement or dimension matching. For example, 3/4 is normalized to 0.75, and 12 3/5 is normalized to 12.6. This allows shoppers to search using familiar fractional measurements while the query uses normalized numeric values for matching.

Generic unit-of-measure searches

A generic unit-of-measure expression is a numeric value followed by a unit. The value can be an integer, decimal, fraction, or mixed fraction. The unit can be written with or without a space after the value, depending on the unit entered by the shopper.

12cm book
12 cm book
12.5 in
12 3/5 m

The numeric value and the unit of measure can be provided with or without a space when the unit is configured for the locale. For example, 12cm and 12 cm are both supported. Decimal values such as 12.5 in are also supported. For mixed fractions, the space between the whole number and the fractional value is part of the expected format, for example 12 3/5 m.

If a fraction or mixed fraction is provided without a unit of measure, and it is not part of a DMM expression, it is handled as a normal text search. Generic measurement matching requires a unit of measure.

Generic unit-of-measure searches are searched against measurement fields. For example, 12cm book searches for the product text book and the 12 centimeter measurement. Similarly, 12 3/5 m is normalized to 12.6 and searched as a meter measurement.

Dimension matchmaker searches

Dimension matchmaker (DMM) processing identifies two-dimensional and three-dimensional measurements in the search term. A DMM expression can be written with separators such as x, X , ',' (comma) or *. When the search term does not explicitly provide a width, length, or height direction, the configured default dimension pattern is used to map values to dimension fields.

DMM without direction

Use this form when the search term contains dimensions but does not specify W, L, H, width, length, height, or similar direction terms. The query maps the values according to the configured default DMM pattern. In the default behavior, the first value maps to width, the second value maps to length, and the third value maps to height.

table 12x15
table 12 x 15 in
table 12 x 15 x 13 ft
1.5 5 table 12 x 15 in

When a unit is specified once after a non-directional DMM expression, the unit is applied to the DMM values. For example, table 12 x 15 in searches width 12 inch and length 15 inch. Non-directional DMM can be used together with standard cardinal numbers and text terms. For example, 1.5 5 table 12 x 15 in searches 1.5 and 5 as cardinal values, table as product text, and 12 x 15 in as DMM.

The unit of measure can be entered with or without a space from the numeric value. For example, table 12 x 15 in, table 12x15in, and 12ftx15in can be parsed as dimensional expressions when the unit is configured for the locale.

DMM processing supports two-dimensional and three-dimensional expressions. Two-dimensional searches map the values to width and length. Three-dimensional searches map the values to width, length, and height, unless explicit directions or a configured dimension pattern determine a different mapping.

If only one unit of measure is provided for a DMM expression, that unit is applied to all dimensions. For example, table 12 x 15 in is interpreted as width 12 inch and length 15 inch. Similarly, table 12 x 15 x 13 ft is interpreted as width 12 foot, length 15 foot, and height 13 foot.

If two units of measure are provided for a three-dimensional DMM expression, the provided units are applied positionally, and the first provided unit is used for the dimension where the unit is not specified. For example, in a three-dimensional expression such as 12ft x 15 x 13in, the missing middle unit is interpreted using the first provided unit.

If all dimensions include their own unit of measure, each unit is assigned to its corresponding dimension. For example, 12ft x 15in x 13cm applies foot, inch, and centimeter respectively.

If a DMM expression does not include a unit of measure, the configured default unit is used. If no default unit is configured, centimeter is used as the fallback unit for DMM searches that can be handled by the parser.

Directional DMM

Use this form when the search term explicitly identifies a dimension direction. Directional DMM can include short forms such as W, L, and H, or equivalent words such as wide, long, high, width, length, and height. Directional DMM can also contain fraction, mixed-fraction, and decimal values.

3/4ft W x 12 3/5ft L
12ft W x 15ft L x 13ft H
12.5 W x 15.75 L x 13.25 H ft
12 long rope
book of thickness 12 in

For example, 3/4ft W x 12 3/5ft L searches width 0.75 foot and length 12.6 foot. A compact expression such as 12ftWx15ftLx13ftH searches width 12 foot, length 15 foot, and height 13 foot.

Combining text with numeric search terms

Shoppers can include product text along with numeric expressions. Product text is searched as the main text portion of the query, while supported numeric expressions are converted into numeric, measurement, or dimension constraints.

book 12cm
black book 35x15ft 12cm
table 12x15
1.5 5 table 12 x 15 in

If a search term contains both a generic measurement and a non-directional DMM expression, both can be represented in the query. For example, black book 35x15ft 12cm can search black as a color term, book as product text, 35 x 15 ft as DMM, and 12 cm as a generic measurement.

Search term metadata

When search term metadata is enabled, the response can include parser details under the nlp object. This metadata helps explain how the search term was interpreted and which parts of the term were used for text, unit-of-measure, dimension, color, fraction, or cardinal-number processing.

The following metadata fields can be used to understand numeric search behavior:

• pos: Shows identified parts of speech, such as nouns and adjectives.
• uom: Shows generic unit-of-measure parsing, including the original value and the normalized unit.
• fraction: Shows fraction or mixed-fraction normalization when applicable.
• dmm: Shows DMM parsing, including mapped width, length, and height values.
• color: Shows identified color terms.
• cardinal: Shows standard numeric values that were retained as cardinal-number searches.

For example, a search term such as 15 5 25 30 35 book 35x15ft black 12cm can produce metadata that indicates book as a noun, black as a color, 12cm as a generic centimeter measurement, 35x15ft as DMM, and 15, 5, 25, 30, and 35 as cardinal numbers.

"nlp": {
"pos": "NOUN --> [book] | ADJECTIVE --> [black]",
"uom": "12cm --> 12 centimeter",
"dmm": "35 15 ft --> 35 foot width | 15 foot length",
"color": "COLOR --> [black]",
"cardinal": "15 | 5 | 25 | 30 | 35"
}

Scoring behavior for standard number searches

For standard cardinal-number searches, the generated query can include multiple numeric values. Products that contain all requested standard numbers receive the highest relevance among the numeric matches. Products that contain fewer of the requested numbers are ranked lower. This behavior allows a search such as 15 5 25 30 35 book to prefer products whose indexed attributes contain all of the requested values, followed by products that contain the next highest number of matching values.

This scoring behavior applies to standard cardinal-number matching. It does not replace DMM field matching or generic unit-of-measure matching. Measurements and DMM expressions are searched against their corresponding measurement or dimension fields.