Get started with NRQL

The New Relic Query Language (NRQL) is an SQL-flavored query language for making calls against an event database. This document explains how to use NRQL to pull data from the events database and organize it to view on your dashboard.

NRQL tutorial

New Relic Query Language (NRQL) enables you to query data collected from your application and transform that data into dynamic charts. From there, you can interpret your data to better understand how your application is used in a variety of ways. If you are new to New Relic Insights or don't know much about query languages, this tutorial will give you a quick overview of NRQL query syntax and composition, along with some real examples.


[video link] To learn more about NRQL syntax and composition, including examples, watch this video (approximately 10 minutes). View more videos and tutorials at

Use the query tool

Insights > (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 history 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.

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:

  • The SELECT statement and FROM clause are required (all other clauses are optional).

  • Attribute names are case sensitive. NRQL clauses and functions are not case sensitive.

  • NRQL uses single quotes '' to designate strings.

  • You must use backticks `` to quote a custom attribute name with a space in it (for example: `Logged-in user`).

  • Insights does not support "duck typing." This means that a float stored as a string is treated as a string and cannot be operated on by functions expecting float values.

  • Insights does not have the equivalent of the SQL JOIN function, but you can simulate a JOIN with custom attributes.

Basic NRQL query
SELECT uniqueCount(user) 
 FROM  PageView 
 WHERE userAgentOS = 'Mac' 
 FACET countryCode
 SINCE 1 day ago 
 LIMIT 20 
NRQL query on attribute with space in name
SELECT count(*) 
 FROM Transaction 
 FACET `Logged-in user`
Query multiple events or columns

Use a comma (,) to merge data from two event types or to return multiple columns from a dataset. To return multiple event types, join the types with a comma:

  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

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

Send custom data to Insights

Adding a high number of custom attributes and events may cause degraded query performance and run up against insertion rate limits for events. For optimal performance, first think about what data you want to analyze, and then create only the custom attributes required for the events.

Source How to send custom data
APM agent Use agent API to send custom events and custom attributes
Browser agent

Send PageAction event and attributes via javascript API.

Forward APM agent custom attributes to PageView event.

Insights API Insert custom events and custom attributes with the Insights API.
Mobile agent Use mobile agent API to send custom events and custom attributes

NRQL examples

You can use NRQL to query your data several ways. NRQL can query the application data collected by New Relic APM, New Relic Browser, and New Relic Mobile. You can then use this data to answer a variety of questions. For example:

Unique users: How many unique user sessions did you have in the last week?
SELECT uniqueCount(session) FROM PageView SINCE 1 week ago
SELECT uniqueCount(session) FROM PageView SINCE 1 week ago COMPARE WITH 1 week ago
Pageview trend graphs: How can I graph the number of unique users yesterday compared with the day before?
SELECT count(*) FROM PageView SINCE 1 day ago COMPARE WITH 1 day ago TIMESERIES AUTO
OS version: How many of your mobile users are on the latest OS version?
SELECT uniqueCount(uuid) FROM MobileSession FACET osVersion SINCE 7 days ago
Key account Apdex: Monitor Apdex score for particularly important customer

If you have defined some custom attributes you can query Insights like this to keep an eye on how this customer experiences your app from a performance standpoint:

SELECT apdex(duration, t: 0.4) FROM Transaction WHERE customerName='MrBigshot' SINCE 1 day ago

For assistance with New Relic Insights, join us in the New Relic Online Technical Community. Ask and answer questions, and learn more about New Relic Insights from fellow Insights users.

If you need additional help, get support at