NerdGraph NRQL tutorial

You can use the New Relic NerdGraph GraphiQL explorer to make New Relic Query Language (NRQL) queries. To learn how to construct these queries and see responses, go to the NerdGraph GraphiQL explorer at https://api.newrelic.com/graphiql. This document explains some of the available functions for NRQL queries.

Basic NRQL queries with NerdGraph

To make NRQL queries using NerdGraph:

  1. Go to the NerdGraph GraphiQL explorer at https://api.newrelic.com/graphiql.
  2. Pass the NRQL query as a string argument to the NRQL object, and include the results field in your NerdGraph query.

For example, to get a count of all transaction events in the last hour, use the following query:

{
   actor {
      account(id: YOUR_ACCOUNT_ID) {
         nrql(query: "SELECT count(*) FROM Transaction SINCE 1 HOUR AGO") {
            results
         }
      }
   }
}

This NerdGraph query example returns the following results:

{
   "data": {
      "actor": {
         "account": {
            "nrql": {
               "results": [
                 {
                  "count": 1000
                 }
                ]
            }
         }
      }
   }
}

The actual value of the count varies depending on your transaction data. Use the NerdGraph GraphiQL explorer to experiment with queries.

Create embeddable charts

In addition to returning raw data, you can fetch embeddable chart links for the data to use in an application. For example, instead of a single count of transaction, you can create a chart that illustrates a timeseries of bucketed counts over time. Add TIMESERIES to your query with embeddedChartUrl:

{
   actor {
      account(id: YOUR_ACCOUNT_ID) {
         nrql(query: "SELECT count(*) from Transaction TIMESERIES") {
            embeddedChartUrl
         }
      }
   }
}

This NerdGraph query example returns the URL for the chart in the following response:

{
   "data": {
      "actor": {
         "account": {
            "nrql": {
               "embeddedChartUrl": "https://chart-embed.service.newrelic.com/charts/EMBEDDABLE-CHART-ID"
            }
         }
      }
   }
}

If you view the embedded chart URL using any standard HTTP client, it returns an image showing a visualization of the response to the query you submitted. These charts follow the same embedded chart rules as embedded charts that are created with New Relic Insights. To change the style of the data visualization, pass a chartType argument to embeddedChartUrl.

Suggested facets

When using NerdGraph to explore your data, you can use the suggestedFacets field to return suggested attributes for use in faceted NRQL queries.

Rules governing suggested facets

Here are some of the rules that govern what attributes are suggested:

  • Built-in suggestions. Each event type comes with its own set of recommended attributes. These are attributes chosen by New Relic for their importance and popularity.
  • Usage-based suggestions. Some attribute suggestions are based on the queries that have been frequently used by your account. These suggestions can include custom attributes.
  • Role restriction. Restricted users do not have access to account-related facet suggestions.

To disable the use of account data for determining suggested queries, contact Support.

Example of returning suggested attributes

Here's an example of returning suggested attributes for faceting transaction counts. The response suggests the host attribute. Faceting by host can reveal that one host is servicing more requests than other hosts.

{
   actor {
      account(id: YOUR_ACCOUNT_ID) {
         nrql(query: "SELECT count(*) from Transaction TIMESERIES") {
            suggestedFacets {
               attributes
            }
         }
      }
   }
}

This NerdGraph query example returns a response similar to this:

{
   "data": {
      "actor": {
         "account": {
            "nrql": {
               "suggestedFacets": [
       	          "attributes": ["host"]
               ]
            }
         }
      }
   }
}

For more help

Recommendations for learning more: