---
title: RoboQL Overview
sidebar:
  order: 50
---
RoboQL is a query language used to search all data elements in the Roboto platform. It enables users to write succinct and powerful queries for [datasets](/docs/learn/concepts#datasets-section), [files](/docs/learn/concepts#files-section), [topics](/docs/learn/concepts#topics-section), [message paths](/docs/learn/concepts#topics-section) and [events](/docs/learn/concepts#events-section). The syntax is easy to learn and succinct enough to be used in a search bar.

![Search log data in Roboto](/docs/blume-assets/content/docs/_static/roboql_overview.png)

## Writing Queries

A RoboQL query consists of conditions, an optional sort clause, and an optional limit clause. Additionally, each RoboQL query operates against a specific entity type, which can be `datasets`, `files`, `topics`, `message paths` or `events`. The entity type determines the fields that can be referenced in the query, and also which values are valid in a sort clause.

The most basic condition involves comparing a field to a value:

```
field = "value"
```

Besides quoted strings, a value can be a number or a Boolean literal — `true` or `false` (case-insensitive):

```
is_calibrated = true
```

Quoting makes a value a string, so `"true"` is the string "true" rather than the Boolean, and is not interchangeable with it.

Multiple conditions can be combined with logical operators `AND` / `OR`:

```
field1 = "value1" AND field2 > 100
```

Conditions can also be grouped with parentheses:

```
(field1 = "value1" AND field2 > 100) OR (field1 = "value2" AND field2 < 100)
```

To sort the results, use the `SORT BY` clause followed by the field name and direction (`ASC` for ascending, `DESC` for descending).

```
field1 = "value" SORT BY field2 ASC
```

To limit the number of results, use the `LIMIT` clause followed by the number of results to return. This generally only makes sense if a `SORT BY` clause is also used.

```
field1 = "value" SORT BY field2 DESC LIMIT 10
```

The literal `*` can be used to specify "no conditions", for queries like "get the 10 most recent datasets"

```
* SORT BY created DESC LIMIT 10
```

## Entity References

Entity references in RoboQL allow you to group multiple conditions that apply to the same entity. This is particularly useful for querying nested data structures and ensuring conditions are evaluated together.

When using entity references, each reference represents a specific instance of an entity. This allows you to construct complex queries that require multiple conditions to be true for the same entity. For example:

```
(files[0].relative_path CONTAINS ".png" AND files[0].size > 100000) AND
(files[1].relative_path CONTAINS ".jpg" AND files[1].size > 500000)
```

This query retrieves datasets that have both a PNG file larger than 100KB (`files[0]`) and a JPG file larger than 500KB (`files[1]`).

Alternatively, entity references can be strings for enhanced readability:

```
(files[png_file].relative_path CONTAINS ".png" AND files[png_file].size > 100000) AND
(files[jpg_file].relative_path CONTAINS ".jpg" AND files[jpg_file].size > 500000)
```

In this case, `png_file` and `jpg_file` are labels for file instances within the dataset, ensuring that conditions grouped under these labels apply to the same files.