Bloomreach Discovery Connector Schema Mapping

Info: This feature in Bloomreach Content requires a standard or premium license. Contact Bloomreach for licensing details.

Overview

This page describes how Bloomreach Discovery response data is mapped to the GraphQL schema models provided by the brX GraphQL Service.

JSONPath expressions are used throughout this documentation to specify how fields are resolved from the JSON response.

GraphQL Schema Models

Refer to the GraphQL Schema of GraphQL Service for a complete schema reference. You can also explore the schema using the GraphQL Playground UI or the generated HTML documentation. The following sections highlight the core schema models relevant to product and category data.

Product search operations (such as those using the Product search API) represent each product as an Item type, each product variant as an ItemVariant, and the overall result set as an ItemsPageResult.

"Abstraction for both product item and product item variant"
interface ItemLike {
  "The ItemId of a product item or product item variant"
  itemId: ItemId!
  "The display name of a product item or product item variant"
  displayName: String
  "The description of a product item or product item variant"
  description: String
  "The ImageSet of a product item or product item variant"
  imageSet: ImageSet
  "The listed price of a product item or product item variant"
  listPrice: Price
  "The purchase price of a product item or product item variant"
  purchasePrice: Price
  // ...SNIP...
}

"Product item abstraction"
type Item implements ItemLike @key(fields: "itemId") {
  "The ItemId of a product item"
  itemId: ItemId!
  "The display name of a product item"
  displayName: String
  "The description of a product item"
  description: String
  "The ImageSet of a product item"
  imageSet: ImageSet
  "The listed price of a product item"
  listPrice: Price
  "The purchase price of a product item"
  purchasePrice: Price
  "Sale price range including the lowest and highest prices to put in the appropriate location"
  salePriceRange: [Float]
  "Price range including the lowest and highest prices to put in the appropriate location"
  priceRange: [Float]
  "All available product item variant dimension names. e.g, [{name:'color'}, {name:'size'}]"
  varAttrTypes: [AttributeType]
  "Product item variants of this product item"
  variants: [ItemVariant]
  // ...SNIP...
}

/**
Item identifier that may hold multiple keys.
e.g, the Commerce Backend Platform specific primary key and other alternate key(s)
such as SKU, UPC, article number, etc.
*/
type ItemId {
  "The primary key identifier of a product item maintained by the Commerce Backend Platform"
  id: String!
  "The default alternate key identifier of a product item"
  code: String
}

"Product item variant abstraction"
type ItemVariant implements ItemLike {
  "The ItemId of a product item variant"
  itemId: ItemId!
  "The display name of a product item variant"
  displayName: String
  "The description of a product item variant"
  description: String
  "Flag whether or not this is the master variant"
  master: Boolean
  "The ImageSet of a product item variant"
  imageSet: ImageSet
  "The listed price of a product item variant"
  listPrice: Price
  "The purchase price of a product item variant"
  purchasePrice: Price
  "The main product item which contains this product item variant"
  mainItem: Item
  "Product item variant dimension name-values mappings"
  varAttrs: [Attribute]
  // ...SNIP...
}

"Pagination-based product search result"
type ItemsPageResult implements PageResult {
  "The offset index from which the search result starts"
  offset: Int!
  "The maximum size limit of the search result"
  limit: Int!
  "The item count of the search result"
  count: Int!
  "The total item count of the search result"
  total: Int!
  "The list of product items of the search result"
  items: [Item]!
  "Optional facet result available in this search"
  facetResult: FacetResult
  "Additional query info"
  queryHint: QueryHint
  // ...SNIP...
}
copy

Product categories use the following schema type:

"Product category abstraction"
type Category {
  "The identifier of this category"
  id: String!
  "The identifier of the parent category of this category"
  parentId: String!
  "The display name of this category"
  displayName: String!
  """
  The optional category path to this category, delimited by '/'.
  Depending on the backend, some category items may appear in multiple tree nodes,
  in which case, this path property can be preferred to the id-parentId pair when constructing category tree nodes.
  """
  path: String
}
copy

Autosuggest API responses are represented as follows:

"Suggestion search result abstraction, including term suggestions and product item suggestions"
type SuggestionResult {
  "Term suggestions"
  terms: [String]!
  "Product item suggestions"
  items: [Item]
}
copy

Product Data Mapping

The Product search API returns data in the following format:

