Run 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
qquery 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-formFor example, using the GET method with the following request returns the search operators and expressions allowed for accounts:
https://mysite.example.com/services/rest/connect/v1.4/accounts-search-formSearch 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-formRequest URI example
For example, to retrieve the search form for the accounts resource, use the following GET request:
https://mysite.example.com/services/rest/connect/v1.4/accounts-search-formNote:
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/accounts-search-form"
},
{
"rel": "search",
"href": "https://mysite.example.com/services/rest/connect/v1.4/accounts"
}
]
}ROQL Object Query Example
Using GET with following query:
https://mysite.example.com/services/rest/connect/v1.4/accounts?q=id>10 and id<15returns the following list of accounts:
{
"items": [
{
"id": 11,
"lookupName": "John Jergenson",
"links": [
{
"rel": "canonical",
"href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/11"
}
]
},
{
"id": 12,
"lookupName": "Matthew Gold",
"links": [
{
"rel": "canonical",
"href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/12"
}
]
},
{
"id": 14,
"lookupName": "JR Sanchez",
"links": [
{
"rel": "canonical",
"href": "https://mysite.example.com/services/rest/connect/v1.4/accounts/14"
}
]
}
],
"hasMore": false,
"links": [
{
"rel": "canonical",
"href": "https://mysite.example.com/services/rest/connect/v1.4/accounts"
},
{
"rel": "describedby",
"href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts",
"mediaType": "application/schema+json"
},
{
"rel": "search-form",
"href": "https://mysite.example.com/services/rest/connect/v1.4/accounts-search-form"
},
{
"rel": "self",
"href": "https://mysite.example.com/services/rest/connect/v1.4/accounts?q=id%3E10%20and%20id%3C15"
}
]
}