Introduction to NRQL, New Relic's query language

One way to query your New Relic data is with the New Relic Query Language (NRQL). This resource explains what NRQL is, when and how you can use it, and basic syntax rules. For more detailed information on querying, including a listing of clauses and functions and example queries, see NRQL syntax, clauses, and functions.

We've included a NRQL Lessons application on our opensource.newrelic.com site to help you quickly see NRQL's value and power by using your own data. To learn how to install and use the NRQL Lessons app, watch this short YouTube video (approx. 2:45 minutes).

Ready to get started? If you haven't already, be sure to sign up for a New Relic account. It's free, forever.

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)

NRQL is used behind the scenes to generate some New Relic charts:

Where can you use NRQL?

You can use NRQL in these places:

• New Relic One query builder
• NerdGraph: our GraphQL-format API, which includes options for making NRQL queries

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

What data can you query with NRQL?

NRQL allows you to query these New Relic data types:

• Event data from all New Relic products, including:
  • APM events, like Transaction
  • Browser monitoring events, like PageView
  • Mobile monitoring events, like Mobile
  • Infrastructure events, like ProcessSample
  • Synthetics events, like SyntheticCheck
  • Custom events, like those reported by the Event API
• Metric timeslice data (metrics reported by APM, browser, and mobile)
• The Metric data type (metrics reported by the Metric API and data sources that use that API)
• The Span data type (distributed tracing data)
• The Log data type (data from New Relic's log management capabilities)

Start using NRQL

One way to start using NRQL and to understand what data you have available is to go to a NRQL interface (for example, the New Relic One query builder), type FROM, and press space. The interface will suggest available types of data:

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

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

FROM Transaction SELECT keyset()

NRQL is used behind the scenes to build some New Relic charts and dashboards. One way to learn NRQL is to find one of these NRQL-generated charts and start playing with the NRQL to create new, customized queries and charts:

NRQL query examples

Here's an example NRQL query of Transaction data, which is reported by APM.

FROM Transaction SELECT average(duration) 
  FACET appName TIMESERIES auto

This would generate a chart that looks like:

Here are some more query examples:

SELECT uniqueCount(user) FROM PageView 
  WHERE userAgentOS = 'Mac' 
  FACET countryCode
  SINCE 1 day ago 
  LIMIT 20

SELECT count(*)
 FROM Transaction
 FACET `Logged-in user`

SELECT count(*) FROM Transaction, PageView SINCE 3 days ago

SELECT function(attribute), function(attribute) ...
  FROM ...

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

See more NRQL query examples.

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:

... where traceId = '030a573f0df02c57'

... FACET `Logged-in user`

Read more about NRQL syntax and functions.