--- title: Query description: To query a resource collection (or resource container if you prefer to think of it that way), perform an HTTP GET and accept a JSON response, including at least a _queryExpression, _queryFilter, or _queryId parameter. These parameters cannot be used together: component: pingidm version: 8.1 page_id: pingidm::crest/crest-query canonical_url: https://docs.pingidentity.com/pingidm/8.1/crest/crest-query.html keywords: ["Rest", "REST API", "JSON"] --- # Query To query a resource collection (or resource container if you prefer to think of it that way), perform an HTTP GET and accept a JSON response, including at least a `_queryExpression`, `_queryFilter`, or `_queryId` parameter. These parameters cannot be used together: ```http GET /users?_queryFilter=true HTTP/1.1 Host: example.com Accept: application/json ``` The server returns the result as a JSON object including a "results" array and other fields related to the query string parameters that you specify. Parameters You can use the following parameters: * `_queryFilter=filter-expression` Query filters request that the server return entries that match the filter expression. You must URL-escape the filter expression. The string representation is summarized as follows. Continue reading for additional explanation: ```none Expr = OrExpr OrExpr = AndExpr ( 'or' AndExpr ) * AndExpr = NotExpr ( 'and' NotExpr ) * NotExpr = '!' PrimaryExpr | PrimaryExpr PrimaryExpr = '(' Expr ')' | ComparisonExpr | PresenceExpr | LiteralExpr ComparisonExpr = Pointer OpName JsonValue PresenceExpr = Pointer 'pr' LiteralExpr = 'true' | 'false' Pointer = JSON pointer OpName = 'eq' | # equal to 'co' | # contains 'sw' | # starts with 'lt' | # less than 'le' | # less than or equal to 'gt' | # greater than 'ge' | # greater than or equal to STRING # extended operator JsonValue = NUMBER | BOOLEAN | '"' UTF8STRING '"' STRING = ASCII string not containing white-space UTF8STRING = UTF-8 string possibly containing white-space ``` JsonValue components of filter expressions follow [RFC 7159: The JavaScript Object Notation (JSON) Data Interchange Format](https://www.rfc-editor.org/rfc/rfc7159.html). In particular, as described in section 7 of the RFC, the escape character in strings is the backslash character. For example, to match the identifier `test\`, use `_id eq 'test\\'`. In the JSON resource, the `\` is escaped the same way: `"_id":"test\\"`. When using a query filter in a URL, be aware that the filter expression is part of a query string parameter. A query string parameter must be URL encoded as described in [RFC 3986: Uniform Resource Identifier (URI): Generic Syntax](https://www.rfc-editor.org/rfc/rfc3986.html). For example, white space, double quotes (`"`), parentheses, and exclamation characters need URL encoding in HTTP query strings. The following rules apply to URL query components: ```none query = *( pchar / "/" / "?" ) pchar = unreserved / pct-encoded / sub-delims / ":" / "@" unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" pct-encoded = "%" HEXDIG HEXDIG sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" ``` `ALPHA`, `DIGIT`, and `HEXDIG` are core rules of [RFC 5234: Augmented BNF for Syntax Specifications](https://www.rfc-editor.org/rfc/rfc5234.html): ```none ALPHA = %x41-5A / %x61-7A ; A-Z / a-z DIGIT = %x30-39 ; 0-9 HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" ``` As a result, a backslash escape character in a JsonValue component is percent-encoded in the URL query string parameter as `%5C`. To encode the query filter expression `_id eq 'test\\'`, use `_id+eq'test%5C%5C'+`, for example. A simple filter expression can represent a comparison, presence, or a literal value. For comparison expressions use json-pointer comparator json-value, where the comparator is one of the following: `eq` (equals)\ `co` (contains)\ `sw` (starts with)\ `lt` (less than)\ `le` (less than or equal to)\ `gt` (greater than)\ `ge` (greater than or equal to) For presence, use json-pointer pr to match resources where: * The JSON pointer is present. * The value it points to is not `null`. Literal values include true (match anything) and false (match nothing). Complex expressions employ `and`, `or`, and `!` (not), with parentheses, `(expression)`, to group expressions. * `_queryId=identifier` Specify a query by its identifier. Specific queries can take their own query string parameter arguments, which depend on the implementation. * `_pagedResultsCookie=string` The string is an opaque cookie used by the server to keep track of the position in the search results. The server returns the cookie in the JSON response as the value of `pagedResultsCookie`. In the request `_pageSize` must also be set and non-zero. You receive the cookie value from the provider on the first request, and then supply the cookie value in subsequent requests until the server returns a `null` cookie, meaning that the final page of results has been returned. The `_pagedResultsCookie` parameter is supported when used with the `_queryFilter` parameter. The `_pagedResultsCookie` parameter is not guaranteed to work when used with the `_queryExpression` and `_queryId` parameters. The `_pagedResultsCookie` and `_pagedResultsOffset` parameters are mutually exclusive, and not to be used together. * `_pagedResultsOffset=integer` When `_pageSize` is non-zero, use this as an index in the result set indicating the first page to return. The `_pagedResultsCookie` and `_pagedResultsOffset` parameters are mutually exclusive, and not to be used together. * `_pageSize=integer` Return query results in pages of this size. After the initial request, use `_pagedResultsCookie` or `_pageResultsOffset` to page through the results. * `_totalPagedResultsPolicy=string` When a `_pageSize` is specified, and non-zero, the server calculates the "totalPagedResults", in accordance with the `totalPagedResultsPolicy`, and provides the value as part of the response. The "totalPagedResults" is either an estimate of the total number of paged results (`_totalPagedResultsPolicy=ESTIMATE`), or the exact total result count (`_totalPagedResultsPolicy=EXACT`). If no count policy is specified in the query, or if `_totalPagedResultsPolicy=NONE`, result counting is disabled, and the server returns value of -1 for "totalPagedResults". * `_sortKeys=[-][.replaceable]##field##[,[-]field...]` Sort the resources returned based on the specified field(s), either in `+` (ascending, default) order, or in `-` (descending) order. Because ascending order is the default, including the ``` ` character in the query is unnecessary. If you do include the ``, it must be URL-encoded as %2B` ```, for example: ```none http://localhost:8080/api/users?_prettyPrint=true&_queryFilter=true&_sortKeys=%2Bname/givenName ``` The `_sortKeys` parameter is not supported for predefined queries (`_queryId`). - `_prettyPrint=true` Format the body of the response. * `_fields=field[,field...]` Return only the specified fields in each element of the "results" array in the response. The `field` values are JSON pointers. For example if the resource is `{"parent":{"child":"value"}}`, `parent/child` refers to the `"child":"value"`. If the `field` is left blank, the server returns all default values.