--- title: Query description: To query a resource collection, which you can think of as a resource container, perform an HTTP GET and accept a JSON response including at least a _queryFilter or _queryId parameter. These parameters cannot be used together. component: pingoneaic page_id: pingoneaic:developer-docs:crest/query canonical_url: https://docs.pingidentity.com/pingoneaic/developer-docs/crest/query.html section_ids: parameters: Parameters crest-query-queryFilter: Filter expressions --- # Query To query a resource collection, which you can think of as a resource container, perform an HTTP GET and accept a JSON response including at least a `_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 endpoint returns the result as a JSON object including a `results` array and other fields related to the query string parameters. ## Parameters You can use the following query string parameters: | Parameter | Description | | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `_fields=field[,field...]` | Return only the specified fields in each element of the `results`.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 endpoint returns all default values. | | `_pagedResultsCookie=string` | The string is an opaque cookie to keep track of the position in the search results. The service returns the cookie in the JSON response as the value of `pagedResultsCookie`.In the request `_pageSize` must be set and non-zero. You receive the cookie value from the provider on the first request. You supply the cookie value in subsequent requests until the service returns a `null` cookie when the final page of results has been returned.Use this parameter with the `_queryFilter` parameter. It is not guaranteed to work with the `_queryId` parameter.The `_pagedResultsCookie` and `_pagedResultsOffset` parameters are mutually exclusive. Do not use them 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. Do not use them together. | | `_pageSize=integer` | Return query results in pages of this size.After the initial request, use `_pagedResultsCookie` or `_pageResultsOffset` to page through the results. | | `_prettyPrint=true` | Format the body of the response. | | `_queryFilter=filter-expression` | Query filters request entries matching the filter expression. You must URL-escape the filter expression.Learn more in [Filter expressions](#crest-query-queryFilter). | | `_queryId=identifier` | Specify a query by its identifier.Specific queries can take their own query string parameter arguments depending on the implementation. | | `_sortKeys=[-][.var]##field##[,[-]field...]` | Sort the resources returned based on the specified field(s) in `+` (ascending, default) or in `-` (descending) order.As 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`:```none https:///api/users?_prettyPrint=true&_queryFilter=true&_sortKeys=%2Bname/givenName ```The `_sortKeys` parameter is not supported for predefined queries (`_queryId`). | | `_totalPagedResultsPolicy=string` | When a non-zero `_pageSize` is specified, the service calculates the `totalPagedResults` in accordance with the `totalPagedResultsPolicy`, and provides the value as part of the response.The `totalPagedResults` is:- An estimate of the total number of paged results (`_totalPagedResultsPolicy=ESTIMATE`). - The exact total result count (`_totalPagedResultsPolicy=EXACT`).If no count policy is specified in the query, or if `_totalPagedResultsPolicy=NONE`, result counting is disabled. The service returns `"totalPagedResults": -1`. | ## Filter expressions Query filters request entries matching the filter expression. You must URL-escape the filter expression. The string representation is summarized as follows: ```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, notice the filter expression is part of a query string parameter. URL-encoded the filter expression. Learn more in [RFC 3986: Uniform Resource Identifier (URI): Generic Syntax](https://www.rfc-editor.org/rfc/rfc3986.html). For example, whitespace, double quotes (`"`), parentheses, and exclamation characters need URL encoding. 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.