Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update to the NRQL predictions and PREDICT syntax docs #20086

Merged
merged 9 commits into from
Mar 4, 2025
Merged
Show file tree
Hide file tree
Changes from 8 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 105 additions & 9 deletions src/content/docs/nrql/nrql-syntax-clauses-functions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -785,32 +785,128 @@ As noted in our [basic NRQL syntax doc](/docs/query-your-data/nrql-new-relic-que
We're still working on this feature, but we'd love for you to try it out!

This feature is currently provided as part of a preview program pursuant to our [pre-release policies](/docs/licenses/license-information/referenced-policies/new-relic-pre-release-policy).
</Callout>
</Callout>

```sql
FROM Transaction SELECT count(*) WHERE error IS TRUE TIMESERIES PREDICT
...
```

With the `PREDICT` clause, you can incorporate predictions regarding future data trends into line charts based on historical data. This clause:
With the `PREDICT` clause, you can add predictions of future data trends into line charts based on historical data. Consider the following points when using this clause:

* Applies only to queries with a `TIMESERIES` clause.
* Uses the `TIMESERIES <time period>` as the interval for predicted data points.
* Sets the prediction range to 20% of the query window by default.
* Processes historical data from the current query window and the two preceding ones to generate predictions by default.
* Does not support [metric timeslice data](/docs/data-analysis/metrics/analyze-your-metrics/data-collection-metric-timeslice-event-data#timeslice-data) while in Public Preview.

<Callout variant="important">
The `PREDICT` clause is not supported when used with the [`COMPARE WITH`](/docs/nrql/nrql-syntax-clauses-functions/#sel-compare) clause or [nested aggregations](/docs/nrql/using-nrql/nested-aggregation-make-ordered-computations-single-query) inside [subqueries](/docs/nrql/using-nrql/subqueries-in-nrql/).
</Callout>
You can additionally append `PREDICT <model>`, `BY <time range>`, and `USING <time range>` to refine the prediction trend to your specific needs.
To indicate the time range and historical data span, use `integer units`.

```sql
FROM Transaction SELECT count(*) WHERE error IS TRUE TIMESERIES PREDICT holtwinters(beta: 0.5) BY 3 hours USING 1 day
### Customization [#customization]
To learn about the default behaviour of the prediction model, refer to [NRQL Predictions](/docs/query-your-data/explore-query-data/use-charts/nrql-predictions/#defaults). You can customize the predictions by manually setting the training model's hyperparameters and adding the `USING` and `BY` keywords.

<CollapserGroup>
<Collapser id="hyperparameters" title="Set model hyperparameters.">
Currently, <DNT>**Holt-Winters**</DNT> is the only prediction algorithm we support, and it comes with several hyperparameters to help you fine-tune your predictions. Refer to the following table to understand the behavior of each hyperparameter and choose the ones that suit your use case.

To modify your query, append `holtwinters(<hyperparameters>: <value>)` after the `PREDICT` clause.

<table id="hyperparameters">
<thead>
<tr>
<th colSpan="3">
</th>
</tr>
<tr>
<th>Hyperparameter</th>
<th>Value</th>
<th>Behavior</th>
</tr>
</thead>

<tbody>
<tr>
<td rowspan="3" style="width: 300px;">`seasonality`</td>
<td>`<season length>`</td>
<td>
Sets the seasonality of the time series to a specific season length. Make sure the season length is an `integer unit` of time.
**Examples**: `1 day` or `3 hours`
</td>
</tr>
<tr>
<td>`AUTO`</td>
<td>
Automatically detects the seasonality of the time series and generates predictions with the identified seasonality.
</td>
</tr>
<tr>
<td>`NONE`</td>
<td>
Disables the seasonality of the time series and generates a non-seasonal prediction.
</td>
</tr>

<tr>
<td>`alpha`</td>
<td>0 to 1</td>
<td>
Sets the level smoothing factor.
* **Higher value**: More weight on recent data.
* **Lower value**: More weight on historical data.
</td>
</tr>

<tr>
<td>`beta`</td>
<td>0 to 1</td>
<td>
Sets the trend smoothing factor.
* **Higher value**: More weight on recent data.
* **Lower value**: More weight on historical data.
</td>
</tr>

<tr>
<td>`gamma`</td>
<td>0 to 1</td>
<td>
Sets the season smoothing factor.
* **Higher value**: More weight on recent data.
* **Lower value**: More weight on historical data.
</td>
</tr>

<tr>
<td>`phi`</td>
<td>0.98 to 1</td>
<td>
Sets the trend damping parameter.
* **Lower value**: More damping effect to the prediction curve that gradually levels out to a flat curve.
* **Higher value**: Lesser damping effect to the prediction curve.
</td>
</tr>
</tbody>
</table>
</Collapser>

<Collapser id="by" title={<>Add the <InlineCode>BY</InlineCode> keyword.</>}>
Use the `BY` keyword to set how far ahead in time you want the model to predict. For example, `PREDICT BY 3 hours` generates a prediction 3 hours into the future from the latest point in the time series. Make sure, the time span is an `integer unit` of time.
</Collapser>

<Collapser id="using" title={<>Add the <InlineCode>USING</InlineCode> keyword.</>}>
Use the `USING` keyword to specify the amount of historical data you want to use to train the model. For example, `PREDICT USING 1 day` uses the query window along with the data from the preceding day to train the model. Make sure the time span is an `integer unit` of time.
amount of time.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Use the `USING` keyword to specify the amount of historical data you want to use to train the model. For example, `PREDICT USING 1 day` uses the query window along with the data from the preceding day to train the model. Make sure the time span is an `integer unit` of time.
amount of time.
Use the `USING` keyword to specify the amount of historical data you want to use to train the model. For example, `PREDICT USING 1 day` uses the query window along with the data from the preceding day to train the model. Make sure the time span is an `integer unit` of time.

nit

</Collapser>
</CollapserGroup>


Example query using hyperparameters, the `BY` keyword, and the `USING` keyword.

```sql
FROM Transaction SELECT count(*) WHERE error IS TRUE TIMESERIES PREDICT holtwinters(seasonality: AUTO, alpha: 0.2) BY 1 hour USING 2 hours
```

To learn more about how and when you can use `PREDICT`, refer to [NRQL Predictions](/docs/query-your-data/explore-query-data/use-charts/nrql-predictions/).
To learn more about how and when you can use `PREDICT`, refer to [NRQL Predictions](/docs/query-your-data/explore-query-data/use-charts/nrql-predictions/).
</Collapser>

<Collapser
Expand Down
Loading