In this chapter describes how to use characteristics in the Service API. It introduces the characteristic operand and the DESCENDANT operator.

Characteristic Operand

Syntax

When searching for items using characteristic record values the term characteristic with parenthesis has to to used. Both qualifications for the characteristic are optional.

characteristic( <Entity Item>,<Language>)

Element

Definition

Entity Item

Characteristic entity item without a container item:

'<external_identifier>'|<internal_id>

Please don't forget to use single quotes when you want
to specify the external identifier of the characteristic!

Language

The value for the language qualification can either be the key or a synonym as defined in the Enum.Language of the repository.

Example:

To qualify the German language the value 7 or "DE" can be used equally.

So valid examples for the characteristic term are:

characteristic()

characteristic('Ingredients')

characteristic(156335)

characteristic(156335, "DE")

characteristic(156335, 7)

It is not possible to search for any characteristic with a specific language.~~characteristic( "DE" )~~

Usage examples

Searching for items which have a specific characteristic and a specific value

This call will return all items which have the string value "Bean" for the characteristic Ingredient. Note that the characteristic has the datatype TEXT and therefore the characteristic record values are of type String.

http://localhost:1512/rest/V1.0/list/Article/bySearch?query=characteristic('Ingredient') = "Bean"

We have these items with characteristic records:

ItemIdentifier	Characteristic	Characteristic record value
Item1	Ingredient	"Salt"
Item2	Ingredient	"Bean"
Item3	Ingredient	"Egg"
Item4	BakingMaterials	"Flour"

The query above will only return Item2.

When searching for string values it is also possible to use specific string operators like : equalsIC, equals , contains, startsWith, contains, ...etc.

All possible operators can be found in the chapter REST Search Query Language

http://localhost:1512/rest/V1.0/list/Article/bySearch?query=characteristic('Ingredient') startsWith "Bean"

We have these items with characteristic records:

ItemIdentifier	Characteristic	Characteristic record value
Item1	Ingredient	"Salt"
Item2	Ingredient	"Beans"
Item3	Ingredient	"Egg"
Item4	BakingMaterials	"Flour"

The query above will only return Item2.

When searching for all items which have a characteristic record for the characteristic Ingredient.

http://localhost:1512/rest/V1.0/list/Article/bySearch?query=not characteristic('Ingredient') is empty

We have these items with characteristic records:

ItemIdentifier	Characteristic	Characteristic record value
Item1	Ingredient	"Salt"
Item2	Ingredient	"Beans"
Item3	Ingredient	"Egg"
Item4	BakingMaterials	"Flour"

The query above will return Item1,Item2,Item3.

Searching for items which have specific characteristics and specific values

This call will return all items which have the value 15678 as a characteristic record for the characteristic "Numeric" and also have the value "2017-12-31" for the characteristic "TerminationDate"

http://localhost:1512/rest/V1.0/list/Article/bySearch?query=characteristic('Numeric') = 15678 and characteristic('TerminationDate') = "2017-12-31"

We have these items with characteristic records:

ItemIdentifier	Characteristic	Characteristic record value	Characteristic	Characteristic record value
Item1	Numeric	12345	`TerminationDate`	2017-12-31
Item2	Numeric	15678	`TerminationDate`	2017-12-31
Item3	Numeric	15678	`TerminationDate`	2017-11-20
Item4	Numeric	1335	`TerminationDate`	2018-12-31

The query above will only return Item2.

Searching for items in a specific language

This call will return all items which contain the value "soup recipe" for the characteristic "Description" in English

http://localhost:1512/rest/V1.0/list/Article/bySearch?query=characteristic('Description',9) contains "soup recipe"

http://localhost:1512/rest/V1.0/list/Article/bySearch?query=characteristic('Description',en) contains "soup recipe"

Both statements are equally valid.

We have these items with characteristic records:

