Query Syntax

📘

Read the primer?

If you're new to Seq's query language, start with Searching and Analyzing Logs and Spans - it's a complete syntax primer for the busy developer.

In addition to simple search expressions, Seq provides an SQL-like qauery syntax for more advanced queries. Queries in Seq permit:

• Tabular queries - select event properties as columns
• Aggregate operators like count, mean, distinct, percentile and sum
• Time groupings to apply an aggregation over individual time slices

Queries enable charting through the view selector that will appear above and to the left of a result set.

Basic Syntax

The syntax of a query in Seq is:

select [<column> [as <label>],]
[from stream
  [[lateral unnest(<arr>) as <label>]]
  [where <predicate>]
  [group by [time(<d>)|<grouping>,]]
  [having <predicate>]
  [order by [time|<label>] [asc|desc]]
  [limit <n>]
  [for refresh]]

The from stream clause indicates the query will run over the event stream currently being viewed, with any active signals used to filter results.

👍

Expressions in a query use SQL-style 'single quoted' strings and familiar SQL operators such as and, or, not and like. Comments begin with -- and continue to the end of the line.

Tabular Queries

The simplest queries pluck properties out of events into columns.

select RequestMethod, RequestPath, StatusCode
from stream
where StatusCode > 399

This produces a rowset:

In many queries, Seq requires that a time range is specified using the date range picker in the Seq web interface. By default the last 24 hours will be included; use the calendar drop down to change the time range and refresh the query.

Tabular queries are great for exporting comma-separated text files from Seq. Use the drop-down beside the refresh button to download results in CSV format.

Limits

Seq automatically limits the size of rowsets that can be computed using queries, and returns an error if a rowset would exceed the default limit.

To override the limit, specifying a limit clause will take a subset of results:

select Method, RequestPath, StatusCode
from stream
where StatusCode > 399
limit 100

The limit clause is specified last, after any conditions or groupings.

👍

Instead of specifying a limit directly, it's usually possible to select a shorter time range using the date picker controls, or group the query at a coarser level.

When a tabular query is executed, options to display the data as a a bar or pie chart will appear to the bottom left of the filter bar. Selecting one of these will display the rowset in a chart of that kind.

Aggregate Operators

Most uses for SQL queries in Seq involve aggregate operators. These provide familiar computations like count, sum, min/max/mean/percentile and distinct.

select count(*)
from stream
group by RequestPath

This produces a rowset:

View the full list of aggregate operators.

Time-Slicing Queries

Rather than compute aggregates across the entire time range, a time slice grouping can be used.

select mean(Elapsed)
from stream
group by RequestPath, time(1m)

Time slicing expressions can group events by a number of days (d), hours (h), minutes (m), seconds (s) or milliseconds (ms).

To retrieve the most-recent results first, specify order by time desc in the query.

📘

Timeseries Result

The time() grouping may be specified last to render the result in timeseries format. Note that in this configuration, limit clauses will apply to the raw (un-filled) result set, so limit 5 may return more than five rows.

Selecting the timeseries icon to the bottom-left of the filter bar will display the results in a timeseries chart.

Cheat Sheet

Need a handy syntax reference to keep by your desk? We've put together a simple cheat sheet with query syntax and operator basics. Download the PDF here.