Search Powered by Google
Search Classic
Customer Experience Management
Command Center
Site Management
Relevancy Optimization
Change Logs
Analytics & Reports

Configuration File

One of the important form parameter while uploading data to the cloud is Configuration file. This file defines the structure of your product catalog, authenticates the upload, and ensures that the engine can parse your records correctly. A configuration file must be sent each time data is sent to the data service. The accepted file encoding is UTF-8 without BOM.

This page outlines the mandatory knowledge, as well as best practices on how to structure your data configuration, so that that your search experience is the best it can be.

Configuration File Parameters

The configuration file consists of the following parameters:

  1. Collection
  2. Baseline Update
  3. Partial Update
  4. Notifications
  5. Field Definitions
Sample Configuration File
# Mandatory: Your client key as found in the command center.
clientKey: --clientKey--

# All the parameters below are optional

# Collection that the records that are being sent as part of this upload should be loaded into
# collection: reviews

# Optional: By default, all updates sent to the engine are partial updates.
# Set this to true to replace the data entirely
# replaceCollection: true

# Notification allows you to track the progress of your upload
# notification: {"type": "Email", "recipients": ["", ""]}
# notification: {"type": "Email", "recipients": ""}
# notificationSettings:
  frequency: 15
  enabled: true,
  enabledForFullUploads: true,
  enabledForPartialUploads: false,

# Field Definitions allow you to define which fields will be indexed and included in the relevancy calculations.
# At least one field must be set to `search:All"`.
# fieldDefinition: {name: "field_name", search: "All"}
# fieldDefinition: {name: "field_name", search: "RelevancyOnly"}
# fieldDefinition: {name: "field_name", displayName: "Field Name"}
# fieldDefinition: {name: "field_name", displayName: "Field Name", type: "String"}
# fieldDefinition: {name: "field_name", displayName: "Field Name", languages: ["lang_en", "lang_fr"]}
# fieldDefinition: {name: "field_name", displayName: "Field Name", languages: "lang_zh-CN"}
# fieldDefinition: {name: "field_name", displayName: "Field Name", sortable: true, refinable: false}
# fieldDefinition: {name: "field_specific", type: "Integer"}
# fieldDefinition: {name: "field_*"}
# fieldDefinition: {name: "field?", displayName: "Field Name"}

# fieldDefinition: {name: "?_field_*", displayName: "Field Name", type: "String"}

# Optional: Specify the type of category structure you wish to use
# categoryVersion: v2

# Optional: The upload service will fail on the first invalid record if failOnFirstError is set to true. The default value is
# false, meaning it will continue uploading until 100 invalid records are found.
# failOnFirstError: false

# An additional ID for Recommendations linking
fieldDefinition: {name: "variants.skuId", additionalId: true}

# ChildRecord definition for automatic re-ordering of visual variants.
# fieldDefinition: {name: "variants", type: "ChildRecord", childAction: "Order"}

# ChildRecord configuration to enforce filtering of the returned child records
# fieldDefinition: {name: "pricingRate", type: "ChildRecord", childAction: "Filter"}

1. Collection

A collection is a set of records, all of which are defined with one upload configuration. All data in the cloud is stored in collections. A limit of 20 collections per endpoint exists. If you require more, please reach out to your Project Manager or Customer Representative. Read more

2. Baseline Updates

A baseline update is done when you replace the entire collection with a replaceCollection flag set to true. Read more

3. Partial Updates

You can use the replaceCollection flag to send partial updates to the engine. If you want to make updates to that collection with the subsequent uploads, change the replaceCollection flag to false. *It is mandatory that you are able to generate baselines (full snapshots) of your catalogues. While partial updates can be used in an ongoing production environment, a baseline is required when the upload configuration changes. Limitations and best practises on Partial Updates.

4. Notifications

Notifications allow you to track the progress of your data upload via email notifications. More than one email can be specified by providing a list of emails or mutliple notification definitions

notification: {"type": "Email", "recipients": ""}
notification: {"type": "Email", "recipients": ["",""]}

If notifications are turned on, you will get notifications for upload start, periodic updates, and a final notification for overall completion (success/fail). Read more

5. Field Definitions

Fields encompass your data. When you are using JSON, the field definitions are defined in JSON dot notation:

fieldDefinition: {name: "product.color"}

You can use the parameters below to control which fields are indexed and included in the relevancy calculations. Only the name field is mandatory. Read more

Parameter Default Required Description
name Yes The JSON dot notation address of the field
search "All" Yes Whether the field should affect recall, relevancy, or not be used for search. Valid options are "All", "RelevancyOnly", "RecallOnly" and "None". See Search Type below for details. At least one field must exist with search set to All.
type "String" No The type of content within this field. Valid options are: "String", "Integer", "Float" and "ChildRecord". See more.
childAction "None" No The type of ChildRecord action to take on this field. Valid options are "None", "Filter" or "Order".
languages "lang_en" No One or more languages can be defined on a field.
displayName No A customer friendly display name to return if a refinement is applied on this field, without a Dynamic Navigation in place.
additionalId No Additional IDs to use for mapping of Recommendations API data.
refinable true No Enables or disables this field for refining and biasing. Improve indexing time. See more
sortable true No Enables or disables this field for sorting. Improves indexing time. See more
accessField false No Enables or disabled security on the collection to this field. See more.