Dell Unity™ Family Unisphere® Management REST API Programmer's Guide

Filtering response data

Use the filter request parameter to specify matching criteria for a list of resources returned by a collection query. The filter parameter works like an SQL WHERE clause. You specify a filter expression composed of boolean predicates, and the expression is applied against the attribute values of the requested resource type. Only those instances that cause the filter expression to evaluate to true are returned in the query response.

Using the filter parameter can save bandwidth, because the server removes extra data before returning data to the client. However the filter parameter does not reduce the amount of work the server performs to answer the request.

NOTE Very complex requests can be slow or can fail.

Syntax

As the first parameter on the request URI: ?filter=<filter_expr>

As a subsequent parameter on the request URI: &filter=<filter_expr>

where <filter_expr> is defined by the following syntax using Backus-Naur Form (BNF):

filter_expr ::= and_bool_expr
             | bool_expr ‘or’ and_bool_expr

and_bool_expr ::= simple_bool_expr
             | and_bool_expr ‘and’ simple_bool_expr

simple_bool_expr ::= cmp_expr
             | unary_expr
             | ‘not’ unary_expr

cmp_expr ::= unary_expr comparator unary_expr
             | lk_expr
             | in_expr

comparator ::= 'eq'  | 'ne'  | 'gt'  | 'ge'  | 'lt'  | 'le' 

lk_expr ::= attribute_name ‘lk’ constant_string

in_expr ::= attribute_name in_items_expr ‘)’

in_items_expr ::= ‘in’ ‘(‘ constant_string
             | in_items_expr ‘,’ constant_string

unary_expr ::= constant_value
             | attribute_name
             | ‘(‘ new_attr_expr ‘)’
             | concat_expr
             | count_expr
             | str_expr
             | enum_expr
             | sum_expr
             | concatList_expr

new_attr_expr ::= unary_expr 
             | bool_expr
             | cond_expr
             | arith_expr

arith_expr ::= high_priority_arith_expr
             | arith_expr [‘+’|’-‘] high_priority_arith_expr

high_priority_arith_expr ::= unary_expr
             | high_priority_arith_expr [‘*’|’/‘] unary_expr

concat_expr ::= concat_prefix_expr ‘)’ 

