Skip to content

Products

Products are a fundamental part of any ecommerce solution. Products in Ecommerce Search contain a set of data necessary for an optimal search experience. Products also contain specific SKUs, that have their own set of data. In order to search for a product, it must contain at least one SKU.

Product fields

Products contain various different fields:

  • ProductId is id of the product
  • ProductNumber is the product number
  • Name is the name of the product
  • ShortDescription contains a short description of the product
  • LongDescription contains a more detailed description of the product
  • Rating is the rating of the product from 0 to 5.
  • Metadata contains metadata for a product.
  • Media contains media data for the product.
  • Categories describes the categories of the product.
  • AlternativeIds contains alternative product ids.
  • AlternativeSearchWords can contain words describing the product which are not part of other product information.
  • ActiveFromUtc specifies when a product is active from.
  • ActiveToUtc specifies when a product is active to.

Searchable fields

For fields to be searchable, they have to be added as searchable fields for the segment.

Optionally, searchable fields can allow partial matching. This may be useful for longer product descriptions and titles, but not for specific values like product IDs and EANs.

For a field to contribute to boosting in a search result, the search relevance of the context has to be configured to boost the field.

All text fields on products and SKUs, including string attributes but excluding metadata and media, can be set as searchable.

Attributes

Attributes can be added to products depending on customer needs.

Warning

Attributes can cause field name conflicts. See field name priority for more information.

Metadata

Some data is not useful when searching for a product, creating a facet, or boosting the sort order. This kind of data should be included as metadata. If data is included as attributes, but is not used to search, facet or boosting, it will have an unnecessary negative impact on the performance of the system. It does not affect the performance when searching, but indexing, publications and diagnostics will take longer than they need to.

Metadata exists on both products and SKUs. When data is the same for all SKU variants of a product, it should be added to the product's metadata. Otherwise, it should be added to the specific SKU.

Metadata is very flexible. It can hold complex unstructured data like JSON or base64. However, if the data is kept simple or flat, and instead is spread out over more metadata-entries, it can be managed with the use of scopes.

Example use cases for Metadata

As metadata can be used for multiple different purposes, a few examples of use cases for metadata is provided.

Retrieve data directly

Metadata can be thought of as a way to keep relevant data about the product that should be returned with the product, but not otherwise used by Ecommerce Search. Metadata can be used to eliminate extra fetches from different sources.

graph TD;
    Search --> _1[Retrieve Product] --> _2[Fetch metadata from the PIM] --> _3[Display the product];
    _1 --> _3;
Campaign

Some campaign info makes sense to have as an attribute, since this allows search, faceting, and boosting based on its value. Other information about the campaign will be better suited as metadata.

Attribute
1
2
3
{
    "on_campaign": ["true"]
}
Metadata
1
2
3
4
{
    "campaign_img_id": "2for1",
    "campaign_name": "Christmas campaign"
}

Media

The media field is useful for adding images, files, videos or some other media to the product. A typical media entry could be an image of the product. Ecommerce Search does not store the actual image/file/video. Instead, it stores a link to it, together with some metadata. It is recommended to use the DAM for storing the media files. The metadata field can be used to supply relevant information about the image, like its retina version or resolution.

Categories

categories contain a list of paths to find categories the product is part of. A product can exist in multiple categories at a time.

Given a category hierarchy like this.

graph TD;
    Electronics --> Mobiles & Computers & Cables;
    Mobiles --> Phones & Tablets & _1[Mobile accessories];
    Computers --> Laptops & _2[Computer accessories];

A USB-cable that exists in both Cables, Mobile accessories and Computer accessories would then structure its categories like this.

"categories": [
    {
        "categoryPathElements": [
            {
                "categoryId": "cat-electronics",
                "categoryName": "Electronics"
            },
            {
                "categoryId": "cat-cables",
                "categoryName": "Cables"
            }
        ]
    },
    {
        "categoryPathElements": [
            {
                "categoryId": "cat-electronics",
                "categoryName": "Electronics"
            },
            {
                "categoryId": "cat-mobiles",
                "categoryName": "Mobiles"
            },
            {
                "categoryId": "cat-mobile-accessories",
                "categoryName": "Mobile accessories"
            }
        ]
    },
    {
        "categoryPathElements": [
            {
                "categoryId": "cat-electronics",
                "categoryName": "Electronics"
            },
            {
                "categoryId": "cat-computers",
                "categoryName": "Computers"
            },
            {
                "categoryId": "cat-computer-accessories",
                "categoryName": "Computer accessories"
            }
        ]
    }
]

Alternative ids

alternativeIds can be used to make a product filterable on specific ids. This is useful if an external system contains an internal id and has to integrate with Ecommerce Search. If the products are ingested with an alternative id, the external id can search with a searchId filter, and export based on that id.

Alternative ids can also be used to reference other products inside Ecommerce Search. If a product has spare parts, the product's id can be added to all the spare parts' alternative id field. Search with the product's id as a searchIds filter, then retrieves all its spare parts as well.

Alternative search words

alternativeSearchWords provides the product with additional words to find it by. They work similarly to synonyms](../text-analysis/synonyms.md) and hypernyms, and it must be carefully considered if those are not better suited for a given use-case.

The benefit of alternative search words is that they work on individual products. This makes sense for well-used abbreviations of, or alternative references to, the product name, such as Salad cheese -> Feta.

Note

It is important to keep in mind, that alternative search words cannot be changed through the Ecommerce Search user interface and requires patching of products to change it.

Warning

Beware of multi-word alternative search words, as they will mess up the search. If you add salad cheese as an alternative word to feta, and then search for salad you would get the feta product, which is not intended.

Active from UTC

activeFromUtc specifies when the product becomes active in the system. Before this date, it cannot be searched for and will not count towards facets. This allows the ingestion of products before they are released.

If the products should be searchable, but not purchasable, this must be handled outside of activeFromUtc. For instance, it is possible to add an attribute specifying whether the product is purchasable or not. Doing this eliminates the need to do an extra roundtrip to the PIM to check if the product is purchasable.

Active to UTC

activeToUtc specifies the end date of the product in the system. After this date, the product is no longer searchable and will not count towards facets.