feat: documentation for intro to data querying

src/markdown-pages/query-and-store-data.mdx

@@ -0,0 +1,103 @@
+---
+path: '/references/query-and-store-data.mdx'
+duration: '10 min'
+title: 'New Relic One apps: Data querying and mutations'
+template: 'GuideTemplate'
+description: 'Reference guide for SDK query components via NerdGraph '
+---
+
+<Intro>
+
+To help you build a [New Relic One application](), we provide you with the [New Relic One SDK](). On this page, you’ll learn how to use SDK query components, which allow you to make queries and mutations via [NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-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.
+
+</Intro>
+
+## Structure 
+
+Our data components are based on [React Apollo](https://www.apollographql.com/docs/react/). The most basic component is `NerdGraphQuery`, which accepts any GraphQL (or GraphQL AST generated by [the `grapqhl-tag` library](https://github.com/apollographql/graphql-tag) 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:
+
+- 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 One is entity-centric](https://docs.newrelic.com/docs/new-relic-one/use-new-relic-one/ui-data/new-relic-one-entity-explorer-view-performance-across-apps-services-hosts), 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 One provides a simple storage mechanism that we call [NerdStorage](). This can be used by Nerdpack creators to store application configuration setting data, user-specific data, and other small pieces of data. Components in this category: `UserStorageQuery`, `AccountStorageQuery`, `EntityStorageQuery`, `UserStorageMutation`, `AccountStorageMutation`, and `EntityStorageMutation`. For details, see [NerdStorage]().
+
+NRQL query: To be able to query your New Relic data via [NRQL](https://docs.newrelic.com/docs/query-data/nrql-new-relic-query-language/getting-started/introduction-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.
+
+<br/>
+
+### 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.
+
+<br/>
+
+### 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.
+
+ <br/>
+
+### 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:
+
+```jsx
+// 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.
+
+<br/>
+
+## 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 are willing to push data, we currently do not expose `NrqlMutation`. To do that, see the [Event API]() for how to add custom events.