Introduction to NRQL

The New Relic Query Language (NRQL), similar to SQL, is a query language for making calls against the Insights event database. NRQL enables you to query data collected from your application, host, or other entity and transform that data into dynamic charts. From there, you can interpret your data to better understand your systems, application, and business.

Use the query tool

crop-nrql-command-line
insights.newrelic.com > (run a query): After running an Insights query, make any necessary adjustments to get the result you want, or add it to a dashboard by using the Add to this dashboard and Add to buttons.

The command line query tool appears at the top of your dashboards and the Query page. Use it to build out commands with SQL-style syntax. As you type, the auto-completion feature suggests attributes, and it flags syntax errors with a red underline. For more information about NRQL syntax, see NRQL reference.

If your company uses multiple New Relic accounts across your teams, you can select the source account from the account switcher in the query tool to query the source account's data.

The parser can identify syntax errors, but logic errors will normally not be apparent until you try to execute the statement. If the statement cannot be run, an error report will indicate the location of the first identified error. New Relic Insights also ignores NULL results entirely, unless your query explicitly requests NULL results.

NRQL syntax

    SELECT function(attribute) [AS 'label'][, ...] 
     FROM event
     [WHERE attribute [comparison] [AND|OR ...]][AS 'label'][, ...]
     [FACET attribute | function(attribute)]
     [LIMIT number]
     [SINCE time]
     [UNTIL time]
     [WITH TIMEZONE timezone]
     [COMPARE WITH time]
     [TIMESERIES time]

New Relic refers to NRQL statements as event queries. The syntax of the NRQL event query is similar to standard SQL queries. Basic syntax rules include:

NRQL syntax Comments
Required values

The SELECT statement and FROM clause are required. All other clauses are optional. You can start your query with either SELECT or FROM.

  • If you start your query with SELECT, you can select from PageView event type attributes that automatically display.
  • If you start your query with FROM, you can select an event type and then add the SELECT clause to select attributes from that event type.
Case sensitivity
Strings NRQL uses single quotes '' to designate strings.
Spaces

You must use backticks `` to quote a custom attribute name with a space in it; for example, `Logged-in user`.

Float values Insights does not support "coercion." This means that a float stored as a string is treated as a string and cannot be operated on by functions expecting float values.
Math functions Basic and advanced math functions are supported in the SELECT statement.
JOIN functions Insights does not have the equivalent of the SQL JOIN function, but you can simulate a JOIN with custom attributes.

NRQL query examples

Basic NRQL query example
SELECT uniqueCount(user) 
 FROM  PageView 
 WHERE userAgentOS = 'Mac' 
 FACET countryCode
 SINCE 1 day ago 
 LIMIT 20 
NRQL query example of attribute with space in name
SELECT count(*)
 FROM Transaction
 FACET `Logged-in user`
Multiple events query examples
To return data from two event types, separate the event types with a comma:
SELECT ...
  FROM event, event
  ...

This query returns a count of all APM transactions and Browser events over the last three days:

SELECT count(*) FROM Transaction, PageView SINCE 3 days ago
Multiple columns query examples
To return multiple columns from a dataset, separate the aggregator arguments with a comma:
SELECT function(attribute), function(attribute) ...
  FROM ...

This query returns the minimum, average, and maximum duration for Browser events over the last week:

SELECT min(duration), max(duration), average(duration)
  FROM PageView SINCE 1 week ago

NRQL in Insights API queries

NRQL is also used with the Insights API to make remote queries of your data. When used in an API request, follow the formatting requirements to create your NRQL query.

For more help

Recommendations for learning more: