Skip to main content

RQL Queries

Mango uses Resource Query Language (RQL) for filtering and querying data through its REST API endpoints. RQL is a textual query syntax similar to SQL that describes a set of conditions items must match. It is used on all list endpoints to filter, sort, and paginate results.

This page is part of the Build Java Module for Mango series. See the full Module Development Overview for all articles.

RQL Syntax Overview​

RQL operators are passed as query string parameters on REST API URLs. You can combine multiple operators with & (logical AND) or wrap them in or() for logical OR. The general pattern is:

/rest/latest/<resource>?<operator>(<field>,<value>)&<operator>(<field>,<value>)

For example, to query devices where the model equals ABC and the protocol equals MODBUS:

/rest/latest/enmet-devices?eq(model,ABC)&eq(protocol,MODBUS)

Common RQL Operators​

OperatorExampleDescription
eqeq(name,Temperature)Equal to
nene(status,DISABLED)Not equal to
gtgt(value,100)Greater than
ltlt(value,50)Less than
gege(value,0)Greater than or equal
lele(value,100)Less than or equal
matchmatch(name,*Temp*)Wildcard match
inin(deviceName,Device1,Device2)In a set of values
limitlimit(10,20)Limit results (count, offset)
sortsort(name) or sort(-name)Sort ascending or descending
oror(eq(a,1),eq(a,2))Logical OR

Adding RQL Support to a Custom Endpoint​

To add RQL query support to a custom module endpoint, you need a controller method that parses the query string and executes the query against your service layer.

Add the following to your DeviceRestController:

@Api(value = "Energy Metering Devices")
@RestController()
@RequestMapping("/enmet-devices")
public class DeviceRestController {
    // ...existing code...

    @ApiOperation(
            value = "Query devices",
            notes = "Use RQL formatted query",
            response = DeviceModel.class,
            responseContainer = "List"
    )
    @RequestMapping(method = RequestMethod.GET)
    public StreamedArrayWithTotal queryRQL(HttpServletRequest request, @AuthenticationPrincipal User user) {
        ASTNode rql = RQLUtils.parseRQLtoAST(request.getQueryString());
        return this.doQuery(rql, user);
    }

    // ...existing code...

    protected StreamedArrayWithTotal doQuery(ASTNode rql, User user) {
        return new StreamedVORqlQueryWithTotal<>(
                this.service,
                rql,
                null,
                null,
                null,
                (item) -> this.mapping.map(item, user, mapper)
        );
    }
}

The RQLUtils.parseRQLtoAST() method parses the RQL query string into an ASTNode object representing the root node of an Abstract Syntax Tree (AST). The StreamedVORqlQueryWithTotal class executes the query against the service layer and returns a response in the standard envelope format:

{
    "items": [...],
    "total": 12
}

Testing RQL Queries​

You can write automated tests for RQL-enabled endpoints using Mocha. Add a test to your device.spec.js file:

it('should query devices with RQL', () => {
    const device = newDevice();

    return client.restRequest({
        path: '/rest/latest/enmet-devices',
        method: 'POST',
        data: device
    }).then(response => {
        assertDevice(response.data, device);

        return client.restRequest({
            path: `/rest/latest/enmet-devices?eq(xid,${device.xid})`,
            method: 'GET'
        }).then(response => {
            assert.equal(response.data.items.length, 1);
            assertDevice(response.data.items[0], device);
        });
    }).finally(() => {
        return client.restRequest({
            path: `/rest/latest/enmet-devices/${device.xid}`,
            method: 'DELETE'
        });
    });
});

This test creates a device, queries for it using the eq RQL operator to filter by XID, verifies that exactly one result is returned and the data matches, and then cleans up by deleting the device.

Further Reading​

For more details on how RQL is used with the built-in Mango endpoints, see the API Examples page. To learn more about RQL syntax, refer to the Oracle RQL documentation.