ItemIdentifier	Characteristic	Language	Characteristic record value
Item1	Description	English	"soup without recipe"
Item2	Description	English	"this is a soup recipe "
Item3	Description	German	"Das ist ein Rezept für Suppe "
Item4	BakingMaterials	French	" soup recipe"

The query above will only return Item2.

Searching for items with lookup values

This call will return all items where the lookup value "Mushroom" of the lookup "Ingredients" is used regardless of the characteristic.

When trying to search by lookup values, it is required to use the entity proxy format: 'EXTERNAL_IDENTIFIER_OF_LOOKUP_VALUE'@'EXTERNAL_IDENTIFIER_OF_LOOKUP'

http://localhost:1512/rest/V1.0/list/Article/bySearch?query=characteristic() = 'Mushroom'@'Ingredients'

We have these items with characteristic records:

ItemIdentifier	Characteristic	Lookup of Characteristic	Characteristic record value
Item1	CookingIngredients	Ingredients	Salt
Item2	CookingIngredients	Ingredients	Mushroom
Item3	CookingIngredients	Ingredients	Egg
Item4	ToxicIngredients	Ingredients	Mushroom

The query above will return Item2 and Item 4.

When specifying a characteristic, it is possible to use the lookup value identifier without the lookup identifier:

http://localhost:1512/rest/V1.0/list/Article/bySearch?query=characteristic('CookingIngredients') = 'Mushroom'

The query above will only return Item2.

All other operators can be used as well just like working with the fieldpath:

http://localhost:1512/rest/V1.0/list/Article/bySearch?query=characteristic('Ingredient') in ( 'Mushroom'@'Ingredients','Egg'@'Ingredients' ) and not characteristic('TerminationDate') > 2017-12-31T15:00:00

We have these items with characteristic records:

ItemIdentifier	Characteristic	Lookup of Characteristic	Characteristic record value	Characteristic	Characteristic record value
Item1	Ingredient	Ingredients	Mushroom	TerminationDate	2017-12-28 17:30:00
Item2	Ingredient	Ingredients	Mushroom	TerminationDate	2020-12-12 15:00:00
Item3	Ingredient	Ingredients	Egg	TerminationDate	2017-12-05 15:00:00
Item4	BakingMaterials	Ingredients	Flour	TerminationDate	2017-12-31 13:37:00

The query above will only return Item1 and Item3.

DESCENDANT Operator

Sometimes it is important to find items with certain values. For example to find all items containing sugar won in Brazil. You don't want items containing sugar from India or meat from Brazil in your result set. In order to maintain such item data, you probably modeled a characteristic "Ingredient" containing the values "Sugar" or "Meat" and a characteristic "Country of origin" which is a descendant of the characteristic "Ingredient" in the characteristic hierarchy. Using the characteristic operand from above you would find items containing the ingredient sugar and items with Brazil as country of origin. In order to tell the system that you only want items having the two values in a direct hierarchy, you can use the DESCENDANT operator.

Syntax

Operator

Allowed datatypes

Description

DESCENDANT

all datatypes

except MIME

This operator searches for characteristics having a hierarchical relationship.

Operands may be all binary expressions containing a characteristic except connectors like AND and OR.

The left operand must be an expression containing a characteristic which is higher in the characteristic hierarchy than the characteristic contained by the right operand.

Note: The left operand must not necessarily contain the root characteristic, but it must be higher in the characteristic hierarchy than the characteristic contained by the right operand.

>>

So valid examples for the DESCENDANT operator are:

Operand1 DESCENDANT Operand2

Operand1 DESCENDANT Operand2 DESCENDANT Operand3

Operand1 >> Operand2

Operand1 >> Operand2 >> Operand3

Operand1 >> NOT(Operand2) >> Operand3

Operand1 >> Operand2 DESCENDANT Operand 3

The following examples are not valid:

Operand1 >> Operand2 AND Operand3 >> Operand 4

Operand1 >> Operand2 OR Operand3 >> Operand 4

Limitations

