Add time() function to formula querying docs (#37478)

* Add time() function to formula querying docs

Add documentation for the time() function and convert the metric
arithmetic, min/max, and related subsections into collapsible blocks.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Apply suggestions from code review

Co-authored-by: Janine Chan <64388808+janine-c@users.noreply.github.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Racheal Ou <144172411+ouracheal@users.noreply.github.com>
Co-authored-by: Janine Chan <64388808+janine-c@users.noreply.github.com>

Author: 4 people

content/en/dashboards/querying/_index.md

@@ -150,15 +150,16 @@ Datadog also supports the ability to graph your metrics, logs, traces, and other
 
 To graph metrics separately, use the comma (`,`). For example, `a, b, c`.
 
-**Note**: Queries using commas are only supported in visualizations, they do not work on monitors. Use [boolean operators][15] or arithmetic operations to combine multiple metrics in a monitor.
+**Note**: Queries using commas are only supported in visualizations; they do not work on monitors. Use [boolean operators][15] or arithmetic operations to combine multiple metrics in a monitor.
 
-#### Metric arithmetic using an integer
+{{% collapse-content title="Metric arithmetic using an integer" level="h4" %}}
 
-Modify the displayed value of a metric on a graph by performing an arithmetic operation. For example, to visualize the double of a specific metric, click the {{< ui >}}Advanced...{{< /ui >}} link in the graph editor. Then enter your arithmetic in the `Formula` box, in this case: `a * 2`:
+Modify the displayed value of a metric on a graph by performing an arithmetic operation. For example, to visualize the double of a specific metric, click the {{< ui >}}Advanced...{{< /ui >}} link in the graph editor. Then enter your arithmetic in the `Formula` box; in this case: `a * 2`:
 
 {{< img src="dashboards/querying/arithmetic_4.png" alt="Formula example - multiply" style="width:75%;" >}}
+{{% /collapse-content %}}
 
-#### Arithmetic between two metrics
+{{% collapse-content title="Arithmetic between two metrics" level="h4" %}}
 
 Visualize the percentage of a metric by dividing one metric over another, for example:
 
@@ -181,12 +182,13 @@ status:error / status:info
 {{< img src="dashboards/querying/arithmetic_6.png" alt="Formula example - logs ratio" style="width:75%;" >}}
 
 **Note**: Formulas are not lettered. Arithmetic cannot be done between formulas.
+{{% /collapse-content %}}
 
 #### Hide a query from the visualization
 
 When a widget has multiple queries and a formula, you can hide individual queries so only the formula result appears on the graph. Click the query's letter label to toggle its visibility on the graph. A blue label indicates the query is displayed; a grey label indicates it is hidden. The hidden query is still used in the formula calculation.
 
-#### Minimum or Maximum between two queries
+{{% collapse-content title="Minimum or Maximum between two queries" level="h4" %}}
 
 Use `minimum()` and `maximum()` to compare two queries point by point and return the lower or higher value at each timestamp.
 
@@ -207,6 +209,19 @@ minimum(status:error, status:warn)
 ```
 
 {{< img src="dashboards/querying/minmax_logs_platform_example.png" alt="Formula example for 'minimum' showing the lower value between two log queries" style="width:75%;" >}}
+{{% /collapse-content %}}
+
+{{% collapse-content title="time() function" level="h4" %}}
+
+The `time()` function returns the current Unix time in seconds as a timeseries. Use it in formulas to compare a metric's timestamp against the present, which helps monitor data freshness or calculate time until an expiration.
+
+For example, to calculate the time elapsed in seconds since the last reported backup, you can use `time()` to find the difference between the present and the timestamp of the backup metric.
+
+```text
+time() - max:backup.last_completed_timestamp{*}
+```
+
+{{% /collapse-content %}}
 
 ### Create an alias