docs-website/src/content/docs/nrql/get-started/introduction-nrql-new-relics-query-language.mdx at develop · newrelic/docs-website

title

Get started with NRQL: The language of data

What you can do with NRQL [#nrql-overview]

Use NRQL to:

Build charts that show transaction throughput, error rates, or latency over time
Answer a specific question for the purpose of troubleshooting or business analysis
Investigate a performance issue by querying the specific events and attributes involved
Set up NRQL-based alerts that fire when a metric crosses a threshold
Make API queries for your New Relic data for example, using our NerdGraph API.

NRQL works for both basic queries (fetching raw rows of event data) and calculated results, such as funnels based on how users interact with your site or application.

New Relic uses NRQL internally to power the charts and dashboards in the New Relic platform. That same query language is available to you.

Queryable data types [#what-you-can-query]

NRQL lets you query nearly every type of our telemetry data, including:

Event data from all New Relic products. Examples include:
- APM events, like Transaction
- Browser monitoring events, like PageView
- Mobile monitoring events, like Mobile
- Infrastructure events, like ProcessSample
- Synthetic events, like SyntheticCheck
- Custom events, like those reported by the Event API
The Metric data type (metrics reported by the Metric API and data sources that use that API)
The Span data type (distributed tracing data)
The Log data type (data from our log management capabilities)

Some data, like relationships between monitored entities, is not available via NRQL but is available using our [NerdGraph API](/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph).

Where to use NRQL [#where]

NRQL is available across the platform:

The query builder

<TabsBarItem id="nrql-alerts-nrql-intro">
  NRQL-based alerts
</TabsBarItem>

<TabsBarItem id="nerdgraph-api-nrql-intro">
  NerdGraph API
</TabsBarItem>

  <figcaption>
    Access the query builder through the <DNT>Query your data</DNT> drawer at the bottom of any New Relic page to run queries and create custom charts.
  </figcaption>

  You can run an NRQL query in the [query builder](/docs/chart-builder/use-chart-builder/get-started/introduction-chart-builder) within [the platform](/docs/new-relic-one/use-new-relic-one/get-started/introduction-new-relic-one). This NRQL query shows a count of [distributed tracing](/docs/understand-dependencies/distributed-tracing/get-started/introduction-distributed-tracing) spans faceted by their entity names.
</TabsPageItem>

<TabsPageItem id="nrql-alerts-nrql-intro">
  [NRQL-based alerts](/docs/alerts-applied-intelligence/new-relic-alerts/alert-conditions/create-nrql-alert-conditions/) are the primary alert type in New Relic. To create one, go to <DNT>**[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Alerts > Alert conditions (Policies) > (select a policy) > Add a condition**</DNT>, click <DNT>**NRQL**</DNT>, and then <DNT>**Next, define thresholds**</DNT>.
</TabsPageItem>

<TabsPageItem id="nerdgraph-api-nrql-intro">
  <img
    title="Nerdgraph API example"
    alt="A screenshot of the Nerdgraph API"
    src="/images/apis-and-data_screenshot-crop_NerdGraph-internal-docs.webp"
  />

  You can also use NRQL with our [NerdGraph API](/docs/apis/graphql-api/tutorials/nerdgraph-graphiql-nrql-tutorial). This lets you run [cross-account queries](/docs/apis/nerdgraph/examples/nerdgraph-nrql-tutorial#cross-account-query) and [asynchronous queries](/docs/apis/nerdgraph/examples/async-queries-nrql-tutorial) that aren't available in the UI.
</TabsPageItem>

NRQL query structure [#nrql-rules]

NRQL follows a structured, clause-based syntax. Here's an NRQL query that counts all transactions in the last hour:

SELECT count(*) FROM Transaction SINCE 1 hour ago

Here's a breakdown of all available clauses:

<a href="/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#state-select">SELECT</a> <a href="/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#functions">function(attribute)</a> [<a href="/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#sel-as">AS</a> 'label'][, ...] 
  <a href="/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#sel-from">FROM</a> data type
  [<a href="/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#sel-where">WHERE</a> attribute [comparison] [AND|OR ...]][AS 'label'][, ...]
  [<a href="/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#sel-facet">FACET</a> attribute | function(attribute)]
  [<a href="/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#sel-limit">LIMIT</a> number]
  [<a href="/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#sel-since">SINCE</a> time]
  [<a href="/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#sel-until">UNTIL</a> time]
  [<a href="/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#sel-timezone">WITH TIMEZONE</a> timezone]
  [<a href="/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#sel-compare">COMPARE WITH</a> time]
  [<a href="/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#sel-timeseries">TIMESERIES</a> time]

Here are the rules that NRQL follows:

  <th>
    Details
  </th>
</tr>

  <td>
    The [`SELECT`](#state-select) clause and [`FROM`](#sel-from) clause are required. All other clauses are optional. You can start your query with either `SELECT` or `FROM`.
  </td>
</tr>

<tr>
  <td>
    Query string size
  </td>

  <td>
    The query string must be less than 4 KB.
  </td>
</tr>

<tr>
  <td>
    Case sensitivity
  </td>

  <td>
    Data type names and attribute names are case sensitive. [NRQL clauses and functions](/docs/nrql/nrql-syntax-clauses-functions/) aren't case sensitive.
  </td>
</tr>

<tr>
  <td>
    Syntax for strings
  </td>

  <td>
    NRQL uses single quotes to designate strings. The following example shows the syntax:

    ```sql
    ... WHERE traceId = '030a573f0df02c57'
    ```
  </td>
</tr>

<tr>
  <td>
    Non-standard custom event and attribute names
  </td>

  <td>
    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. You must enclose custom names that don't follow these guidelines in backticks in NRQL queries. The following example shows a custom name enclosed in backticks:

    ```sql
    ... FACET `Logged-in user`
    ```
  </td>
</tr>

<tr>
  <td>
    Data type coercion
  </td>

  <td>
    We don't support data type "coercion." For more information, see [Data type conversion](/docs/insights/nrql-new-relic-query-language/nrql-reference/nrql-syntax-components-functions#type-conversion).
  </td>
</tr>

NRQL rule
Required values

For more information, see our NRQL reference to help you build your queries.

Next steps [#next-steps]

How NRQL works (query execution, data freshness, and limits)
Charts and dashboards with NRQL (visualize your query results)
Guided NRQL tutorial (hands-on walkthrough for new users)
NRQL reference (full syntax, clauses, and functions)

Navigation Menu

Uh oh!

What you can do with NRQL [#nrql-overview]

Queryable data types [#what-you-can-query]

Where to use NRQL [#where]

NRQL query structure [#nrql-rules]

Next steps [#next-steps]

Uh oh!

FilesExpand file tree

introduction-nrql-new-relics-query-language.mdx

Latest commit

History

introduction-nrql-new-relics-query-language.mdx

File metadata and controls

What you can do with NRQL [#nrql-overview]

Queryable data types [#what-you-can-query]

Where to use NRQL [#where]

NRQL query structure [#nrql-rules]

Next steps [#next-steps]