New Relic developers

New Relic One: Guide to data queries and mutations

Introduction

We provide you a variety of tools for building a New Relic One application, including the client-side SDK. On this page, you’ll learn how to use SDK query components, which allow you to make queries and mutations via NerdGraph (our GraphQL endpoint). 

Query-related React components can be identified by the Query suffix. Mutation-related components can be identified by the Mutation prefix.

Structure

Our data components are based on React Apollo. The most basic component is NerdGraphQuery, which accepts any GraphQL (or GraphQL AST generated by the grapqhl-tag library as the query parameter, and a set of query variables passed as variables.

Over this query, we have created an additional set of queries, which can be divided into four groups:

NRQL query: To be able to query your New Relic data via NRQL (New Relic query language), we provide a NrqlQuery component. This component can return data in different formats, so that you can use it for charting and not only for querying.

Query components

All query components accept as a children prop a function where the different statuses will be passed. This callback will receive an object with the following properties:

  • loading: Boolean that is set to true when data fetching is happening. Our components use the cache-and-network strategy, meaning that after the data has loaded, subsequent data reloads might be triggered first with stale data, then refreshed when the most recent data has arrived.

  • data: Root property where the data requested is retrieved. The structure matches a root structure based on the NerdGraph schema. This is true even for highly nested data structures, which means you’ll have to traverse down to find the desired data.

  • error: Contains an Error instance when the query fails. Set to undefined when data is loading or the fetch was successful.

  • fetchMore: Callback function that can be called when the query is being loaded in chunks. The function will only be present when it’s feasible to do so, more data is available, and no fetchMore has already been triggered. Data is loaded in batches of 200 by default. Other components provided by the platform (like the Dropdown or the List) are capable of accepting fetchMore, meaning you can combine them easily.

Mutation components

Mutation components also accept, like the query ones, a children as a function. The mutation can be pre-configured at the component level, and a function will be passed back that you can use in your component.

This is the standard React Apollo approach for performing mutations, but you might find it easier to use our static mutation method added to the component. More on this topic below.

Static methods

All of the described components also expose a static method so that they can be used imperatively rather than declaratively. All Query components have a static Query method, and all Mutation components have a mutation method. These static methods accept the same props as their query component, but passed as an object. For example:

// Declarative way (using components).
function renderAccountList() {
  return (
    <ul>
      <AccountsQuery>
        ({data, error}) => {
          if (error) {
            return <li>Failed to retrieve list: {error.message}</li>;
          }

          return data.map((account) => {
            <li key={account.id}>{account.name}</li>
          });
        }}
      </AccountsQuery>
    </ul>
  );
}

// Imperative way (using promises).
async function getAccountList() {
  let data = {};

  try {
    data = await AccountsQuery.query();
  } catch (error) {
    console.log('Failed to retrieve list: ' + error.message);
    return;
  }

  return data.actor.accounts.map((account) => {
    return account.name;
  });
}

Similarly, a mutation can happen either way; either declaratively or imperatively. 

NrqlQuery

NrqlQuery deserves additional explanation, because there are multiple formats in which you can return data from it. To provide maximum functionality, all three are exposed through a formatType property. You can find its different values under NrqlQuery.formatType:

  • NERD_GRAPH: Returns the format in which it arrives from NerdGraph.

  • RAW: The format exposed by default in Insights and dashboards when being plotted as JSON. This format is useful if you have a pre-existing script that used this format, that you are willing to migrate or incorporate to.

  • CHART: The format used by the charting engine that we also expose. You can find a more detailed explanation of how to manipulate this format in the guide to chart components, and some examples.

If you are willing to push data, we currently do not expose NrqlMutation. To do that, see the Event API for how to add custom events.