• /
  • Log in

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.

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:

New Relic view chart NRQL query

Some New Relic charts are built using NRQL. One way to start using NRQL is to view a chart's query and then edit it to make your own custom chart.

Where can you use NRQL?

You can use NRQL in these places:

nrql_example.png

one.newrelic.com > Query your data: You can run a NRQL query in New Relic One. 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 all query options, see Query your data.

What data can you query with NRQL?

NRQL allows you to query these New Relic data types:

Tip

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:

nrql_query01.png

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:

nrql_query02.png

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:

New Relic view chart NRQL query

Charts built with NRQL will have View query as an option. You can then edit and customize that query to see how your changes affect the resulting visualization.

Important

To explore your data without having to use NRQL, use the data explorer. Learn more about querying data in New Relic.

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:

nrql_example.png

Here are some more query examples:

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:

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.

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.