Query Builder v5 - Advanced Querying Guide

The Query Builder is SigNoz's visual query interface for logs, traces, and metrics. It combines expression-based filtering with intelligent auto-completion so you can query telemetry data without writing raw SQL or PromQL.

Where You Can Use Query Builder

The Query Builder is available across multiple surfaces in SigNoz:

• Logs Explorer — filter and aggregate log data
• Traces Explorer — search spans, filter by service/operation, and analyze trace data
• Metrics Explorer — explore and query metric data with temporal and spatial aggregations
• Dashboards — build custom panels with any telemetry signal
• Alert rules — define alert conditions on logs, traces, or metrics

View Modes

The view modes available depend on the signal you are querying.

Logs Explorer supports three view modes:

• List View — shows individual log lines. Useful for browsing raw logs and drilling into specific records.
• Time Series — plots aggregated results as a chart over time. Requires an aggregation function to be selected.
• Table — displays aggregated results in a tabular format. Like Time Series, requires an aggregation function.

Traces Explorer supports four view modes:

• List View — shows individual spans. Useful for browsing raw span data.
• Traces — groups spans into full traces, showing the end-to-end request flow. Click a trace to open the trace detail view with the flamegraph/waterfall.
• Time Series — plots aggregated span data as a chart over time. Requires an aggregation function.
• Table — displays aggregated span data in tabular format. Requires an aggregation function.

Aggregation, Group By, Result Manipulation, and Formulas are available in Time Series and Table views. List View and Traces view show raw records without aggregation.

Core Capabilities

Filtering

Filtering is the foundation of every query. The Query Builder supports expression-based filters with auto-completed attribute names, values, and operators. You can either use the point-and-click dropdowns or type expressions directly into the filter bar (e.g., service.name = 'frontend' AND http.status_code >= 400).

How to filter:

1. Click the Search Filter field to see available attributes (or start typing an expression)
2. Select an attribute (e.g., service.name, severity_text, status_code)
3. Choose an operator (=, !=, IN, NOT_IN, LIKE, EXISTS, etc.)
4. Enter the value to match
5. Combine multiple filters — they are joined with AND

For the full list of supported operators and syntax patterns, see the Operators Reference and Search Syntax.

Full-Text Search

In the Logs Explorer, you can search log bodies without specifying a field name. Wrap your search phrase in single quotes and enter it in the filter bar:

'database connection timeout'

This searches across log body content. Full-text search is only available for logs — traces and metrics require field-based filters. For details on quoted vs unquoted search behavior, see Full-Text Search.

Aggregation

Aggregation functions reduce your filtered data into summary values — counts, averages, percentiles, rates, and more.

Available aggregation functions for logs and traces:

For detailed usage, real-world examples, and legend formatting, see Aggregation & Grouping.

Group By

Group By segments your aggregated results by one or more attributes. This is how you break down data by service, endpoint, region, or any custom dimension.

For example, grouping count of error spans by service.name shows you which services produce the most errors. You can group by multiple attributes simultaneously to create more granular breakdowns.

For details on how grouping interacts with aggregation, how missing values are handled, and how to format legends, see Aggregation & Grouping.

Legend Format

When using Group By in Time Series view, each group becomes a separate line on the chart. The Legend format field lets you control how these lines are labeled. Use {{attribute_name}} placeholders to insert group-by values into the legend text.

For example, if you group by service.name and set the legend format to {{service.name}} - errors, each line is labeled like frontend - errors, cartservice - errors, etc.

Result Manipulation

After aggregation and grouping, you can further refine results:

• Order By — sort results ascending or descending by any aggregated column
• Limit — restrict the number of results returned
• Having — filter aggregated results (e.g., show only services where error count > 100)

For sorting mechanics, limit behavior with group by, and common HAVING patterns, see Result Manipulation.

Multiple Queries & Formulas

You can run multiple queries simultaneously and combine them using formulas. This is useful for computing ratios (e.g., error rate = errors / total requests) or comparing different signals side by side.

For formula syntax, available mathematical functions, and trace matching operators (=>, ->, &&, ||), see Multi-Query Analysis.

Metrics Query Builder

The Metrics Query Builder includes all the capabilities above — filtering, aggregation, group by, ordering — plus two additional aggregation layers that are specific to metric data: temporal aggregation and spatial aggregation. For a detailed explanation of how different metric types (Gauge, Counter, Histogram) affect which aggregation functions are valid, see Metric Types & Aggregation.

Temporal and Spatial Aggregation

Metrics are fundamentally different from logs and traces. A single metric (e.g., system.cpu.utilization) produces multiple time series — one per unique combination of labels like host.name, cpu.state, and service.name. Each time series contains many data points over time.

When you query metrics, SigNoz applies two aggregation layers in sequence:

Temporal Aggregation (Within Each Time Series)

Temporal aggregation consolidates raw data points within each individual time series over each time interval. Instead of plotting every raw sample (which can be thousands), it reduces them into one value per interval per series.

For example, if you have CPU utilization samples every 10 seconds and your chart shows 1-minute intervals, temporal aggregation decides how those 6 raw values become a single point — by taking the latest value, averaging them, summing them, etc.

Available functions: Latest, Sum, Avg, Min, Max, Count, Count Distinct

For counter metrics, additional functions are available: Rate (per-second rate of change) and Increase (total change over interval).

Spatial Aggregation (Across Time Series)

Spatial aggregation merges multiple time series into fewer series by combining values across dimensions. This is how you go from seeing one line per host to seeing a single line for the entire service.

For example, if system.cpu.utilization has 10 time series (one per host), spatial aggregation with Avg gives you the average CPU across all hosts as a single line.

Available functions: Sum, Avg, Min, Max

How They Work Together

1. Temporal first — each individual time series is reduced to one value per time interval
2. Spatial second — the resulting time series are combined across the dimensions you didn't group by

Temporal aggregation always happens within a single series, and spatial aggregation always happens across series — they never mix.

Functions

The Metrics Query Builder supports additional functions for extended analysis:

• Exclusion functions — cut off values above or below thresholds
• Clamping functions — constrain values to a range
• Arithmetic functions — absolute value, running diff, logarithms
• Smoothing functions — exponential weighted moving average (EWMA)
• Time shift functions — compare current data with a previous time period

For the full list, chaining behavior, and examples, see Functions for Extended Analysis.

Related

• Aggregation & Grouping — aggregation functions, group-by segmentation, and legend formatting
• Result Manipulation — sort, limit, and conditionally filter aggregated results
• Multi-Query Analysis — formulas, trace matching operators, and cross-signal comparisons
• Metric Types & Aggregation — how Gauge, Counter, and Histogram metrics work with temporal and spatial aggregation
• Time Aggregation Windows — how SigNoz calculates step intervals for time series queries
• Functions for Extended Analysis — exclusion, arithmetic, smoothing, and time shift functions
• Full-Text Search — search log bodies without specifying field names
• Search Syntax — complete reference for filter bar expressions and operators