Specification Search in the catalog system

           Specification search is a cool feature in the product catalog system which allows you to search products in a category based on the specifications of the products in that category. In a way it resembles a drill down search since it allows you to drill down to the products based on product specifications. To illustrate this consider a category named Printers in the Computer Bits catalog, containing a set of printers.Each printer has attributes like ColorPrinting, Manufacturer, PrintingTechnology etc. Specification search allows you to get the list of products with desired specifications eg ColorPrinting='Yes' AND PrintingTechnology='Laser'.

Implementing specification search on the runtime site.

  • Identify all the properties which define the product specifications and set the IncludeInSpecSearch attribute to true.  

  • For each category (in individual catalogs) that you want to be specification searchable set the IsSearchable property to -1 (true).

  • On the runtime site, the first task would be to display all the specification searchable categories.

  • The ProductCatalog.SpecificationSearchableCategories property  in the RuntimeBCLs returns a collection of categories in the catalog that are specification searchable. 

CatalogContext catalogContext = CommerceContext.Current.CatalogSystem;
ProductCatalog productCatalog = catalogContext.GetCatalog("Computer Bits");

ReadOnlyStringCollection searchableCategories = productCatalog.SpecificationSearchableCategories;


  • When the user clicks on a category the next task would be to display the specification searchable properties and a list of distinct values for each property, for all the products under that category.

SpecificationSearchPropertyResult [] propertyValues;
string searchHandle = productCatalog.BeginSpecificationSearch(”Printers”, out propertyValues);         

foreach(SpecificationSearchPropertyResult specificationSearchableproperty in propertyValues)


            String propertyName = specificationSearchableproperty.Property;

            object [] values = specificationSearchableproperty.Values;



The propertyValues is an array of SpecificationSearchPropertyResult class. Each propertyValue has a property called Property which contains the name of the property and another property called Values which contains the distinct values the property has for all the products under that category.

There are two things that can be done on this page depending on which button the user clicks.

  1. Refine Search: Clicking on Refine search should display a similar screen but with only the the property values that match the listbox selection in the previous screen.For each value selected by the user in the list box you should call ProductCatalog.AddSpecificationSearchClause and then finally call ProductCatalog.PerformSpecificationSearch to get the new set of property values.                         
    string searchHandle = productCatalog.BeginSpecificationSearch("Printers", out initialPropertyValues);
    searchHandle = productCatalog.AddSpecificationSearchClause(@"[ColorPrinting]=N'Yes'", searchHandle);
    searchHandle = productCatalog.AddSpecificationSearchClause(@"[Manufacturer]=N'SuperLaser Technologies'", searchHandle);
    SpecificationSearchPropertyResult [] propertyValues;
    DataSet searchResults = productCatalog.PerformSpecificationSearch(searchHandle, out initialPropertyValues);

  2. Display Products: Clicking on Display Products should finally display the list of products that match the users specifications. For each value selected by the user in the list box you should call ProductCatalog.AddSpecificationSearchClause and then finally call ProductCatalog.PerformSpecificationSearch to get the list of products that match the user's specifications. 

 string searchHandle = productCatalog.BeginSpecificationSearch("Printers", out initialPropertyValues);
 searchHandle = productCatalog.AddSpecificationSearchClause(@"[ColorPrinting]=N'Yes'", searchHandle);
 searchHandle = productCatalog.AddSpecificationSearchClause(@"[Manufacturer]=N'SuperLaser Technologies'",  searchHandle);
 searchHandle = productCatalog.AddSpecificationSearchClause(@"[PrintingTechnology]=N'Laser'", searchHandle);
 SpecificationSearchPropertyResult [] propertyValues;
 DataSet searchResults = productCatalog.PerformSpecificationSearch(searchHandle, out initialPropertyValues);

The searchResults dataset will contain the list of products that match the product specifications. You can also use an overload of the ProductCatalog.PerformSpecificationSearch method which takes a CatalogSearchOptions object to further filter the search results. Instead of using ProductCatalog.PerformSpecificationSearch you can also use ProductCatalog.GuaranteedSpecificationSearch method to return the search results. The difference between ProductCatalog.PerformSpecificationSearch and ProductCatalog.GuaranteedSpecificationSearch is that ProductCatalog.GuaranteedSpecificationSearch always returns a non empty dataset if the category that you are performing the search on is not empty. It does this by removing the clauses you added using the ProductCatalog.AddSpecificationSearchClause one by one (starting with the last clause) until the method can return a non empty dataset. For eg if you add PrintinngTechnology='Yes' AND Manufacturer='SuperLaser Technologies' as the search clauese then   ProductCatalog.GuaranteedSpecificationSearch  will first check if there are any products in that category that match these conditions. If not then it will remove the Manufacturer='SuperLaser Technologies' clause and attempt to return results for the PrintinngTechnology='Yes' clause. If this clause is also not able to return results then this method will remove this clause and return all the products in the category.


The other Specification Search related methods are

Comments (5)

  1. Robin Smith says:

    This is a beautiful explanation. I never understood the specification search feature up until now.Will this be implemented in the Retail2002 site in future?

Skip to main content