6.2 KiB
6.2 KiB
Query Parameters
Table of Contents
Sorting
The sort query parameter defines the sort order for query results.
A sort criteria includes a field name and direction (ASC ascending or DESC descending).
Multiple criteria can be used, defining the sort order of entities in the result.
Syntax:
| Parameter | Value |
|---|---|
| sort | sort_criteria {"," sort_criteria} |
| sort_criteria | field_name ":" ("ASC"|"DESC") |
| field_name | alpha |
| alpha | (digit|character){digit|character}; |
| digit | "0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9"; |
| character | lowercase_character|uppercase_character|special_character |
| special_character | "_" |
| lowercase_character | "a"|"b"|"c"|"d"|"e"|"f"|"g"|"h"|"i"|"j"|"k"|"l"|"m"|"n"|"o"|"p"|"q"|"r"|"s"|"t"|"u"|"v"|"w"|"x"|"y"|"z"; |
| uppercase_character | "A"|"B"|"C"|"D"|"E"|"F"|"G"|"H"|"I"|"J"|"K"|"L"|"M"|"N"|"O"|"P"|"Q"|"R"|"S"|"T"|"U"|"V"|"W"|"X"|"Y"|"Z"; |
Example:
/targets?sort=field_1:ASC,field_2:DESC,field_3:ASC
Paging
Pagination is automatically applied to all GET requests for collection resources.
Configuration parameters:
offset: paging offset (default is 0)limit: maximum entries per page (default is 50)
The maximum value for limit is 500. For groups, the maximum is 1000 (subject to change in future versions).
Invalid values default to standard settings. Limits exceeding the maximum use the maximum value instead.
Examples
| URL | Description |
|---|---|
/targets?sort=name:ASC |
Sorts targets by name, returns first 50 (default offset 0, default limit 50) |
/targets?sort=name:ASC&limit=10 |
Sorts targets by name, returns first 10 |
/targets?sort=name:ASC&offset=10 |
Sorts targets by name, returns next 50 targets after the 10th (starting with 11th) |
/targets?sort=name:ASC&offset=20&limit=10 |
Sorts targets by name, returns next 10 targets after the 20th (starting with 21st) |
/targets?sort=name:ASC&offset=100&limit=600 |
Sorts targets by name, returns next 500 targets (max limit, not 600) after the 100th (starting with 101st) |
FIQL Syntax Search Query
The q parameter filters resource fields using Feed Item Query Language (FIQL).
Syntax:
q=FIQL-expression
Expression structure:
q=field<basic_operator>value<composite_operator>field<basic_operator>value<...>
q: identifier for FIQL queryfield: resource field name (see Entity definitions for filterable fields)value: field value<basic_operator>: operators for simple queries<composite_operator>: operators to join simple queries
Basic Operators and Composite Operators at a Glance
Basic Operators:
| Operator | Description | Example |
|---|---|---|
== |
Equal to expression | /targets?q=name==ccu299792 |
!= |
Not equal to expression | /targets?q=name!=ccu299792 |
=lt= |
Less than expression | /distributionsets?q=id=lt=142 |
=le= |
Less than or equal expression | /distributionsets?q=id=le=142 |
=gt= |
Greater than expression | /distributionsets?q=id=gt=142 |
=ge= |
Greater than or equal expression | /distributionsets?q=id=ge=142 |
=li= |
Like expression | /targets?q=name=li=_________0 |
=in= |
In expression | /targets?q=name=in=(ccu299792, shc137) |
=out= |
Not in (out) expression | /targets?q=name=out=(ccu299792, shc137) |
Composite Operators:
| Operator | Description | Example |
|---|---|---|
and or ; |
AND expression | /rest/v1/targets?q=updatestatus==unknown and controllerId==SHC* |
or or , |
OR expression | /rest/v1/targets?q=updatestatus==unknown or updatestatus==error |
Using Wildcards to Filter
Use * for wildcard matches.
| Example URL | Description |
|---|---|
/targets?q=name==ccu* |
Returns targets with names starting with ccu |
/targets?q=name==*ccu |
Returns targets with names ending with ccu |
/targets?q=name==*ccu* |
Returns targets containing ccu in their name |
/targets?q=name=="ccu\\*" |
Returns targets with names starting with ccu* |
/targets?q=name=="*\\*\*" |
Returns targets containing asterisk(*) in their names |
Combining Sorting, Paging, and FIQL
| Example URL | Description |
|---|---|
/targets?sort=controllerId:DESC&limit=5&q=updatestatus==pending |
Returns 5 targets with updatestatus 'pending', sorted descending |
/softwaremodules?sort=name:ASC&q=version==5.1.1 and type==application |
Returns software modules sorted by name, with version 5.1.1 and type application |
/distributionsets?sort=name:DESC&limit=150&q=name==*CCU* or description==*CCU* |
Returns 150 distribution sets sorted descending by name with CCU in name or description |
/distributionsettypes?limit=100&offset=100&q=key==vhicletypex2015 |
Returns 100 distribution set types (starting with 101st) with key vhicletypex2015 |
/targets?sort=name:ASC&offset=100&limit=25&q=(description==*SH* or name==*SH*) and name=li=_____ |
Returns 25 targets (starting with 101st), sorted ascending, with 'SH' in name or description and exactly 5 characters |
/targets?sort=name:DESC&limit=50&q=name=in=(*ccu*, *ecu*) and updatestatus=in=(pending, in\_sync) |
Returns 50 targets sorted descending with 'ccu' or 'ecu' in name and updatestatus 'pending' or 'in_sync' |