Using ROQL Object Queries

You can use RightNow Object Query Language (ROQL) object queries to perform searches in the REST API.

This topic contains the following sections:

ROQL Object Queries

ROQL object queries have the following characteristics:

  • They use the q query parameter with ROQL syntax:
    https://your_site_interface/services/rest/connect/version/resource/?q=ROQL WHERE clause
  • They support logical operators, such as the following: AND, OR, NOT
  • They support all expressions in ROQL syntax, such as the following: =, !=, >, <, LIKE, IN

Note:

Operators and expressions aren't case sensitive. Operators must be separated by spaces from query terms.

To get a list of allowed search operators and expressions for a resource, retrieve the corresponding resource-search-form resource, which provides all search-related metadata:

https://your_site_interface/services/rest/connect/version/resource-search-form

For example, using the GET method with the following request returns the search operators and expressions allowed for incidents:

https://mysite.example.com/services/rest/connect/v1.4/incidents-search-form

Search Syntax for ROQL Object Queries

To retrieve the search syntax for the q query parameter, use a GET request with the following syntax:

https://your_site_interface/services/rest/connect/version/resource-search-form

Request URI example

For example, to retrieve the search form for the incidents resource, use the following GET request:

https://mysite.example.com/services/rest/connect/v1.4/incidents-search-form

Note:

The search form is the same for any collection resource. The search form doesn't work with special resources such as queryResults.

Response body example

{
  "title": "Search Form",
  "description": "Describe the metadata for query parameter 'q' syntax .",
  "syntax": {
    "operators": {
      "eq": {
        "code": [
          "="
        ],
        "types": [
          "string",
          "integer",
          "boolean"
        ],
        "description": "equal",
        "example": "age=18"
      },
      "ne": {
        "code": [
          "!="
        ],
        "types": [
          "string",
          "integer",
          "boolean"
        ],
        "description": "not equal",
        "example": "age!=18"
      },
      "gt": {
        "code": [
          ">"
        ],
        "types": [
          "string",
          "integer",
          "boolean"
        ],
        "description": "greater than",
        "example": "age>18"
      },
      "lt": {
        "code": [
          "<"
        ],
        "types": [
          "string",
          "integer",
          "boolean"
        ],
        "description": "less than",
        "example": "age<18"
      },
      "ge": {
        "code": [
          ">="
        ],
        "types": [
          "string",
          "integer",
          "boolean"
        ],
        "description": "greater than or equal to",
        "example": "age>=18"
      },
      "le": {
        "code": [
          "<="
        ],
        "types": [
          "string",
          "integer",
          "boolean"
        ],
        "description": "less than or equal to",
        "example": "age<=18"
      },
      "like": {
        "code": [
          "LIKE"
        ],
        "types": [
          "string"
        ],
        "description": "like",
        "wildcard": [
          "'%'",
          "'_'"
        ],
        "example": [
          "name LIKE 'ELIZABETH'",
          "name LIKE '%BETH'",
          "name LIKE 'ELIZ_BETH'"
        ]
      },
      "in": {
        "code": [
          "IN"
        ],
        "types": [
          "string",
          "integer",
          "boolean"
        ],
        "description": "In",
        "example": "name IN ('MT', 'CO')"
      },
      "not in": {
        "code": [
          "NOT IN"
        ],
        "types": [
          "string",
          "integer",
          "boolean"
        ],
        "description": "Not In",
        "example": "name NOT IN ('MT', 'CO')"
      },
      "null": {
        "code": [
          "IS NULL"
        ],
        "types": [
          "string",
          "integer",
          "boolean"
        ],
        "description": "Is Null",
        "example": "name IS NULL"
      },
      "not null": {
        "code": [
          "IS NOT NULL"
        ],
        "types": [
          "string",
          "integer",
          "boolean"
        ],
        "description": "Is Not Null",
        "example": "name IS NOT NULL"
      }
    },
    "logicalOperators": {
      "not": {
        "code": [
          "NOT"
        ],
        "description": "logical not",
        "example": "NOT ID=18"
      },
      "or": {
        "code": [
          "OR"
        ],
        "description": "logical or",
        "example": "age>18 OR name='Alice'"
      },
      "and": {
        "code": [
          "AND"
        ],
        "description": "logical and",
        "example": "age>18 AND name='Alice'"
      }
    },
    "precedenceGrouping": "()"
  },
  "links": [
    {
      "rel": "self",
      "href": "https://mysite.example.com/services/rest/connect/v1.4/incidents-search-form"
    },
    {
      "rel": "search",
      "href": "https://mysite.example.com/services/rest/connect/v1.4/incidents"
    }
  ]
}

ROQL Object Query Example

Using GET with following query:

https://mysite.example.com/services/rest/connect/v1.4/incidents?q=id>10 and id<15

returns the following list of incidents:

{
    "items": [
    {
        "id": 11,
        "lookupName": "100909-000012",
        "createdTime": "2015-08-21T21:48:52Z",
        "updatedTime": "2015-08-21T21:48:52Z",
        "links": [
            {
            "rel": "canonical",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/incidents/11"
            }
        ]
    },
    {
        "id": 12,
        "lookupName": "100910-000001",
        "createdTime": "2015-08-22T17:31:54Z",
        "updatedTime": "2015-08-22T17:32:24Z",
        "links": [
            {
            "rel": "canonical",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/incidents/12"
            }
        ]
    },
    {
        "id": 13,
        "lookupName": "100910-000000",
        "createdTime": "2015-08-22T17:34:29Z",
        "updatedTime": "2015-08-22T17:34:29Z",
        "links": [
            {
            "rel": "canonical",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/incidents/13"
            }
        ]
    },
    {
        "id": 14,
        "lookupName": "100910-000002",
        "createdTime": "2015-08-22T17:35:52Z",
        "updatedTime": "2015-08-22T17:35:52Z",
        "links": [
            {
            "rel": "canonical",
            "href": "https://mysite.example.com/services/rest/connect/v1.4/incidents/14"
            }
        ]
    }
    ],
    "links": [
    ...
    ]
}