The readPersistedAggregation() function reads an existing persisted aggregation (PA) and returns its contents as rows in a table. A PA persists as the state of the first aggregator in a query pipeline. Reading a PA requires reading that state after validation, then executing the remainder of the PA query before returning the resulting events.

Persisted aggregations allow query results to be stored and retrieved efficiently without re-executing the full query over raw data each time. The readPersistedAggregation() function provides access to those stored results as a table, optionally filtered by time range and grouped by a specified interval.

For more information about persisted aggregations, see Persisted Aggregations.

Note

It is recommended to use the readPersistedAggregation() function at the beginning of the query. Using the function later in the query will always discard anything before it, and only return the content of the referenced persisted aggregation.

ParameterTypeRequiredDefault ValueDescription
endstringoptional[a] Same as the primary query The end of the time interval for reading the persisted aggregation, expressed as a time-point string. When specified, this value is validated against the start value, against the current time, and against the PA time interval. When not specified, the end time of the primary query is used.
startstringoptional[a] Same as the primary query The start of the time interval for reading the persisted aggregation, expressed as a time-point string. When specified, this value is validated against the end value, against the current time, and against the PA time interval. When not specified, the start time of the primary query is used.
tagstringrequired   The tag that identifies the persisted aggregation to read. The tag must correspond to an existing PA in the specified or default view.
viewstringoptional[a] Same as the primary query The view in which to locate the persisted aggregation. When not specified, the view of the primary query is used. The specified view must contain a PA matching the provided tag value.

[a] Optional parameters use their default value unless explicitly set.

The argument name for function can be omitted.

readPersistedAggregation() Function Operation

The readPersistedAggregation() function has specific implementation and operational considerations, outlined below.

  • The readPersistedAggregation() function simply reads the events from a Persisted Aggregation Repository (view) with matching tag as provided in the parameter (tag) and then outputs these.

  • The readPersistedAggregation() function locates the persisted aggregation identified by the tag parameter within the specified or default view.

  • When start and end are not specified, the function uses the same time interval as the primary query. When specified, these values are validated against each other, against the current time, and against the PA time interval.

  • The view parameter identifies the view in which the PA is located. When not specified, the view of the primary query is used.

Note

The readPersistedAggregation() function is permitted only in static queries. It is not permitted in cross-products such as sequence functions.

This example demonstrates basic usage of readPersistedAggregation(), reading all events from a persisted aggregation by specifying a tag and view.

In this scenario, a persisted aggregation exists with the tag myTag in the view myView. The query retrieves all events stored under that tag. Only events matching the specified tag are returned; events from other tags in the same view are excluded.

logscale
readPersistedAggregation("myTag", view="myView")

If event data looks like this:

field1field2@timestamp
value1value21451606301001
value3<no value>1451606301003

it would return:

field1field2@timestamp
value1value21451606301001
value3<no value>1451606301003

This example demonstrates filtering events using an absolute time interval specified as Unix millisecond timestamps. Only events with a @timestamp value in the range [start, end) are returned.

In this scenario, the persisted aggregation contains four events with timestamps spread across a short interval. The query specifies an absolute start of 1451606301002 and an absolute end of 1451606301010. Events with timestamps before start or at and after end are excluded from the result.

logscale
readPersistedAggregation("myTag", view="myView", start=1451606301002, end=1451606301010)

If event data looks like this:

field1@timestamp
11451606301001
21451606301003
31451606301008
41451606301015

it would return:

field1@timestamp
21451606301003
31451606301008

This example demonstrates filtering events using relative durations for start and end. Relative values are interpreted as offsets back from the outer query's end time.

In this scenario, the outer query has an end time of 1451606301020. Specifying start=17ms and end=3ms translates to the absolute range [1451606301003, 1451606301017), that is, from 17 milliseconds before the query end time up to 3 milliseconds before the query end time. Events outside this range are excluded.

logscale
readPersistedAggregation("myTag", view="myView", start=17ms, end=3ms)

If event data looks like this:

field1@timestamp
11451606301001
21451606301003
31451606301008
41451606301015
51451606301018

it would return:

field1@timestamp
21451606301003
31451606301008
41451606301015

This example demonstrates the behaviour of readPersistedAggregation() when the specified persisted aggregation contains no events.

When the persisted aggregation identified by tag myTag in view myView has no stored events, the function returns an empty result set. No error is raised; the query simply produces no output rows.

logscale
readPersistedAggregation("myTag", view="myView")

If the persisted aggregation contains no events, the query returns an empty result set with no rows.

Click + next to an example below to get the full details.

Retrieve Events from a Persisted Aggregation

Reading events stored in a persisted aggregation from a specific view using the readPersistedAggregation() function

Query
logscale
readPersistedAggregation("myTag", view="myView")
Introduction

In this example, the readPersistedAggregation() function is used to retrieve all events stored under the tag myTag in the view myView. Only events matching the specified tag are returned; events from other tags in the same view are excluded.