concat_prefix_expr ::= ‘@concat’ ‘(‘ concat_items_expr ‘,’ concat_items_expr
             | concat_prefix_expr ‘,’ concat_items_expr

concat_items_expr ::= unary_expr
             | new_attr_expr

count_expr ::= ‘@count’ ‘(‘ attribute_name ‘)’

str_expr::= ‘@str ‘(‘ attribute_name ‘)’

enum_expr::= ‘@enum ‘(‘ attribute_name ‘)’

sum_expr::= ‘@sum ‘(‘ attribute_name ‘)’

concatList_expr::= ‘@concatList ‘(‘unary_expr ',' 'separator='  const_value ‘)’
             |‘@concatList ‘(‘unary_expr unary_expr const_string ‘)’
             |‘@concatList ‘(‘unary_expr ',' 'separator='  const_value  ',' 'order='  const_string ‘)’
             |‘@concatList ‘(‘unary_expr ',' 'order='  const_string  ',' 'separator='  const_value  ‘)’

In the syntax for <filter_expr>:

attribute_name is the name of an attribute of the resource type. If the value of the attribute is a list, then the comparison is done against each value in the list, and the match is successful if at least one value in the list matches the filter expression. one of the following:
- Null
- The integer 0
- An empty collection
- An empty array
It evaluates to true in all other cases.
constant_value can be a:
- double quoted constant string
- constant number: integer/float in decimal or hexadecimal format
- boolean constant: true/false/True/False/TRUE/FALSE
- null/Null/NULL
All string comparisons, including lk and in, are case insensitive.

NOTE You can use dot notation syntax (resource_type.attribute) in a filter expression to filter by attributes from a related resource type. A related resource type is a resource type that is either referred to explicitly in the definition of the target resource type or embedded in the target resource type.

Filter expressions that apply to all base types

The following comparators in a filter expression apply to all base types:


Comparator	Symbol	Description
eq	=	Equal
ne	!=	Not equal
gt	>	Greater than
ge	>=	Greater than or equal
lt	<	Less than
le	<=	Less than or equal

The interpretation of gt, ge, lt, and le is type dependent. For example, gt used with dateTime attributes means the date value to the right of gt must be more recent than the date value to the left of gt.

Filter expressions that apply only to strings

The following comparators in a filter expression apply only to strings:


Comparator	Symbol	Description
lk	LIKE	(Like the SQL LIKE condition) Tests for a match against a value that contains one or more wildcards. % matches zero or more characters. _ matches one character Use the escape character \ if a constant string includes the % or _ characters (such as abc%d or abc_d), and you do not want to treat the % or _ as a wildcard. When using a wildcard or escape character in HTML, you must use the following HTML-encoded characters: %25 to represent % %5F to represent _ %5C to represent / For example: ServerName lk "server%25" matches instances where ServerName equals server1, server2, server3, server10, and so forth. In this example, %25 is the encoded character for %. ServerName lk "serv%5Fer" matches instances where ServerName equals serv1er, ser2er, serv3er and so forth. In this example, %5F is the encoded character for _. ServerName lk "serv%5C%25" matches instances where ServerName equals serv%. In this example, %25 makes the wildcard a literal string.
in	IN	(Like the SQL IN function) Tests for a match against one of a list of values. For example: ServerName in ("server1", "server2", "server3") matches instances where ServerName equals server1, server2, or server3.

NOTE

All string comparisons, including lk and in, are case insensitive.
Spaces are supported in string compares when enclosed in single or double quotes. For example, ?filter=description lk "%mount point%".

Example 1 - Filtering response data using the eq comparator

The following request returns the alert resource instances with severity equal to 3.

Header

Accept: application/json

Request

GET https://10.108.53.216/api/types/alert/instances?fields=severity,component,message,resolution,resource&filter=severity eq 3&compact=true

Response

{
  "@base": "https://10.108.53.216/api/types/alert/instances?filter=severity eq 3&fields=severity,component,message,resolution,id&per_page=2000&compact=true",
  "updated": "2015-10-28T13:01:50.054Z",
  "links": [
    {
      "rel": "self",
      "href": "&page=1"
    }
  ],
  "entries": [
    {
      "content": {
        "id": "alert_4",
        "severity": 3,
        "component": {
          "id": "nas_4",
          "resource": "nasServer"
        },
        "message": "All DNS servers configured for DNS client of NAS server DHWindows2 are not reachable.",
        "resolution": "0"
      }
    },
    {
      "content": {
        "id": "alert_7",
        "severity": 3,
        "component": {
          "id": "nas_6",
          "resource": "nasServer"
        },
        "message": "All LDAP servers configured for LDAP client of NAS server DHWindows3 are not reachable.",
        "resolution": "0"
      }
    }
  ]
}

Example 2 - Filtering response data using the lk comparator

The following request returns user instances with names that start with the string "userA".

Header

Accept: application/json

Request

GET https://10.108.53.216/api/types/user/instances?fields=name,role &filter=name lk \"userA%\"&compact=true

Response

{
  "@base": "https://10.108.53.216/api/types/user/instances?fields=name,id,role.id&per_page=2000&compact=true",
  "updated": "2015-10-28T13:15:20.183Z",
  "links": [
    {
      "rel": "self",
      "href": "&page=1"
    }
  ],
  "entries": [
    {
      "content": {
        "id": "user_admin",
        "name": "admin",
        "role": {
          "id": "administrator"
        }
      }
    }
  ]
}

Example 2 - Filtering response data using a conditional expression

The following example returns user information for users whose role is "admin":

Header

Accept: application/json

Request

GET https://10.108.53.216/api/types/user/instances?fields=name,role&filter=role.id lk "admin%25"&compact=true

Response

{
  "@base": "https://10.108.53.216/api/types/user/instances?filter=role.id lk \"admin%\"&fields=name,id,role.id&per_page=2000&compact=true",
  "updated": "2015-10-28T13:17:50.371Z",
  "links": [
    {
      "rel": "self",
      "href": "&page=1"
    }
  ],
  "entries": [
    {
      "content": {
        "id": "user_admin",
        "name": "admin",
        "role": {
          "id": "administrator"
        }
      }
    }
  ]
}

Welcome

Welcome to Dell

Dell Unity™ Family Unisphere® Management REST API Programmer's Guide

Filtering response data

Syntax

Filter expressions that apply to all base types

Filter expressions that apply only to strings

Example 1 - Filtering response data using the eq comparator

Example 2 - Filtering response data using the lk comparator

Example 2 - Filtering response data using a conditional expression

Rate this content