{
  "response":{
    "numFound":86,
    "start":0,
    "docs":[
      {
        "sale_price":115.9,
        "price":115.9,
        "score":0.014999093,
        "description":"",
        "title":"PILOT SPORT A/S 3+",
        "url":"",
        "brand":"Michelin",
        "pid":"PILOT_SPORT_AS3PLUS",
        "thumb_image":"https://demo-images.s3-us-west-2.amazonaws.com/VESTRI_VIRTUAL_V2/92861.png",
        "sale_price_range":[
          115.9,
          115.9
        ],
        "price_range":[
          115.9,
          115.9
        ],
        "variants":[
          {
            "sku_swatch_images":[
              "92861"
            ],
            "sku_thumb_images":[
              "https://demo-images.s3-us-west-2.amazonaws.com/VESTRI_VIRTUAL_V2/92861.png"
            ]
          },
          {
            "sku_swatch_images":[
              "56201"
            ],
            "sku_thumb_images":[
              "https://demo-images.s3-us-west-2.amazonaws.com/VESTRI_VIRTUAL_V2/56201.png"
            ]
          },
          {
            "sku_swatch_images":[
              "80472"
            ],
            "sku_thumb_images":[
              "https://demo-images.s3-us-west-2.amazonaws.com/VESTRI_VIRTUAL_V2/80472.png"
            ]
          }
        ]
      },
    // ...SNIP...
    ]
  },
  "facet_counts":{
    "facet_ranges":{

    },
    "facet_fields":{
      "category":[
        {
          "count":15,
          "crumb":"/VPA_VEHICLE_ADDONS",
          "cat_name":"Vehicle Addons",
          "parent":"",
          "cat_id":"VPA_VEHICLE_ADDONS",
          "tree_path":"/VPA_VEHICLE_ADDONS,Vehicle Addons"
        },
        {
          "count":14,
          "crumb":"/VPA_VEHICLE_ADDONS/VPA_VA_MCLASS",
          "cat_name":"M-Class",
          "parent":"VPA_VEHICLE_ADDONS",
          "cat_id":"VPA_VA_MCLASS",
          "tree_path":"/VPA_VEHICLE_ADDONS,Vehicle Addons/VPA_VA_MCLASS,M-Class"
        },
        {
          "count":10,
          "crumb":"/VPA_VEHICLE_ADDONS/VPA_VA_T50",
          "cat_name":"T50",
          "parent":"VPA_VEHICLE_ADDONS",
          "cat_id":"VPA_VA_T50",
          "tree_path":"/VPA_VEHICLE_ADDONS,Vehicle Addons/VPA_VA_T50,T50"
        },
        {
          "count":28,
          "crumb":"/VESTRI_BM_APPAREL",
          "cat_name":"Apparel",
          "parent":"",
          "cat_id":"VESTRI_BM_APPAREL",
          "tree_path":"/VESTRI_BM_APPAREL,Apparel"
        },
        {
          "count":9,
          "crumb":"/VPA_VEHICLE_ADDONS/VPA_VA_XCLASS",
          "cat_name":"X-Class",
          "parent":"VPA_VEHICLE_ADDONS",
          "cat_id":"VPA_VA_XCLASS",
          "tree_path":"/VPA_VEHICLE_ADDONS,Vehicle Addons/VPA_VA_XCLASS,X-Class"
        },
        // ...SNIP...
      ],
      "brand":[
        {
          "count":80,
          "name":"Vestri"
        },
        // ...SNIP...
      ],
      "colors":[
        {
          "count":18,
          "name":"black"
        },
        {
          "count":19,
          "name":"blue"
        },
        // ...SNIP...
      ],
      // ...SNIP...
    },
    // ...SNIP...
  },
  // ...SNIP...
}
copy

When retrieving multiple products (for example, with findItemsByKeyword or findItemsByCategory GraphQL queries), the main response object maps to the ItemsPageResult type as follows:

Mapping for ItemsPageResult

Field of ItemsPageResult	JSONPath Expression	Notes
offset	$.response.start
limit		Set to the limit query input parameter.
count	($.response.docs).length
total	$.response.numFound
items		See the Mapping for Item table below.
facetResult	$.facet_count.facet_fields	Constructs facet navigation as a FacetResult schema type using the resolved facet fields.
queryHint	{ "autoCorrectQuery": $.autoCorrectQuery, "autoCorrectQuerySet": $.did_you_mean, "redirectHint": { "url": keywordRedirect['redirected url'], "query": keywordRedirect['original query'], "newQuery": keywordRedirect['redirected query'] } }	For details, see: Search Query Processing: Autocorrect and Query Relaxation Keyword redirects

Each product in $.response.docs is mapped to the Item model in the ItemsPageResult.items array as follows:

Mapping for Item

Field of Item	JSONPath on $.response.docs[*]	Notes
itemId	{ "id": pid, "code": variants[0].sku_swatch_images[0] }	The itemId field contains id and code properties. If code is not available, use the pid value for both.
displayName	title
description	description
imageSet	{ "original": { "link": thumb_image }, "thumbnail": { "link": thumb_image } }
listPrice	price
purchasePrice	sale_price
salePriceRange	sale_price_range
priceRange	price_range
variants	variants	See the Mapping for ItemVariant table below.
customAttrs		For details on including extra custom fields from the API response, see the FAQ.

Mapping for ItemVariant

Field of ItemVariant	JSONPath on $.response.docs[*].variants[*]	Notes
itemId	{ "id": pid, "code": variants[0].sku_swatch_images[0] }	The itemId field contains id and code properties. If code is not available, use the pid value for both.
displayName		Uses the parent product Item's displayName property.
description		Uses the parent product Item's description property.
imageSet	{ "original": { "link": sku_thumb_images[0] }, "thumbnail": { "link": sku_thumb_images[0] } }
listPrice		Uses the parent product Item's listPrice property.
purchasePrice		Uses the parent product Item's purchasePrice property.
mainItem		References the parent product Item.
customAttrs		For details on including extra custom fields from the API response, see the FAQ.

