Skip to content

X-Digital-Catalog provides high performance search queries for catalog data directly from search index engine

X-Digital-Catalog key features:

  • Full-text search (→)
  • Fuzzy search (→)
  • Filters syntax (↪)
  • Filter by category subtree (→)
  • Filter by price (→)
  • Filter by custom properties (→)
  • Filter by products availability (→)
  • Facets (→)
  • Multi-select faceting search (→)

How to use

Read this article...

QueryRoot

Product

This query allows you to get a product by Id and calculate all the fields based on the parameters sent.

Defenition:

product(id: !string, storeId: !string, userId: !string, currencyCode: string, cultureName: string)

Arguments:

№ Name Type Description
1 id Non null StringGraphType Product of the Id
2 storeId Non null StringGraphType Store Id
3 userId Non null StringGraphType Current user Id
4 currencyCode StringGraphType Currency code (e.g. "USD")
5 cultureName StringGraphType Culture name (e.g. "en-US")
#### Example: 
{
    product(
        id: "8b7b07c165924a879392f4f51a6f7ce0"
        storeId: "Electronics"
        userId: "d97ee2c7-e29d-440a-a43a-388eb5586087"
        cultureName: "en-us"
        currencyCode: "USD")
    {
        id
        name
    }
}
### Products
This connection allows you to search products.
#### Defenition:
products(productIds: string[], storeId: !string, userId: !string, currencyCode: string, cultureName: string, query: string, filter: string, fuzzy: bool, fuzzyLevel: int, facet: string, sort: string)
#### Arguments:
№ Name Type Description
-- ------------ ------------------------- ---------------------------
1 productIds List of StringGraphType Products Ids
2 storeId Non null StringGraphType Store Id
3 userId Non null StringGraphType Current user Id
4 currencyCode StringGraphType Currency code (e.g. "USD")
5 cultureName StringGraphType Culture name (e.g. "en-US")
6 query StringGraphType The query parameter performs the full-text search
7 filter StringGraphType This parameter applies a filter to the query results
8 fuzzy BooleanGraphType When the fuzzy query parameter is set to true the search endpoint will also return products that contain slight differences to the search text
9 fuzzyLevel IntGraphType The fuzziness level is quantified in terms of the Damerau-Levenshtein distance, this distance being the number of operations needed to transform one word into another
10 facet StringGraphType Facets calculate statistical counts to aid in faceted navigation
11 sort StringGraphType The sort expression

Example:

{
    products(
        storeId: "Electronics"
        userId: "d97ee2c7-e29d-440a-a43a-388eb5586087"
        cultureName: "en-Us"
        currencyCode: "USD"
        first: 10
        after: "10")
    {
        items
        {
            id
            code
        }
        pageInfo
        {
            hasNextPage
            startCursor
        }
    }
}

Categories

This connection allows you to search products.

Defenition:

categories(categoryIds: string[], storeId: !string, userId: !string, currencyCode: string, cultureName: string, query: string, filter: string, fuzzy: bool, fuzzyLevel: int, facet: string, sort: string)

Arguments:

№ Name Type Description
1 categoryIds List of StringGraphType Categories Ids
2 storeId Non null StringGraphType Store Id
3 userId Non null StringGraphType Current user Id
4 currencyCode StringGraphType Currency code (e.g. "USD")
5 cultureName StringGraphType Culture name (e.g. "en-US")
6 query StringGraphType The query parameter performs the full-text search
7 filter StringGraphType This parameter applies a filter to the query results
8 fuzzy BooleanGraphType When the fuzzy query parameter is set to true the search endpoint will also return products that contain slight differences to the search text
9 fuzzyLevel IntGraphType The fuzziness level is quantified in terms of the Damerau-Levenshtein distance, this distance being the number of operations needed to transform one word into another
10 facet StringGraphType Facets calculate statistical counts to aid in faceted navigation
11 sort StringGraphType The sort expression

Example:

{
    categories(
        storeId: "Electronics"
        userId: "d97ee2c7-e29d-440a-a43a-388eb5586087"
        cultureName: "en-Us"
        currencyCode: "USD"
        first: 10
        after: "10")
    {
        items
        {
            id
            name
            hasParent
        }
        pageInfo
        {
            hasNextPage
            startCursor
        }
    }
}

Queriable objects

ProductType

image

Schema fields:

№ Name Type Description
1 id StringGraphType The unique ID of the product
2 code StringGraphType The product SKU
3 catalogId StringGraphType CatalogId of the product
4 category CategoryType Field to resolve category of the requested product
5 name StringGraphType Name of the product
6 descriptions List of DesciptionType Reviews of product
7 productType StringGraphType The type of product
8 slug StringGraphType Url of the product
9 metaDescription StringGraphType Meta description of the product
10 metaKeywords StringGraphType Meta keywords of the product
11 metaTitle StringGraphType Meta title of the product
12 imgSrc StringGraphType Main image of the product
13 outerId StringGraphType Category outer Id
14 brandName StringGraphType Brand name of the product
15 masterVariation VariationType Main variation of the product
16 variations List of VariationType Product variations
17 availabilityData AvailabilityDataType Product availability information
18 images List of ImageType Product images
19 prices List of PriceType Product prices
20 properties List of PropertyType Product properties
21 assets List of AssetType Product assets
22 outlines List of OutlineType Category outlines
23 seoInfos List of SeoInfoType SEO information of the product
24 associations ProductAssociationType Product associations
25 breadcrumbs BreadcrumbType Product navigation information
### CategoryType
image
#### Schema fields:
№ Name Type Description
- ---------- ----------------------- -----------
1 id StringGraphType Id of category
2 code StringGraphType SKU of category
3 name StringGraphType Name of category
4 slug StringGraphType Url of category
5 parent CategoryType Field to resolve parent category
6 hasParent BooleanGraphType Indicates if category has parent
7 images List of ImageType Category images
8 outlines List of OutlineType Category outlines
9 seoInfos List of SeoInfoType SEO information of the category

Syntax

Full-Text Search

The query - parameter performs the full-text search on the product index document. Expects the full-text search phrase.

Searchable fields

The search conducts a full-text search over product data in the index. A product search returns all product variations a product has. We are stored all searchable text data of a product in one __content field in the resulting index document and perform full-text search only for this field.

product document in the index 

"__content": [
    "JGC-85796278",
    "ASUS ZenFone 2 ZE551ML Gold",
    "asus",
    "android",
    "2.3 ghz intel gtx quad-core",
    "micro-sim",
    "1080"
  ],
The following product properties are stored in the __content field and are searched by default.

  • product.name
  • product.code
  • product.seoinfos.seoinfo.slug
  • product.properties.value
  • product.variations.code
  • product.variations.properties.value

Example requests:

# Search all products by keyword `sony` and return the  name and primary image url for first 20 found products and total count
{
  products(query: "sony" storeId: "Electronics" first:20) {
      totalCount
      items
      {
        name
        imgSrc
      }
  }
}

When the fuzzy query parameter is set to true the search will also return product that contain slight differences to the search text. For example, when someone searches for ‘unversty’, the fuzzy search would also return products labelled with ‘university’. The fuzzy level can be optionally set with the parameter fuzzyLevel, otherwise the will be used auto fuzzy level based on the length of the searched text. Min value 3, max value 6.

Example requests:

# Will return products that have such terms "university", "unversty", "universe" etc.
{
  products(query: "unversty" storeId: "Electronics" first:20) {
      totalCount
      items
      {
        name
        imgSrc
      }
  }
}

Filter by category

Filter products that belong to exactly specified category path. filter: "category.path:{catalog id/category path}"

filter: "category.path:catalogId/cat1d1/cat2id"

The search will be performed on __path index field of product document

Filter by category subtrees, keep only the products that belong to the specified Category or any of its descendant categories. filter: "category.subtree:{catalog id/category path}"

filter: "category.subtree:catalogId/cat1d1/cat2id"

The search will be performed on __outline index field of product document

Filter by price

Keep only the products which Price match the specified value or range

filter: "price.{currency}.{pricelist?}:{range expression}"

filter: "price.usd:(TO 100]"

filter: "price.usd.pricelist_1:(20 TO 100]"

Keep only products that with at least one price set

filter: "is:priced

The search will be performed on price_{currency} and price_{currency}_{pricelist} index fields of product document Please note, that only the indexed prices were used for filtration. Scoped prices based on user groups or dynamic expressions temporary do not support filtration.

Filter by SKU

Keep only the product which matches the specified SKU: filter: "sku:DLL-65789352

Filter products or variations

Keep only the products or variations in result. If not set will return both types.

filter: "is:product

filter: "is:variation

Filter by custom properties

