Item Data Structure
The following section details the data input format for Fredhopper Access Service (FAS) and how this data should be transmitted to Fredhopper's Managed Services environments.
Last updated
Fredhopper Integration Guide
The following section details the data input format for Fredhopper Access Service (FAS) and how this data should be transmitted to Fredhopper's Managed Services environments.
Last updated
The Fredhopper data structure is item-based. All data must be linked to a valid item in order for it to be accepted/processed and each item must belong to at least one valid category. An item is typically a product, but it can also be another type of data that needs to be stored within FAS, e.g. a content article.
Each new data attribute that is created and included within the product feed must have a base-type value assigned. This dictates the type of data that can be included within the field and how it is used within FAS. The following data types (base-types) are accepted by Fredhopper:
int
The int data type is intended for non-negative integer attribute values (0, 1, 2, 10, ...) which can be used for (bracketed) facets and sorting on, e.g. stock amounts, ratings, etc.
float
The float data type can hold positive floating point numbers (0.1, 12.6767676, ....) and is typically used for bracketed facets and sorting on prices, margin, discounts etc. For technical reasons, values less than 0.00001 are not allowed and so '0.0' is treated equivalently to 'undefined'.
list
1 out of n values (n = 32765)
The list data type represents one of a fixed list of values. List attributes have locale independent value identifiers (typically the lowercase English representation or database id of a value) and multi-lingual, locale dependent display values. Identifiers should be unique to the attribute and not contain spaces, UPPERCASE characters or any special characters (,"/\ etc.). Basically, the identifiers may contain the letters a to z and an underscore (_) only.
list64
1 out of 64 values
Same as list. However, if the attribute only has a maximum of 64 different values, list64 is more efficient in terms of memory usage and performance compared to the list type.
set
1..n out of n values (n = 32765)
The set data type is identical to the list data type but, per item, this attribute can have more than 1 value. Lists and sets are typically used for facets.
set64
1..64 out of 64 values
Same as set. However, if the attribute only has a maximum of 64 different values, set64 is more efficient in terms of memory usage and performance compared to the set type.
hierarchical
nested categories
The hierarchical data type is used for categorisation (classification) of the items. An item should at least have one hierarchical attribute, and this attribute is always named categories. Categories can have child categories which can in turn have child categories. The number of children (levels) is not limited and does not have to be the same across all categories. Items can exist in one or more categories. The top-level category value is called universe. Fredhopper supports only one hierarchical attribute per universe.
text
any unicode string
The text type is a data type without locale specific values, i.e. its value is the same across all locales. It is typically used for product codes that are locale independent and need to be displayed or searchable free text. It is possible to create a facet or sort on a text type attribute. However, it is recommended to use list and set attribute types for facets because they perform better, and text does not allow multi select facets.
asset
any multi lingual value
The asset data type holds multilingual free text data and is meant for free text search and display purposes. Typical examples of this are product descriptions or image references. An asset value does not have a locale independent identifier. It is not possible to create facets or sort on assets.
ref
any primary universe product id
The ref data type represents a reference from one item to one or more other items in a Relational Universe (link). This reference can be used to have an item inherit attributes from the items that are referring to it. This data type is used in travel/leisure and B2B Retail installations to deal with different prices per holiday (travel), or different prices per customer segment (B2B Retail).
datetime
Please note, that the timezone of the datetime string is used only for parsing the date. An alternative response date format can be specified in the Merchandising Studio for each universe/locale, as well as a timezone. That means for example that you can parse the dates as ISO 8601, with the UTC timezone, and display them for the Sydney timezone by customising the display format. It is the display format that gets returned in the FAS query responses and shown on the Preview Page, rather than the input datetime string.
Examples for ISO 8601 formatted dates include: 2021-06-27T13:55:48+01:00 - a datetime with UTC+1 offset 2021-06-27T13:55:48Z - a datetime with UTC timezone 2021-06-27T13:55:48 - a datetime without a timezone, UTC will be used 2021-06-27T13:55 - a datetime without seconds or timezone specified 2021-06-27T13:55+01:00 - a datetime without seconds specified
datetime, int, float and text are non-localisable attribute base-types. The values supplied for attributes of these types should be sent only once (not one per locale) per product or variant in the input files. That single value will be available for that product or variant across all locales.
The following table provides a quick guide on how the above Data Types can be used within key Fredhopper elements:
asset
datetime
float
int
hierarchical (category)
list, list64
set, set64
text
Between 0 and 2147,483,647 ()
Between 0.00001 and
any date/timestamp after 1970-01-01T00:00:00 using the standard
The datetime data type represents instances in time down to seconds precision. The values are read as strings, and are then stored internally within FAS as milliseconds since 00:00:00 UTC on 1 January 1970. An offset from UTC can be specified as part of the datetime, and UTC will be assumed if it is not specified. Attributes that are set as datetime can then be used for selection, sorting and facets.
