One way to query your New Relic data is with the New Relic Query Language (NRQL). This document will introduce you to what NRQL is, why you'd use it, and basic syntax rules.
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:
- Advanced mode is a NRQL query interface
- Basic mode provides a simplified query experience that doesn't require knowledge of NRQL but that uses NRQL to generate results
- New Relic Insights
- 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:
- Metric timeslice data (metrics reported by New Relic APM, Browser, and Mobile)
Metricdata type (metrics reported by the Metric API and data sources that use that API)
Spandata type (distributed tracing data)
Logdata type (data from New Relic Logs)
Some data, like relationships between monitored entities, is not available via NRQL but is available using our NerdGraph API.
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:
To explore your data without having to use NRQL, use the basic mode of New Relic One query builder.
NRQL query examples
Here's an example NRQL query of
Transaction data, which is reported by New Relic APM.
FROM Transaction SELECT average(duration) FACET appName TIMESERIES auto
This would generate a chart that looks like:
Here are some more query examples:
- Basic NRQL query of Browser data
Here's a NRQL query of
PageViewdata, which is reported by New Relic Browser.
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
PageViewevents over the last week:
SELECT min(duration), max(duration), average(duration) FROM PageView SINCE 1 week ago
See more NRQL query examples.
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:
|Query string size||
The query string must be less than 4 KB.
|Syntax for strings||NRQL uses single quotes to designate strings. For example:
... where traceId = '030a573f0df02c57'
|Attribute names with spaces||
... 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
|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.