> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blinkops.com/llms.txt
> Use this file to discover all available pages before exploring further.

# RQL

> Learn how to use Blink's Resource Query Language (RQL) to filter and query resources across your workspace.

## 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).

<Note>
  **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](/docs/api/case-management-list-records.api.mdx)
</Note>

### `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

```json theme={"dark"}
{
  "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.

```json theme={"dark"}
{
  "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.

```json theme={"dark"}
{
  "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:

```json theme={"dark"}
{
  "filter": {
    "$or": [{ "severity": "high" }, { "severity": "critical" }]
  }
}
```

* If the field follows the format: `field: { <predicate>: <value>, ...}`, For example:

```json theme={"dark"}
{
  "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:

```json theme={"dark"}
{
  "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 descending order:

```json theme={"dark"}
{
  "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.

```json theme={"dark"}
{
  "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`:

  * `$contains_any`: Specifies that the "case\_manager" field must contain at least one of the specified values ("[johndoe@gmail.com](mailto:johndoe@gmail.com)" or "[janedoe@gmail.com](mailto:janedoe@gmail.com)").

* `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".