How to use NRQL: the mechanics of querying

Before using any tool, it's best to know how to use it. There's a process to creating, structuring, and writing queries with NRQL. Understanding the rules of querying with NRQL enables you to get the most from your data. Even if you've never queried anything before, just a basic understanding the rules allows you to access (almost) any data you need and visualize them in charts and dashboards.

NRQL syntax

If you're already familiar with SQL queries, you'll be happy to know that NRQL has a lot of similarities. Here's a quick 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]

NRQL's basic rules are as follows:

NRQL condition	Details
Required values	The `SELECT` clause 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'`
Non-standard custom event and attribute names	Events that we report by default have names that contain alphanumeric characters, colons (`:`), and underscores (`_`). Attribute names can have those characters and periods (`.`). Default-reported names start with a letter. Custom names that don't follow these guidelines must be enclosed with backticks in NRQL queries. For example: ... FACET `Logged-in user`
Data type coercion	We don't 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.
Subqueries	NRQL supports subqueries.
`JOIN` clauses	NRQL does not have the equivalent of the SQL `JOIN` clause, but you can simulate a `JOIN` with custom attributes.
Comments	You can add comments to your NRQL queries. Learn more about comments.

These are the basic rules for NRQL, and we have more information in our NRQL reference to help you build your queries.

Data exploration

One of the best ways to learn how to use NRQL is to access a New Relic query tool and use it to explore your data. Here's an example of exploring your data using the query builder and the suggested entries from the interface.

Tip

Don't be afraid to play with your data! You won't break anything using any of our query interfaces, so feel free to explore early and often!

The query begins with FROM followed by space. The interface suggests available types of data, and Transaction is chosen from that list.

Next, an attribute is chosen using SELECT, and the query looks as follows:

FROM Transaction SELECT

Pressing space again causes the interface to suggest available attributes. In the example below, appId is chosen.

The result is a very basic NRQL query using the required clause and statement (FROM and SELECT), and it provides a list of transactions and the associated appId for each, as shown below.

Another great way to explore your data is to go into any existing dashboards you have, click View query, and run your chart in the query builder.

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.

NRQL query examples

Here's an example of a slightly more in-depth NRQL query of Transaction data, which is reported by APM. For this query:

Transaction is the chosen data type
Select is used to determine the average duration
Results are grouped by appName using Facet
Timeseries is used to display the data over an automated timespan.

FROM Transaction 
SELECT average(duration) 
  FACET appName 
  TIMESERIES auto

This would generate a chart that looks like:

Here are some more query examples:

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

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 browser monitoring PageView events over the last week:

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

Important

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

Ready to learn more? Be sure to check out our introduction to NRQL if you haven't already, or learn how to use charts and dashboards with NRQL. If you want to start using NRQL right away, jump straight into our guided NRQL tutorial.

How to use NRQL: the mechanics of querying

NRQL syntax

Data exploration

Tip

NRQL query examples

Basic NRQL query of browser data

Attribute name with a space in it

Querying multiple data sources

Query returning multiple columns

Important