Streaming Property Service
Introduction
The streaming-property service is used to define property definitions for specific item types. A group of property definitions for one item type is referred to as a property definition collection. Published property definition collections must be associated to a snapshot.
Currently there are six item types: product, category, region, reference content, assortments and visibility. Each item type can have different property definitions, which represent the attributes of that item type.
For more information on creating and managing property definition collections refer to Property Definition Collection.
Types of Property Definitions
In a property definition collection, there are three types of property definitions:
- Canonical properties:
- Pre-defined property definitions
- Clients can provide data for canonical attributes at ingest time
- Some canonical properties are required by Algonomy products.
- It is recommended not to modify canonical properties as Algonomy applications require them.
However, search attributes (findAttributeSettings) can be altered. For example, "storable" can be changed to true or false, and propertyValueStyle can be modified.
- Derived properties:
- Reserved names that cannot be used for custom property definitions.
- Derived properties are populated by Algonomy applications, not by the customer.
- Derived properties cannot be used when ingesting products.
- Exception for Streaming Find only: "product_effectiveprice_cents" (Long) is an optional attribute which needs to be provided by the customer. Value is in "cents". For batch customers,the value is calculated and doesn't need to be provided.
- Custom properties:
- Client defined properties.
- There is a list of "reserved words" that cannot be used for custom attributes.
https://help.richrelevance.com/Relev...Reserved_Words
Modifications to Canonical and Derived Property Definitions
Canonical and derived property definitions are pre-defined and are automatically created when the property definition collection is created. The only modifiable elements in a canonical or derived property definition are:
- findAttributeSettings
- Find search attributes.
- propertyValueStyle
- scopedActionSettings
- For Scoped Actions - The property with this element limits a scoped action to a set based on the value of the property. This is usually used with custom property definitions.
Modifying other elements in a canonical property, such as canonicalName, will cause the property definition collection update to fail. Derived properties cannot be used when ingesting products, as they are reserved for Algonomy products.
It is recommended not to remove any canonical properties as each Algonomy product requires specific properties.
- Recommend requires the following properties: product_id, name, image_url, link_url, price and recommendable.
Note: 'Image_url' is a required canonical property that needs to be ingested. For customers without images, this field should be populated with a dummy ID.
- Find: If the image_url is not populated in a product, then those products will not be returned in the result set by default. A workaround is to use the "fl" (field list) parameter and not include the image_url. This way, products without an image_url will still be returned.
- Find ignores the "recommendable" property.
Examples:
Below is an example of the canonical property definition for rating:
"rating": {
"canonicalName": "product_rating",
"dataType": "float",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": false,
"regionAware": false
}
}
Custom property definitions must be provided for items that require specific attributes. For example, if a product has an attribute called "promotion", then this attribute needs to be defined in the property definition collection before ingesting the product. Failure to define an attribute in the property definition collection, will result in the ingested product failing.
Property definitions collections are required to create a snapshot, and catalog items can only be ingested once a snapshot is created.
Product Snapshot: Requires both product and category property definition collections.
Place Snapshot: Requires the region property definition collection.
Specific Requirements for FIND
The search attribute settings (findAttributeSettings) must be set in the product definition collection. These settings are only required in the product definition collection and not other property definition collections.
NOTE: The Streaming Catalog does not utilize the current Portal Search Attributes when setting up the index. By default only the canonical attributes are initially displayed in the Portal Search Attributes. However, attributes that are searchable are still required in the Portal Search Attributes in order to be able to include them the search configuration (sliders). Only the "searchable" parameter is required. Other parameters such as "facetable" will be ignored.
If the image_url is not populated, those products will not be returned in the Find result set. For customers who don't have images, there are two options available. The first option is to provide a dummy value for the image_url. The second option is to use the "fl" parameter (field list) and exclude the image_url from the list of fields to be returned by the query. This way, products without an image_url will be returned. For more information, see Find API - fl parameter.
Property Definition Collections
Each property definition collection contains property definitions for a specific item type (product, category, region or referenceContent).
There are five actions for property definition collections: create, publish, clone, archive and delete. There are four states: creating, published, archived and deleted.
| Action | State | Note: |
|---|---|---|
| create* | creating |
Can modify. Cannot be used with a snapshot * Don't add "create" action to endpoint. POST will create a new collection. |
| publish | published |
Can be used when creating a snapshot. Can add a new property but cannot modify an existing one. |
| clone | creating | |
| archive | archived | Will continue to be viable for an existing snapshot but cannot be used with a new snapshot |
| delete* | deleted |
Can only delete a "creating" property definition collection. Cannot delete a *Don't add "delete" to endpoint. DELETE will delete the collection. DELETE https:<host>/streaming-property/v1/<apiKey>/collection/<itemType>/<collectionId> |
Create a new property definition collection
When a property definition collection is "created", the response includes all the canonical and derived attributes specific to the item type along with the collectionId. The collection's state will be "creating". Any property definition can be updated or new property definitions added while in the "creating" state. Once the property definition collection is "published", existing property definitions cannot be updated but new ones can be added at any time.
The below syntax is used to create a new property definition collection. For more information, see Syntax Overview. An example API call with a full response is available in the Examples section.
POST https://<host>/streaming-property/v1/<apiKey>/collections/<itemType>
Update an existing property definition - "creating" state only
Existing property definitions can only be updated in property definition collections that are in the "creating" state. For any update, a complete property definition is required. To update either the PUT or PATCH methods can be used.
Below is the syntax for PATCH where one or more property definitions can be updated.
PATCH https://<host>/streaming-property/v1/<apiKey>/collections/<itemType>/<collectionId>/definitions
The example below illustrates changing a canonical property's find attributes. In this case, the facetable parameter is changed to false.
collectionID: 123, itemType: product.
PATCH https://<host>/streaming-property/v1/<apiKey>/collections/product/123/definitions
Body
{
"brand": {
"canonicalName": "product_brand",
"dataType": "string",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 255,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": false,
"regionAware": false
}
}
}
Add a new property definition
A new property definition can be added to a "creating" or "published" property definition collection with no restrictions.
The most common requirement is to add a custom property. The syntax for adding a new property definition is the same as updating a property definition.
Modify an existing property in a "published" property definition collection
- If changes are required, for an existing property definition, you have two options. You can either create a new property definition collection or clone the existing collection. The new or cloned collection will be in the “creating” state, allowing you to make updates.If the property definition was used by a snapshot, a new snapshot needs to be created to leverage the new property definition collection.
Support of SKU Feature with Streaming
Starting from the May 2023 release, the Personalization platform supports the SKU feature with Streaming. This allows you to ingest SKU data via the Streaming API, which will be consumed by the platform’s SKU functionality. In addition to ingesting SKU data via the Streaming API, you need to add SKU to your instrumentation to support this functionality.
Note: Currently support for SKUs is not compatible with support for regions. This means, it's not possible to set attributes such as price and availability to work differently for each product SKU in a region. For example, you cannot define a region-specific price and availability for a product that is different from the parent product.
Adding SKU as New Attributes to Product Property Definition
To update either the PUT or PATCH methods can be used. Below is the syntax for PUT method, where SKU property definitions are being added to an existing published collection.
PUT https://<host>/streaming-property/v1/<apiKey>/collections/<itemType>/<collectionId>/definitions
The example below illustrates adding color, size, and style as SKU-specific attributes to the existing product properties.
collectionID: 123, itemType: product.
PUT https://<host>/streaming-property/v1/<apiKey>/collections/product/123/definitions
PATCH https://<host>/streaming-property/v1/<apiKey>/collections/product/123/definitions
Body
{
"color": {
"dataType": "string",
"propertyValuestyle:fullyCoveredOverride,
"origin": "custom",
"lengthLimit": 1024
"required": false
},
"size": {
"dataType": "string",
"propertyValuestyle:fullyCoveredOverride,
"origin": "custom",
"lengthLimit": 1024
"required": false
},
"style": {
"dataType": "string",
"propertyValuestyle:fullyCoveredOverride,
"origin": "custom",
"lengthLimit": 1024
"required": false
}
}
Note: For customers who plan to use SKU with the Search service (Streaming Find), it is necessary to define SKU attributes with the propertyValuestyle:fullyCoveredOverride. this is because SKU is treated as an override feature with Streaming Find (similar to language).
Notes
Property definition collections must be created before creating a snapshot. Currently "Published" property definition collections are required for all snapshot states: "creating", "complete" or "active". All snapshots must reference the required property definition collections.
There are distinct snapshot types for product, place and referenceContent.
- Product snapshots require both product and category property definition collections.
- Place snapshot only require the region property definition collection.
- referenceContent snapshot requires the referenceContent property definition collection.
Streaming-Property Syntax for Creating and Managing Property Definition Collections
Hosts:
Production
https://gateway.richrelevance.com/
QA
https://qa-gateway.richrelevance.com/
Staging
https://staging-gateway.richrelevance.com/
The following syntax is for creating, managing state, and getting details of a property definition collection.
Base URL: https://<host>/streaming-property/v1/
Full URL: https://<host>/streaming-property/v1/<apiKey>/collections/<itemType>/<collectionId>/<action>
API Endpoints
| Actions | Syntax |
|
Create a property definition collection for a specific item type. The canonical and derived properties for the item type will automatically be created. Example for creating a product property definition collection is here. |
POST {baseURL}/<apiKey>/collections/<itemType> |
| List all property definition collections for a given site (apiKey) | GET {baseURL}/<apiKey>/collections |
| List all property definition collections for a given site and item type. | GET {baseURL}/<apiKey>/collections/<itemType> |
| Retrieve a specific collection specified by site, itemType and collection id. | GET {baseURL}/<apiKey>/collections/<itemType>/<collectionId> |
| Publish a collection. The collection must be in “creating” state. | POST {baseURL}/<apiKey>/collections/<itemType>/<collectionId>/publish |
| Clone a collection. | POST {baseURL}/<apiKey>/collections/<itemType>/<collectionId>/clone |
| Delete a collection | DELETE {baseURL}/<apiKey>/collections/<itemType>/<collectionId> |
| Archive a collection | POST {baseURL}/<apiKey>/collections/<itemType>/<collectionId>/archive |
Parameters
| Parameter | Description | Additional Information and Options |
|---|---|---|
| apiKey |
Unique identifier for a customer's environment. For example, if a customer has multiple environments in production or staging, each would have a unique apiKey. There can be many apiKeys associated to a client_ID. |
Provided by Algonomy to customer. |
| collectionId | Unique identifier for the property definition collection. | collectionId is provided in the response to a POST when creating the collection. It is the "id" in the response. |
| name | Name of the property definition collection | Currently, the name of the property definition collection is the same as its ID. However, introduce the capability for customer to create a custom name (string, 255 characters). |
| itemType | The item type for this property definition collection. |
Supported item types: product, category, region and referenceContent
|
| state |
Three states: creating, published, and archived.
|
creating, published, archived |
| action |
Since there is no explicit action for creating a property definition collection, three action parameters are available: publish, clone, and archive. The clone action creates a new collection based on an existing one, and the state of the new collection will be "creating". |
publish, clone, archive |
Property Definitions
Below are actions and syntax for managing property definitions in a property definition collection.
New property definitions and updates can only be applied to a “creating” collection. When updating or creating, a property definition needs to be complete.
Property Definition Actions and Syntax
Base URL: https://<host>/streaming-property/v1/
'Authorization:Bearer <tokenValue>’
Full URL: https://<host>/streaming-property/v1/<apiKey>/collections/<itemType>/<collectionId>/definitions
'Authorization:Bearer <tokenValue>’
| Action | Syntax |
|---|---|
|
Update or Create one property definition. |
PUT {baseURL}/<apiKey>/collections/<itemType>/<collectionId>/definitions/<propertyName>{property definition} |
|
Update or create more than one property definition. Note: Any definition supplied must be complete. |
PATCH {baseURL}/<apiKey>/collections/<itemType>/<collectionId>/definitions Body {<propertyName>{property definition}, <propertyName>{property definition}}
|
| Delete one property definition from a “creating” collection only. Currently, the functionality to delete multiple property definitions is not supported. | DELETE {baseURL}/<apiKey>/collections/<itemType>/<collectionId>/definitions/<propertyName>. |
Property Definition Elements
| Element | Description | Data Type | Length limit |
Optional/ Mandatory |
Values |
|---|---|---|---|---|---|
| <propertyName> | Name of the specific property definition. | string, (case sensitive) | 255 | Mandatory | Can be any string value. For example, “color”. |
| canonicalName | Name of a canonical property. Not to be modified. It will be provided. | string, (case sensitive) | 255 | For Canonical properties only. | For custom property definitions this value is not required. |
| dataType |
The data type of the property definition. Data types with the suffix "list" support multiple values, indicating a cardinality that allows for multi-valued properties. Note: There is no need to supply “cardinality” with the Streaming Catalog which was formerly required with the feed.
|
string (case sensitive) | Mandatory |
"boolean", "booleanList", "date". "dateList", "datetime", "datetimeList", "double", "doubleList", "float", "floatList", "int", "intList", "long", "longList", "price", "priceList" "string", "stringList"
Further details on Dates can be found below after this section. |
|
| origin | Defines the origin which can be canonical, derived, or custom. | string (case sensitive) | Default is "custom" for new property definitions |
"canonical" - pre-defined property Default: "custom" - client-defined "derived" - system generated attributes. Also pre-defined. |
|
| propertyValueStyle | See below for detailed explanation. | string | Optional |
Default: "baseOnly" "fullyCoveredOverride", "overrideWithDefault" |
|
| findAttributeSettings | Search attribute settings are required for Find. This element is only set for product property definitions. It will use the existing validation rules which are explained below. | Boolean for each attribute | Optional | “facetable”: false, “storable”: false, “searchable”: true, “filterable”: false, “sortable”: false, “regionAware”: false |
|
| scopedActionSettings | Required to determine the set of products to be updated and deleted in a scoped action. Only one property definition can be used in a Scoped Action. | Boolean (propertyMatch) | Optional |
{"scopedActionSettings" : {"propertyMatch”: true} } If not provided, default is false. Can have multiple property definitions with this parameter but only one can be used with a scoped action at one time. |
|
| required | Defines whether or not a value is required for a given Property. Currently should be set to "false". | boolean | Optional |
Default: false true |
|
| lengthLimit |
character limit for a "string" property. Note: lengthLimits of external_id properties for each item type property are enforced even if the lenghtLimit is modified Limits are: Product varchar(100). example: product_external_id lengthLimit will be 100. |
integer | Optional |
Default: 1024 . Max limit: 4096
Note: Some canonical properties will have a length limit of 255 and should not be changed. |
Date Formats
- date
- The format for "date" is based on the short date format defined in the Portal in Admin > Site configurations.
- In the example below, the format for November 2, 2020 would be 02/11/2020.
- datetime
- The format for "datetime" is based on the long date format defined in the Portal in Admin > Site configurations.
propertyValueStyle
- baseOnly (default)
- Property values with this style only appear in the base properties section and can be directly shown to the shopper. Examples include physical properties, such as screen size.
- fullyCoveredOverride
- Property values with this style appear only in an override section, where each override context has this value. Since there is only one value for a given override context, the value can be directly shown within its context. Examples include language text, where each language code has a translated value. Base values of this property are ignored.
- NOTE: Currently the Catalog in the Portal requires a base value for an attribute. It is recommended to add a base value (such as the “english” value). Find will still use the override values and not the base value.
- overrideWithDefault
- Properties with this value style include overrides for some override contexts, but not all, and also have a default value in the base properties section. With this style, all property values must be considered before showing any value to the shopper. Examples include properties that vary by region, such as availability. Due to data optimization, unchanged property values propagate only when the force flag is true. Therefore, either all values need to be updated in all contexts plus the base with force = true, or the consuming application must retrieve the full item from the long-term item store before applying any update when force = false.
Search Attribute Validation Rules
The following are the search attribute validation rules.
- Sortable:
- Multi-value attributes are not sortable. This applies to any property definition with a dataType that has the "list" suffix, such as "stringList"
- Only single value attributes may be sortable
- Product_external_id and content_external_id: These must be filterable and storable
- product_region_id: This is a derived property used internally where "storable" will always be "false". Even if it is changed to "true", Find will not return it in a result set.
- Image attributes: These must be storable.
- Any facetable attribute must be filterable
Example 1: Find Search Attributes
Example of adding property definitions with the findAttributeSettings
- This example add or updates named definitions to collection 123 of item type "product"
collectionId: 123
apiKey: 1234
PATCH https://<host>/streaming-property/v1/1234/collections/product/123/definitions
“myProperty1”: {
“dataType”: “string”,
“origin”: “custom”,
“propertyValueStyle”: “baseOnly”,
“required”: false,
“findAttributeSettings”: {
“facetable”: false,
“storable”: false,
“searchable”: true,
“filterable”: false,
“sortable”: false,
“regionAware”: false
}
},
“myProperty2”: {
“dataType”: “string”,
“origin”: “custom”,
“propertyValueStyle”: “baseOnly”,
“required”: false,
“findAttributeSettings”: {
“facetable”: false,
“storable”: false,
“searchable”: true,
“filterable”: false,
“sortable”: false,
“regionAware”: false
}
}
Example 2: Custom property definition "size"
Example of a custom property definition called "size".
Note: The canonicalName is not required. Origin needs to be “custom”.
size":{
"dataType":"string","
"origin":"custom",
"required":false“,
"findAttributeSettings”: {
“facetable”: true,
“storable”: true
“searchable”: true,
“filterable”: true,
“sortable”: true,
“regionAware”: false
}
}
Steps to create a Property Definition Collection
The following is a step by step summary with examples for creating property definition collections for a product snapshot. It is important to consider the states when associating them with snapshots.
Product snapshot requires both published product and category property definition collections.
Place snapshot requires a published region property definition collection.
Summary of steps
1. Create a new product definition collection (POST) - state: "creating"
- A new product definition with a state of "creating" is created.
- The response will include all pre-defined canonical and derived properties.
- The response will also include the collectionId.
- Example of "POST" call and response is below.
2. Modify and add custom product property definitions for the "creating" product property definition collection (PUT/PATCH)
- For pre-defined canonical property definitions can only modify:
-
search attributes (under the findAttributeSettings)
-
propertyValueStyle
-
scopedAction
-
-
Add and modify any custom property definitions
3. Review changes (GET)
4. Repeat steps 2 and 3 until satisfied with the product property definition collection.
5. Create a category property definition collection following the same steps above (steps 2 and 3).
6. "Publish" both the product and category property definition collections - state: "published".
7. The published property definition collections are ready to be associated to a snapshot.
Examples
The following are examples of creating and managing a product property definition collection.
1. Creating the Property Definition Collection for a Product Snapshot
Below is the API call to create a product property definition collection.
POST https://gateway.richrelevance.com/streaming-property/v1/<apiKey>/collections/product 'Authorization:Bearer <tokenValue>’
Response: Property definition collection id is returned with state, and all the pre-defined canonical and derived property definitions.
The tracking ID can be found at the end of the response under "statusTracker"
{
"propertyDefinitionCollection": {
"id": 11374,
"name": "11374",
"itemType": "product",
"state": "creating",
"definitions": {
"end_date": {
"canonicalName": "product_end_date",
"dataType": "date",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": false,
"storable": false,
"searchable": false,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"list_price_max": {
"canonicalName": "product_price_range_max_cents",
"dataType": "price",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false
},
"product_region_id": {
"dataType": "longList",
"origin": "derived",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": false,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"rating": {
"canonicalName": "product_rating",
"dataType": "float",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": true,
"regionAware": false
}
},
"description": {
"canonicalName": "product_description",
"dataType": "string",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 1024,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": true,
"filterable": false,
"sortable": false,
"regionAware": false
}
},
"in_stock": {
"canonicalName": "in_stock",
"dataType": "boolean",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": false,
"filterable": true,
"sortable": false,
"regionAware": true
}
},
"product_category_id": {
"dataType": "longList",
"origin": "derived",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": false,
"storable": false,
"searchable": false,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"product_effectiveprice_cents": {
"dataType": "price",
"origin": "derived",
"propertyValueStyle": "overrideWithDefault",
"required": false,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": false,
"filterable": true,
"sortable": true,
"regionAware": true
}
},
"product_category_name": {
"dataType": "stringList",
"origin": "derived",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 1024,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"price": {
"canonicalName": "product_pricecents",
"dataType": "price",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": false,
"filterable": true,
"sortable": true,
"regionAware": true
}
},
"product_id": {
"dataType": "long",
"origin": "derived",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"product_sku_id": {
"dataType": "string",
"origin": "derived",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 1024,
"findAttributeSettings": {
"facetable": false,
"storable": false,
"searchable": false,
"filterable": false,
"sortable": false,
"regionAware": false
}
},
"link_url": {
"canonicalName": "product_link_id",
"dataType": "string",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 255,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": false,
"filterable": false,
"sortable": false,
"regionAware": false
}
},
"findable": {
"canonicalName": "product_findable",
"dataType": "boolean",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false
},
"price_description": {
"canonicalName": "price_description",
"dataType": "string",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 1024
},
"brand": {
"canonicalName": "product_brand",
"dataType": "string",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 255,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"start_date": {
"canonicalName": "product_release_date",
"dataType": "date",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": false,
"storable": false,
"searchable": false,
"filterable": true,
"sortable": true,
"regionAware": false
}
},
"sale_price_min": {
"canonicalName": "product_sale_price_range_min_cents",
"dataType": "price",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false
},
"recommendable": {
"canonicalName": "product_recommendable",
"dataType": "boolean",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false
},
"margin": {
"canonicalName": "margin",
"dataType": "string",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 50
},
"image_url": {
"canonicalName": "product_image_id",
"dataType": "string",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 255,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": false,
"filterable": false,
"sortable": false,
"regionAware": false
}
},
"sale_price": {
"canonicalName": "product_saleprice_cents",
"dataType": "price",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": false,
"filterable": true,
"sortable": true,
"regionAware": true
}
},
"sale_price_max": {
"canonicalName": "product_sale_price_range_max_cents",
"dataType": "price",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false
},
"list_price_min": {
"canonicalName": "product_price_range_min_cents",
"dataType": "price",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false
},
"name": {
"canonicalName": "product_name",
"dataType": "string",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 255,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": true,
"filterable": false,
"sortable": false,
"regionAware": false
}
},
"num_reviews": {
"canonicalName": "product_num_reviews",
"dataType": "int",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"product_category_external_id": {
"dataType": "stringList",
"origin": "derived",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 1024,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"product_external_id": {
"dataType": "string",
"origin": "derived",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 1024,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": false,
"regionAware": false
}
}
}
},
"statusTracker": {
"trackingId": "7f39730a-5fd7-11ea-9cb2-fdac9789e86e",
"trackingInstant": "2020-03-06T18:22:54.530023400Z"
}
}
2. Adding Custom Property Definitions or Updating Existing Property Definitions in a Product Property Definition Collection
You can add new custom property definitions to both "creating" or "published" property definition.
However, modifying an existing property definition, is only allowed in a "creating" collection and not in a "published" property definition.
In the example below, we will add a new property to a published property definition.
collectionID: 26660
PUT http://gateway.richrelevance.com/streaming-property/v1/<apiKey>/collections/product/11374/definitions/size:
'Authorization:Bearer <tokenValue>’
Body:
{"dataType":"string","origin":"custom","required":false,
"findAttributeSettings": {"facetable": true,"storable": true, "searchable": true,"filterable": true, "sortable": false,"regionAware": false}}
Response: A trackingID is returned along with the all the properties in the collection include the new property. At the end of the response there is a summary of new, updated, and deleted properties for this specific collection. The snapshot is also referenced as a property definition collection can belong to multiple snapshots.
{
"statusTracker": {
"trackingInstant": "2020-11-05T00:39:18.285025200Z",
"trackingId": "56923ccc-1eff-11eb-88ad-1b7e642befe5"
},
"data": {
"siteId": 608,
"collection": {
"id": 26660,
"name": "26660",
"itemType": "product",
"state": "published",
"definitions": {
"end_date": {
"canonicalName": "product_end_date",
"dataType": "date",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": false,
"storable": false,
"searchable": false,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"list_price_max": {
"canonicalName": "product_price_range_max_cents",
"dataType": "price",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false
},
"product_region_id": {
"dataType": "longList",
"origin": "derived",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": false,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"rating": {
"canonicalName": "product_rating",
"dataType": "float",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": true,
"regionAware": false
}
},
"description": {
"canonicalName": "product_description",
"dataType": "string",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 1024,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": true,
"filterable": false,
"sortable": false,
"regionAware": false
}
},
"in_stock": {
"canonicalName": "in_stock",
"dataType": "boolean",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": false,
"filterable": true,
"sortable": false,
"regionAware": true
}
},
"product_category_id": {
"dataType": "longList",
"origin": "derived",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": false,
"storable": false,
"searchable": false,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"product_effectiveprice_cents": {
"dataType": "price",
"origin": "derived",
"propertyValueStyle": "overrideWithDefault",
"required": false,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": false,
"filterable": true,
"sortable": true,
"regionAware": true
}
},
"product_category_name": {
"dataType": "stringList",
"origin": "derived",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 1024,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"price": {
"canonicalName": "product_pricecents",
"dataType": "price",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": false,
"filterable": true,
"sortable": true,
"regionAware": true
}
},
"product_id": {
"dataType": "long",
"origin": "derived",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"product_sku_id": {
"dataType": "string",
"origin": "derived",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 1024,
"findAttributeSettings": {
"facetable": false,
"storable": false,
"searchable": false,
"filterable": false,
"sortable": false,
"regionAware": false
}
},
"link_url": {
"canonicalName": "product_link_id",
"dataType": "string",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 255,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": false,
"filterable": false,
"sortable": false,
"regionAware": false
}
},
"findable": {
"canonicalName": "product_findable",
"dataType": "boolean",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false
},
"price_description": {
"canonicalName": "price_description",
"dataType": "string",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 1024
},
"brand": {
"canonicalName": "product_brand",
"dataType": "string",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 255,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"start_date": {
"canonicalName": "product_release_date",
"dataType": "date",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": false,
"storable": false,
"searchable": false,
"filterable": true,
"sortable": true,
"regionAware": false
}
},
"sale_price_min": {
"canonicalName": "product_sale_price_range_min_cents",
"dataType": "price",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false
},
"recommendable": {
"canonicalName": "product_recommendable",
"dataType": "boolean",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false
},
"margin": {
"canonicalName": "margin",
"dataType": "string",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 50
},
"image_url": {
"canonicalName": "product_image_id",
"dataType": "string",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 255,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": false,
"filterable": false,
"sortable": false,
"regionAware": false
}
},
"store": {
"dataType": "string",
"origin": "custom",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 1024,
"scopedActionSettings": {
"propertyMatch": true
}
},
"sale_price": {
"canonicalName": "product_saleprice_cents",
"dataType": "price",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": false,
"filterable": true,
"sortable": true,
"regionAware": true
}
},
"marce": {
"dataType": "string",
"origin": "custom",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 1024,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": false,
"regionAware": false
},
"scopedActionSettings": {
"propertyMatch": true
}
},
"sale_price_max": {
"canonicalName": "product_sale_price_range_max_cents",
"dataType": "price",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false
},
"list_price_min": {
"canonicalName": "product_price_range_min_cents",
"dataType": "price",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false
},
"name": {
"canonicalName": "product_name",
"dataType": "string",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 255,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": true,
"filterable": false,
"sortable": false,
"regionAware": false
}
},
"num_reviews": {
"canonicalName": "product_num_reviews",
"dataType": "int",
"origin": "canonical",
"propertyValueStyle": "baseOnly",
"required": false,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"size": {
"dataType": "string",
"origin": "custom",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 1024,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"product_category_external_id": {
"dataType": "stringList",
"origin": "derived",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 1024,
"findAttributeSettings": {
"facetable": true,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": false,
"regionAware": false
}
},
"product_external_id": {
"dataType": "string",
"origin": "derived",
"propertyValueStyle": "baseOnly",
"required": false,
"lengthLimit": 1024,
"findAttributeSettings": {
"facetable": false,
"storable": true,
"searchable": true,
"filterable": true,
"sortable": false,
"regionAware": false
}
}
}
},
"snapshots": {
"9758": "product"
},
"added": [
"size"
],
"updated": [],
"removed": []
}
}
Use the trackingID to check the status as below.
https://<host>/streaming-status/v1/<apiKey>/trackingId/cfe4b2ca-1efe-11eb-88ad-175aaa904061 'Authorization:Bearer <tokenValue>’
Response from status service:
[
{
"siteId": 608,
"snapshotId": 9758,
"statusId": "d0011401-1efe-11eb-9930-391743bf3b81",
"trackingId": "cfe4b2ca-1efe-11eb-88ad-175aaa904061",
"source": "streaming-engine",
"statusType": "PropertyChangeEvent",
"message": "PropertyChangeEvent",
"kafkaSource": {
"topic": "streaming.engine.in",
"partition": 7,
"offset": 331406
},
"level": "SUMMARY",
"statusData": {},
"datacenter": "qa",
"trackingInstant": "2020-11-05T00:35:32.333025Z",
"statusInstant": "2020-11-05T00:35:32.519014500Z",
"msSinceRequest": 186
},
{
"siteId": 608,
"snapshotId": 9758,
"statusId": "cff5c9cb-1efe-11eb-88ad-bfc931fca502",
"trackingId": "cfe4b2ca-1efe-11eb-88ad-175aaa904061",
"source": "streaming-property",
"statusType": "PropertyChangeEvent",
"message": "PropertyChangeEvent for site: 608, snapshot: (PRODUCT:9758), collection: (PRODUCT:26660)\n added: [size]\n updated: []\n removed: []",
"level": "SUMMARY",
"statusData": {},
"datacenter": "qa",
"trackingInstant": "2020-11-05T00:35:32.333025Z",
"statusInstant": "2020-11-05T00:35:32.445025100Z",
"msSinceRequest": 112
}
]
d