In this scenario, a persisted aggregation has been set up to periodically aggregate web server access log data — counting requests per HTTP status code and endpoint — and store the results under the tag myTag in the view myView. The readPersistedAggregation() function is then used to read back those stored results for further analysis or visualization without re-running the original aggregation query.

Example incoming data might look like this:

@timestampstatus_codeendpointrequest_countavg_response_mserror_rate
2026-03-15T08:00:00Z200/api/users15231420.00
2026-03-15T08:00:00Z200/api/products987980.00
2026-03-15T08:00:00Z200/api/orders6542100.00
2026-03-15T08:00:00Z301/api/legacy45120.00
2026-03-15T08:00:00Z400/api/users78551.00
2026-03-15T08:00:00Z400/api/products34481.00
2026-03-15T08:00:00Z401/api/orders112331.00
2026-03-15T08:00:00Z403/api/admin29281.00
2026-03-15T08:00:00Z404/api/users56221.00
2026-03-15T08:00:00Z404/api/products41191.00
2026-03-15T08:00:00Z500/api/orders188901.00
2026-03-15T08:00:00Z500/api/users712401.00
2026-03-15T08:00:00Z503/api/products321001.00
2026-03-15T09:00:00Z200/api/users17891380.00
2026-03-15T09:00:00Z200/api/products1102950.00
2026-03-15T09:00:00Z200/api/orders7232050.00
2026-03-15T09:00:00Z301/api/legacy38110.00
2026-03-15T09:00:00Z400/api/users91521.00
2026-03-15T09:00:00Z401/api/orders98311.00
2026-03-15T09:00:00Z404/api/products63201.00
2026-03-15T09:00:00Z500/api/orders229101.00
2026-03-15T09:00:00Z503/api/users519801.00
Step-by-Step

  1. Starting with the source repository events.

  2. logscale
    readPersistedAggregation("myTag", view="myView")

    The readPersistedAggregation() function retrieves all events previously stored in the persisted aggregation identified by the tag myTag. The view parameter specifies that the aggregation is read from the view named myView. If the view parameter is omitted, the function defaults to reading from the current view in which the query is executed. Only events associated with the tag myTag are returned; any other persisted aggregations stored under different tags within myView are excluded from the result set. The function acts as a source in the query pipeline, meaning it replaces the normal event stream with the stored aggregation results, making it suitable as the first and only statement when the goal is simply to retrieve the persisted data.

  3. Event Result set.

Summary and Results

The query is used to read back pre-aggregated web server access log data that was previously stored under the tag myTag in the view myView, returning all fields and events captured at the time the persisted aggregation was last written.

This query is useful, for example, to power dashboards or alerts that need to display aggregated HTTP traffic metrics — such as request counts, average response times, and error rates per endpoint and status code — without incurring the cost of re-running the full aggregation query over raw log data each time.

Sample output from the incoming example data:

@timestampstatus_codeendpointrequest_countavg_response_mserror_rate
2026-03-15T08:00:00Z200/api/users15231420.00
2026-03-15T08:00:00Z200/api/products987980.00
2026-03-15T08:00:00Z200/api/orders6542100.00
2026-03-15T08:00:00Z301/api/legacy45120.00
2026-03-15T08:00:00Z400/api/users78551.00
2026-03-15T08:00:00Z400/api/products34481.00
2026-03-15T08:00:00Z401/api/orders112331.00
2026-03-15T08:00:00Z403/api/admin29281.00
2026-03-15T08:00:00Z404/api/users56221.00
2026-03-15T08:00:00Z404/api/products41191.00
2026-03-15T08:00:00Z500/api/orders188901.00
2026-03-15T08:00:00Z500/api/users712401.00
2026-03-15T08:00:00Z503/api/products321001.00
2026-03-15T09:00:00Z200/api/users17891380.00
2026-03-15T09:00:00Z200/api/products1102950.00
2026-03-15T09:00:00Z200/api/orders7232050.00
2026-03-15T09:00:00Z301/api/legacy38110.00
2026-03-15T09:00:00Z400/api/users91521.00
2026-03-15T09:00:00Z401/api/orders98311.00
2026-03-15T09:00:00Z404/api/products63201.00
2026-03-15T09:00:00Z500/api/orders229101.00
2026-03-15T09:00:00Z503/api/users519801.00

Note that the output is a direct reflection of the data stored in the persisted aggregation at the time it was last written — no additional filtering, transformation, or re-aggregation is applied by the readPersistedAggregation() function itself.

Note also that events from other tags that may exist within myView are entirely absent from the results, confirming that the tag filter is applied strictly. Note that the error_rate field carries a value of 1.00 for all non-2xx and non-3xx status codes, reflecting that these were pre-computed and stored as part of the original aggregation logic, and their meaning depends entirely on how the persisted aggregation was defined.