Skip to main content

RQL

What is RQL?​

Many of the Blink API endpoints support the use of Resource Query Language (RQL) syntax to select and sort records or filter results.

RQL Syntax Format​

An RQL query is a JSON object that can contain the following fields: offset, limit, filter and sort (all of them are optional).

info

The following RQL syntax examples based on the Blink API for listing records from the Case Management Table. List Records from Case Management Table

offset and limit​

These two fields are useful for paging and they are equivalent to OFFSET and LIMIT in a standard SQL syntax.

  • limit must be greater than 0 and less than or equal to 1000
  • offset must be greater than or equal to 0 and its default value is 0

offset and limit example​

{
  "limit": 30, // returns only the first 30 records (max is 1000).
  "offset": 0 // the offset from where to return the data.
}

sort​

Sort accepts a list of strings ([]string) that is equivalent to the SQL ORDER BY clause. The default order for a column is ascending order, but you can control the order by using the following prefix: + or -. + means ascending order, and - means descending order.

sort example​

This query is sorting results of the updated_at column in a Case Management Table in ascending order as there is a + before the updated_at field value.

{
  "sort": ["+updated_at"]
}

select​

Select accepts a list of strings ([]string) that is joined with a comma (",") to the RQL SELECT clause.

select Example:​

This query will retrieve only the id, name, and status fields for each record from your case management table.

{
  "select": ["id", "name", "status"]
}

filter​

Filter works like the SQL WHERE clause. The $or operator is used to combine multiple conditions, requiring that at least one of the specified conditions must be true for a record to match. Its type is an array of condition objects.

filter Example:​

{
  "filter": {
    "$or": [{ "severity": "high" }, { "severity": "critical" }]
  }
}
  • If the field follows the format: field: { <predicate>: <value>, ...}, For example:
{
  "created_at": {
    "$gt": "2018-01-01T16:00:00.000Z",
    "$lt": "2018-06-01T16:00:00.000Z"
  }
}

It means that the logical AND operator is used between the two predicates. Its type is an object of conditions.

predicates​

RQL supports various predicates for filtering:

  • $eq: Equals (can be used on all types)
  • $neq: Not equals (can be used on all types)
  • $gt: Greater than (can be used on numbers, strings, and timestamp)
  • $lt: Less than (can be used on numbers, strings, and timestamp)
  • $gte: Greater than or equal to (can be used on numbers, strings, and timestamp)
  • $lte: Less than or equal to (can be used on numbers, strings, and timestamp)
  • $like: Like (can be used only on type string)

More Examples:​

Example One​

A basic query to fetch records from a Case Table with a low status:

{
  "limit": 25,
  "offset": 0,
  "filter": {
    "severity": "low"
  }
}

Example Two​

A more complex query that filters records from a Case Table based on creation date, severity status, and sorts the results according to the date the case was created in decending order:

{
  "limit": 25,
  "filter": {
    "case_type": {
      "$eq": "cloud security"
    },
    "created_at": {
      "$gt": "2018-01-01T16:00:00.000Z",
      "$lt": "2018-04-01T16:00:00.000Z"
    },
    "$or": [{ "severity": "high" }, { "status": "open" }]
  },
  "sort": ["-created_at"]
}

A detailed explanation of the above RQL Query:

  • limit: Limits the number of records returned

    • 25: Specifies that the query should return a maximum of 25 records.

  • filter: The main object containing the filtering criteria.

    • case_type:
    • %eq: Filters records where the "case_type" field is "Cloud Security".

  • created_at

    • $gt: Specifies that the created_at field must be greater than "2018-01-01T16:00:00.000Z".
    • $lt: Specifies that the created_at field must be less than "2018-04-01T16:00:00.000Z".

  • $or: Logical OR operator to combine multiple conditions.

    • severity:
      • "high" : Filters records where the severity field is "high".
    • status:
      • "open": Filters records where the status field is "open".

  • sort: Specifies the sorting order of the returned records.

    • ["-created_at"]: Sorts the records in descending order by the created_at field (the - sign indicates descending order).

Example Three​

This query filters the case management records to retrieve those that are open, have a severity status of critical, the case manager is either John Doe or Jane Doe, contain the word "urgent" in the case overview, and were created within the first 4 months of 2024.

{
  "filter": {
    "status": {
      "$eq": "open"
    },
    "severity": {
      "$eq": "medium"
    },
    "case_manager": {
      "$contains_any": ["johndoe@gmail.com", "janedoe@gmail.com"]
    },
    "overview": {
      "$like": "%urgent%"
    },
    "created_at": {
      "$gte": "2024-01-01T00:00:00Z",
      "$lt": "2024-04-31T23:59:59Z"
    }
  }
}

Detailed Explanation of the above RQL Query:

  • filter: The main object containing the filtering criteria

    • status:
    • $eq: Specifies that the status field must be equal to "open".

  • priority:

    • $gt: Specifies that the priority field must be greater than 2.

  • case_manager:

  • overview:

    • $like: Specifies that the overview field must match the pattern "%urgent%", meaning it should contain the word "urgent" anywhere within the overview text field.

  • created_at:

    • $gte: Specifies that the "created_at" field must be greater than or equal to "2024-01-01T00:00:00Z".
    • $lt: Specifies that the created_at field must be less than "2024-04-31T23:59:59Z".