Filters' Query Composition

Abstract

The document summarizes the filtering operators and options available for the items' queries through API methods. Get Items and Get Attachments List employ such operators.

The Filters' Query Composition document lists and explains each filtering operator and option available when composing a request body for the Get Items and Get Attachments List API methods.

Supported ODATA Comparison Operators¶

The Get Items API supports the following list of ODATA comparison operators:

Operator	Operation	Example
`eq`	Equal	`$filter=userEmail eq 'j.doe@vesenda.com'`
`ne`	Not Equal	`$filter=SaleOrderCategoryNumber neq 11`
`gt`	Greater than	`$filter=budget gt 300`
`lt`	Less than	`$filter=budget lt 300`
`ge`	Greater than or Equal	`$filter=budget gte 300`
`le`	Less than or Equal	`$filter=budget le 300`

Note

You should write String-type values for ODATA Comparison Operators between apostrophes (''). Insert special characters in String-type values through the URL Encode format. (E.g. She's She%27s.)

You can use null values for comparison. E.g. ?$filter=Name eq null. The query looks for Name field's values that are null.

Supported ODATA Functions¶

The Get Items API supports the following list of ODATA functions:

Function	Meaning	Example
`substringof`	Searches the specified alphanumeric characters within a text (i.e. a String-type value). Accepts two values in order: the field's name as first parameter and the string value to be searched as second parameter.	`$filter=substringof(Code, '77aQ')`
`startswith`	Returns all the String-type values beginning with the specified set of alphanumeric characters. Accepts two values in order: the field's name as first parameter and a string value to be searched as second parameter.	`$filter=startswith(Code, 'AA27')`
`endswith`	Returns all the String-type values ending with the specified set of alphanumeric characters. Accepts two values in order: the field's name as first parameter and a string value to be searched as second parameter.	`$filter=endswith(Code, 'RM005')`
`multi`	Returns all the entries having certain values stored in a Multiselection field. Accepts at least three parameters and you can specify as many values as you want after the requested parameters. The function requires the following parameters: the field's name as first parameters; 0 (the entry's Multiselection contains AT LEAST ONE of the values) or 1 (the entry's Multiselection must contain ALL the specified values); the option's Id to search in the Multiselection field (and you can add more divided by a comma).	`$filter=multi(tags, 0, 11, 12, 13)`

Supported ODATA Combining Filters¶

The Get Items API supports the following list of ODATA combining filters:

Logical Operator	Example
`and`	`$filter=Name eq 'Joe' and Surname eq 'Doe'`
`or`	`$filter=Name eq 'Joe' or Surname eq 'Doe'`
`not`	`$filter=Surname not 'Black'`

ODATA Paging and Sorting Options¶

Use the following operators to provide criteria to page the results' list:

Option	Meaning	Example
`$top`	The query returns only the first n number of entries (e.g. first 200).	`$top=200`
`$skip`	The query ignores the first n number of entries resulting from the search.(E.g. Query ignores the first 50 entries, then the query starts returning the rest of the entries.)	`$skip=50`
`$orderby`	The query sorts the results' list according to the specified field and the specified order option: Ascending (`asc`) or Descending (`desc`) option. Divide each attribute through a comma.	`$orderby=Name desc, Age asc`