Query and store data

To help you build a New Relic application, we provide you with the New Relic One SDK. Here you can learn how to use the SDK query components, which allow you to make queries and mutations via NerdGraph, our GraphQL endpoint.

Components overview

We base our data components on React Apollo. The most basic component is NerdGraphQuery, which accepts any GraphQL or GraphQL AST generated by the graphql-tag library as the query parameter, and a set of query variables passed as variables. Over this query, we've created an additional set of queries, which can be divided into four groups:

• User queries: These allow you to query the current user and its associated accounts. Components in this category: UserStorageQuery and AccountsQuery.
• Entities queries: Because New Relic is entity-centric, we use queries to make access to your entities easier. You can count, search, list, query, and favorite them. Components in this category: EntityCountQuery, EntitySearchQuery, EntitiesByDomainTypeQuery, EntitiesByGuidsQuery, EntityByGuidQuery, EntityByNameQuery.
• Storage queries: New Relic provides a simple storage mechanism that we call NerdStorage. Nerdpack creators can use it to store application configuration setting data, user-specific data, and other small pieces of data. This category includes these components: UserStorageQuery, AccountStorageQuery, EntityStorageQuery, UserStorageMutation, AccountStorageMutation, and EntityStorageMutation.
• NRQL queries: To be able to query your New Relic data via NRQL, 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 a function as a children prop where the different statuses can be passed. This callback receives an object with these 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 you can use 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 a children as a function, like the query ones. The mutation can be preconfigured at the component level, and a function is 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 in this format that you're willing to migrate to or incorporate with.
• 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're willing to push data, we currently don't expose NrqlMutation. To do that, see the Event API for how to add custom events.