Search for	Example	Results
A single word	`cat`	Topics that contain the word "cat". You will also find its grammatical variations, such as "cats".
A phrase. You can specify that the search results contain a specific phrase.	`"cat food"` (quotation marks)	Topics that contain the literal phrase "cat food" and all its grammatical variations. Without the quotation marks, the query is equivalent to specifying an OR operator, which finds topics with one of the individual words instead of the phrase.

Search for	Operator	Example
Two or more words in the same topic	`AND` `and` `+` (plus symbol) `&` (ampersand)	`cat AND dog` `"cat food"+milk` `"cat food"&"dog food"`
Either word in a topic	`OR` `or` `\|` (pipe)	`cat OR dog` `cat \| dog`
Topics that do not contain a specific word or phrase	`NOT` `not` `!` (exclamation point)	`NOT cat` `! dog`
Topics that contain one string and do not contain another	`^` (caret)	`cat ^ mouse`
A combination of search types	`( )` parentheses	`cat + (dog \| mouse)` `cat \| dog + (! mouse)`

Service Management

Develop > Developer reference > REST API collection query protocol

REST API collection query protocol

This section provides specifications for HTTP GET query parameters designed to be used with REST services APIs.

Collection filtering

The filter query parameter specifies a filtering condition for a resource collection. The service then returns only resources that meet the specified condition.

Logical operators

The following logical operators are supported:

Name	Description	Examples
Logical And	Evaluates to true if both the left and right operands evaluate to true, otherwise evaluates to false.	http://domain/resource?filter=Id gt 1000 and Name eq ‘Jake’ http://domain/resource?filter=Id > 1000 and Name = ‘Jake’
Logical Or	Evaluates to true if at least one of the left and right operands evaluates to true, otherwise evaluates to false.	http://domain/resource?filter=Id gt 1000 or Name eq ‘Jane’ http://domain/resource?filter=Id > 1000 or Name = ‘Jane’

Note Logical Not is not supported. Specific operators have their own negation syntax. For example: “in” and “not in”, “=” and “!=”.

Comparison operators

Comparison logical operators evaluate to a boolean value depending on the operand values.

The following comparison operators are supported:

Name	Description	Examples
Equals	Evaluates to true if the left and right operands are equal, otherwise evaluates to false.	http://domain/resource?filter=Rank eq 2 http://domain/resource?filter=Rank = 2
Not equals	Evaluates to true if the left and right operands are not equal, otherwise evaluates to false.	http://domain/resource?filter=Rank ne 2 http://domain/resource?filter=Rank != 2
Greater than	Evaluates to true if the left operand is greater than the right operand, otherwise evaluates to false.	http://domain/resource?filter=Rank gt 2 http://domain/resource?filter=Rank > 2
Greater or equal	Evaluates to true if the left operand is greater than or equal to the right operand, otherwise evaluates to false.	http://domain/resource?filter=Rank ge 2 http://domain/resource?filter=Rank >= 2
Less than	Evaluates to true if the left operand is less than the right operand, otherwise evaluates to false.	http://domain/resource?filter=Rank lt 2 http://domain/resource?filter=Rank < 2
Less or equal	Evaluates to true if the left operand is less than or equal to the right operand, otherwise evaluates to false.	http://domain/resource?filter=Rank le 2 http://domain/resource?filter=Rank <= 2
Between	Evaluates to true if the left-most operand is in the range defined by the two comma-separated operands in the parentheses, otherwise evaluates to false. The first operand in the parentheses represents the lower limit of the range and the second the upper limit.	http://domain/resource?filter=LastUpdate btw(2012.01.01, 2013.01.01)
Not between	Evaluates to true if the left-most operand is not in the range defined by the two comma-separated operands in the parentheses, otherwise evaluates to false. The first operand in the parentheses represents the lower limit of the range and the second the upper limit. Range boundaries are inclusive.	http://domain/resource?filter=LastUpdate not btw(2012.01.01, 2013.01.01)
In	Evaluates to true if the left-most operand is equal to one of the expressions in the parentheses, otherwise evaluates to false.	http://domain/resource?filter=Id in(1,2,3)
Not in	Evaluates to true if the left-most operand is not equal to any of the expressions in the parentheses, otherwise evaluates to false.	http://domain/resource?filter=Id not in(1, 2, 3)

Note Different expressions and data types might not have a strict definition of how they evaluate against one another, so the definition of how operators evaluate might become service dependent.

Arithmetic operators

The following artihmetic operators are supported:

Name	Description	Examples
Add	Evaluates to the result of the sum of the left operand to the right operand.	http://domain/resource?filter=PreviousRank gt (CurrentRank add 3) http://domain/resource?filter=PreviousRank > (CurrentRank + 3)
Subtract	Evaluates to the value of the left operand minus the value of the right operand.	http://domain/resource?filter=PreviousRank gt (CurrentRank sub 3) http://domain/resource?filter=PreviousRank > (CurrentRank - 3)
Multiply	Evaluates to the product of the left operand and right operand values.	http://domain/resource?filter=PreviousRank lt (CurrentRank mul 3) http://domain/resource?filter=PreviousRank < (CurrentRank * 3)
Modulo	Evaluates to the remainder of the division of the left operand by the right operand.	http://domain/resource?filter=Actual gt Planned and (Planned mod Actual) gt 5 http://domain/resource?filter=Actual > Planned and (Planned % Actual) > 5
Divide	Evaluates to the value of the division of the left operand by the right operand.	http://domain/resource?filter=PlannedHours div 10 http://domain/resource?filter=PlannedHours / 10
Parentheses	Used around conditions and expressions to define priority.	http://domain/resource?filter=(x add y) mul (x sub z) http://domain/resource?filter=(x + y) * (x - z)
Unary plus	Syntax: +number
Unary minus	Syntax: -number

