Important: RQL is a work in progress. While it's generally stable, expect bugs at the corners.
RQL ("Rollbar Query Language") is an attempt at exposing a rich querying interface to the data in Rollbar. Its goal is to be SQL-like, so it should be familiar to SQL users.
This first release allows running
SELECTs on two logical tables,
deploy. Basic GROUP BY, ORDER BY, LIMIT, and
aggregation functions all work, as do arbitrary expressions in the WHERE
clause. No DISTINCT, HAVING, subqueries, or joins yet.
Simple-ish queries are supported. SELECT, FROM, and WHERE are required. GROUP BY, ORDER BY, and LIMIT are optional.
SELECT * *may* be used (as long as there is no GROUP BY). It will
return a list of columns similar to the Occurrences tab on Item Detail
SQL keywords and built-in function names are case-insensitive (i.e.
select are both fine).
Names (i.e. column names) should start with a lowercase letter and may
contain letters, numbers, and periods (for specifying a JSON path). If
you need any other characters (i.e. a hyphen, or to start with an
uppercase letter), escape with backticks (i.e.
count(*): counts all rows
count(foo): counts rows where foo is not null
sum(foo): sums value of foo (for rows where not null)
avg(foo): average value of foo (for rows where not null)
min(foo): minimum value of foo
max(foo): maximum value of foo
unix_timestamp(): returns the current Unix timestamp, as an integer
concat(str1, str2, ...): returns the string resulting from concatenating all arguments
concat_ws(sep, str1, str2, ...): returns the string resulting from concatenating the second argument and beyond, separated by the first argument
lower(str): converts str to lowercase
upper(str): converts str to uppercase
left(str, len): returns the len leftmost characters of str
right(str, len): returns the len rightmost characters of str
substring(str, pos): returns the substring from str starting at pos (all characters from pos until the end)
substring(str, pos, len): returns a substring from str starting at pos, at most len characters
locate(substr, str): returns the position of the first occurrence of substr in str. (1-indexed)
locate(substr, str, pos): returns the position of the first occurrence of substr in str, starting the search at position pos
char_length(str): returns the length of str in characters
length(str): returns the length of str in bytes
SELECT request.user_ip, min(timestamp), max(timestamp), count(*) FROM item_occurrence WHERE item.counter = 47 GROUP BY request.user_ip ORDER BY count(*) DESC LIMIT 10
SELECT timestamp, body.message.body FROM item_occurrence WHERE item.counter BETWEEN 40 AND 50
SELECT * FROM item_occurrence WHERE item.counter IN (1,2,3)
SELECT * FROM item_occurrenceto get a display similar to the Occurrences tab
- For better performance, filter by item (i.e.
WHERE item.counter = 123) or by timestamp (i.e.
WHERE timestamp > unix_timestamp() - 86400)
- When using GROUP BY or ORDER BY, make sure the group/order clause is also present in the SELECT clause
- You can share the URL with a co-worker and they'll see the same results you do, without having to run the query again.
- After a query has completed, press Execute again to re-run it.
- At most 1000 rows will be returned per query (though any number of rows may be examined)
HAVING, subqueries, joins, or unions
SELECT *cannot be combined with
- Can only be used to examine data within a single project
item_occurrence is a table where each row contains data for a single
occurrence and the item it is associated with. Column names starting with "item."
reference the item, and all other column names reference the occurrence.
Column names that do not exist in a particular occurrence evaluate to NULL.
The following columns exist for every row in
||System-wide Item ID|
||Project-wide Item ID|
||Computed fingerprint of the item (controls grouping)|
||ID of the first occurrence|
||Timestamp of the first occurrence|
||ID of the first occurrence since the item was last resolved|
||Timestamp the item was last activated|
||Timestamp the item was last resolved|
||Timestamp the item was last muted|
||ID of the most recent occurrence|
||Timestamp of the most recent occurrence|
||ID of the user who last modified this item|
||Item level (50=critical, 40=error, 30=warning, 20=info, 10=debug)|
||The revision the item was last marked as resolved in|
||Status (as an integer: 1=active, 2=resolved, 3=muted)|
||The number of occurrences since the last time this item was resolved|
||System-wide Occurrence ID|
||Timestamp of the occurrence, as a Unix timestamp|
Many virtual columns will usually exist as well, depending on what notifier you are using and what custom data you are sending. Simply use the JSON path to the field you want to query. To see the JSON structure of one of your occurrences, click the "Raw JSON" button on an Occurrence page. The structure will follow the Rollbar API Item Schema.
Here are some common column names, all of which refer to data for the occurrence:
||The raw crash report (if the occurrence is a crash report)|
||The primary message text (if the occurrence is a message)|
||Any arbitrary keys of metadata you sent (if the occurrence is a message)|
||The exception class name (if the occurrence is a single exception)|
||The exception message (if the occurrence is a single exception)|
||The first exception class (if the occurrence is a list of nested exceptions)|
||The first exception message (if the occurrence is a list of nested exceptions)|
||Raw user agent string (from rollbar.js)|
||Whether or not source map deobfuscation is enabled|
||Whether or not frame guessing is enabled|
||How long the page was open before the event occurred (rollbar.js)|
||The version of the application code|
||An identifier for which part of your application the error came from|
||Arbitrary metadata you sent|
||Nested arbitrary metadata you sent|
||The name of the reported language for the event|
||Name of the library that sent the item|
||The version string of the library that sent the item|
||A string identifying the user in your system|
||A username string|
||An email string|
||Full URL where the error occurred|
||The request method|
||Object containing the request headers|
||Any routing parameters|
||Query string parameters|
||The raw query string|
||The raw POST body|
||The end user's IP address as a string|
||The server hostname|
||Path to the application code root|
||Name of the checked-out source control branch|
||String describing the running code version on the server|
||A string that uniquely identifies the occurrence. See UUIDs|
deploy is a table where each row represents a single deploy. It has
the following columns:
||Rollbar user_id of the rollbar_username recorded for the deploy|
||Name of the deployed environment|
||Revision (i.e. git sha or version number) deployed|
||Local username recorded for the deploy|
||The deploy comment|
||Timestamp when the deploy was recorded|
- "DISTINCT", "HAVING"
- More performance optimizations
- More functions
- Better progress indicators
- Saved searches
- More visualization options (i.e. bar graphs, line graphs, etc.)
- Download results as CSV/JSON dump (with support for large resultsets)
- More data tables
- An aggregation query that does not match any rows will return no results at all, instead of a row indicating that zero rows were found.
item.framework property is an integer value which maps as follows:
'unknown': 0, 'rails': 1, 'django': 2, 'pyramid': 3, 'node-js': 4, 'pylons': 5, 'php': 6, 'browser-js': 7, 'rollbar-system': 8, # system messages, like "over rate limit" 'android': 9, 'ios': 10, 'mailgun': 11, 'logentries': 12, 'python': 13, 'ruby': 14, 'sidekiq': 15, 'flask': 16, 'celery': 17, 'rq': 18,
item.platform property is an integer value which maps as follows:
'unknown': 0, 'browser': 1, 'flash': 2, 'android': 3, 'ios': 4, 'heroku': 5, 'google-app-engine': 6, 'client': 7,