Managing Attributes
When sending data for indexing, there are a number of default attributes which can be sent and used for searching and/or as facets. Your store, however, likely has custom or non-standard attributes which you would like to use in your search solutions. Unlike the old XML-based indexing, the JSON API requires attributes to be registered before they can be included in an indexing payload otherwise the batch request will be rejected.
The PHP-SDK provides service classes to retrieve attributes present in your indexes, as well as to add; update; or delete attribute definitions.
Attributes are defined by the Attribute model and contain the following information.
Property | Description |
|---|---|
attributeName | string Unique identifier for the attribute. Must be alphnumeric and can include underscores (_), but cannot start or end with an underscore. Example: "my_custom_attribute" Note: value is defined during object instantiation and cannot be changed post hoc |
datatype | string Type of data which is expected to be sent in payloads. See table below for options. Example: "STRING" Note: value is defined during object instantiation and cannot be changed post hoc |
label | array<string, string> Array of label(s) used when rendering attribute, for example in facets. Value should always contain one key named default, along with optional values for different locales. Example: [ 'default' => 'My Custom Attribute', 'es-ES' => 'Mi atributo personalizado', ] |
searchable | boolean Whether this attribute's data should be considered when searching |
filterable | boolean Whether this attribute should be used in faceting on the storefront |
returnable | boolean Whether this attributer's value should be returned in search payloads, allowing use in storefront template |
immutable | boolean Whether this attribute's properties can be updated. |
Attribute definitions apply to all record types, meaning you cannot define an attribute with the same name and different definitions for KLEVU_PRODUCT and KLEVU_CATEGORY records, for example.
If you need multiple definitions for the same attribute name across different record types, you should define unique names - we recommend using a prefix, such as category__attr / product__attr - and handling mapping within your application.
Note, data validity is not checked within the model itself but is performed by the AttributeValidator . This validator is not executed until you interact with Klevu APIs via the AttributesService class, meaning invalid attribute names or datatypes, for example, will not be picked up at time of definition.
The data type of an attribute is used by the indexing APIs to determine whether provided data in an indexing payload is valid. For example, defining an attribute as STRING and sending an array of integers would be rejected and cause the Indexing\BatchService to return a BadRequestException.
Despite the DataType enum, the Attribute model's datatype property is a string. This is to ensure that as new data types are introduced to the API, instantiation of Attribute models does not fail.
Be aware that attempting to update attributes with datatypes not available in the DataType enum will fail validation.
Data Types currently supported the the PHP-SDK:
Datatype | Description |
|---|---|
STRING | Default attribute type expecting any content, providing it is transmitted as a string type |
NUMBER | Attribute value must be sent as an integer or float Note: not currently supported for creating custom attributes |
DATETIME | Attribute value must be sent as a string in ISO-8601 format. Special handling may be performed in Klevu's indexes Note: not currently supported for creating custom attributes |
MULTIVALUE | Attribute value must be sent as an array (with numeric keys, rather than a hash or object). Individual values may be any scalar type. |
JSON | Attribute value must be sent as a valid JSON string. Note: not currently supported for creating custom attributes; some core attributes will use this type |
BOOLEAN | Attribute value must be sent as a boolean Note: not currently supported for creating custom attributes; some core attributes will use this type |
Protected Data Types
As noted in the table above, some data types are not available to custom attributes. The DATETIME and NUMBER types will be available in future versions, but are not currently used by any attribute; JSON and BOOLEAN are used by some core (immutable) attributes, but are not available to create custom attributes with.
Immutable attributes cover those defined by default in Klevu's indexes and include, for example, name ; sku; and url . Attributes retrieved via the AttributesService get or getByName methods will havethis value populated from the API response.
Attributes with the immutable flag set to true cannot have their data changed using setters. For example, the following code would throw a CouldNotUpdateException
Immutable attributes cannot be sent for add, update, or delete operations via the AttributeService and will be rejected during the validation stage.
Note that the immutable flag can be disabled at any time to circumvent these restrictions, however disabling locks and sending update / delete requests for attributes defined as immutable in Klevu's indexes will result in a BadRequestException as the APIs will reject the request. Additionally, the immutable flag is ignored when creating or updating an attribute via the API.
The AttributesService::get method will query the indexing.ksearchnet.com/v2/attributes endpoint using your JS API Key and REST AUTH Key (available via Store Settings in KMC) and return an AttributeIterator containing Attribute models representing all existing attributes in your installation.
Additionally, you can use AttributesService::getByName to query a single attribute, returning either an Attribute model or null.
- Prior to transmitting data, the provided account credentials are validated as not empty and correctly formatted, throwing a ValidationException on failure.
- Request exceptions, or responses identifying an invalid request throw aBadRequestException
- Client or Network exceptions, responses with unexpected status codes, or responses with a missing or invalid body content throw a BadResponseException
- Request headers and body are logged prior to send at DEBUG level
- Data used to generate the request bearer token is logged at DEBUG level
- Response headers, body, and execution time are logged on successful request send at DEBUG level
More information and code samples can be found under Examples / How To > Data Indexing > List Existing Attributes
The AttributesService::put method will send a PUT request to the indexing.ksearchnet.com/v2/attributes/[ATTRIBUTE_NAME] endpoint using your JS API Key and REST AUTH Key (availble via Store Settings in KMC).
Data is provided as an Attribute object and validated using the AttributeValidator .
When updating an attribute, the attribute name is both case-insensitive and immutable, meaning if you have an existing attribute called my_attribute and you submit a request to update MY_ATTRIBUTE, the changes will be applied but the attribute will retain the name my_attribute
An attribute's datatype cannot be changed after registration. As such, if you need to change an attribute (for example, from a string to a multivalue), you must first delete the existing attribute and recreate it with the new definition.
Important: this will delete all existing data for this attribute from the Klevu indexes and require a full resync of your catalog data.
More information and code samples can be found under Examples / How To > Data Indexing > Add, Update, or Delete Indexing Attributes
Data for custom attributes should be sent within the attributes section of an indexing request, and should be formatted as an object containing at least the "default" key with the attribute's value. Alternative language values can be sent within this array, identified by a language code key. For more information, see the guide on Synchronising Data
Note, there may be a short delay between creating an attribute and it being available for us when synchronising data. We recommend waiting for 60 seonds after registering an attribute before sending an indexing request referencing it.
- Prior to transmitting data, the provided account credentials are validated as not empty and correctly formatted, throwing a ValidationException on failure.
- Prior to transmitting data, the Attribute data is validated, throwing a ValidationException on failure.
- Request exceptions, or responses identifying an invalid request throw aBadRequestException
- Client or Network exceptions, responses with unexpected status codes, or responses with a missing or invalid body content throw a BadResponseException
- Request headers and body are logged prior to send at DEBUG level
- Data used to generate the request bearer token is logged at DEBUG level
- Response headers, body, and execution time are logged on successful request send at DEBUG level
The AttributesService will send a DELETE request to the indexing.kseachnet.com/attributes/[ATTRIBUTE_NAME] endpoint using your JS API Key and REST AUTH Key (availble via Store Settings in KMC).
Data is provided either as a string (deleteByName) or by providing an Attribute object to delete, from which the name is extracted and passed to deleteByName.
- Prior to transmitting data, the provided account credentials are validated as not empty and correctly formatted, throwing a ValidationException on failure.
- Prior to transmitting data, the Attribute name is validated, throwing a ValidationException on failure.
- Request exceptions, or responses identifying an invalid request throw aBadRequestException
- Client or Network exceptions, responses with unexpected status codes, or responses with a missing or invalid body content throw a BadResponseException
- Request headers and body are logged prior to send at DEBUG level
- Data used to generate the request bearer token is logged at DEBUG level
- Response headers, body, and execution time are logged on successful request send at DEBUG level
More information and code samples can be found under Examples / How To > Data Indexing > Add, Update, or Delete Indexing Attributes