It is not possible to use the same characteristic more than once in one DESCENDANT expression. So the following example ist not valid:

characteristic( 'ABC' ) equals otherValue DESCENDANT characteristic( 'ABC' ) equals otherValue DESCENDANT characteristic( 'ABC' ) equals otherValue

The descendant operator cannot be negated. So the following example ist not valid:

NOT (characteristic( 'ABC' ) equals value DESCENDANT characteristic( 'ABCD' ) equals otherValue)

Usage Examples

Rest call

GET http://localhost:1512/rest/V1.0/list/Article/bySearch?query=characteristic( 'Ingredient' ) equals 'SUGAR'@'Ingredients' DESCENDANT characteristic( 'CountryOfOrigin' ) equals 'BRAZIL'@'OriginCountries' 

Rest call - Alternative syntax with >>

GET http://localhost:1512/rest/V1.0/list/Article/bySearch?query=characteristic( 'Ingredient' ) equals 'SUGAR'@'Ingredients' >> characteristic( 'CountryOfOrigin' ) equals 'BRAZIL'@'OriginCountries'  

We have these items with characteristic records:

Item Identifier	Characteristic	Lookup of Characteristic	Characteristic record value
Item1	Ingredient	Ingredients	Sugar
Item1	CountryOfOrigin	OriginCountries	Thailand
Item2	Ingredient	Ingredients	Sugar
Item2	CountryOfOrigin	OriginCountries	India
Item2	Ingredient	Ingredients	Meat
Item2	CountryOfOrigin	OriginCountries	Brazil
Item3	Ingredient	Ingredients	Sugar
Item3	CountryOfOrigin	OriginCountries	Brazil

The query above will return Item3.

Rest call

GET http://localhost:1512/rest/V1.0/list/Article/bySearch?query=(characteristic( 'Ingredient' ) equals 'SUGAR'@'Ingredients' or characteristic( 'Ingredient' ) equals 'SALT'@'Ingredients') >> characteristic( 'CountryOfOrigin' ) equals 'BRAZIL'@'OriginCountries'   

We have these items with characteristic records:

Item Identifier	Characteristic	Lookup of Characteristic	Characteristic record value
Item1	Ingredient	Ingredients	Sugar
Item1	CountryOfOrigin	OriginCountries	Thailand
Item2	Ingredient	Ingredients	Sugar
Item2	CountryOfOrigin	OriginCountries	India
Item2	Ingredient	Ingredients	Meat
Item2	CountryOfOrigin	OriginCountries	Brazil
Item3	Ingredient	Ingredients	Sugar
Item3	CountryOfOrigin	OriginCountries	Brazil
Item4	Ingredient	Ingredients	Salt
Item4	CountryOfOrigin	OriginCountries	Brazil

The query above will return Item3 and Item4.

Rest call

GET http://localhost:1512/rest/V1.0/list/Article/bySearch?query=(characteristic('Ingredient') = 'WOOL' >> characteristic('SerialNumber') = 55) AND ( characteristic('Ingredient') = 'LEATHER' >> characteristic('CountryOfOrigin') = 'ES')  

We have these items with characteristic records:

Item Identifier	Characteristic	Lookup of Characteristic	Characteristic record value
Item1	Ingredient	Ingredients	Wool
Item1	CountryOfOrigin	OriginCountries	Spain
Item1	SerialNumber	-	55
Item2	Ingredient	Ingredients	Wool
Item2	CountryOfOrigin	OriginCountries	India
Item2	SerialNumber	-	55
Item2	Ingredient	Ingredients	Leather
Item2	CountryOfOrigin	OriginCountries	Spain
Item3	Ingredient	Ingredients	Wool
Item3	CountryOfOrigin	OriginCountries	Brazil
Item4	Ingredient	Ingredients	Leather
Item4	CountryOfOrigin	OriginCountries	Spain

The query above will return Item2.

Limitation

Currently it is not possible to search for the datatype MIME in search expressions.