Layout

The layout query parameter specifies which properties or sub-structure of a data resource should be returned by a service. Similar to SQL, this parameter provides a comma separated list of properties or multi-part properties.

Selecting Resource Properties. Specify the required properties according to the following syntax: http://domain/resource?layout=Id,Name,Description.
Selecting Related Resource Properties. Specify a relationship name and a property name according to the following syntax: http://domain/Person?layout=PrimaryAddress.City.
Selecting a Sub-Structure Using Multipart Properties. Resources that contain complex object structures can be queried for a sub-structure using multi-part property conventions.

Example: Query a resource named UserSetting for a Select object, which is a sub-structure of a Filter object, which is a sub-structure of a UserSetting object. Enter a request according to the following syntax: http://domain/UserSetting?layout=Settings.Filter.Select.
Selecting Calculated Values. The query protocol supports function and arithmetic operators.

Example 1: Query a Formula resource for the product of a property named X and a property named Y. Enter a request according to the following syntax: http://domain/Formula?layout=X mul Y.

Example 2: Query a Person resource for FirstName and LastName and return a concatenation in the format “FirstName.LastName”. Enter a request according to the following syntax: http://domain/Person?layout=Concat(FirstName, Concat(‘ ’, LastName)).

Ordering

The order query parameter specifies the order in which the returned resources are placed. Similar to SQL, this parameter contains a comma-separated list of order expressions. Each order expression specifies a property name and a sort direction.

The following syntax is supported:

order=property-name desc | asc

Size

The size parameter specifies the maximum number of resources requested to be returned.

The following syntax is supported:

size=<integer>

Example: Return the first ten people with age lower than 30 in ascending order. Enter the following request:

http://<domain>/Person?layout=FirstName,LastName,Email&filter=Age<30&order=Age asc&size=10

Skip

The skip parameter specifies how many resources should be skipped by specifying the starting index of the returned result. When not specified, its default value is zero, such that the first resource returned from the data-store is the first resource returned by the queried service.

The following syntax is supported:

skip=<integer>

Example: Return people, starting from person number 51. Enter the following request:

http://<domain>/Person?layout=FirstName,LastName,Email&skip=50

Paging

Paging is achieved by the combination of the skip and size parameters.

Example: Return a page of 50 people starting from the first person. Enter the following request:

http://<domain>/Person?layout=FirstName,LastName,Email&order=Id&skip=0&size=50.

To return the next page (page = 2), enter the following request:

http://<domain>/Person?layout=FirstName,LastName,Email&order=Id&skip=50&size=50.

To return the next page (page = 3), enter the following request:

http://<domain>/Person?layout=FirstName,LastName,Email&order=Id&skip=100&size=50.

Metadata

The meta parameter allows clients to request metadata about the queried object and the request itself.

The following syntax is supported:

meta=<comma separated list of meta-data properties>

Example: Return people with age greater than 10, starting from person number 51. Include the total number of people that apply to the specified filter (totalCount) and the number of returned resources (Count). Enter the following request:

http://<domain>/Person?layout=FirstName,LastName,Email&skip=50&filter=Age>10&meta= TotalCount,Count

The following are some common metadata attributes:

Name	HTTP Method	Retrieved	Description	Value Range
completion_status	Any	Always (based on service specifications)	A request completion status.	One of: OK Failed Rejected TemporarilyRejected
totalCount	GET	On Demand (based on service specifications)	The total number of resources that apply for the request (discards skip and size).	Integer

Name

HTTP Method

Retrieved

Description

Value Range

completion_status

Any

Always (based on service specifications)

A request completion status.

One of:

OK
Failed
Rejected
TemporarilyRejected

totalCount

GET

On Demand (based on service specifications)

The total number of resources that apply for the request (discards skip and size).

Integer

The following is an example of a JSON meta structure:

{

"meta": {
	"completion_status": "OK",
	"total_count": "1023",
	}

}

String literals

String literals can be used as expressions in query elements such as comparison condition on properties, function parameters and others. A string literal must always start and end with a single quote. If a single quote character is a part of the string itself, an additional single quote character must be added.

Example: The string Jimi’s new guitar should be passed as Jimi’’s new guitar.

Locking system – service behavior

The EMS data engine implements an optimistic locking system in order to prevent clients from accidentally overwriting each other’s data. Without appropriate validation, two clients can retrieve the same record, edit it and send it to the server for update. One of the changes is committed first and the second one overwrites the record. The optimistic locking approach checks the version or timestamp of the record when it arrives and only allows updates on it if the incoming version is not lower than the version currently stored in the database.

When a record is received for update, if it does not pass the optimistic locking version validation, the transaction fails. In such cases, the REST API returns HTTP status code 409. In case of a bulk API, the 409 status is returned in the body of the response, inside the JSON which represents the corresponding record result.

Note

To use this locking system, the incoming record must include the LastUpdateTime property with the value assigned to it when it was retrieved from the server.
The locking system is not relevant for the Analytics REST API.