Category Data Mapping

When retrieving categories (using the findCategories GraphQL query), the response is an array of Category models. For single category lookups (findCategoryByID), the response is a single Category model if found.

Both queries use the Product search API, which returns data in the following format:

{
  "response":{
    "numFound":86,
    "start":1,
    "docs":[
      // ...SNIP...
    ]
  },
  "facet_counts":{
    "facet_ranges":{

    },
    "facet_fields":{
      "category":[
        {
          "count":15,
          "crumb":"/VPA_VEHICLE_ADDONS",
          "cat_name":"Vehicle Addons",
          "parent":"",
          "cat_id":"VPA_VEHICLE_ADDONS",
          "tree_path":"/VPA_VEHICLE_ADDONS,Vehicle Addons"
        },
        {
          "count":14,
          "crumb":"/VPA_VEHICLE_ADDONS/VPA_VA_MCLASS",
          "cat_name":"M-Class",
          "parent":"VPA_VEHICLE_ADDONS",
          "cat_id":"VPA_VA_MCLASS",
          "tree_path":"/VPA_VEHICLE_ADDONS,Vehicle Addons/VPA_VA_MCLASS,M-Class"
        },
        {
          "count":10,
          "crumb":"/VPA_VEHICLE_ADDONS/VPA_VA_T50",
          "cat_name":"T50",
          "parent":"VPA_VEHICLE_ADDONS",
          "cat_id":"VPA_VA_T50",
          "tree_path":"/VPA_VEHICLE_ADDONS,Vehicle Addons/VPA_VA_T50,T50"
        },
        {
          "count":28,
          "crumb":"/VESTRI_BM_APPAREL",
          "cat_name":"Apparel",
          "parent":"",
          "cat_id":"VESTRI_BM_APPAREL",
          "tree_path":"/VESTRI_BM_APPAREL,Apparel"
        },
        {
          "count":9,
          "crumb":"/VPA_VEHICLE_ADDONS/VPA_VA_XCLASS",
          "cat_name":"X-Class",
          "parent":"VPA_VEHICLE_ADDONS",
          "cat_id":"VPA_VA_XCLASS",
          "tree_path":"/VPA_VEHICLE_ADDONS,Vehicle Addons/VPA_VA_XCLASS,X-Class"
        },
        // ...SNIP...
      ],
      // ...SNIP...
    },
    // ...SNIP...
  },
  // ...SNIP...
}
copy

Each entry in the $.response.facet_counts.facet_fields.category array is mapped to a Category model as follows:

Mapping for Category

Field of Category	JSONPath on $.response.facet_counts.facet_fields.category[*]	Notes
id	cat_id
parentId	parent
displayName	cat_name
path	tree_path

Autosuggest Data Mapping

The Autosuggest API returns data in the following format:

{
  "queryContext":{
    "originalQuery":"b"
  },
  "suggestionGroups":[
    {
      "catalogName":"example_com",
      "view":"default",
      "querySuggestions":[
        {
          "query":"boots",
          "displayText":"boots"
        },
        {
          "query":"backpack",
          "displayText":"backpack"
        },
        {
          "query":"bench",
          "displayText":"bench"
        },
        // ...SNIP...
      ],
      "searchSuggestions":[
        {
          "sale_price":40,
          "url":"https://www.example.com/not-available/craftsman-safety-boots-size-8/5055160047421_BQ.prd?_br_psugg_q=boots",
          "pid":"5055160047421_BQ",
          "thumb_image":"//king.scene7.com/is/image/King/productTemplate?$baseImage=King/5055160047421_01bq",
          "title":"Craftsman Safety boots, Size 8"
        },
        {
          "sale_price":25,
          "url":"https://www.example.com/not-available/site-granite-grey-trainer-boots-size-10/289361_BQ.prd?_br_psugg_q=boots",
          "pid":"289361_BQ",
          "thumb_image":"//king.scene7.com/is/image/King/productTemplate?$baseImage=King/5055338404995_01bq",
          "title":"Site Granite Grey Trainer boots, Size 10"
        },
        {
          "sale_price":40,
          "url":"https://www.example.com/not-available/site-brown-mudguard-dealer-boots-size-8/3663602605942_BQ.prd?_br_psugg_q=boots",
          "pid":"3663602605942_BQ",
          "thumb_image":"//king.scene7.com/is/image/King/productTemplate?$baseImage=King/3663602605942_01bq",
          "title":"Site Brown Mudguard Dealer boots, Size 8"
        },
        // ...SNIP...
      ],
      // ...SNIP...
    }
  ]
}
copy

When executing a findSuggestions GraphQL query, the response maps to the SuggestionResult type as follows:

Mapping for SuggestionResult

Field of SuggestionResult	JSONPath Expression	Notes
terms	$.suggestionGroups[*].querySuggestions[*].query
items	$.suggestionGroups[*].searchSuggestions[*]	For mapping each product item, refer to the Mapping for Item table above.