Keep only the products or variation with the custom attribute matching the specified value or range.

filter: "properties.{property name}: {value}

filter: "properties.color:red

To use property name contains spaces need to use the following syntax with escaped double quotes filter= "\"processor core (ghz)\":\"1.8 GHz Intel GTX Quad-Core\""

For numeric and date time properties you might use range filter

filter: "length:(10 TO 20)"

filter: "publishDate:(TO \"2020-01-28\")"

All product custom properties are stored in the index as fields with the same names as properties have. {property.name}:{property.value}

Filter by product availability

Keep only the products or variations with the availability matching the specified value or range.

filter: "available_in:{warehouse}"

filter: "available_in:my-warehouse"

The policy let select multiple values of the same facet (e.g using checkbox). You can read more for how the muti-select faceting search work on this great article How to implement multi-select faceting for nested documents in Solr and Elastic search post filter

The muti-select faceting search policy is enabled by default and you do not need any extra parameters or setting to activate it.

Sorting

By default, search results are sorted descending by their relevancy with respect to the provided text (that is their “score”). An alternative sorting can be specified via the sort query parameter which has the structure {field}:{asc|desc} you can combine multiple sort expression by semicolon ;

sort: "priority:desc;price_usd;score"

Facets

Faceted search (sometimes also called faceted navigation) allows users to navigate through a web site by applying filters for categories, attributes, price ranges and so on. The main idea behind faceted search is to present the attributes of the documents of the previous search result as filters, which can be used by the user to narrow down search results along with calculate statistical counts to aid.

Facet calculation is requested by providing facet expression via the facet query parameter. Consider for example the following two facets:

facet: "color price:[TO 100),[100 TO 200])"

The resulting json would be like seen here:

"data": {
    "products": {
      "totalCount": 182,
      "items": [...],
      "range_facets": [
        {
          "name": "price_*-100_100-200",
          "ranges": [
            {
              "from": 0,
              "to": 100,
              "count": 5959,
              "includeTo": false,
              "includeFrom": true
            },
            {
              "from": 100,
              "to": 200,
              "count": 2143,
              "includeTo": true,
              "includeFrom": true
            }
          ]
        }
      ],
      "term_facets": [
        {
          "name": "color",
          "terms": [
            {
              "term": "EXPRESSO",
              "count": 2343
            },
            {
              "term": "Sierra Brown",
              "count": 362
            },
            ...
        }]
    }
}

TermFacet expression

To retrieve facet counts for all occurring values of a product document field the following notations can be applied:

facet: "category.path" Counts the products of all categories.

facet: "{propertyName}" facet: "properties.{propertyName}" Counts the product documents for all occurring values of custom properties.

TermFacet result

The term type facets provide the counts for each of the different values the query parameter happens to have. name - represents the key of requested facet taken from facet expression. terms.term - one of the values for the field specified in facet expression for which at least one product could be found terms.count - amount of products for which the term applies terms.isSelected - flag indicates that requested facet term is used in filter expression, in order to simplify displaying the already selected facet terms on the frontend.

RangeFacet expression

To aggregate facet counts across ranges of values, the range qualifier can be applied analogous to the filter parameters. The range notation is applicable to the date, time, datetime, number and money type fields.

facet: "price.{currency}:[TO 100),[100 TO 200])" Counts the products whose price falls in one of the specified ranges

facet: "properties.{propertyName}[1 TO 100)" Counts the products whose values of the custom property fall in one of the specified ranges

RangeFacet result

The range facet type counts the products for which the query value is a range specified in the range expression. Range facets are typically used to determine the minimum and maximum value for example product prices to filter products by price with a range slider.

name - represents the key of requested facet taken from facet expression and build from range parameters concatenated by _. e.g price_*-100_100-200 ranges.from - the range’s lower endpoint in number format ranges.to - the range’s upper endpoint in string format ranges.count - amount of products fall into the specified range ranges.includeTo - flag indicates that lower bound is included ranges.includeFrom - flag indicates that upper bound is included ranges.isSelected - flag indicates that requested facet term is used in filter expression, in order to simplify displaying the already selected facet terms on the frontend.

Querying product breadcrumbs

When querying breadcrumbs of the product make sure your store's SEO Links setting is not set to None, otherwise breadcrumbs for the store would not be created. To check the setting go to Store - select your store - Settings - SEO - SEO Links.

Last update: May 14, 2021