Introduction

This article illustrates the steps to perform operations with variants, specifically:

Setup fields for variants
Index variant information
Searching against variants

Overview

Hawksearch supports both indexing variants and searching against variants in a feature that is called variant logic. Variants are typically defined as a parent child relationship between product groups and SKUs, however there are plenty of use cases where it might make sense to use variant logic.

Enabling variants is done at the account level, therefore, all indexes under a specific account will have variant logic if enabled.

Important Prerequisite information

Variant Logic does NOT update fields or variants within a document. You should not be using the update-items endpoint when indexing with variants. You must override the entire item when adding or removing parent or child level attributes or variants within a product group.
Up to 1000 variants per product group are supported.
Variant Logic is a lot of times combined with the query object that can be passed in the search request to achieve complex UI requirements. If you have questions on how to achieve a specific layout, please reach out to Support Specialist or your Project Manager.

Field-Specific Search - V2

Fields Set up

When variant logic is enabled on an account you will notice that on the fields edit screen there is a new on/off toggle that is displayed to indicate if a field is a parent or a child field.

When the “Is Child Field” toggle is set to off, the field is considered a parent level field. A parent level field is used to indicate that values in this field will be the same for every sku in a single product group, for every product group in the catalog. A good example of a parent level field is the brand field.

When the “Is Child Field” toggle is set to on, the field is considered a child level field. A child level field indicates that there can be variance going across sku’s in a single product group. Good examples of child level fields would be color and size. Take an example for a clothing store that sells shirts. Typically, the same style of shirt can come in multiple colors and sizes. By defining these two attributes as child level attributes, you are letting Hawksearch know that these attributes are related to one another, and they vary within a single product.

Screenshot of the Fields Edit Screen

Indexing API

When indexing variants within Hawksearch, you can leverage the same indexing api in which one would use to index non-variant accounts.

Hawksearch v4.0 - Indexing API

https://indexingapi-na.hawksearch.com/swagger/ui/index#/IndexV2

This API endpoint has been extended to support variants by adding a specialized array object where one can pass in variant child groups. This name of this object is the “hawk_child_attributes” object.

The fields that are defined as parent would be stored at the same level of the document as the “hawk_child_attributes” object. Fields defined as Child Field should be nested objects within the “hawk_child_attributes” array.

Example of Variant Indexing Request

POST https://indexing-dev.hawksearch.net/v2/indexing/index-items

{
	"IndexName": "demo.20210608.103512.variantindex",
	"Items": [{
		"_id": ["1"],
		"product_name": ["Shirt"],
		"brand": ["Nike"],
		"hawk_child_attributes": [{
				"size": ["Medium"],
				"color": ["Blue"]
			},
			{
				"size": ["Large"],
				"color": ["Blue"]
			},
			{
				"size": ["Medium"],
				"color": ["Red"]
			}
		]
	}]
}

Search API

When searching for variants within Hawksearch, you can leverage the same search api in which one would use to search againstnon-variant accounts.

Hawksearch v4.0 - Search API

https://essearchapi-na.hawksearch.com/swagger/ui/index#!/SearchV2/SearchV2_Search

This API endpoint has been extended to support variants by adding a specialized array object that is used to return all variant information. The name of this object is the “hawk_child_attributes” object. A second object is also included that returns variants that find a match on the keyword and are filtered facet selections. The name of this object is named “hawk_child_attributes_hits”. The “hawk_child_attributes_hits” object contains 3 objects. The information included in these objects is described in the following table.

Key	Description
NofResults	Number of variants that match the keyword and facets
NofPages	Number of pages of variant options.
Items	Array of variant objects

In terms of relevancy, parent level fields roll down to the children, therefore if someone searches for a parent level field, all variants will match. If there is not a match on any variant, the full document will not display in the search response.

As part of our search request, we have added into the ability override variant options as part of the search request. Below are the options

Key	Description	Default Value
CountFacetHitOnChild	Used to specify if you want the facet count to be calculated based off the parents or the children.	False
PageNo	Specifies the page number for all variants	1
MaxPerPage	Specifies the Max Per Page for all variants (Up to 300 max)	1
SortCode	Gives you the ability to specify a sorting set for the variants	None
Sort By	Gives you the ability to override the sort of the variants	Score

When determining the score of the parent product, we are taking the score of the variant with the highest score and combining it with the score of the parent level attributes. This will handle sorting global across product groups.

Example of Variant Search Request and Response– Default Values

Request

POST https://searchapi-dev.hawksearch.net/api/v2/search

Response

Example of Variant Search Request and Response – With Options Override

Request

Response

List of Options to Override

Lines 4 through 10 indicate options override for variants

Hawksearch Knowledge Base

Hawksearch 4.0 Variants

Table of Contents