Filtering with RSQL
Learn how to apply filters to limit the results of a query.
Overview
This article describes how RSQL can be used to filter results from a response for endpoints in the Jamf Pro API that support filtering.
Comparison Operators
Comparisons are composed of a selector, an operator and an argument, in that order. In the context of Jamf Pro, the selector will be the field name. The list of supported operators and their functions are noted below.
| Operator | Example | Description |
|---|---|---|
| == | general.assetTag=="ValueA" | Equals query. Returns all matches where values of the filter field exactly equal ValueA |
| != | general.assetTag!="ValueA" | Not equals query. Returns all matches where values of the filter field do not equal ValueA |
| =lt= or < | general.assetTag<"ValueA" | Less than query. Returns all matches where values of the filter field is less than ValueA |
| =le= or <= | general.assetTag<="ValueA" | Less than or equal to query. Returns all matches where values of the filter field is less than or equal to ValueA |
| =gt= or > | general.assetTag>"ValueA" | Greater than query. Returns all matches where values of the filter field is greater than ValueA |
| =ge= or >= | general.assetTag>="ValueA" | Greater than or equal to query. Returns all matches where values of the filter field is greater than or equal to ValueA |
| =in= | general.assetTag=in=(ValueA | ValueB) | In query. Returns all matches where values of the filter field contains ValueA OR ValueB |
| =out= | general.assetTag=out=(ValueA | ValueB) | Out query. Returns all matches where values of the filter field do not contain ValueA OR ValueB |
- Jamf Pro is not case sensitive when doing string comparisons. For example,
New Yorkwill evaluate the same asnew yorkfor all operators. - Arguments that include white spaces must be passed within quotations.
- Single quotes and double quotes can be used interchangeably, but need to be used consistently.
- For example,
city=="new york'will fail to evaluate. However, bothcity=="new york"andcity=='New York'are acceptable and equivalent.
- For example,
- Special characters can be escaped using the forward slash. For example, to compare against the following argument
"New York's Finest", an escape character is required because the argument contains both single quotes, double quotes and spaces. Although multiple methods for supplying this argument exist, here are two acceptable examples:
city=='\"New York\'s Finest\"'
city=="\"New York's Finest\""
Wildcards
An asterisk can be used as a wildcard with both the equal and not equal operators. This also has the implication that values with an asterisk need to be escaped when attempting a lookup for the literal value.
Logical Operators
These operators can be used to relate multiple comparisons. By default, AND operators take precedence and are evaluated before any OR operators, however parenthesis can be used to change the order of evaluation.
| Operator | Description |
|---|---|
| , | Logical OR |
| ; | Logical AND |
Below is an example of an RSQL filter that will identify devices whose Barcode 1 or Barcode 2 values are "Sample" and whose Asset Tag is greater than 20.
(general.barcode1=="Sample",general.barcode2=="Sample");general.assetTag>"20"
Additional Information
- Null values are not returned as part of any comparisons, however fields with empty values "" are included in the comparisons.
- Responses from the Jamf Pro API automatically escape necessary characters, allowing the response to be used in the request body of future requests.
- Example requests, generated from the "Try it out" feature of the built-in documentation page, will automatically escape necessary characters.
Updated over 2 years ago