Introduction to NRQL

One way to query your New Relic data is with the New Relic Query Language (NRQL). NRQL is a query language for making calls against the New Relic database, and is similar in format to SQL.

This document will introduce you to what NRQL is, why you'd use it, and basic syntax rules.

Want to watch an introductory video about NRQL? See the New Relic University tutorial Introduction to NRQL. Or, go directly to the full online course Writing NRQL queries.

What is NRQL?

NRQL is New Relic's SQL-like query language. You can use NRQL to retrieve detailed New Relic data and get insight into your applications, hosts, and business-important activity.

Reasons to use NRQL include:

  • To answer a question for the purpose of troubleshooting or business analysis
  • To create a new chart
  • To make API queries of New Relic data (for example, using our NerdGraph API)

Where can you use NRQL?

You can use NRQL in these places:

New Relic One NRQL query example
one.newrelic.com > Chart builder: You can run a NRQL query in both New Relic One and New Relic Insights. This NRQL query shows a count of distributed tracing spans faceted by their entity names.

NRQL is one of several ways to query New Relic data. For more on other query options, see Query your data.

What data can you query with NRQL?

Here are some of the data types you can query with NRQL:

The best way to understand the data you have available to you is to go into any NRQL UI interface, type FROM, and press space. The NRQL interface will suggest the types of data you can query, as shown here:

New Relic NRQL - find available data

To understand what attributes are available for a specific data type, type FROM DATA_TYPE SELECT and press space. The interface will suggest available attributes. For example:

New Relic NRQL - find available attributes

To see the JSON associated with a data type, including all of its attributes, use the keyset() attribute. For example:

FROM Transaction SELECT keyset()

NRQL syntax

The syntax of a NRQL query is similar to standard SQL queries. Here is a breakdown of the structure of a NRQL query:

SELECT function(attribute) [AS 'label'][, ...] 
  FROM data type
  [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]

Basic rules include:

NRQL condition Details
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.

Query string size

The query string must be less than 4 KB.

Case sensitivity
  • The data type names and attribute names are case sensitive.
  • NRQL clauses and functions are not case sensitive.
Syntax for strings NRQL uses single quotes to designate strings. For example:
... where traceId = '030a573f0df02c57'
Attribute names with spaces

Use backticks `` to quote a custom attribute name that has a space in it. For example:

... FACET `Logged-in user`
Data type coercion Insights does not support data type "coercion." For more information, see Data type conversion.
Use of math functions Basic and advanced math functions are supported in the SELECT statement.
JOIN functions NRQL does not have the equivalent of the SQL JOIN function, but you can simulate a JOIN with custom attributes.

Read more about NRQL syntax and functions.

NRQL query examples

Here are some NRQL query examples that will help you understand NRQL syntax:

Basic NRQL query
SELECT uniqueCount(user) FROM  PageView 
  WHERE userAgentOS = 'Mac' 
  FACET countryCode
  SINCE 1 day ago 
  LIMIT 20 
Attribute name with a space in it

If a custom attribute name has a space in it, use backticks around the attribute name:

SELECT count(*)
 FROM Transaction
 FACET `Logged-in user`
Querying multiple data sources
To return data from two data sources, separate their data types with a comma. For example, 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
Query returning multiple columns
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 New Relic Browser PageView events over the last week:

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

See more NRQL query examples.

For more help

Recommendations for learning more: