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 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 data types 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 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 \<?php $attribute = new attrbute('attr', 'string'); $attribute >setsearchable(true); // ok $attribute >setimmutable(true); $attribute >setsearchable(false); // throws exception 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 listing existing attributes 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 validation and exception handling 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 a badrequestexception client or network exceptions, responses with unexpected status codes, or responses with a missing or invalid body content throw a badresponseexception logging 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 list existing attributes creating or updating 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 handling changes to data type 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 add, update, or delete indexing attributes syncing data for new 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 validation and exception handling 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 a badrequestexception client or network exceptions, responses with unexpected status codes, or responses with a missing or invalid body content throw a badresponseexception logging 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 deleting attributes 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 validation and exception handling 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 a badrequestexception client or network exceptions, responses with unexpected status codes, or responses with a missing or invalid body content throw a badresponseexception logging 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 add, update, or delete indexing attributes