Query parameters and operators

To fetch a resource whose unique ID is known, you can supply the ID of the resource as part of the URI path. You can also use query parameters to filter and fetch resource collections.

In a resource collection, the representation has a pointer to the unique ID of each resource. The ID is used by the consuming software to create the link to the resource. The link is used to update, delete, and query the resource.

A RESTful interaction often begins by fetching a resource collection and then drilling down to a particular resource in the collection.

You can use any field of a business object resource or a related business object resource as a query parameter. The business object query by example (QBE) framework restricts the relationship between the business objects to one level deep. Any field of an object structure resource can be used as a query parameter if the field belongs to an object that resides in the top two levels of the object structure.

If you use a business object attribute as a query parameter, the following operators can be used as part of the parameter.

Operator	Notation	Example
Equals	`~eq~`	`status=~eq~APPR` Use the equals operator to perform an exact match. A `status=APPR` query implies a like operator comparison. If you use `status=APPR&_exactmatch=1`, the processor is forced to do an exact match. This notation produces the same result as `status=~eq~APPR`.
Not equals	`~neq~`	`status=~neq~APPR`
Greater than	`~gt~`	`quantity=~gt~2.5`
Greater than equals	`~gteq~`	`quantity=~gteq~2.5`
Less than	`~lt~`	`quantity=~lt~2.5`
Less than equals	`~lteq~`	`quantity=~lteq~2.5`
Ends with	`~ew~`	`description=~ew~APPR`
Starts with	`~sw~`	`description=~sw~APPR`
Like	No notation required	`description=APPR`

Example: Querying by location

The following example queries for a location by using the location number as a query parameter without an operator:

GET maxrest/rest/mbo/locations?location=PT100

The following XML is returned by the query:

<?xml version="1.0" encoding="UTF-8" ?> 
  <LOCATIONSMboSet rsStart="0" rsTotal="2" rsCount="2" 
    xmlns="http://www.ibm.com/maximo" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <LOCATIONS>
      <LOCATION>PT100</LOCATION> 
      <DESCRIPTION>PT100</DESCRIPTION> 
      .
      .
    </LOCATIONS>
    <LOCATIONS>
      <LOCATION>PT1001</LOCATION> 
      <DESCRIPTION>1001</DESCRIPTION> 
      .
      .
    </LOCATIONS>
  </LOCATIONSMboSet>

Because no operator is specified, a like comparison is used, and the result has two locations. If the request uses the equals operator, only location PT100 is returned for the query request, because the operator enforces an exact match:

GET /maxrest/rest/mbo/locations?location=~eq~PT100

Example: Using multiple parameters

The following example shows the use of multiple parameters to query for an Issue YTD quantity that is greater than 1 and an order quantity that is greater than 5:

GET /maxrest/rest/mbo/inventory?issueytd=~gt~1&orderqty=~gt~5

Example: Using the ormode condition

You can request multiple values for a single field by using the ormode condition. The following example selects records where the issue YTD quantity is equal to 7 or less than 4:

GET /maxrest/rest/mbo/inventory?issueytd.ormode=~eq~7&issueytd.ormode=~lt~4

Example: No records selected

If a query request results in no records being selected, an empty result set (not an exception condition) is returned.

For example, the following request is for records that have an Issue YTD quantity of 99:

GET /maxrest/rest/mbo/inventory?issueytd=~eq~99

No records are selected as a result of the request, and therefore the following empty result is returned:

<?xml version="1.0" encoding="UTF-8" ?> 
  <INVENTORYMboSet rsStart="0" rsTotal="0" rsCount="0" 
    xmlns="http://www.ibm.com/maximo" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />