NRQL: New Relic Query Language, getting started

NRQL (New Relic Query Language) is a query language similar to ANSI SQL used to retrieve detailed New Relic data for insight into applications, hosts, and business-important activity. Teams use NRQL to create charts, answer troubleshooting questions, set up NRQL-based alerts, and query New Relic data via the NerdGraph API.

What is NRQL and what can I use it for?

NRQL is New Relic's purpose-built query language for analyzing metrics, events, logs, and traces stored in NRDB. It supports simple queries that fetch rows of raw tabular data on individual events, as well as powerful calculations such as funnels based on user interactions. New Relic uses NRQL behind the scenes to generate many of its curated UI charts and dashboards.

Common uses:

Create new charts and custom dashboards
Answer specific questions for troubleshooting or business analysis
Set up NRQL-based alerts — New Relic's primary and most powerful alert type
Make API queries via NerdGraph

What clauses does NRQL support and in what order?

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]

SELECT and FROM are required. All other clauses are optional. A query can start with either SELECT or FROM.

What are the NRQL rules?

Rule	Details
Required clauses	`SELECT` and `FROM` are required; all others are optional
Query string size	Must be less than 4 KB
Case sensitivity	Data type names and attribute names are case sensitive. NRQL clause keywords and functions are not.
String syntax	Use single quotes for strings: `WHERE traceId = '030a573f0df02c57'`
Non-standard names	Custom event or attribute names that do not follow default naming must be enclosed in backticks: FACET `Logged-in user`
Data type coercion	Not supported

How do I write a query for average transaction duration, faceted by app?

SELECT average(duration) FROM Transaction
FACET appName
SINCE 1 day ago

SELECT average(duration) FROM Transaction
FACET appName
SINCE 1 day ago

This selects the average duration attribute from the Transaction event type, groups results by appName, and limits the time range to the past 24 hours.

How do I escape a reserved keyword or attribute name with spaces?

Enclose the attribute name in backticks:

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

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

Standard alphanumeric attribute names do not require backticks. Only custom names with spaces, hyphens, or other non-standard characters need them.

Where does NRQL run?

Query builder: accessible via "Query your data" at the bottom of any New Relic page, for running queries and creating custom charts
NRQL-based alerts: at one.newrelic.com under Alerts > Alert conditions (Policies)
NerdGraph API: running NRQL through NerdGraph enables cross-account querying and asynchronous queries

What data can I query with NRQL?

NRQL queries nearly every type of New Relic telemetry data:

Event data from all New Relic products: APM events like Transaction, browser events like PageView, mobile events like Mobile, infrastructure events like ProcessSample, synthetic events like SyntheticCheck, and custom events via the Event API
Metric timeslice data (metrics reported by APM)
The Metric data type (dimensional metrics from the Metric API)
The Span data type (distributed tracing data)
The Log data type (log management data)

Relationships between monitored entities are not available via NRQL but are available through the NerdGraph API.