| title | tags | translate | metaDescription | redirects | freshnessValidatedDate | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Get started with NRQL: the language of data |
|
|
Learn how to query your New Relic data with NRQL, our SQL-like query language. |
|
2024-03-19 |
import queriesnrqlViewQueryforChart from 'images/queries-nrql_screenshot-crop_view-query-for-chart.webp'
import queriesnrqlNrqlExampleTimeseries from 'images/queries-nrql_screenshot-crop_nrql-example-timeseries.webp'
import queriesnrqlEventDefinitionsQueryBuilder from 'images/queries-nrql_screenshot-crop_event-definitions-query-builder.webp'
import queriesnrqlAttributeDefinitionsQueryBuilder from 'images/queries-nrql_screenshot-crop_attribute-definitions-query-builder.webp'
import queriesnrqlconsole from 'images/queriesNrql_screenshot-full_nrql-console.webp'
import nr1NrqlAlertConditions from 'images/nr1_nrql_alert_conditions.webp'
import NerdGraphscreenshot from 'images/apis-and-data_screenshot-crop_NerdGraph-internal-docs.webp'
The New Relic Query Language (NRQL) is a powerful tool you can use to query and understand nearly any type of data, but it can seem overwhelming at first glance. Don't worry! Here's some information to give you a foundational understanding of NRQL, including what it is, how to use it, and some tips and tricks that will help you get the most out of your queries. Once you've learned about NRQL, you can capture and interpret your data, letting you break down the big picture into easily understandable pieces and helping you identify problems as they occur.
Here's a quick video to help introduce you to using NRQL by showing you how to find a query from a dashboard and modify it in the query builder. For more detailed information on querying, including a listing of clauses, functions, and example queries, see our NRQL reference.
If you haven't already, create your free New Relic account below to start monitoring your data today!
NRQL is an acronym of New Relic query language. It's a query language similar to ANSI SQL (see the syntax), and you can use it to retrieve detailed New Relic data to get insight into your applications, hosts, and business-important activity. NRQL can help you:
- Create a new chart
- Answer a specific question for the purpose of troubleshooting or business analysis
- Set up NRQL-based alerts (our primary and most powerful type of alert)
- Make API queries of New Relic data (for example, using our NerdGraph API)
You can use NRQL to create simple queries, such as fetching rows of data in a raw tabular form that gives insight on individual events. You can also use NRQL to run powerful calculations on the data before it's presented to you, such as crafting funnels based on how end users interact with your site or application.
We use NRQL behind the scenes to generate many of the charts and dashboards in our curated UI experiences:
You can use NRQL across the platform to access your data. Those places include:
If you're already familiar with writing SQL queries, you'll be happy to know that NRQL has a lot of similarities. Here's a quick breakdown of the structure of a NRQL query:
<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>
* The data type names and attribute names are case sensitive.
* [NRQL clauses](/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#clauses) and [functions](/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#functions) are not case sensitive.
</td>
</tr>
<tr>
<td>
Syntax for strings
</td>
<td>
NRQL uses single quotes to designate strings. For example:
```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. Custom names that don't follow these guidelines must be enclosed with backticks in NRQL queries. For example:
```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 |
If you need any more information, you can check out our NRQL reference to help you build your queries.
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
- APM events, like
- Metric timeslice data (metrics reported by APM)
- The
Metricdata type (metrics reported by the Metric API and data sources that use that API) - The
Spandata type (distributed tracing data) - The
Logdata type (data from our log management capabilities)
Ready to learn more? We have information on how to use NRQL and how to use charts and dashboards with NRQL. If you want to start using NRQL instead, jump straight into our guided NRQL tutorial.