feat: support ai trace aggregate filtering in ai span list

.github/workflows/integrationci.yaml

@@ -53,6 +53,7 @@ jobs:
           - queriermetrics
           - querierscalar
           - queriercommon
+          - querierai
           - rawexportdata
           - role
           - rootuser

docs/api/openapi.yml

@@ -8312,6 +8312,7 @@ components:
     TelemetrytypesSource:
       enum:
       - meter
+      - ai
       type: string
     TelemetrytypesTelemetryFieldKey:
       properties:

frontend/src/api/generated/services/sigNoz.schemas.ts

@@ -3631,6 +3631,7 @@ export enum Querybuildertypesv5QueryBuilderQueryGithubComSigNozSignozPkgTypesQue
 }
 export enum TelemetrytypesSourceDTO {
 	meter = 'meter',
+	ai = 'ai',
 }
 export interface Querybuildertypesv5QueryBuilderQueryGithubComSigNozSignozPkgTypesQuerybuildertypesQuerybuildertypesv5LogAggregationDTO {
 	/**

pkg/modules/llmpricingrule/impllmpricingrule/module.go

@@ -213,18 +213,18 @@ func (module *module) discoverModels(ctx context.Context, orgID valuer.UUID) ([]
 					Spec: qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
 						Name:   "A",
 						Signal: telemetrytypes.SignalTraces,
-						Filter: &qbtypes.Filter{Expression: fmt.Sprintf("%s EXISTS", llmpricingruletypes.GenAIRequestModel)},
+						Filter: &qbtypes.Filter{Expression: fmt.Sprintf("%s EXISTS", telemetrytypes.GenAIRequestModel)},
 						Aggregations: []qbtypes.TraceAggregation{
 							{Expression: "count()", Alias: "spanCount"},
 						},
 						GroupBy: []qbtypes.GroupByKey{
 							{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{
-								Name:          llmpricingruletypes.GenAIRequestModel,
+								Name:          telemetrytypes.GenAIRequestModel,
 								FieldContext:  telemetrytypes.FieldContextSpan,
 								FieldDataType: telemetrytypes.FieldDataTypeString,
 							}},
 							{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{
-								Name:          llmpricingruletypes.GenAIProviderName,
+								Name:          telemetrytypes.GenAIProviderName,
 								FieldContext:  telemetrytypes.FieldContextSpan,
 								FieldDataType: telemetrytypes.FieldDataTypeString,
 							}},
@@ -254,9 +254,9 @@ func (module *module) discoverModels(ctx context.Context, orgID valuer.UUID) ([]
 		switch c.Type {
 		case qbtypes.ColumnTypeGroup:
 			switch c.Name {
-			case llmpricingruletypes.GenAIRequestModel:
+			case telemetrytypes.GenAIRequestModel:
 				modelIdx = i
-			case llmpricingruletypes.GenAIProviderName:
+			case telemetrytypes.GenAIProviderName:
 				providerIdx = i
 			}
 		case qbtypes.ColumnTypeAggregation:

pkg/querier/querier.go

@@ -42,6 +42,7 @@ type querier struct {
 	metadataStore            telemetrytypes.MetadataStore
 	promEngine               prometheus.Prometheus
 	traceStmtBuilder         qbtypes.StatementBuilder[qbtypes.TraceAggregation]
+	aiTraceStmtBuilder       qbtypes.StatementBuilder[qbtypes.TraceAggregation]
 	logStmtBuilder           qbtypes.StatementBuilder[qbtypes.LogAggregation]
 	auditStmtBuilder         qbtypes.StatementBuilder[qbtypes.LogAggregation]
 	metricStmtBuilder        qbtypes.StatementBuilder[qbtypes.MetricAggregation]
@@ -61,6 +62,7 @@ func New(
 	metadataStore telemetrytypes.MetadataStore,
 	promEngine prometheus.Prometheus,
 	traceStmtBuilder qbtypes.StatementBuilder[qbtypes.TraceAggregation],
+	aiTraceStmtBuilder qbtypes.StatementBuilder[qbtypes.TraceAggregation],
 	logStmtBuilder qbtypes.StatementBuilder[qbtypes.LogAggregation],
 	auditStmtBuilder qbtypes.StatementBuilder[qbtypes.LogAggregation],
 	metricStmtBuilder qbtypes.StatementBuilder[qbtypes.MetricAggregation],
@@ -82,6 +84,7 @@ func New(
 		metadataStore:            metadataStore,
 		promEngine:               promEngine,
 		traceStmtBuilder:         traceStmtBuilder,
+		aiTraceStmtBuilder:       aiTraceStmtBuilder,
 		logStmtBuilder:           logStmtBuilder,
 		auditStmtBuilder:         auditStmtBuilder,
 		metricStmtBuilder:        metricStmtBuilder,
@@ -235,10 +238,18 @@ func (q *querier) buildQueries(
 			case qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]:
 				spec.ShiftBy = extractShiftFromBuilderQuery(spec)
 				timeRange := adjustTimeRangeForShift(spec, qbtypes.TimeRange{From: req.Start, To: req.End}, req.RequestType)
-				bq := newBuilderQuery(q.logger, q.telemetryStore, q.traceStmtBuilder, spec, timeRange, req.RequestType, tmplVars, builderConfig{})
+				stmtBuilder := q.traceStmtBuilder
+				if spec.Source == telemetrytypes.SourceAI {
+					event.Source = telemetrytypes.SourceAI.StringValue()
+					stmtBuilder = q.aiTraceStmtBuilder
+				}
+				bq := newBuilderQuery(q.logger, q.telemetryStore, stmtBuilder, spec, timeRange, req.RequestType, tmplVars, builderConfig{})
 				queries[spec.Name] = bq
 				steps[spec.Name] = spec.StepInterval
 			case qbtypes.QueryBuilderQuery[qbtypes.LogAggregation]:
+				if spec.Source == telemetrytypes.SourceAI {
+					return nil, nil, errors.NewInvalidInputf(errors.CodeInvalidInput, "source \"ai\" is only supported for the traces signal, not logs")
+				}
 				spec.ShiftBy = extractShiftFromBuilderQuery(spec)
 				timeRange := adjustTimeRangeForShift(spec, qbtypes.TimeRange{From: req.Start, To: req.End}, req.RequestType)
 				stmtBuilder := q.logStmtBuilder
@@ -249,6 +260,9 @@ func (q *querier) buildQueries(
 				queries[spec.Name] = bq
 				steps[spec.Name] = spec.StepInterval
 			case qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation]:
+				if spec.Source == telemetrytypes.SourceAI {
+					return nil, nil, errors.NewInvalidInputf(errors.CodeInvalidInput, "source \"ai\" is only supported for the traces signal, not metrics")
+				}
 				// Spec was already patched by resolveMetricMetadata. Queries
 				// whose every aggregation was missing live in
 				// missingMetricQuerySet and produce empty preseeded results
@@ -479,6 +493,10 @@ func (q *querier) QueryRawStream(ctx context.Context, orgID valuer.UUID, req *qb
 		if query.Type == qbtypes.QueryTypeBuilder {
 			switch spec := query.Spec.(type) {
 			case qbtypes.QueryBuilderQuery[qbtypes.LogAggregation]:
+				if spec.Source == telemetrytypes.SourceAI {
+					client.Error <- errors.NewInvalidInputf(errors.CodeInvalidInput, "source \"ai\" is only supported for the traces signal, not logs")
+					return
+				}
 				event.FilterApplied = spec.Filter != nil && spec.Filter.Expression != ""
 			default:
 				// return if it's not log aggregation
@@ -858,7 +876,11 @@ func (q *querier) createRangedQuery(originalQuery qbtypes.Query, timeRange qbtyp
 		specCopy := qt.spec.Copy()
 		specCopy.ShiftBy = extractShiftFromBuilderQuery(specCopy)
 		adjustedTimeRange := adjustTimeRangeForShift(specCopy, timeRange, qt.kind)
-		return newBuilderQuery(q.logger, q.telemetryStore, q.traceStmtBuilder, specCopy, adjustedTimeRange, qt.kind, qt.variables, builderConfig{})
+		shiftStmtBuilder := q.traceStmtBuilder
+		if qt.spec.Source == telemetrytypes.SourceAI {
+			shiftStmtBuilder = q.aiTraceStmtBuilder
+		}
+		return newBuilderQuery(q.logger, q.telemetryStore, shiftStmtBuilder, specCopy, adjustedTimeRange, qt.kind, qt.variables, builderConfig{})
 
 	case *builderQuery[qbtypes.LogAggregation]:
 		specCopy := qt.spec.Copy()

pkg/querier/querier_test.go

@@ -49,6 +49,7 @@ func TestQueryRange_MetricTypeMissing(t *testing.T) {
 		metadataStore,
 		nil,                // prometheus
 		nil,                // traceStmtBuilder
+		nil,                // aiTraceStmtBuilder
 		nil,                // logStmtBuilder
 		nil,                // auditStmtBuilder
 		nil,                // metricStmtBuilder
@@ -121,6 +122,7 @@ func TestQueryRange_MetricTypeFromStore(t *testing.T) {
 		metadataStore,
 		nil,                      // prometheus
 		nil,                      // traceStmtBuilder
+		nil,                      // aiTraceStmtBuilder
 		nil,                      // logStmtBuilder
 		nil,                      // auditStmtBuilder
 		&mockMetricStmtBuilder{}, // metricStmtBuilder

pkg/querier/signozquerier/provider.go

@@ -9,6 +9,7 @@ import (
 	"github.com/SigNoz/signoz/pkg/prometheus"
 	"github.com/SigNoz/signoz/pkg/querier"
 	"github.com/SigNoz/signoz/pkg/querybuilder"
+	"github.com/SigNoz/signoz/pkg/telemetryai"
 	"github.com/SigNoz/signoz/pkg/telemetryaudit"
 	"github.com/SigNoz/signoz/pkg/telemetrylogs"
 	"github.com/SigNoz/signoz/pkg/telemetrymetadata"
@@ -92,6 +93,22 @@ func newProvider(
 		cfg.SkipResourceFingerprint.Threshold,
 	)
 
+	// AI trace statement builder (source=ai). The gen_ai gate/column keys are
+	// surfaced by the metadata store itself (enrichWithGenAIKeys), so queries work
+	// before any gen_ai metadata is ingested — no per-builder decoration needed.
+	// The standard trace builder doubles as the delegate for the span-list path.
+	aiBaseCondition := telemetryai.NewGenAIBaseConditionProvider()
+	aiTraceStmtBuilder := telemetryai.NewAITraceStatementBuilder(
+		settings,
+		telemetryMetadataStore,
+		aiBaseCondition,
+		traceStmtBuilder,
+		telemetryStore,
+		flagger,
+		cfg.SkipResourceFingerprint.Enabled,
+		cfg.SkipResourceFingerprint.Threshold,
+	)
+
 	// Create trace operator statement builder
 	traceOperatorStmtBuilder := telemetrytraces.NewTraceOperatorStatementBuilder(
 		settings,
@@ -185,6 +202,7 @@ func newProvider(
 		telemetryMetadataStore,
 		prometheus,
 		traceStmtBuilder,
+		aiTraceStmtBuilder,
 		logStmtBuilder,
 		auditStmtBuilder,
 		metricStmtBuilder,

pkg/query-service/rules/setups_test.go

@@ -48,6 +48,7 @@ func prepareQuerierForMetrics(t *testing.T, telemetryStore telemetrystore.Teleme
 		metadataStore,
 		nil, // prometheus
 		nil, // traceStmtBuilder
+		nil, // aiTraceStmtBuilder
 		nil, // logStmtBuilder
 		nil, // auditStmtBuilder
 		metricStmtBuilder,
@@ -103,6 +104,7 @@ func prepareQuerierForLogs(t *testing.T, telemetryStore telemetrystore.Telemetry
 		metadataStore,
 		nil,            // prometheus
 		nil,            // traceStmtBuilder
+		nil,            // aiTraceStmtBuilder
 		logStmtBuilder, // logStmtBuilder
 		nil,            // auditStmtBuilder
 		nil,            // metricStmtBuilder
@@ -152,6 +154,7 @@ func prepareQuerierForTraces(t *testing.T, telemetryStore telemetrystore.Telemet
 		metadataStore,
 		nil,              // prometheus
 		traceStmtBuilder, // traceStmtBuilder
+		nil,              // aiTraceStmtBuilder
 		nil,              // logStmtBuilder
 		nil,              // auditStmtBuilder
 		nil,              // metricStmtBuilder

pkg/querybuilder/filter_split.go

@@ -0,0 +1,160 @@
+package querybuilder
+
+import (
+	"strings"
+
+	"github.com/SigNoz/signoz/pkg/errors"
+	grammar "github.com/SigNoz/signoz/pkg/parser/filterquery/grammar"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/antlr4-go/antlr/v4"
+)
+
+// SplitFilterForAggregates partitions a single filter expression into a span-level
+// part (a WHERE over spans) and a trace-level part (a HAVING over per-trace
+// aggregates), splitting on the top-level AND.
+//
+// A key is trace-level when, with no explicit field context, its name is in
+// aggregateNames — written bare (`completion_tokens`) or with the user-facing `trace.`
+// prefix (`trace.completion_tokens`). Any explicit context (`span.`, `resource.`, …) is
+// span-level. Trace-level and span-level keys may be AND-combined (they run at different
+// query stages) but not OR-combined; an OR that mixes the two is an error.
+//
+// Syntax errors are ignored here — each part is re-parsed downstream (PrepareWhereClause
+// for the span part, the HAVING rewriter for the trace part), which surface them.
+func SplitFilterForAggregates(query string, aggregateNames map[string]struct{}) (spanExpr string, havingExpr string, err error) {
+	if strings.TrimSpace(query) == "" {
+		return "", "", nil
+	}
+
+	s := filterSplitter{query: []rune(query), aggregateNames: aggregateNames}
+	s.visit(parseFilterQuery(query))
+
+	if s.mixed {
+		return "", "", errors.NewInvalidInputf(errors.CodeInvalidInput,
+			"trace-level and span-level filters cannot be combined within an OR/NOT group; separate them with a top-level AND")
+	}
+	return strings.Join(s.span, " AND "), strings.Join(s.having, " AND "), nil
+}
+
+func parseFilterQuery(query string) antlr.Tree {
+	lexer := grammar.NewFilterQueryLexer(antlr.NewInputStream(query))
+	lexer.RemoveErrorListeners()
+	parser := grammar.NewFilterQueryParser(antlr.NewCommonTokenStream(lexer, 0))
+	parser.RemoveErrorListeners()
+	return parser.Query()
+}
+
+// filterSplitter walks the parse tree once, flattening the top-level AND chain and
+// routing each atom (a comparison, a NOT expression, or a whole multi-branch OR group)
+// to the span or having bucket by the class of the keys it references.
+type filterSplitter struct {
+	query          []rune
+	aggregateNames map[string]struct{}
+	span           []string
+	having         []string
+	mixed          bool
+}
+
+func (s *filterSplitter) visit(node antlr.Tree) {
+	switch n := node.(type) {
+	case *grammar.QueryContext:
+		if n.Expression() != nil {
+			s.visit(n.Expression())
+		}
+	case *grammar.ExpressionContext:
+		if n.OrExpression() != nil {
+			s.visit(n.OrExpression())
+		}
+	case *grammar.OrExpressionContext:
+		// a single branch is just an AND chain; multiple branches are a real OR, kept
+		// whole so a class-mixing OR can be rejected.
+		if ands := n.AllAndExpression(); len(ands) == 1 {
+			s.visit(ands[0])
+		} else {
+			s.route(n)
+		}
+	case *grammar.AndExpressionContext:
+		for _, u := range n.AllUnaryExpression() {
+			s.visit(u)
+		}
+	case *grammar.UnaryExpressionContext:
+		if n.NOT() != nil {
+			s.route(n)
+		} else if n.Primary() != nil {
+			s.visit(n.Primary())
+		}
+	case *grammar.PrimaryContext:
+		if n.OrExpression() != nil { // parenthesized sub-expression
+			s.visit(n.OrExpression())
+		} else {
+			s.route(n)
+		}
+	}
+}
+
+// route classifies an atom and appends its original source text to the right bucket.
+func (s *filterSplitter) route(atom antlr.ParserRuleContext) {
+	isTrace, isSpan := classifyKeys(atom, s.aggregateNames)
+	if isTrace && isSpan {
+		s.mixed = true
+		return
+	}
+	text := atomSourceText(s.query, atom)
+	// A multi-branch OR group's source slice excludes its enclosing parens (they belong
+	// to the parent Primary). Re-wrap it so rejoining a bucket with " AND " cannot invert
+	// OR/AND precedence, e.g. `a AND (b OR c)` must not flatten to `a AND b OR c`.
+	if or, ok := atom.(*grammar.OrExpressionContext); ok && len(or.AllAndExpression()) > 1 {
+		text = "(" + text + ")"
+	}
+	if isTrace {
+		s.having = append(s.having, text)
+	} else {
+		s.span = append(s.span, text)
+	}
+}
+
+// classifyKeys reports whether a subtree references trace-level and/or span-level keys.
+// A key is trace-level when it has no explicit field context and its name — after the
+// optional user-facing `trace.` prefix is stripped — is a known aggregate, or when it
+// carries the trace field context explicitly (`tracefield.`, which Normalize parses
+// into FieldContextTrace; no span field mapper resolves that context, so it can only
+// mean a trace-level aggregate — an unknown name is then rejected by the aggregate
+// validation with a targeted error instead of failing as an unknown span field). Any
+// other explicit context (`span.`, `resource.`, …) is span-level.
+func classifyKeys(node antlr.Tree, aggregateNames map[string]struct{}) (isTrace, isSpan bool) {
+	kc, ok := node.(*grammar.KeyContext)
+	if ok {
+		key := telemetrytypes.GetFieldKeyFromKeyText(kc.GetText())
+		switch key.FieldContext {
+		case telemetrytypes.FieldContextUnspecified:
+			// `trace.` is the user-facing prefix for trace-level aggregates. It is not a
+			// registered field context, so it stays on the name; strip it before matching.
+			name := strings.TrimPrefix(key.Name, telemetrytypes.FieldContextTrace.StringValue()+".")
+			_, isTrace = aggregateNames[name]
+			isSpan = !isTrace
+		case telemetrytypes.FieldContextTrace:
+			isTrace = true
+		default:
+			isSpan = true
+		}
+		return
+	}
+	for i := 0; i < node.GetChildCount(); i++ {
+		t, s := classifyKeys(node.GetChild(i), aggregateNames)
+		isTrace = isTrace || t
+		isSpan = isSpan || s
+	}
+	return
+}
+
+// atomSourceText returns the original source substring for an atom, preserving
+// whitespace. The token stream drops skipped whitespace, which would glue word
+// operators (OR/AND/NOT) to their operands, so slice the input by token offsets.
+// ANTLR offsets are rune indices (InputStream holds []rune), hence the rune slice.
+func atomSourceText(query []rune, atom antlr.ParserRuleContext) string {
+	start, stop := atom.GetStart(), atom.GetStop()
+	if start == nil || stop == nil || start.GetStart() < 0 || stop.GetStop() >= len(query) || stop.GetStop() < start.GetStart() {
+		return atom.GetText()
+	}
+	return string(query[start.GetStart() : stop.GetStop()+1])
+}

pkg/querybuilder/filter_split_test.go

@@ -0,0 +1,174 @@
+package querybuilder
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestSplitFilterForAggregates(t *testing.T) {
+	agg := map[string]struct{}{"completion_tokens": {}, "span_count": {}, "prompt_tokens": {}}
+
+	type tc struct {
+		name    string
+		query   string
+		span    string // expected span-level (WHERE) part; "" => empty
+		having  string // expected trace-level (HAVING) part; "" => empty
+		wantErr bool
+	}
+
+	cases := []tc{
+		// --- empty input ---------------------------------------------------------
+		{
+			name: "empty",
+		},
+		{
+			name:  "whitespace only",
+			query: "   ",
+		},
+
+		// --- single class --------------------------------------------------------
+		{
+			name:  "span only",
+			query: "service.name = 'x'",
+			span:  "service.name = 'x'",
+		},
+		{
+			name:   "agg only bare",
+			query:  "completion_tokens > 1000",
+			having: "completion_tokens > 1000",
+		},
+		{
+			// the user-facing `trace.` prefix marks a trace-level aggregate.
+			name:   "agg only trace prefix",
+			query:  "trace.completion_tokens > 1000",
+			having: "trace.completion_tokens > 1000",
+		},
+		{
+			// `tracefield.` is the explicit trace field context (Normalize parses it into
+			// FieldContextTrace), so it marks a trace-level aggregate like `trace.`.
+			name:   "agg only tracefield prefix",
+			query:  "tracefield.completion_tokens > 1000",
+			having: "tracefield.completion_tokens > 1000",
+		},
+		{
+			// an unknown name under the explicit trace context still routes trace-level,
+			// so the aggregate validation rejects it with a targeted error instead of the
+			// span path failing on an unknown field.
+			name:   "unknown agg under tracefield prefix stays trace-level",
+			query:  "tracefield.not_an_aggregate > 1000",
+			having: "tracefield.not_an_aggregate > 1000",
+		},
+
+		{
+			// ANTLR token offsets are rune indices; slicing must not shift after a
+			// multi-byte char (this used to truncate 1000 → 100).
+			name:   "unicode value before the split",
+			query:  "service.name = 'héllo' AND completion_tokens > 1000",
+			span:   "service.name = 'héllo'",
+			having: "completion_tokens > 1000",
+		},
+
+		// --- top-level AND splits across the two buckets -------------------------
+		{
+			name:   "span AND agg",
+			query:  "service.name = 'x' AND completion_tokens > 1000",
+			span:   "service.name = 'x'",
+			having: "completion_tokens > 1000",
+		},
+		{
+			// order within a bucket is preserved; the two span atoms join with AND.
+			name:   "span AND span AND agg",
+			query:  "service.name = 'x' AND kind_string = 'Internal' AND completion_tokens > 1000",
+			span:   "service.name = 'x' AND kind_string = 'Internal'",
+			having: "completion_tokens > 1000",
+		},
+		{
+			// a parenthesized top-level AND still splits across the two buckets.
+			name:   "parenthesized span AND agg",
+			query:  "(service.name = 'x' AND completion_tokens > 1000)",
+			span:   "service.name = 'x'",
+			having: "completion_tokens > 1000",
+		},
+
+		// --- OR groups are re-wrapped in parens so a later AND-join can't invert
+		//     precedence (`a AND (b OR c)` must not flatten to `a AND b OR c`) ------
+		{
+			name:   "agg OR agg",
+			query:  "completion_tokens > 1000 OR span_count > 3",
+			having: "(completion_tokens > 1000 OR span_count > 3)",
+		},
+		{
+			name:  "span OR span",
+			query: "service.name = 'x' OR kind_string = 'Internal'",
+			span:  "(service.name = 'x' OR kind_string = 'Internal')",
+		},
+		{
+			name:  "span AND (span OR span)",
+			query: "service.name = 'x' AND (kind_string = 'Internal' OR kind_string = 'Client')",
+			span:  "service.name = 'x' AND (kind_string = 'Internal' OR kind_string = 'Client')",
+		},
+		{
+			name:   "agg AND (agg OR agg)",
+			query:  "prompt_tokens > 5 AND (completion_tokens > 1000 OR span_count > 3)",
+			having: "prompt_tokens > 5 AND (completion_tokens > 1000 OR span_count > 3)",
+		},
+		{
+			// the OR group routes to span, the trailing aggregate to having.
+			name:   "span AND (span OR span) AND agg",
+			query:  "a.b = 'x' AND (c.d = 'y' OR e.f = 'z') AND completion_tokens > 1000",
+			span:   "a.b = 'x' AND (c.d = 'y' OR e.f = 'z')",
+			having: "completion_tokens > 1000",
+		},
+
+		// --- a nested AND group flattens across the buckets (no spurious parens) --
+		{
+			name:   "(span AND agg) AND agg",
+			query:  "(service.name = 'x' AND completion_tokens > 1000) AND prompt_tokens > 5",
+			span:   "service.name = 'x'",
+			having: "completion_tokens > 1000 AND prompt_tokens > 5",
+		},
+
+		// --- NOT wrapping a single-class group is routed whole to that class ------
+		{
+			name:   "not agg",
+			query:  "NOT (completion_tokens > 1000)",
+			having: "NOT (completion_tokens > 1000)",
+		},
+		{
+			name:  "not span",
+			query: "NOT (service.name = 'x')",
+			span:  "NOT (service.name = 'x')",
+		},
+
+		// --- class-mixing is rejected in an OR group, a NOT group, or a nested OR -
+		{
+			name:    "agg OR span rejected",
+			query:   "completion_tokens > 1000 OR service.name = 'x'",
+			wantErr: true,
+		},
+		{
+			name:    "not mixed rejected",
+			query:   "NOT (completion_tokens > 1000 AND service.name = 'x')",
+			wantErr: true,
+		},
+		{
+			name:    "span AND (agg OR span) rejected",
+			query:   "service.name = 'x' AND (completion_tokens > 1000 OR kind_string = 'Client')",
+			wantErr: true,
+		},
+	}
+
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			span, having, err := SplitFilterForAggregates(c.query, agg)
+			if c.wantErr {
+				require.Error(t, err)
+				return
+			}
+			require.NoError(t, err)
+			require.Equal(t, c.span, span, "span part")
+			require.Equal(t, c.having, having, "having part")
+		})
+	}
+}

pkg/querybuilder/having_rewriter.go

@@ -18,6 +18,19 @@ func NewHavingExpressionRewriter() *HavingExpressionRewriter {
 	}
 }
 
+// Rewrite rewrites and validates a HAVING expression against a caller-supplied
+// column map (user-facing name -> SQL identifier/expression). Values are inlined, so
+// the result is a bare SQL boolean expression with no bound args. Used by callers
+// that project their own aggregate columns (e.g. the AI trace list) rather than the
+// query's Aggregations.
+func (r *HavingExpressionRewriter) Rewrite(expression string, columnMap map[string]string) (string, error) {
+	if len(strings.TrimSpace(expression)) == 0 {
+		return "", nil
+	}
+	r.columnMap = columnMap
+	return r.rewriteAndValidate(expression)
+}
+
 // RewriteForTraces rewrites and validates the HAVING expression for a traces query.
 func (r *HavingExpressionRewriter) RewriteForTraces(expression string, aggregations []qbtypes.TraceAggregation) (string, error) {
 	if len(strings.TrimSpace(expression)) == 0 {

pkg/telemetryai/base_condition.go

@@ -0,0 +1,40 @@
+package telemetryai
+
+import (
+	"strings"
+
+	scopedtraces "github.com/SigNoz/signoz/pkg/telemetryscopedtraces"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+)
+
+// genAIBaseConditionProvider: an AI trace has >=1 gen_ai LLM, tool, or agent span.
+type genAIBaseConditionProvider struct {
+	keys []string
+}
+
+var _ scopedtraces.BaseConditionProvider = (*genAIBaseConditionProvider)(nil)
+
+func NewGenAIBaseConditionProvider() scopedtraces.BaseConditionProvider {
+	return &genAIBaseConditionProvider{
+		keys: []string{telemetrytypes.GenAIRequestModel, telemetrytypes.GenAIToolName, telemetrytypes.GenAIAgentName},
+	}
+}
+
+func (p *genAIBaseConditionProvider) FilterExpression() string {
+	parts := make([]string, 0, len(p.keys))
+	for _, k := range p.keys {
+		parts = append(parts, k+" EXISTS")
+	}
+	return strings.Join(parts, " OR ")
+}
+
+func (p *genAIBaseConditionProvider) FieldKeys() []*telemetrytypes.TelemetryFieldKey {
+	// Definitions come from GenAIFieldDefinitions so they can't drift from the
+	// canonical semconv keys; copy to take the address.
+	keys := make([]*telemetrytypes.TelemetryFieldKey, 0, len(p.keys))
+	for _, k := range p.keys {
+		def := telemetrytypes.GenAIFieldDefinitions[k]
+		keys = append(keys, &def)
+	}
+	return keys
+}

pkg/telemetryai/columns.go

@@ -0,0 +1,64 @@
+package telemetryai
+
+import (
+	scopedtraces "github.com/SigNoz/signoz/pkg/telemetryscopedtraces"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+)
+
+// genAIColumnProvider adds AI/LLM per-trace metrics on top of the common columns.
+type genAIColumnProvider struct{}
+
+var _ scopedtraces.ColumnProvider = (*genAIColumnProvider)(nil)
+
+func NewGenAIColumnProvider() scopedtraces.ColumnProvider {
+	return &genAIColumnProvider{}
+}
+
+func (genAIColumnProvider) Columns() []scopedtraces.TraceColumn {
+	defs := telemetrytypes.GenAIFieldDefinitions
+	reqModel := defs[telemetrytypes.GenAIRequestModel]
+	toolName := defs[telemetrytypes.GenAIToolName]
+	inTok := defs[telemetrytypes.GenAIUsageInputTokens]
+	outTok := defs[telemetrytypes.GenAIUsageOutputTokens]
+	cost := defs[telemetrytypes.SignozGenAITotalCost]
+	inMsg := defs[telemetrytypes.GenAIInputMessages]
+	outMsg := defs[telemetrytypes.GenAIOutputMessages]
+
+	str := telemetrytypes.FieldDataTypeString
+	return append(scopedtraces.CommonTraceColumns(),
+		// LLM calls only (request model present), not the full gate.
+		scopedtraces.TraceColumn{Alias: "llm_call_count", Orderable: true, Expr: scopedtraces.CountExists(&reqModel)},
+		scopedtraces.TraceColumn{Alias: "tool_call_count", Orderable: true, Expr: scopedtraces.CountExists(&toolName)},
+		scopedtraces.TraceColumn{Alias: "distinct_tool_count", Orderable: true, Expr: scopedtraces.UniqCount(&toolName, str)},
+		// tokens live only on LLM spans, so a plain sum needs no gate scoping.
+		scopedtraces.TraceColumn{Alias: "input_tokens", Orderable: true, Expr: scopedtraces.Reduce(scopedtraces.AggSum, &inTok)},
+		scopedtraces.TraceColumn{Alias: "output_tokens", Orderable: true, Expr: scopedtraces.Reduce(scopedtraces.AggSum, &outTok)},
+		scopedtraces.TraceColumn{Alias: "total_tokens", Orderable: true, Expr: scopedtraces.SumOfKeys(telemetrytypes.FieldDataTypeFloat64, &inTok, &outTok)},
+		// per-span cost attached by the SigNoz LLM pricing processor.
+		scopedtraces.TraceColumn{Alias: "estimated_cost_usd", Orderable: true, Expr: scopedtraces.Reduce(scopedtraces.AggSum, &cost)},
+		// slowest single LLM call in the trace.
+		scopedtraces.TraceColumn{Alias: "max_llm_latency_ns", Orderable: true, Expr: scopedtraces.ScopedToKeyColumn(scopedtraces.AggMax, "duration_nano", &reqModel)},
+		// errors across the whole trace (any span), so display-only.
+		scopedtraces.TraceColumn{Alias: "error_count", Expr: scopedtraces.PredicateCount("has_error = true")},
+		// timestamp of the last gen_ai span (LLM/tool/agent), hence gate-scoped.
+		scopedtraces.TraceColumn{Alias: "last_activity_time", Orderable: true, Expr: scopedtraces.ScopedReduce(scopedtraces.AggMax, "timestamp")},
+		// previews: first call's input (the prompt), last call's output (the answer).
+		scopedtraces.TraceColumn{Alias: "input", SpanLevel: true, Expr: scopedtraces.PickBy(&inMsg, str, "timestamp", scopedtraces.PickEarliest)},
+		scopedtraces.TraceColumn{Alias: "output", SpanLevel: true, Expr: scopedtraces.PickBy(&outMsg, str, "timestamp", scopedtraces.PickLatest)},
+	)
+}
+
+func (genAIColumnProvider) DefaultOrderAlias() string { return "last_activity_time" }
+
+func (p genAIColumnProvider) AggregateAliases() []string {
+	// Derived from Columns() so a new column can't be forgotten; SpanLevel columns
+	// are filtered span-level, so skip them.
+	cols := p.Columns()
+	aliases := make([]string, 0, len(cols))
+	for _, c := range cols {
+		if !c.SpanLevel {
+			aliases = append(aliases, c.Alias)
+		}
+	}
+	return aliases
+}

pkg/telemetryai/statement_builder.go

@@ -0,0 +1,26 @@
+package telemetryai
+
+import (
+	"github.com/SigNoz/signoz/pkg/factory"
+	"github.com/SigNoz/signoz/pkg/flagger"
+	scopedtraces "github.com/SigNoz/signoz/pkg/telemetryscopedtraces"
+	"github.com/SigNoz/signoz/pkg/telemetrystore"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+)
+
+// NewAITraceStatementBuilder wires the generic scoped-trace builder with the gen_ai
+// gate and AI columns. This package holds only gen_ai domain knowledge; the query
+// topology lives in telemetryscopedtraces.
+func NewAITraceStatementBuilder(
+	settings factory.ProviderSettings,
+	metadataStore telemetrytypes.MetadataStore,
+	baseCond scopedtraces.BaseConditionProvider,
+	traceStmtBuilder qbtypes.StatementBuilder[qbtypes.TraceAggregation],
+	telemetryStore telemetrystore.TelemetryStore,
+	fl flagger.Flagger,
+	skipResourceFingerprintEnable bool,
+	skipResourceFingerprintThreshold uint64,
+) qbtypes.StatementBuilder[qbtypes.TraceAggregation] {
+	return scopedtraces.NewScopedTraceStatementBuilder(settings, metadataStore, baseCond, NewGenAIColumnProvider(), traceStmtBuilder, telemetryStore, fl, skipResourceFingerprintEnable, skipResourceFingerprintThreshold)
+}

pkg/telemetryai/statement_builder_test.go

@@ -0,0 +1,952 @@
+package telemetryai
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
+	"github.com/SigNoz/signoz/pkg/instrumentation/instrumentationtest"
+	"github.com/SigNoz/signoz/pkg/querybuilder"
+	scopedtraces "github.com/SigNoz/signoz/pkg/telemetryscopedtraces"
+	"github.com/SigNoz/signoz/pkg/telemetrytraces"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes/telemetrytypestest"
+	"github.com/stretchr/testify/require"
+)
+
+// otelKeysMap seeds the OpenTelemetry gen_ai semantic-convention keys the AI
+// queries reference, so the metadata-backed field resolution succeeds in tests.
+func otelKeysMap() map[string][]*telemetrytypes.TelemetryFieldKey {
+	strKey := func(name string) *telemetrytypes.TelemetryFieldKey {
+		return &telemetrytypes.TelemetryFieldKey{
+			Name:          name,
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextAttribute,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}
+	}
+	numKey := func(name string) *telemetrytypes.TelemetryFieldKey {
+		return &telemetrytypes.TelemetryFieldKey{
+			Name:          name,
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextAttribute,
+			FieldDataType: telemetrytypes.FieldDataTypeFloat64,
+		}
+	}
+
+	m := make(map[string][]*telemetrytypes.TelemetryFieldKey)
+
+	// gen_ai semconv keys sourced from the single source of truth, mirroring what the
+	// production metadata store surfaces via enrichWithGenAIKeys.
+	for name, def := range telemetrytypes.GenAIFieldDefinitions {
+		keyCopy := def
+		m[name] = []*telemetrytypes.TelemetryFieldKey{&keyCopy}
+	}
+
+	// Extra keys these tests reference that aren't gen_ai semconv definitions.
+	m["gen_ai.user.id"] = []*telemetrytypes.TelemetryFieldKey{strKey("gen_ai.user.id")}
+	m["_signoz.gen_ai.total_cost"] = []*telemetrytypes.TelemetryFieldKey{numKey("_signoz.gen_ai.total_cost")}
+	m["gen_ai.usage.cached_input_tokens"] = []*telemetrytypes.TelemetryFieldKey{numKey("gen_ai.usage.cached_input_tokens")}
+	m["has_error"] = []*telemetrytypes.TelemetryFieldKey{{
+		Name:          "has_error",
+		Signal:        telemetrytypes.SignalTraces,
+		FieldContext:  telemetrytypes.FieldContextSpan,
+		FieldDataType: telemetrytypes.FieldDataTypeBool,
+	}}
+	return m
+}
+
+// standard test window (ms), matching the traces builder tests.
+const (
+	testStartMs = uint64(1747947419000)
+	testEndMs   = uint64(1747983448000)
+)
+
+func newTestBuilder(t *testing.T) qbtypes.StatementBuilder[qbtypes.TraceAggregation] {
+	return newTestBuilderWithKeys(t, otelKeysMap())
+}
+
+// newTestBuilderWithKeys mirrors the production wiring in signozquerier's provider.
+// The gen_ai keys are seeded via keysMap here; in production the metadata store
+// surfaces them itself (enrichWithGenAIKeys).
+func newTestBuilderWithKeys(t *testing.T, keysMap map[string][]*telemetrytypes.TelemetryFieldKey) qbtypes.StatementBuilder[qbtypes.TraceAggregation] {
+	t.Helper()
+	settings := instrumentationtest.New().ToProviderSettings()
+	fm := telemetrytraces.NewFieldMapper()
+	cb := telemetrytraces.NewConditionBuilder(fm)
+	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
+	mockMetadataStore.KeysMap = keysMap
+	fl := flaggertest.New(t)
+	baseCond := NewGenAIBaseConditionProvider()
+	// In production the metadata store enriches gen_ai keys (enrichWithGenAIKeys);
+	// here the mock is seeded directly via keysMap.
+	metadataStore := telemetrytypes.MetadataStore(mockMetadataStore)
+	rewriter := querybuilder.NewAggExprRewriter(settings, nil, fm, cb, nil, fl)
+	traceStmtBuilder := telemetrytraces.NewTraceQueryStatementBuilder(
+		settings,
+		metadataStore,
+		fm,
+		cb,
+		rewriter,
+		nil,
+		fl,
+		false,
+		100000,
+	)
+	return NewAITraceStatementBuilder(
+		settings,
+		metadataStore,
+		baseCond,
+		traceStmtBuilder,
+		nil, // telemetryStore: only used by the skip-fingerprint count query, which is disabled here
+		fl,
+		false,
+		100000,
+	)
+}
+
+// ---------------------------------------------------------------------------
+// Full-query golden tests
+//
+// Each pins the WHOLE generated statement, with bound args inlined into the `?`
+// placeholders, as ONE self-contained literal — so a failure diff shows the entire
+// query and the expected SQL can be copied straight into a ClickHouse client. The
+// `want` strings are formatted for readability; the comparison is whitespace- and
+// backtick-insensitive (see normalizeSQL), so only the SQL tokens themselves matter.
+//
+// The four trace-list goldens cover the corners of how `matched` is assembled —
+// {no span filter, span filter} × {no aggregate filter, aggregate filter} — plus a
+// mixed filter + multi-key order, plus the delegated span list. Note `matched` selects
+// only the aggregates ORDER BY / HAVING reference; the rest appear only in enrichment.
+//
+// Run `go test ./pkg/telemetryai/ -run TestBuild_FullSQL -v` to also print each query.
+// ---------------------------------------------------------------------------
+
+// renderSQL substitutes bound args into the `?` placeholders so the whole statement
+// reads as one literal SQL string.
+func renderSQL(t *testing.T, stmt *qbtypes.Statement) string {
+	t.Helper()
+	var b strings.Builder
+	argi := 0
+	for i := 0; i < len(stmt.Query); i++ {
+		if stmt.Query[i] == '?' {
+			require.Less(t, argi, len(stmt.Args), "more ? than args in query")
+			b.WriteString(formatArg(stmt.Args[argi]))
+			argi++
+			continue
+		}
+		b.WriteByte(stmt.Query[i])
+	}
+	require.Equal(t, len(stmt.Args), argi, "arg count does not match number of placeholders")
+	return b.String()
+}
+
+func formatArg(a any) string {
+	if s, ok := a.(string); ok {
+		return "'" + s + "'"
+	}
+	return fmt.Sprintf("%v", a)
+}
+
+// normalizeSQL makes the comparison insensitive to formatting: it drops identifier
+// backticks, collapses whitespace runs to a single space, and removes spaces directly
+// inside parentheses. This lets the golden strings be freely indented/wrapped (and
+// written as Go raw literals, which cannot contain backticks) — only the SQL tokens
+// and their order matter.
+func normalizeSQL(s string) string {
+	s = strings.Join(strings.Fields(strings.ReplaceAll(s, "`", "")), " ")
+	s = strings.ReplaceAll(s, "( ", "(")
+	s = strings.ReplaceAll(s, " )", ")")
+	return s
+}
+
+func requireSQLEqual(t *testing.T, want string, stmt *qbtypes.Statement) {
+	t.Helper()
+	got := renderSQL(t, stmt)
+	t.Logf("\n%s", got)
+	require.Equal(t, normalizeSQL(want), normalizeSQL(got))
+}
+
+// No filter: matched selects only the default order key (last_activity_time), WHERE is
+// just window + gate mask, no HAVING.
+func TestBuild_FullSQL_TraceList_NoFilter(t *testing.T) {
+	b := newTestBuilder(t)
+	stmt, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace,
+		qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+			Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI, Limit: 20,
+		}, nil)
+	require.NoError(t, err)
+
+	requireSQLEqual(t, `
+WITH matched AS (
+    SELECT trace_id,
+        maxIf(timestamp, (mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)) AS last_activity_time
+    FROM signoz_traces.distributed_signoz_index_v3
+    WHERE timestamp >= '1747947419000000000'
+      AND timestamp < '1747983448000000000'
+      AND ts_bucket_start >= 1747945619
+      AND ts_bucket_start <= 1747983448
+      AND ((mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true))
+    GROUP BY trace_id
+    ORDER BY last_activity_time DESC, trace_id DESC
+    LIMIT 20
+),
+ranked AS (
+    SELECT trace_id, min(start) AS t_start, max(end) AS t_end
+    FROM signoz_traces.distributed_trace_summary
+    WHERE trace_id GLOBAL IN (SELECT trace_id FROM matched)
+      AND end >= fromUnixTimestamp64Nano(1747947419000000000)
+      AND start < fromUnixTimestamp64Nano(1747983448000000000)
+    GROUP BY trace_id
+),
+buckets AS (
+    SELECT DISTINCT b AS ts_bucket
+    FROM ranked
+    ARRAY JOIN range(toUInt64(intDiv(toUnixTimestamp(t_start), 1800) * 1800 - 1800), toUInt64(intDiv(toUnixTimestamp(t_end), 1800) * 1800 + 1800), 1800) AS b
+)
+SELECT trace_id,
+    min(timestamp) AS start_time,
+    max(timestamp) AS end_time,
+    (max(toUnixTimestamp64Nano(timestamp) + duration_nano) - min(toUnixTimestamp64Nano(timestamp))) AS duration_nano,
+    count() AS span_count,
+    anyIf(name, parent_span_id = '') AS root_span_name,
+    any(resource_string_service$$name) AS service.name,
+    countIf(mapContains(attributes_string, 'gen_ai.request.model') = true) AS llm_call_count,
+    countIf(mapContains(attributes_string, 'gen_ai.tool.name') = true) AS tool_call_count,
+    uniqIf(multiIf(mapContains(attributes_string, 'gen_ai.tool.name') = true, attributes_string['gen_ai.tool.name'], NULL), mapContains(attributes_string, 'gen_ai.tool.name') = true) AS distinct_tool_count,
+    sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.input_tokens') = true, toFloat64(attributes_number['gen_ai.usage.input_tokens']), NULL)) AS input_tokens,
+    sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)) AS output_tokens,
+    coalesce(sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.input_tokens') = true, toFloat64(attributes_number['gen_ai.usage.input_tokens']), NULL)), 0) + coalesce(sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)), 0) AS total_tokens,
+    sum(multiIf(mapContains(attributes_number, '_signoz.gen_ai.total_cost') = true, toFloat64(attributes_number['_signoz.gen_ai.total_cost']), NULL)) AS estimated_cost_usd,
+    maxIf(signoz_traces.distributed_signoz_index_v3.duration_nano, mapContains(attributes_string, 'gen_ai.request.model') = true) AS max_llm_latency_ns,
+    countIf(has_error = true) AS error_count,
+    maxIf(timestamp, (mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)) AS last_activity_time,
+    argMinIf(multiIf(mapContains(attributes_string, 'gen_ai.input.messages') = true, attributes_string['gen_ai.input.messages'], NULL), timestamp, mapContains(attributes_string, 'gen_ai.input.messages') = true) AS input,
+    argMaxIf(multiIf(mapContains(attributes_string, 'gen_ai.output.messages') = true, attributes_string['gen_ai.output.messages'], NULL), timestamp, mapContains(attributes_string, 'gen_ai.output.messages') = true) AS output
+FROM signoz_traces.distributed_signoz_index_v3
+WHERE ts_bucket_start GLOBAL IN (SELECT ts_bucket FROM buckets)
+  AND trace_id GLOBAL IN (SELECT trace_id FROM ranked)
+GROUP BY trace_id
+ORDER BY last_activity_time DESC, trace_id DESC
+SETTINGS distributed_product_mode='allow', max_memory_usage=10000000000
+`, stmt)
+}
+
+// Promotion: a materialized gen_ai attribute must resolve to its materialized column
+// everywhere it appears — gate mask, countIf/scoped existence, and value columns —
+// while un-promoted attributes stay in the attributes map, so one query mixes both
+// forms. Here gen_ai.request.model and gen_ai.usage.input_tokens are materialized:
+// the gate/llm_call_count/max_llm_latency use `..._exists`, input_tokens/total_tokens
+// use the materialized value column, and tool/output_tokens/cost/messages stay in the map.
+func TestBuild_FullSQL_TraceList_MaterializedColumns(t *testing.T) {
+	keys := otelKeysMap()
+	for _, name := range []string{"gen_ai.request.model", "gen_ai.usage.input_tokens"} {
+		for _, k := range keys[name] {
+			k.Materialized = true
+		}
+	}
+	b := newTestBuilderWithKeys(t, keys)
+	stmt, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace,
+		qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+			Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI, Limit: 20,
+		}, nil)
+	require.NoError(t, err)
+
+	requireSQLEqual(t, `
+WITH matched AS (
+    SELECT trace_id,
+        maxIf(timestamp, (attribute_string_gen_ai$$request$$model_exists = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)) AS last_activity_time
+    FROM signoz_traces.distributed_signoz_index_v3
+    WHERE timestamp >= '1747947419000000000'
+      AND timestamp < '1747983448000000000'
+      AND ts_bucket_start >= 1747945619
+      AND ts_bucket_start <= 1747983448
+      AND ((attribute_string_gen_ai$$request$$model_exists = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true))
+    GROUP BY trace_id
+    ORDER BY last_activity_time DESC, trace_id DESC
+    LIMIT 20
+),
+ranked AS (
+    SELECT trace_id, min(start) AS t_start, max(end) AS t_end
+    FROM signoz_traces.distributed_trace_summary
+    WHERE trace_id GLOBAL IN (SELECT trace_id FROM matched)
+      AND end >= fromUnixTimestamp64Nano(1747947419000000000)
+      AND start < fromUnixTimestamp64Nano(1747983448000000000)
+    GROUP BY trace_id
+),
+buckets AS (
+    SELECT DISTINCT b AS ts_bucket
+    FROM ranked
+    ARRAY JOIN range(toUInt64(intDiv(toUnixTimestamp(t_start), 1800) * 1800 - 1800), toUInt64(intDiv(toUnixTimestamp(t_end), 1800) * 1800 + 1800), 1800) AS b
+)
+SELECT trace_id,
+    min(timestamp) AS start_time,
+    max(timestamp) AS end_time,
+    (max(toUnixTimestamp64Nano(timestamp) + duration_nano) - min(toUnixTimestamp64Nano(timestamp))) AS duration_nano,
+    count() AS span_count,
+    anyIf(name, parent_span_id = '') AS root_span_name,
+    any(resource_string_service$$name) AS service.name,
+    countIf(attribute_string_gen_ai$$request$$model_exists = true) AS llm_call_count,
+    countIf(mapContains(attributes_string, 'gen_ai.tool.name') = true) AS tool_call_count,
+    uniqIf(multiIf(mapContains(attributes_string, 'gen_ai.tool.name') = true, attributes_string['gen_ai.tool.name'], NULL), mapContains(attributes_string, 'gen_ai.tool.name') = true) AS distinct_tool_count,
+    sum(multiIf(attribute_number_gen_ai$$usage$$input_tokens_exists = true, toFloat64(attribute_number_gen_ai$$usage$$input_tokens), NULL)) AS input_tokens,
+    sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)) AS output_tokens,
+    coalesce(sum(multiIf(attribute_number_gen_ai$$usage$$input_tokens_exists = true, toFloat64(attribute_number_gen_ai$$usage$$input_tokens), NULL)), 0) + coalesce(sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)), 0) AS total_tokens,
+    sum(multiIf(mapContains(attributes_number, '_signoz.gen_ai.total_cost') = true, toFloat64(attributes_number['_signoz.gen_ai.total_cost']), NULL)) AS estimated_cost_usd,
+    maxIf(signoz_traces.distributed_signoz_index_v3.duration_nano, attribute_string_gen_ai$$request$$model_exists = true) AS max_llm_latency_ns,
+    countIf(has_error = true) AS error_count,
+    maxIf(timestamp, (attribute_string_gen_ai$$request$$model_exists = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)) AS last_activity_time,
+    argMinIf(multiIf(mapContains(attributes_string, 'gen_ai.input.messages') = true, attributes_string['gen_ai.input.messages'], NULL), timestamp, mapContains(attributes_string, 'gen_ai.input.messages') = true) AS input,
+    argMaxIf(multiIf(mapContains(attributes_string, 'gen_ai.output.messages') = true, attributes_string['gen_ai.output.messages'], NULL), timestamp, mapContains(attributes_string, 'gen_ai.output.messages') = true) AS output
+FROM signoz_traces.distributed_signoz_index_v3
+WHERE ts_bucket_start GLOBAL IN (SELECT ts_bucket FROM buckets)
+  AND trace_id GLOBAL IN (SELECT trace_id FROM ranked)
+GROUP BY trace_id
+ORDER BY last_activity_time DESC, trace_id DESC
+SETTINGS distributed_product_mode='allow', max_memory_usage=10000000000
+`, stmt)
+}
+
+// Span-level AND trace-level filter, order by the aggregate, pagination. matched selects
+// only output_tokens (the sole aggregate referenced by both ORDER BY and HAVING) — not
+// input_tokens/llm_call_count/last_activity_time. The span predicate widens the WHERE
+// prune and becomes a countIf(...) > 0 existence check alongside the gate countIf.
+func TestBuild_FullSQL_TraceList_SpanAndTraceFilter(t *testing.T) {
+	b := newTestBuilder(t)
+	stmt, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace,
+		qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+			Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI,
+			Filter: &qbtypes.Filter{Expression: "gen_ai.request.model = 'gpt-4o-mini' AND output_tokens > 1000"},
+			Order:  []qbtypes.OrderBy{{Key: qbtypes.OrderByKey{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{Name: "output_tokens"}}, Direction: qbtypes.OrderDirectionDesc}},
+			Limit:  10, Offset: 30,
+		}, nil)
+	require.NoError(t, err)
+
+	requireSQLEqual(t, `
+WITH matched AS (
+    SELECT trace_id,
+        sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)) AS output_tokens
+    FROM signoz_traces.distributed_signoz_index_v3
+    WHERE timestamp >= '1747947419000000000'
+      AND timestamp < '1747983448000000000'
+      AND ts_bucket_start >= 1747945619
+      AND ts_bucket_start <= 1747983448
+      AND ((mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)
+        OR (attributes_string['gen_ai.request.model'] = 'gpt-4o-mini' AND mapContains(attributes_string, 'gen_ai.request.model') = true))
+    GROUP BY trace_id
+    HAVING countIf((mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)) > 0
+        AND countIf((attributes_string['gen_ai.request.model'] = 'gpt-4o-mini' AND mapContains(attributes_string, 'gen_ai.request.model') = true)) > 0
+        AND output_tokens > 1000
+    ORDER BY output_tokens DESC, trace_id DESC
+    LIMIT 10 OFFSET 30
+),
+ranked AS (
+    SELECT trace_id, min(start) AS t_start, max(end) AS t_end
+    FROM signoz_traces.distributed_trace_summary
+    WHERE trace_id GLOBAL IN (SELECT trace_id FROM matched)
+      AND end >= fromUnixTimestamp64Nano(1747947419000000000)
+      AND start < fromUnixTimestamp64Nano(1747983448000000000)
+    GROUP BY trace_id
+),
+buckets AS (
+    SELECT DISTINCT b AS ts_bucket
+    FROM ranked
+    ARRAY JOIN range(toUInt64(intDiv(toUnixTimestamp(t_start), 1800) * 1800 - 1800), toUInt64(intDiv(toUnixTimestamp(t_end), 1800) * 1800 + 1800), 1800) AS b
+)
+SELECT trace_id,
+    min(timestamp) AS start_time,
+    max(timestamp) AS end_time,
+    (max(toUnixTimestamp64Nano(timestamp) + duration_nano) - min(toUnixTimestamp64Nano(timestamp))) AS duration_nano,
+    count() AS span_count,
+    anyIf(name, parent_span_id = '') AS root_span_name,
+    any(resource_string_service$$name) AS service.name,
+    countIf(mapContains(attributes_string, 'gen_ai.request.model') = true) AS llm_call_count,
+    countIf(mapContains(attributes_string, 'gen_ai.tool.name') = true) AS tool_call_count,
+    uniqIf(multiIf(mapContains(attributes_string, 'gen_ai.tool.name') = true, attributes_string['gen_ai.tool.name'], NULL), mapContains(attributes_string, 'gen_ai.tool.name') = true) AS distinct_tool_count,
+    sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.input_tokens') = true, toFloat64(attributes_number['gen_ai.usage.input_tokens']), NULL)) AS input_tokens,
+    sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)) AS output_tokens,
+    coalesce(sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.input_tokens') = true, toFloat64(attributes_number['gen_ai.usage.input_tokens']), NULL)), 0) + coalesce(sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)), 0) AS total_tokens,
+    sum(multiIf(mapContains(attributes_number, '_signoz.gen_ai.total_cost') = true, toFloat64(attributes_number['_signoz.gen_ai.total_cost']), NULL)) AS estimated_cost_usd,
+    maxIf(signoz_traces.distributed_signoz_index_v3.duration_nano, mapContains(attributes_string, 'gen_ai.request.model') = true) AS max_llm_latency_ns,
+    countIf(has_error = true) AS error_count,
+    maxIf(timestamp, (mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)) AS last_activity_time,
+    argMinIf(multiIf(mapContains(attributes_string, 'gen_ai.input.messages') = true, attributes_string['gen_ai.input.messages'], NULL), timestamp, mapContains(attributes_string, 'gen_ai.input.messages') = true) AS input,
+    argMaxIf(multiIf(mapContains(attributes_string, 'gen_ai.output.messages') = true, attributes_string['gen_ai.output.messages'], NULL), timestamp, mapContains(attributes_string, 'gen_ai.output.messages') = true) AS output
+FROM signoz_traces.distributed_signoz_index_v3
+WHERE ts_bucket_start GLOBAL IN (SELECT ts_bucket FROM buckets)
+  AND trace_id GLOBAL IN (SELECT trace_id FROM ranked)
+GROUP BY trace_id
+ORDER BY output_tokens DESC, trace_id DESC
+SETTINGS distributed_product_mode='allow', max_memory_usage=10000000000
+`, stmt)
+}
+
+// Aggregate-only filter (no span filter). WHERE prune is NOT widened, there is no
+// gate/span countIf, just the aggregate HAVING. `trace.output_tokens` rewrites to the
+// output_tokens alias. matched selects output_tokens (HAVING) + last_activity_time (default order).
+func TestBuild_FullSQL_TraceList_AggregateFilterOnly(t *testing.T) {
+	b := newTestBuilder(t)
+	stmt, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace,
+		qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+			Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI,
+			Filter: &qbtypes.Filter{Expression: "trace.output_tokens > 1000"},
+			Limit:  20,
+		}, nil)
+	require.NoError(t, err)
+
+	requireSQLEqual(t, `
+WITH matched AS (
+    SELECT trace_id,
+        sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)) AS output_tokens,
+        maxIf(timestamp, (mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)) AS last_activity_time
+    FROM signoz_traces.distributed_signoz_index_v3
+    WHERE timestamp >= '1747947419000000000'
+      AND timestamp < '1747983448000000000'
+      AND ts_bucket_start >= 1747945619
+      AND ts_bucket_start <= 1747983448
+      AND ((mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true))
+    GROUP BY trace_id
+    HAVING output_tokens > 1000
+    ORDER BY last_activity_time DESC, trace_id DESC
+    LIMIT 20
+),
+ranked AS (
+    SELECT trace_id, min(start) AS t_start, max(end) AS t_end
+    FROM signoz_traces.distributed_trace_summary
+    WHERE trace_id GLOBAL IN (SELECT trace_id FROM matched)
+      AND end >= fromUnixTimestamp64Nano(1747947419000000000)
+      AND start < fromUnixTimestamp64Nano(1747983448000000000)
+    GROUP BY trace_id
+),
+buckets AS (
+    SELECT DISTINCT b AS ts_bucket
+    FROM ranked
+    ARRAY JOIN range(toUInt64(intDiv(toUnixTimestamp(t_start), 1800) * 1800 - 1800), toUInt64(intDiv(toUnixTimestamp(t_end), 1800) * 1800 + 1800), 1800) AS b
+)
+SELECT trace_id,
+    min(timestamp) AS start_time,
+    max(timestamp) AS end_time,
+    (max(toUnixTimestamp64Nano(timestamp) + duration_nano) - min(toUnixTimestamp64Nano(timestamp))) AS duration_nano,
+    count() AS span_count,
+    anyIf(name, parent_span_id = '') AS root_span_name,
+    any(resource_string_service$$name) AS service.name,
+    countIf(mapContains(attributes_string, 'gen_ai.request.model') = true) AS llm_call_count,
+    countIf(mapContains(attributes_string, 'gen_ai.tool.name') = true) AS tool_call_count,
+    uniqIf(multiIf(mapContains(attributes_string, 'gen_ai.tool.name') = true, attributes_string['gen_ai.tool.name'], NULL), mapContains(attributes_string, 'gen_ai.tool.name') = true) AS distinct_tool_count,
+    sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.input_tokens') = true, toFloat64(attributes_number['gen_ai.usage.input_tokens']), NULL)) AS input_tokens,
+    sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)) AS output_tokens,
+    coalesce(sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.input_tokens') = true, toFloat64(attributes_number['gen_ai.usage.input_tokens']), NULL)), 0) + coalesce(sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)), 0) AS total_tokens,
+    sum(multiIf(mapContains(attributes_number, '_signoz.gen_ai.total_cost') = true, toFloat64(attributes_number['_signoz.gen_ai.total_cost']), NULL)) AS estimated_cost_usd,
+    maxIf(signoz_traces.distributed_signoz_index_v3.duration_nano, mapContains(attributes_string, 'gen_ai.request.model') = true) AS max_llm_latency_ns,
+    countIf(has_error = true) AS error_count,
+    maxIf(timestamp, (mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)) AS last_activity_time,
+    argMinIf(multiIf(mapContains(attributes_string, 'gen_ai.input.messages') = true, attributes_string['gen_ai.input.messages'], NULL), timestamp, mapContains(attributes_string, 'gen_ai.input.messages') = true) AS input,
+    argMaxIf(multiIf(mapContains(attributes_string, 'gen_ai.output.messages') = true, attributes_string['gen_ai.output.messages'], NULL), timestamp, mapContains(attributes_string, 'gen_ai.output.messages') = true) AS output
+FROM signoz_traces.distributed_signoz_index_v3
+WHERE ts_bucket_start GLOBAL IN (SELECT ts_bucket FROM buckets)
+  AND trace_id GLOBAL IN (SELECT trace_id FROM ranked)
+GROUP BY trace_id
+ORDER BY last_activity_time DESC, trace_id DESC
+SETTINGS distributed_product_mode='allow', max_memory_usage=10000000000
+`, stmt)
+}
+
+// Span-only filter (no aggregate filter). WHERE is widened; HAVING has the gate + span
+// countIf pair but no trailing aggregate. `has_error = true` resolves to a
+// materialized-column predicate (not a map access). matched selects only the default order key.
+func TestBuild_FullSQL_TraceList_SpanFilterOnly(t *testing.T) {
+	b := newTestBuilder(t)
+	stmt, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace,
+		qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+			Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI,
+			Filter: &qbtypes.Filter{Expression: "has_error = true"},
+			Limit:  20,
+		}, nil)
+	require.NoError(t, err)
+
+	requireSQLEqual(t, `
+WITH matched AS (
+    SELECT trace_id,
+        maxIf(timestamp, (mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)) AS last_activity_time
+    FROM signoz_traces.distributed_signoz_index_v3
+    WHERE timestamp >= '1747947419000000000'
+      AND timestamp < '1747983448000000000'
+      AND ts_bucket_start >= 1747945619
+      AND ts_bucket_start <= 1747983448
+      AND ((mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)
+        OR has_error = true)
+    GROUP BY trace_id
+    HAVING countIf((mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)) > 0
+        AND countIf(has_error = true) > 0
+    ORDER BY last_activity_time DESC, trace_id DESC
+    LIMIT 20
+),
+ranked AS (
+    SELECT trace_id, min(start) AS t_start, max(end) AS t_end
+    FROM signoz_traces.distributed_trace_summary
+    WHERE trace_id GLOBAL IN (SELECT trace_id FROM matched)
+      AND end >= fromUnixTimestamp64Nano(1747947419000000000)
+      AND start < fromUnixTimestamp64Nano(1747983448000000000)
+    GROUP BY trace_id
+),
+buckets AS (
+    SELECT DISTINCT b AS ts_bucket
+    FROM ranked
+    ARRAY JOIN range(toUInt64(intDiv(toUnixTimestamp(t_start), 1800) * 1800 - 1800), toUInt64(intDiv(toUnixTimestamp(t_end), 1800) * 1800 + 1800), 1800) AS b
+)
+SELECT trace_id,
+    min(timestamp) AS start_time,
+    max(timestamp) AS end_time,
+    (max(toUnixTimestamp64Nano(timestamp) + duration_nano) - min(toUnixTimestamp64Nano(timestamp))) AS duration_nano,
+    count() AS span_count,
+    anyIf(name, parent_span_id = '') AS root_span_name,
+    any(resource_string_service$$name) AS service.name,
+    countIf(mapContains(attributes_string, 'gen_ai.request.model') = true) AS llm_call_count,
+    countIf(mapContains(attributes_string, 'gen_ai.tool.name') = true) AS tool_call_count,
+    uniqIf(multiIf(mapContains(attributes_string, 'gen_ai.tool.name') = true, attributes_string['gen_ai.tool.name'], NULL), mapContains(attributes_string, 'gen_ai.tool.name') = true) AS distinct_tool_count,
+    sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.input_tokens') = true, toFloat64(attributes_number['gen_ai.usage.input_tokens']), NULL)) AS input_tokens,
+    sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)) AS output_tokens,
+    coalesce(sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.input_tokens') = true, toFloat64(attributes_number['gen_ai.usage.input_tokens']), NULL)), 0) + coalesce(sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)), 0) AS total_tokens,
+    sum(multiIf(mapContains(attributes_number, '_signoz.gen_ai.total_cost') = true, toFloat64(attributes_number['_signoz.gen_ai.total_cost']), NULL)) AS estimated_cost_usd,
+    maxIf(signoz_traces.distributed_signoz_index_v3.duration_nano, mapContains(attributes_string, 'gen_ai.request.model') = true) AS max_llm_latency_ns,
+    countIf(has_error = true) AS error_count,
+    maxIf(timestamp, (mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)) AS last_activity_time,
+    argMinIf(multiIf(mapContains(attributes_string, 'gen_ai.input.messages') = true, attributes_string['gen_ai.input.messages'], NULL), timestamp, mapContains(attributes_string, 'gen_ai.input.messages') = true) AS input,
+    argMaxIf(multiIf(mapContains(attributes_string, 'gen_ai.output.messages') = true, attributes_string['gen_ai.output.messages'], NULL), timestamp, mapContains(attributes_string, 'gen_ai.output.messages') = true) AS output
+FROM signoz_traces.distributed_signoz_index_v3
+WHERE ts_bucket_start GLOBAL IN (SELECT ts_bucket FROM buckets)
+  AND trace_id GLOBAL IN (SELECT trace_id FROM ranked)
+GROUP BY trace_id
+ORDER BY last_activity_time DESC, trace_id DESC
+SETTINGS distributed_product_mode='allow', max_memory_usage=10000000000
+`, stmt)
+}
+
+// Resource filter: a resource attribute in the filter is pulled into a __resource_filter
+// CTE (fingerprints matching the resource condition), and the `matched` scan is narrowed
+// by `resource_fingerprint GLOBAL IN (…)`. The resource key is dropped from the span
+// predicate (skipResourceFilter), so here there is no span-level existence check — the
+// prune stays the gate mask and the whole match is scoped to the resource fingerprints.
+func TestBuild_FullSQL_TraceList_ResourceFilter(t *testing.T) {
+	keys := otelKeysMap()
+	keys["service.name"] = []*telemetrytypes.TelemetryFieldKey{{
+		Name:          "service.name",
+		Signal:        telemetrytypes.SignalTraces,
+		FieldContext:  telemetrytypes.FieldContextResource,
+		FieldDataType: telemetrytypes.FieldDataTypeString,
+	}}
+	b := newTestBuilderWithKeys(t, keys)
+	stmt, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace,
+		qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+			Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI,
+			Filter: &qbtypes.Filter{Expression: "resource.service.name = 'checkout'"},
+			Limit:  20,
+		}, nil)
+	require.NoError(t, err)
+
+	requireSQLEqual(t, `
+WITH __resource_filter AS (
+    SELECT fingerprint
+    FROM signoz_traces.distributed_traces_v3_resource
+    WHERE (simpleJSONExtractString(labels, 'service.name') = 'checkout' AND labels LIKE '%service.name%' AND labels LIKE '%service.name":"checkout%')
+      AND seen_at_ts_bucket_start >= 1747945619
+      AND seen_at_ts_bucket_start <= 1747983448
+    GROUP BY fingerprint
+),
+matched AS (
+    SELECT trace_id,
+        maxIf(timestamp, (mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)) AS last_activity_time
+    FROM signoz_traces.distributed_signoz_index_v3
+    WHERE timestamp >= '1747947419000000000'
+      AND timestamp < '1747983448000000000'
+      AND ts_bucket_start >= 1747945619
+      AND ts_bucket_start <= 1747983448
+      AND ((mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true))
+      AND resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter)
+    GROUP BY trace_id
+    ORDER BY last_activity_time DESC, trace_id DESC
+    LIMIT 20
+),
+ranked AS (
+    SELECT trace_id, min(start) AS t_start, max(end) AS t_end
+    FROM signoz_traces.distributed_trace_summary
+    WHERE trace_id GLOBAL IN (SELECT trace_id FROM matched)
+      AND end >= fromUnixTimestamp64Nano(1747947419000000000)
+      AND start < fromUnixTimestamp64Nano(1747983448000000000)
+    GROUP BY trace_id
+),
+buckets AS (
+    SELECT DISTINCT b AS ts_bucket
+    FROM ranked
+    ARRAY JOIN range(toUInt64(intDiv(toUnixTimestamp(t_start), 1800) * 1800 - 1800), toUInt64(intDiv(toUnixTimestamp(t_end), 1800) * 1800 + 1800), 1800) AS b
+)
+SELECT trace_id,
+    min(timestamp) AS start_time,
+    max(timestamp) AS end_time,
+    (max(toUnixTimestamp64Nano(timestamp) + duration_nano) - min(toUnixTimestamp64Nano(timestamp))) AS duration_nano,
+    count() AS span_count,
+    anyIf(name, parent_span_id = '') AS root_span_name,
+    any(resource_string_service$$name) AS service.name,
+    countIf(mapContains(attributes_string, 'gen_ai.request.model') = true) AS llm_call_count,
+    countIf(mapContains(attributes_string, 'gen_ai.tool.name') = true) AS tool_call_count,
+    uniqIf(multiIf(mapContains(attributes_string, 'gen_ai.tool.name') = true, attributes_string['gen_ai.tool.name'], NULL), mapContains(attributes_string, 'gen_ai.tool.name') = true) AS distinct_tool_count,
+    sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.input_tokens') = true, toFloat64(attributes_number['gen_ai.usage.input_tokens']), NULL)) AS input_tokens,
+    sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)) AS output_tokens,
+    coalesce(sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.input_tokens') = true, toFloat64(attributes_number['gen_ai.usage.input_tokens']), NULL)), 0) + coalesce(sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)), 0) AS total_tokens,
+    sum(multiIf(mapContains(attributes_number, '_signoz.gen_ai.total_cost') = true, toFloat64(attributes_number['_signoz.gen_ai.total_cost']), NULL)) AS estimated_cost_usd,
+    maxIf(signoz_traces.distributed_signoz_index_v3.duration_nano, mapContains(attributes_string, 'gen_ai.request.model') = true) AS max_llm_latency_ns,
+    countIf(has_error = true) AS error_count,
+    maxIf(timestamp, (mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)) AS last_activity_time,
+    argMinIf(multiIf(mapContains(attributes_string, 'gen_ai.input.messages') = true, attributes_string['gen_ai.input.messages'], NULL), timestamp, mapContains(attributes_string, 'gen_ai.input.messages') = true) AS input,
+    argMaxIf(multiIf(mapContains(attributes_string, 'gen_ai.output.messages') = true, attributes_string['gen_ai.output.messages'], NULL), timestamp, mapContains(attributes_string, 'gen_ai.output.messages') = true) AS output
+FROM signoz_traces.distributed_signoz_index_v3
+WHERE ts_bucket_start GLOBAL IN (SELECT ts_bucket FROM buckets)
+  AND trace_id GLOBAL IN (SELECT trace_id FROM ranked)
+GROUP BY trace_id
+ORDER BY last_activity_time DESC, trace_id DESC
+SETTINGS distributed_product_mode='allow', max_memory_usage=10000000000
+`, stmt)
+}
+
+// Mixed filter (two span predicates AND'd into one existence check + an aggregate) with
+// a two-key order on different aggregates than the filter. matched selects input_tokens
+// + last_activity_time (ORDER BY) and output_tokens (HAVING) — three of four; llm_call_count is not.
+func TestBuild_FullSQL_TraceList_MixedFiltersMultiOrder(t *testing.T) {
+	b := newTestBuilder(t)
+	stmt, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace,
+		qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+			Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI,
+			Filter: &qbtypes.Filter{Expression: "gen_ai.request.model = 'gpt-4o' AND has_error = true AND output_tokens > 500"},
+			Order: []qbtypes.OrderBy{
+				{Key: qbtypes.OrderByKey{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{Name: "input_tokens"}}, Direction: qbtypes.OrderDirectionDesc},
+				{Key: qbtypes.OrderByKey{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{Name: "last_activity_time"}}, Direction: qbtypes.OrderDirectionAsc},
+			},
+			Limit: 15,
+		}, nil)
+	require.NoError(t, err)
+
+	requireSQLEqual(t, `
+WITH matched AS (
+    SELECT trace_id,
+        sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.input_tokens') = true, toFloat64(attributes_number['gen_ai.usage.input_tokens']), NULL)) AS input_tokens,
+        sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)) AS output_tokens,
+        maxIf(timestamp, (mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)) AS last_activity_time
+    FROM signoz_traces.distributed_signoz_index_v3
+    WHERE timestamp >= '1747947419000000000'
+      AND timestamp < '1747983448000000000'
+      AND ts_bucket_start >= 1747945619
+      AND ts_bucket_start <= 1747983448
+      AND ((mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)
+        OR ((attributes_string['gen_ai.request.model'] = 'gpt-4o' AND mapContains(attributes_string, 'gen_ai.request.model') = true) AND has_error = true))
+    GROUP BY trace_id
+    HAVING countIf((mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)) > 0
+        AND countIf(((attributes_string['gen_ai.request.model'] = 'gpt-4o' AND mapContains(attributes_string, 'gen_ai.request.model') = true) AND has_error = true)) > 0
+        AND output_tokens > 500
+    ORDER BY input_tokens DESC, last_activity_time ASC, trace_id DESC
+    LIMIT 15
+),
+ranked AS (
+    SELECT trace_id, min(start) AS t_start, max(end) AS t_end
+    FROM signoz_traces.distributed_trace_summary
+    WHERE trace_id GLOBAL IN (SELECT trace_id FROM matched)
+      AND end >= fromUnixTimestamp64Nano(1747947419000000000)
+      AND start < fromUnixTimestamp64Nano(1747983448000000000)
+    GROUP BY trace_id
+),
+buckets AS (
+    SELECT DISTINCT b AS ts_bucket
+    FROM ranked
+    ARRAY JOIN range(toUInt64(intDiv(toUnixTimestamp(t_start), 1800) * 1800 - 1800), toUInt64(intDiv(toUnixTimestamp(t_end), 1800) * 1800 + 1800), 1800) AS b
+)
+SELECT trace_id,
+    min(timestamp) AS start_time,
+    max(timestamp) AS end_time,
+    (max(toUnixTimestamp64Nano(timestamp) + duration_nano) - min(toUnixTimestamp64Nano(timestamp))) AS duration_nano,
+    count() AS span_count,
+    anyIf(name, parent_span_id = '') AS root_span_name,
+    any(resource_string_service$$name) AS service.name,
+    countIf(mapContains(attributes_string, 'gen_ai.request.model') = true) AS llm_call_count,
+    countIf(mapContains(attributes_string, 'gen_ai.tool.name') = true) AS tool_call_count,
+    uniqIf(multiIf(mapContains(attributes_string, 'gen_ai.tool.name') = true, attributes_string['gen_ai.tool.name'], NULL), mapContains(attributes_string, 'gen_ai.tool.name') = true) AS distinct_tool_count,
+    sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.input_tokens') = true, toFloat64(attributes_number['gen_ai.usage.input_tokens']), NULL)) AS input_tokens,
+    sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)) AS output_tokens,
+    coalesce(sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.input_tokens') = true, toFloat64(attributes_number['gen_ai.usage.input_tokens']), NULL)), 0) + coalesce(sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)), 0) AS total_tokens,
+    sum(multiIf(mapContains(attributes_number, '_signoz.gen_ai.total_cost') = true, toFloat64(attributes_number['_signoz.gen_ai.total_cost']), NULL)) AS estimated_cost_usd,
+    maxIf(signoz_traces.distributed_signoz_index_v3.duration_nano, mapContains(attributes_string, 'gen_ai.request.model') = true) AS max_llm_latency_ns,
+    countIf(has_error = true) AS error_count,
+    maxIf(timestamp, (mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)) AS last_activity_time,
+    argMinIf(multiIf(mapContains(attributes_string, 'gen_ai.input.messages') = true, attributes_string['gen_ai.input.messages'], NULL), timestamp, mapContains(attributes_string, 'gen_ai.input.messages') = true) AS input,
+    argMaxIf(multiIf(mapContains(attributes_string, 'gen_ai.output.messages') = true, attributes_string['gen_ai.output.messages'], NULL), timestamp, mapContains(attributes_string, 'gen_ai.output.messages') = true) AS output
+FROM signoz_traces.distributed_signoz_index_v3
+WHERE ts_bucket_start GLOBAL IN (SELECT ts_bucket FROM buckets)
+  AND trace_id GLOBAL IN (SELECT trace_id FROM ranked)
+GROUP BY trace_id
+ORDER BY input_tokens DESC, last_activity_time ASC, trace_id DESC
+SETTINGS distributed_product_mode='allow', max_memory_usage=10000000000
+`, stmt)
+}
+
+// Span list (requestType raw): delegated to the traces builder with the gate ANDed
+// into the user filter, so only gen_ai spans matching the filter come back. Standard
+// span columns, single SELECT (no CTE pipeline).
+func TestBuild_FullSQL_SpanList_Raw(t *testing.T) {
+	b := newTestBuilder(t)
+	stmt, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeRaw,
+		qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+			Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI,
+			Filter: &qbtypes.Filter{Expression: "gen_ai.request.model = 'gpt-4o-mini'"},
+			Limit:  10,
+		}, nil)
+	require.NoError(t, err)
+
+	requireSQLEqual(t, `
+SELECT timestamp AS timestamp, trace_id AS trace_id, span_id AS span_id,
+    trace_state AS trace_state, parent_span_id AS parent_span_id, flags AS flags,
+    name AS name, kind AS kind, kind_string AS kind_string, duration_nano AS duration_nano,
+    status_code AS status_code, status_message AS status_message,
+    status_code_string AS status_code_string, events AS events, links AS links,
+    response_status_code AS response_status_code, external_http_url AS external_http_url,
+    http_url AS http_url, external_http_method AS external_http_method,
+    http_method AS http_method, http_host AS http_host, db_name AS db_name,
+    db_operation AS db_operation, has_error AS has_error, is_remote AS is_remote,
+    attributes_string, attributes_number, attributes_bool, resources_string
+FROM signoz_traces.distributed_signoz_index_v3
+WHERE (((mapContains(attributes_string, 'gen_ai.request.model') = true
+        OR mapContains(attributes_string, 'gen_ai.tool.name') = true
+        OR mapContains(attributes_string, 'gen_ai.agent.name') = true))
+    AND ((attributes_string['gen_ai.request.model'] = 'gpt-4o-mini'
+        AND mapContains(attributes_string, 'gen_ai.request.model') = true)))
+  AND timestamp >= '1747947419000000000'
+  AND timestamp < '1747983448000000000'
+  AND ts_bucket_start >= 1747945619
+  AND ts_bucket_start <= 1747983448
+LIMIT 10
+`, stmt)
+}
+
+// ---------------------------------------------------------------------------
+// Behavior / branch tests not covered by the goldens above
+// ---------------------------------------------------------------------------
+
+// resourceKeysMap returns the gen_ai keys plus a resource-context service.name key so
+// resource.* filters route into the fingerprint CTE.
+func resourceKeysMap() map[string][]*telemetrytypes.TelemetryFieldKey {
+	keys := otelKeysMap()
+	keys["service.name"] = []*telemetrytypes.TelemetryFieldKey{{
+		Name:          "service.name",
+		Signal:        telemetrytypes.SignalTraces,
+		FieldContext:  telemetrytypes.FieldContextResource,
+		FieldDataType: telemetrytypes.FieldDataTypeString,
+	}}
+	return keys
+}
+
+// A filter mixing a resource attribute with a span-level and an aggregate condition:
+// the resource key routes into __resource_filter (fingerprint prune), the span key stays
+// as a countIf existence check, and the aggregate becomes a HAVING — all AND-combined.
+func TestBuild_TraceList_ResourcePlusSpanPlusAggregateFilter(t *testing.T) {
+	b := newTestBuilderWithKeys(t, resourceKeysMap())
+	stmt, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace,
+		qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+			Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI,
+			Filter: &qbtypes.Filter{Expression: "resource.service.name = 'checkout' AND has_error = true AND output_tokens > 1000"},
+			Limit:  10,
+		}, nil)
+	require.NoError(t, err)
+
+	got := renderSQL(t, stmt)
+	// resource condition -> fingerprint CTE + prune, not applied on the span index.
+	require.Contains(t, got, "__resource_filter AS (")
+	require.Contains(t, got, "resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter)")
+	require.NotContains(t, got, "resources_string['service.name']")
+	// span condition -> existence check in matched HAVING.
+	require.Contains(t, got, "countIf(has_error = true) > 0")
+	// aggregate condition -> HAVING on the matched aggregate alias.
+	require.Contains(t, got, "output_tokens")
+}
+
+// The resolver-unset (nil) fallback is covered in pkg/telemetryscopedtraces, which
+// can construct that builder state directly.
+
+// Trace-level and span-level predicates may not be OR-combined.
+func TestBuild_TraceList_TraceOrSpanMixRejected(t *testing.T) {
+	b := newTestBuilder(t)
+	query := qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+		Signal: telemetrytypes.SignalTraces,
+		Source: telemetrytypes.SourceAI,
+		Filter: &qbtypes.Filter{Expression: "trace.output_tokens > 1000 OR gen_ai.request.model = 'x'"},
+		Limit:  10,
+	}
+	_, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace, query, nil)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "cannot be combined")
+}
+
+// An output-only aggregate (span_count / duration_nano) can be displayed but not used
+// in the aggregate filter or ORDER BY — it is not computable in the matched pass.
+func TestBuild_TraceList_OutputOnlyAggregateRejected(t *testing.T) {
+	b := newTestBuilder(t)
+
+	// filter by span_count -> rejected
+	_, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace,
+		qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+			Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI,
+			Filter: &qbtypes.Filter{Expression: "span_count > 3"},
+		}, nil)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "span_count")
+
+	// order by duration_nano -> rejected
+	_, err = b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace,
+		qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+			Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI,
+			Order: []qbtypes.OrderBy{{Key: qbtypes.OrderByKey{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{Name: "duration_nano"}}, Direction: qbtypes.OrderDirectionDesc}},
+		}, nil)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "unsupported order key")
+}
+
+// A HAVING referencing a non-aggregate column is rejected.
+func TestBuild_TraceList_Having_UnknownColumn(t *testing.T) {
+	b := newTestBuilder(t)
+	query := qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+		Signal: telemetrytypes.SignalTraces,
+		Source: telemetrytypes.SourceAI,
+		Having: &qbtypes.Having{Expression: "service.name > 1"}, // not an aggregate column
+		Limit:  10,
+	}
+	_, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace, query, nil)
+	require.Error(t, err)
+}
+
+// Ordering by an unknown key is rejected.
+func TestBuild_TraceList_UnsupportedOrderKey(t *testing.T) {
+	b := newTestBuilder(t)
+	query := qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+		Signal: telemetrytypes.SignalTraces,
+		Source: telemetrytypes.SourceAI,
+		Order: []qbtypes.OrderBy{
+			{Key: qbtypes.OrderByKey{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{Name: "http.request.method"}}, Direction: qbtypes.OrderDirectionDesc},
+		},
+	}
+	_, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace, query, nil)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "unsupported order key")
+}
+
+// With no limit set, the builder applies the default of 100.
+func TestBuild_TraceList_DefaultLimit(t *testing.T) {
+	b := newTestBuilder(t)
+	query := qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+		Signal: telemetrytypes.SignalTraces,
+		Source: telemetrytypes.SourceAI,
+	}
+	stmt, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace, query, nil)
+	require.NoError(t, err)
+	require.Contains(t, stmt.Query, "LIMIT ?")
+	require.Contains(t, stmt.Args, 100)
+}
+
+// Only trace list and span list (raw) are supported; distribution is not.
+func TestBuild_UnsupportedRequestType(t *testing.T) {
+	b := newTestBuilder(t)
+	query := qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+		Signal: telemetrytypes.SignalTraces,
+		Source: telemetrytypes.SourceAI,
+		Aggregations: []qbtypes.TraceAggregation{
+			{Expression: "count()"},
+		},
+	}
+	_, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeDistribution, query, nil)
+	require.ErrorIs(t, err, scopedtraces.ErrUnsupportedRequestType)
+}
+
+// A gate key ingested under several data types (e.g. string + number from a
+// misbehaving SDK) contributes ALL variants to the mask, OR-combined — not just
+// the first — matching the standard visitor's EXISTS handling.
+func TestBuild_TraceList_MultiVariantGateKey(t *testing.T) {
+	keys := otelKeysMap()
+	keys[telemetrytypes.GenAIToolName] = append(keys[telemetrytypes.GenAIToolName], &telemetrytypes.TelemetryFieldKey{
+		Name:          telemetrytypes.GenAIToolName,
+		Signal:        telemetrytypes.SignalTraces,
+		FieldContext:  telemetrytypes.FieldContextAttribute,
+		FieldDataType: telemetrytypes.FieldDataTypeFloat64,
+	})
+	b := newTestBuilderWithKeys(t, keys)
+	stmt, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace,
+		qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+			Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI, Limit: 10,
+		}, nil)
+	require.NoError(t, err)
+
+	got := renderSQL(t, stmt)
+	require.Contains(t, got, "mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_number, 'gen_ai.tool.name') = true")
+}
+
+// `tracefield.` is the explicit trace field context, so in a filter it marks a
+// trace-level aggregate exactly like the user-facing `trace.` prefix — same statement,
+// and the same targeted rejection for a non-filterable aggregate. (Filter and Having
+// accept the same forms; the splitter used to misroute tracefield. as span-level.)
+func TestBuild_TraceList_TracefieldPrefixMatchesTracePrefix(t *testing.T) {
+	b := newTestBuilder(t)
+	build := func(expr string) (*qbtypes.Statement, error) {
+		return b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace,
+			qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+				Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI,
+				Filter: &qbtypes.Filter{Expression: expr},
+				Limit:  20,
+			}, nil)
+	}
+
+	viaTrace, err := build("trace.output_tokens > 1000")
+	require.NoError(t, err)
+	viaTracefield, err := build("tracefield.output_tokens > 1000")
+	require.NoError(t, err)
+	require.Equal(t, viaTrace.Query, viaTracefield.Query)
+	require.Equal(t, viaTrace.Args, viaTracefield.Args)
+
+	// output-only aggregate under tracefield. gets the aggregate rejection, not an
+	// unknown-span-field failure.
+	_, err = build("tracefield.span_count > 3")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "cannot be used")
+}
+
+// Query variables in a trace-level condition are substituted into the HAVING (the
+// span path binds them via PrepareWhereClause; the HAVING is a text rewrite).
+func TestBuild_TraceList_VariableInAggregateFilter(t *testing.T) {
+	b := newTestBuilder(t)
+	build := func(expr string, vars map[string]qbtypes.VariableItem) (*qbtypes.Statement, error) {
+		return b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeTrace,
+			qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+				Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI,
+				Filter: &qbtypes.Filter{Expression: expr},
+				Limit:  20,
+			}, vars)
+	}
+
+	// scalar variable -> literal in HAVING
+	stmt, err := build("trace.output_tokens > $threshold",
+		map[string]qbtypes.VariableItem{"threshold": {Value: 700}})
+	require.NoError(t, err)
+	require.Contains(t, stmt.Query, "HAVING output_tokens > 700")
+
+	// list variable with IN
+	stmt, err = build("trace.llm_call_count IN $counts",
+		map[string]qbtypes.VariableItem{"counts": {Value: []any{1, 2}}})
+	require.NoError(t, err)
+	require.Contains(t, stmt.Query, "HAVING llm_call_count IN")
+
+	// dynamic __all__ -> condition dropped, no HAVING at all
+	stmt, err = build("trace.output_tokens > $threshold",
+		map[string]qbtypes.VariableItem{"threshold": {Type: qbtypes.DynamicVariableType, Value: "__all__"}})
+	require.NoError(t, err)
+	require.NotContains(t, stmt.Query, "HAVING")
+
+	// unresolved variable -> rejected, not compared as a literal
+	_, err = build("trace.output_tokens > $missing", map[string]qbtypes.VariableItem{"other": {Value: 1}})
+	require.Error(t, err)
+}

pkg/telemetryai/trace_scope_test.go

@@ -0,0 +1,141 @@
+package telemetryai
+
+import (
+	"context"
+	"testing"
+
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/stretchr/testify/require"
+)
+
+// Span list with a mixed filter: gen_ai spans matching the span-level part, in
+// traces whose window-clipped aggregates satisfy the trace-level part (the
+// __trace_scope qualification on the delegated path).
+func TestBuild_FullSQL_SpanList_TraceScoped(t *testing.T) {
+	b := newTestBuilder(t)
+	stmt, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeRaw,
+		qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+			Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI,
+			Filter: &qbtypes.Filter{Expression: "gen_ai.request.model = 'gpt-4o-mini' AND trace.output_tokens > 1000"},
+			Limit:  10,
+		}, nil)
+	require.NoError(t, err)
+
+	requireSQLEqual(t, `
+WITH __trace_scope AS (
+    SELECT trace_id,
+        sum(multiIf(mapContains(attributes_number, 'gen_ai.usage.output_tokens') = true, toFloat64(attributes_number['gen_ai.usage.output_tokens']), NULL)) AS output_tokens
+    FROM signoz_traces.distributed_signoz_index_v3
+    WHERE timestamp >= '1747947419000000000'
+      AND timestamp < '1747983448000000000'
+      AND ts_bucket_start >= 1747945619
+      AND ts_bucket_start <= 1747983448
+      AND (mapContains(attributes_string, 'gen_ai.request.model') = true OR mapContains(attributes_string, 'gen_ai.tool.name') = true OR mapContains(attributes_string, 'gen_ai.agent.name') = true)
+    GROUP BY trace_id
+    HAVING output_tokens > 1000
+)
+SELECT timestamp AS timestamp, trace_id AS trace_id, span_id AS span_id,
+    trace_state AS trace_state, parent_span_id AS parent_span_id, flags AS flags,
+    name AS name, kind AS kind, kind_string AS kind_string, duration_nano AS duration_nano,
+    status_code AS status_code, status_message AS status_message,
+    status_code_string AS status_code_string, events AS events, links AS links,
+    response_status_code AS response_status_code, external_http_url AS external_http_url,
+    http_url AS http_url, external_http_method AS external_http_method,
+    http_method AS http_method, http_host AS http_host, db_name AS db_name,
+    db_operation AS db_operation, has_error AS has_error, is_remote AS is_remote,
+    attributes_string, attributes_number, attributes_bool, resources_string
+FROM signoz_traces.distributed_signoz_index_v3
+WHERE trace_id GLOBAL IN (SELECT trace_id FROM __trace_scope)
+  AND (((mapContains(attributes_string, 'gen_ai.request.model') = true
+        OR mapContains(attributes_string, 'gen_ai.tool.name') = true
+        OR mapContains(attributes_string, 'gen_ai.agent.name') = true))
+    AND ((attributes_string['gen_ai.request.model'] = 'gpt-4o-mini'
+        AND mapContains(attributes_string, 'gen_ai.request.model') = true)))
+  AND timestamp >= '1747947419000000000'
+  AND timestamp < '1747983448000000000'
+  AND ts_bucket_start >= 1747945619
+  AND ts_bucket_start <= 1747983448
+LIMIT 10
+`, stmt)
+}
+
+// Without a trace-level condition nothing changes: the span list stays a single
+// gated span scan (no __trace_scope CTE).
+func TestBuild_SpanList_NoTraceFilter_NoScope(t *testing.T) {
+	b := newTestBuilder(t)
+	stmt, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeRaw,
+		qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+			Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI,
+			Filter: &qbtypes.Filter{Expression: "gen_ai.request.model = 'gpt-4o-mini'"},
+			Limit:  10,
+		}, nil)
+	require.NoError(t, err)
+	require.NotContains(t, stmt.Query, "__trace_scope")
+}
+
+// The span-list trace-level filter shares the trace list's rules: output-only
+// aggregates are rejected, OR-mixing the two classes is rejected, and explicitly
+// trace-level order keys get a targeted error — while bare span columns that happen
+// to share a name with an aggregate alias (duration_nano) stay orderable.
+func TestBuild_SpanList_TraceFilter_Validation(t *testing.T) {
+	b := newTestBuilder(t)
+	build := func(q qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]) error {
+		q.Signal = telemetrytypes.SignalTraces
+		q.Source = telemetrytypes.SourceAI
+		_, err := b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeRaw, q, nil)
+		return err
+	}
+
+	err := build(qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+		Filter: &qbtypes.Filter{Expression: "trace.span_count > 3"},
+	})
+	require.ErrorContains(t, err, `aggregate "span_count" cannot be used`)
+
+	err = build(qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+		Filter: &qbtypes.Filter{Expression: "trace.output_tokens > 1000 OR kind_string = 'Client'"},
+	})
+	require.ErrorContains(t, err, "cannot be combined")
+
+	err = build(qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+		Order: []qbtypes.OrderBy{{Key: qbtypes.OrderByKey{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{Name: "trace.output_tokens"}}}},
+	})
+	require.ErrorContains(t, err, `ordering the span list by trace-level aggregate "trace.output_tokens" is not supported`)
+
+	err = build(qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+		Order: []qbtypes.OrderBy{{Key: qbtypes.OrderByKey{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{Name: "duration_nano"}}, Direction: qbtypes.OrderDirectionDesc}},
+		Limit: 10,
+	})
+	require.NoError(t, err, "bare duration_nano is a span column, not a trace-level key")
+}
+
+// Variables in a trace-level condition on the span list get the trace list's
+// treatment: substituted as literals, __all__ drops the condition (no scope CTE),
+// tracefield. spelling behaves like trace..
+func TestBuild_SpanList_TraceFilter_Variables(t *testing.T) {
+	b := newTestBuilder(t)
+	build := func(expr string, vars map[string]qbtypes.VariableItem) (*qbtypes.Statement, error) {
+		return b.Build(context.Background(), testStartMs, testEndMs, qbtypes.RequestTypeRaw,
+			qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+				Signal: telemetrytypes.SignalTraces, Source: telemetrytypes.SourceAI,
+				Filter: &qbtypes.Filter{Expression: expr},
+				Limit:  10,
+			}, vars)
+	}
+
+	stmt, err := build("trace.output_tokens > $threshold",
+		map[string]qbtypes.VariableItem{"threshold": {Value: 700}})
+	require.NoError(t, err)
+	require.Contains(t, stmt.Query, "HAVING output_tokens > 700")
+
+	stmt, err = build("trace.output_tokens > $threshold",
+		map[string]qbtypes.VariableItem{"threshold": {Type: qbtypes.DynamicVariableType, Value: "__all__"}})
+	require.NoError(t, err)
+	require.NotContains(t, stmt.Query, "__trace_scope")
+
+	viaTrace, err := build("trace.output_tokens > 1000", nil)
+	require.NoError(t, err)
+	viaTracefield, err := build("tracefield.output_tokens > 1000", nil)
+	require.NoError(t, err)
+	require.Equal(t, viaTrace.Query, viaTracefield.Query)
+}

pkg/telemetrymetadata/metadata.go

@@ -19,6 +19,7 @@ import (
 	"github.com/SigNoz/signoz/pkg/telemetrymetrics"
 	"github.com/SigNoz/signoz/pkg/telemetrystore"
 	"github.com/SigNoz/signoz/pkg/telemetrytraces"
+	"github.com/SigNoz/signoz/pkg/types/authtypes"
 	"github.com/SigNoz/signoz/pkg/types/ctxtypes"
 	"github.com/SigNoz/signoz/pkg/types/featuretypes"
 	"github.com/SigNoz/signoz/pkg/types/instrumentationtypes"
@@ -1190,6 +1191,45 @@ func enrichWithIntrinsicMetricKeys(keys map[string][]*telemetrytypes.TelemetryFi
 	return keys
 }
 
+// genAIEnrichmentEnabled reports whether the org in ctx has AI observability enabled.
+// The static gen_ai key definitions are surfaced (autocomplete + query-time resolution
+// before any gen_ai data is ingested) only for those orgs, so other tenants don't see
+// gen_ai keys in trace autocomplete. Contexts without claims (internal paths) resolve
+// to false — an org relying on enrichment has no gen_ai data ingested, so those paths
+// had nothing to resolve anyway.
+func (t *telemetryMetaStore) genAIEnrichmentEnabled(ctx context.Context) bool {
+	claims, err := authtypes.ClaimsFromContext(ctx)
+	if err != nil {
+		return false
+	}
+	orgID, err := valuer.NewUUID(claims.OrgID)
+	if err != nil {
+		return false
+	}
+	return t.fl.BooleanOrEmpty(ctx, flagger.FeatureEnableAIObservability, featuretypes.NewFlaggerEvaluationContext(orgID))
+}
+
+// enrichWithGenAIKeys adds keys that can be queried for GenAI signals, even though they have not been ingested yet.
+func enrichWithGenAIKeys(keys map[string][]*telemetrytypes.TelemetryFieldKey, selectors []*telemetrytypes.FieldKeySelector) map[string][]*telemetrytypes.TelemetryFieldKey {
+	for _, selector := range selectors {
+		if selector.Signal != telemetrytypes.SignalTraces && selector.Signal != telemetrytypes.SignalUnspecified {
+			continue
+		}
+		for name, def := range telemetrytypes.GenAIFieldDefinitions {
+			if len(keys[name]) > 0 {
+				continue // already resolved from ingested data
+			}
+			if !selectorMatchesIntrinsicField(selector, def) {
+				continue
+			}
+			keyCopy := def
+			keys[name] = []*telemetrytypes.TelemetryFieldKey{&keyCopy}
+		}
+	}
+
+	return keys
+}
+
 func selectorMatchesIntrinsicField(selector *telemetrytypes.FieldKeySelector, definition telemetrytypes.TelemetryFieldKey) bool {
 	if selector.FieldContext != telemetrytypes.FieldContextUnspecified && selector.FieldContext != definition.FieldContext {
 		return false
@@ -1275,6 +1315,9 @@ func (t *telemetryMetaStore) GetKeys(ctx context.Context, fieldKeySelector *tele
 
 	applyBackwardCompatibleKeys(mapOfKeys)
 	mapOfKeys = enrichWithIntrinsicMetricKeys(mapOfKeys, selectors)
+	if t.genAIEnrichmentEnabled(ctx) {
+		mapOfKeys = enrichWithGenAIKeys(mapOfKeys, selectors)
+	}
 
 	return mapOfKeys, complete, nil
 }
@@ -1353,6 +1396,9 @@ func (t *telemetryMetaStore) GetKeysMulti(ctx context.Context, fieldKeySelectors
 
 	applyBackwardCompatibleKeys(mapOfKeys)
 	mapOfKeys = enrichWithIntrinsicMetricKeys(mapOfKeys, fieldKeySelectors)
+	if t.genAIEnrichmentEnabled(ctx) {
+		mapOfKeys = enrichWithGenAIKeys(mapOfKeys, fieldKeySelectors)
+	}
 
 	return mapOfKeys, complete, nil
 }

pkg/telemetryscopedtraces/base_condition.go

@@ -0,0 +1,17 @@
+package telemetryscopedtraces
+
+import (
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+)
+
+// BaseConditionProvider defines which spans are in scope. It only declares the gate
+// (a filter expression + its field keys); the builder resolves the keys through the
+// field mapper, so attribute access stays materialization-aware.
+type BaseConditionProvider interface {
+	// FilterExpression is the grammar-level (EXISTS) gate, used on the delegated
+	// span-list path.
+	FilterExpression() string
+	// FieldKeys are the gate's keys, used to build the per-span mask
+	// (OR of resolved EXISTS conditions).
+	FieldKeys() []*telemetrytypes.TelemetryFieldKey
+}

pkg/telemetryscopedtraces/columns.go

@@ -0,0 +1,181 @@
+package telemetryscopedtraces
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/huandu/go-sqlbuilder"
+)
+
+// TraceColumn is one per-trace output column.
+type TraceColumn struct {
+	Alias string
+	// Orderable columns can be used in ORDER BY and the aggregate filter. All-span
+	// aggregates (span_count, duration_nano, …) are display-only and set false.
+	Orderable bool
+	// SpanLevel columns surface a real span/resource attribute (service.name,
+	// input/output messages); a filter on them is applied span-level, so they are
+	// excluded from AggregateAliases.
+	SpanLevel bool
+	Expr      Aggregate
+}
+
+// Aggregate renders one column's SQL and lists the attribute keys it references so
+// the builder can pre-fetch their metadata. Build one with the constructors below;
+// the zero value is not usable.
+type Aggregate struct {
+	keys   []*telemetrytypes.TelemetryFieldKey
+	render func(r aggResolver) (expr string, args []any, err error)
+}
+
+// aggResolver hands each aggregate the field-mapper primitives it may need — an
+// EXISTS predicate, a resolved value expression, and the gate mask. Populated per
+// query by resolveColumns.
+type aggResolver struct {
+	exists   func(key *telemetrytypes.TelemetryFieldKey) (string, []any, error)
+	value    func(key *telemetrytypes.TelemetryFieldKey, dt telemetrytypes.FieldDataType) (string, []any, error)
+	maskExpr string
+	maskArgs []any
+}
+
+// AggFunc is a ClickHouse aggregate function name.
+type AggFunc string
+
+const (
+	AggSum AggFunc = "sum"
+	AggMax AggFunc = "max"
+	AggMin AggFunc = "min"
+)
+
+// PickDirection selects the earliest (argMin) or latest (argMax) span by ordering.
+type PickDirection int
+
+const (
+	PickLatest PickDirection = iota
+	PickEarliest
+)
+
+// Intrinsic emits fixed intrinsic-column SQL verbatim (escaped once).
+func Intrinsic(text string) Aggregate {
+	return Aggregate{render: func(aggResolver) (string, []any, error) {
+		return sqlbuilder.Escape(text), nil, nil
+	}}
+}
+
+// CountExists renders countIf(<key> EXISTS) — counts spans carrying key.
+func CountExists(key *telemetrytypes.TelemetryFieldKey) Aggregate {
+	return Aggregate{keys: keysOf(key), render: func(r aggResolver) (string, []any, error) {
+		cond, args, err := r.exists(key)
+		return fmt.Sprintf("countIf(%s)", cond), args, err
+	}}
+}
+
+// Reduce renders <fn>(<value>) over a resolved numeric attribute value.
+func Reduce(fn AggFunc, valueKey *telemetrytypes.TelemetryFieldKey) Aggregate {
+	return Aggregate{keys: keysOf(valueKey), render: func(r aggResolver) (string, []any, error) {
+		v, args, err := r.value(valueKey, telemetrytypes.FieldDataTypeFloat64)
+		return fmt.Sprintf("%s(%s)", fn, v), args, err
+	}}
+}
+
+// ScopedReduce renders <fn>If(<valueExpr>, <gate mask>) over a fixed value expression.
+func ScopedReduce(fn AggFunc, valueExpr string) Aggregate {
+	return Aggregate{render: func(r aggResolver) (string, []any, error) {
+		return fmt.Sprintf("%sIf(%s, %s)", fn, valueExpr, r.maskExpr), append([]any{}, r.maskArgs...), nil
+	}}
+}
+
+// ScopedToKeyColumn renders <fn>If(<column>, <scopeKey> EXISTS) — a physical
+// span-index column aggregated over spans carrying scopeKey (e.g. max LLM latency).
+// Providers pass the bare column name; it is table-qualified here so it binds to the
+// physical column and not a same-named output alias, which ClickHouse would reject
+// as an aggregate inside an aggregate.
+func ScopedToKeyColumn(fn AggFunc, column string, scopeKey *telemetrytypes.TelemetryFieldKey) Aggregate {
+	return Aggregate{keys: keysOf(scopeKey), render: func(r aggResolver) (string, []any, error) {
+		cond, args, err := r.exists(scopeKey)
+		return fmt.Sprintf("%sIf(%s.%s, %s)", fn, spanTable(), column, cond), args, err
+	}}
+}
+
+// PickBy renders argMinIf/argMaxIf(<value>, <orderExpr>, <value> EXISTS) — the value
+// from the earliest/latest span that carries it.
+func PickBy(valueKey *telemetrytypes.TelemetryFieldKey, dt telemetrytypes.FieldDataType, orderExpr string, dir PickDirection) Aggregate {
+	fn := "argMaxIf"
+	if dir == PickEarliest {
+		fn = "argMinIf"
+	}
+	return Aggregate{keys: keysOf(valueKey), render: func(r aggResolver) (string, []any, error) {
+		v, vargs, err := r.value(valueKey, dt)
+		if err != nil {
+			return "", nil, err
+		}
+		cond, cargs, err := r.exists(valueKey)
+		return fmt.Sprintf("%s(%s, %s, %s)", fn, v, orderExpr, cond), append(vargs, cargs...), err
+	}}
+}
+
+// UniqCount renders uniqIf(<value>, <value> EXISTS) — distinct count of an attribute.
+func UniqCount(valueKey *telemetrytypes.TelemetryFieldKey, dt telemetrytypes.FieldDataType) Aggregate {
+	return Aggregate{keys: keysOf(valueKey), render: func(r aggResolver) (string, []any, error) {
+		v, vargs, err := r.value(valueKey, dt)
+		if err != nil {
+			return "", nil, err
+		}
+		cond, cargs, err := r.exists(valueKey)
+		return fmt.Sprintf("uniqIf(%s, %s)", v, cond), append(vargs, cargs...), err
+	}}
+}
+
+// PredicateCount renders countIf(<predicate>) over a fixed boolean predicate.
+func PredicateCount(predicate string) Aggregate {
+	return Aggregate{render: func(aggResolver) (string, []any, error) {
+		return fmt.Sprintf("countIf(%s)", sqlbuilder.Escape(predicate)), nil, nil
+	}}
+}
+
+// SumOfKeys renders coalesce(sum(<v1>), 0) + coalesce(sum(<v2>), 0) + … over several
+// numeric attributes. Coalesced because a key absent from every span sums to NULL and
+// NULL + n = NULL — a trace with only output tokens would otherwise total NULL.
+func SumOfKeys(dt telemetrytypes.FieldDataType, valueKeys ...*telemetrytypes.TelemetryFieldKey) Aggregate {
+	return Aggregate{keys: valueKeys, render: func(r aggResolver) (string, []any, error) {
+		parts := make([]string, 0, len(valueKeys))
+		var args []any
+		for _, k := range valueKeys {
+			v, vargs, err := r.value(k, dt)
+			if err != nil {
+				return "", nil, err
+			}
+			parts = append(parts, fmt.Sprintf("coalesce(sum(%s), 0)", v))
+			args = append(args, vargs...)
+		}
+		return strings.Join(parts, " + "), args, nil
+	}}
+}
+
+func keysOf(k *telemetrytypes.TelemetryFieldKey) []*telemetrytypes.TelemetryFieldKey {
+	return []*telemetrytypes.TelemetryFieldKey{k}
+}
+
+// ColumnProvider supplies the columns a trace list computes.
+type ColumnProvider interface {
+	Columns() []TraceColumn
+	// DefaultOrderAlias is sorted by (desc) when the query gives no order.
+	DefaultOrderAlias() string
+	// AggregateAliases are the computed per-trace column names, used to classify a
+	// filter key as trace-level vs span-level. Excludes SpanLevel columns.
+	AggregateAliases() []string
+}
+
+// CommonTraceColumns are domain-neutral columns any trace list can reuse. All
+// aggregate over every span, so none is Orderable.
+func CommonTraceColumns() []TraceColumn {
+	return []TraceColumn{
+		{Alias: "start_time", Expr: Intrinsic("min(timestamp)")},
+		{Alias: "end_time", Expr: Intrinsic("max(timestamp)")},
+		{Alias: "duration_nano", Expr: Intrinsic("(max(toUnixTimestamp64Nano(timestamp) + duration_nano) - min(toUnixTimestamp64Nano(timestamp)))")},
+		{Alias: "span_count", Expr: Intrinsic("count()")},
+		{Alias: "root_span_name", Expr: Intrinsic("anyIf(name, parent_span_id = '')")},
+		{Alias: "service.name", SpanLevel: true, Expr: Intrinsic("any(resource_string_service$$name)")},
+	}
+}

pkg/telemetryscopedtraces/statement_builder.go

@@ -0,0 +1,932 @@
+package telemetryscopedtraces
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"sort"
+	"strings"
+
+	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/factory"
+	"github.com/SigNoz/signoz/pkg/flagger"
+	"github.com/SigNoz/signoz/pkg/querybuilder"
+	"github.com/SigNoz/signoz/pkg/telemetryresourcefilter"
+	"github.com/SigNoz/signoz/pkg/telemetrystore"
+	"github.com/SigNoz/signoz/pkg/telemetrytraces"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	qbvariables "github.com/SigNoz/signoz/pkg/variables"
+	"github.com/huandu/go-sqlbuilder"
+)
+
+var (
+	ErrUnsupportedRequestType = errors.NewInvalidInputf(errors.CodeInvalidInput, "unsupported request type for the scoped trace builder")
+)
+
+// scopedTraceStatementBuilder builds a trace list scoped to one span category
+// (e.g. gen_ai spans). The query shape is fixed; BaseConditionProvider decides which
+// spans are in scope and ColumnProvider decides the per-trace columns, so a new
+// category only needs a new pair of providers.
+type scopedTraceStatementBuilder struct {
+	logger                         *slog.Logger
+	metadataStore                  telemetrytypes.MetadataStore
+	fm                             qbtypes.FieldMapper
+	cb                             qbtypes.ConditionBuilder
+	baseCond                       BaseConditionProvider
+	columnProvider                 ColumnProvider
+	traceStmtBuilder               qbtypes.StatementBuilder[qbtypes.TraceAggregation]
+	resourceFilterResolver         *telemetryresourcefilter.ResourceFingerprintResolver[qbtypes.TraceAggregation]
+	skipResourceFingerprintEnabled bool
+}
+
+var _ qbtypes.StatementBuilder[qbtypes.TraceAggregation] = (*scopedTraceStatementBuilder)(nil)
+
+// NewScopedTraceStatementBuilder wires the generic trace-list builder. The field
+// mapper / condition builder are built here, not injected — the list always scans the
+// telemetrytraces span index. traceStmtBuilder (the delegate for the span-list path)
+// is injected because the provider already has the canonical instance.
+func NewScopedTraceStatementBuilder(
+	settings factory.ProviderSettings,
+	metadataStore telemetrytypes.MetadataStore,
+	baseCond BaseConditionProvider,
+	columnProvider ColumnProvider,
+	traceStmtBuilder qbtypes.StatementBuilder[qbtypes.TraceAggregation],
+	telemetryStore telemetrystore.TelemetryStore,
+	fl flagger.Flagger,
+	skipResourceFingerprintEnable bool,
+	skipResourceFingerprintThreshold uint64,
+) qbtypes.StatementBuilder[qbtypes.TraceAggregation] {
+	scopedSettings := factory.NewScopedProviderSettings(settings, "github.com/SigNoz/signoz/pkg/telemetryscopedtraces")
+
+	fieldMapper := telemetrytraces.NewFieldMapper()
+	conditionBuilder := telemetrytraces.NewConditionBuilder(fieldMapper)
+
+	// Same resource-fingerprint prune as the standard trace builder — the list scans
+	// the same span index.
+	resourceFilterResolver := telemetryresourcefilter.NewResolver[qbtypes.TraceAggregation](
+		settings,
+		telemetrytraces.DBName,
+		telemetrytraces.TracesResourceV3TableName,
+		telemetrytypes.SignalTraces,
+		telemetrytypes.SourceUnspecified,
+		metadataStore,
+		nil,
+		fl,
+		telemetryStore,
+		skipResourceFingerprintThreshold,
+	)
+
+	return &scopedTraceStatementBuilder{
+		logger:                         scopedSettings.Logger(),
+		metadataStore:                  metadataStore,
+		fm:                             fieldMapper,
+		cb:                             conditionBuilder,
+		baseCond:                       baseCond,
+		columnProvider:                 columnProvider,
+		traceStmtBuilder:               traceStmtBuilder,
+		resourceFilterResolver:         resourceFilterResolver,
+		skipResourceFingerprintEnabled: skipResourceFingerprintEnable,
+	}
+}
+
+func (b *scopedTraceStatementBuilder) Build(
+	ctx context.Context,
+	start uint64,
+	end uint64,
+	requestType qbtypes.RequestType,
+	query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation],
+	variables map[string]qbtypes.VariableItem,
+) (*qbtypes.Statement, error) {
+	switch requestType {
+	case qbtypes.RequestTypeTrace:
+		return b.buildTraceListQuery(ctx, querybuilder.ToNanoSecs(start), querybuilder.ToNanoSecs(end), query, variables)
+	case qbtypes.RequestTypeRaw:
+		if err := b.validateRawOrderKeys(query); err != nil {
+			return nil, err
+		}
+		return b.buildDelegated(ctx, start, end, requestType, query, variables)
+	default:
+		return nil, ErrUnsupportedRequestType
+	}
+}
+
+// traceScopedStatementBuilder is the delegate's optional capability of constraining a
+// query to a set of trace ids (implemented by the telemetrytraces builder).
+type traceScopedStatementBuilder interface {
+	BuildTraceScoped(ctx context.Context, start, end uint64, requestType qbtypes.RequestType, query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation], variables map[string]qbtypes.VariableItem, traceScope *qbtypes.Statement) (*qbtypes.Statement, error)
+}
+
+// substituteTraceLevelVariables resolves query variables in a trace-level expression.
+// The span-level parts bind variables via PrepareWhereClause; trace-level parts are
+// text rewrites, so variables become literals (a dynamic __all__ drops its condition).
+func substituteTraceLevelVariables(expr string, variables map[string]qbtypes.VariableItem) (string, error) {
+	if strings.TrimSpace(expr) == "" || len(variables) == 0 {
+		return expr, nil
+	}
+	return qbvariables.ReplaceVariablesInExpression(expr, variables)
+}
+
+// validateRawOrderKeys rejects ordering the span list by an explicitly trace-level
+// aggregate (trace./tracefield. prefix or trace field context) — the per-trace value
+// does not exist on span rows. Bare names pass through: they may legitimately be span
+// columns (duration_nano, timestamp).
+func (b *scopedTraceStatementBuilder) validateRawOrderKeys(query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]) error {
+	aliases := b.aggregateAliasSet()
+	for _, o := range query.Order {
+		name := strings.TrimPrefix(strings.TrimPrefix(o.Key.Name, "tracefield."), "trace.")
+		if _, ok := aliases[name]; !ok {
+			continue
+		}
+		if name != o.Key.Name || o.Key.FieldContext == telemetrytypes.FieldContextTrace {
+			return errors.NewInvalidInputf(errors.CodeInvalidInput,
+				"ordering the span list by trace-level aggregate %q is not supported; order by span columns instead (e.g. timestamp, duration_nano)", o.Key.Name)
+		}
+	}
+	return nil
+}
+
+// buildDelegated ANDs the base gate into the span-level filter part and delegates to
+// the standard trace builder. A trace-level part (trace.output_tokens > 1000) becomes
+// a __trace_scope qualification the delegate constrains trace_id by.
+func (b *scopedTraceStatementBuilder) buildDelegated(
+	ctx context.Context,
+	start, end uint64,
+	requestType qbtypes.RequestType,
+	query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation],
+	variables map[string]qbtypes.VariableItem,
+) (*qbtypes.Statement, error) {
+	spanExpr, traceExpr := "", ""
+	if query.Filter != nil && strings.TrimSpace(query.Filter.Expression) != "" {
+		var err error
+		spanExpr, traceExpr, err = querybuilder.SplitFilterForAggregates(query.Filter.Expression, b.aggregateAliasSet())
+		if err != nil {
+			return nil, err
+		}
+	}
+	traceExpr, err := substituteTraceLevelVariables(traceExpr, variables)
+	if err != nil {
+		return nil, err
+	}
+
+	gate := b.baseCond.FilterExpression()
+	expr := gate
+	if strings.TrimSpace(spanExpr) != "" {
+		expr = fmt.Sprintf("(%s) AND (%s)", gate, spanExpr)
+	}
+
+	// shallow copy; only Filter is replaced, caller's query untouched
+	gated := query
+	gated.Filter = &qbtypes.Filter{Expression: expr}
+
+	if strings.TrimSpace(traceExpr) == "" {
+		return b.traceStmtBuilder.Build(ctx, start, end, requestType, gated, variables)
+	}
+
+	scoped, ok := b.traceStmtBuilder.(traceScopedStatementBuilder)
+	if !ok {
+		return nil, errors.NewInternalf(errors.CodeInternal, "trace statement builder does not support trace-scoped queries")
+	}
+	scope, err := b.buildQualifiedStatement(ctx, querybuilder.ToNanoSecs(start), querybuilder.ToNanoSecs(end), traceExpr)
+	if err != nil {
+		return nil, err
+	}
+	return scoped.BuildTraceScoped(ctx, start, end, requestType, gated, variables, scope)
+}
+
+// buildQualifiedStatement builds the __trace_scope statement: trace ids whose
+// window-clipped per-trace aggregates satisfy traceExpr, from one windowed,
+// mask-pruned GROUP BY trace_id scan. start/end are ns.
+func (b *scopedTraceStatementBuilder) buildQualifiedStatement(ctx context.Context, start, end uint64, traceExpr string) (*qbtypes.Statement, error) {
+	keys, err := b.fetchKeys(ctx)
+	if err != nil {
+		return nil, err
+	}
+	maskExpr, maskArgs, err := b.resolveMask(ctx, start, end, keys)
+	if err != nil {
+		return nil, err
+	}
+	resolved, err := b.resolveColumns(ctx, start, end, keys, maskExpr, maskArgs)
+	if err != nil {
+		return nil, err
+	}
+	orderableSet := orderableAliasSet(resolved)
+	if err := validateAggregateFilter(traceExpr, orderableSet); err != nil {
+		return nil, err
+	}
+	having, err := b.buildHaving(traceExpr, orderableSet)
+	if err != nil {
+		return nil, err
+	}
+
+	startBucket := start/querybuilder.NsToSeconds - querybuilder.BucketAdjustment
+	endBucket := end / querybuilder.NsToSeconds
+
+	sb := sqlbuilder.NewSelectBuilder()
+	needed := neededMatchedAliases(nil, traceExpr, orderableSet)
+	selects := []string{"trace_id"}
+	for _, rc := range resolved {
+		if _, ok := needed[rc.alias]; !ok {
+			continue
+		}
+		colExpr, err := embedExpr(sb, rc.expr, rc.args)
+		if err != nil {
+			return nil, err
+		}
+		selects = append(selects, colExpr+" AS "+quoteAlias(rc.alias))
+	}
+	sb.Select(selects...)
+	sb.From(spanTable())
+	mask, err := embedExpr(sb, maskExpr, maskArgs)
+	if err != nil {
+		return nil, err
+	}
+	sb.Where(append(windowWhere(sb, start, end, startBucket, endBucket), mask)...)
+	sb.GroupBy("trace_id")
+	if strings.TrimSpace(having) != "" {
+		sb.Having(having)
+	}
+	sql, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	return &qbtypes.Statement{Query: sql, Args: args}, nil
+}
+
+// buildTraceListQuery wires the CTE pipeline (benchmarked, see ai-qb-handoff.md): one
+// windowed pass picks the top-N traces, then a bucket-pruned pass enriches only those.
+// Helpers appear in this file in the order they run. start/end are nanoseconds.
+//
+//	RESOLVE (keys/columns → SQL via the field mapper)
+//	  fetchKeys         metadata for every key we reference
+//	  resolveMask       the "span is in scope" predicate (OR of EXISTS)
+//	  resolveColumns    per-trace column SQL
+//	  resolveListOrders which columns to ORDER BY
+//	  splitFilter       span-level predicate + trace-level HAVING
+//
+//	BUILD
+//	  matched    one windowed, mask-pruned GROUP BY trace_id scan fusing gate + span
+//	     │       filter + HAVING + ORDER BY + LIMIT/OFFSET → the top-N trace_ids
+//	     ▼
+//	  ranked     [start,end] bounds of those traces, from the small summary table
+//	     ▼
+//	  buckets    the ts_bucket_start values they touch, to prune the next scan
+//	     ▼
+//	  enrichment every per-trace column for those traces over their full extent
+//	             (not window-clipped), scanning only their buckets
+//
+// Only Orderable columns are computable in the mask-pruned matched pass, so only they
+// can be ordered or filtered on; all-span columns (span_count, …) are output-only.
+func (b *scopedTraceStatementBuilder) buildTraceListQuery(
+	ctx context.Context,
+	start, end uint64,
+	query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation],
+	variables map[string]qbtypes.VariableItem,
+) (*qbtypes.Statement, error) {
+
+	startBucket := start/querybuilder.NsToSeconds - querybuilder.BucketAdjustment
+	endBucket := end / querybuilder.NsToSeconds
+
+	limit := query.Limit
+	if limit <= 0 {
+		limit = 100
+	}
+
+	// Resolve keys and columns once; all attribute access goes through the field mapper.
+	keys, err := b.fetchKeys(ctx)
+	if err != nil {
+		return nil, err
+	}
+	maskExpr, maskArgs, err := b.resolveMask(ctx, start, end, keys)
+	if err != nil {
+		return nil, err
+	}
+	resolved, err := b.resolveColumns(ctx, start, end, keys, maskExpr, maskArgs)
+	if err != nil {
+		return nil, err
+	}
+	orders, err := b.resolveListOrders(query.Order, resolved)
+	if err != nil {
+		return nil, err
+	}
+	orderableSet := orderableAliasSet(resolved)
+
+	// If the filter references resource attributes, add a __resource_filter CTE and
+	// narrow the matched scan by resource_fingerprint; skipResourceFilter then drops
+	// those keys from the span predicate so they aren't applied twice.
+	resourceFrag, resourceArgs, resourcePred, skipResourceFilter, err := b.maybeAttachResourceFilter(ctx, query, start, end, variables)
+	if err != nil {
+		return nil, err
+	}
+
+	// Split the user filter: span-level predicate + trace-level HAVING expression.
+	fp, err := b.splitFilter(ctx, query, b.aggregateAliasSet(), orderableSet, start, end, skipResourceFilter, variables)
+	if err != nil {
+		return nil, err
+	}
+
+	// matched → ranked → buckets → enrichment
+	matchedFrag, matchedArgs, err := b.buildMatchedCTE(start, end, startBucket, endBucket, resolved, orders, orderableSet, maskExpr, maskArgs, fp, resourcePred, limit, query.Offset)
+	if err != nil {
+		return nil, err
+	}
+	rankedFrag, rankedArgs := b.buildRankedCTE(start, end)
+	bucketsFrag := buildBucketsCTE()
+	mainSQL, mainArgs := b.buildEnrichmentSelect(resolved, orders)
+
+	cteFragments := []string{matchedFrag, rankedFrag, bucketsFrag}
+	cteArgs := [][]any{matchedArgs, rankedArgs, nil}
+
+	// __resource_filter must precede `matched`, which references it.
+	if resourceFrag != "" {
+		cteFragments = append([]string{resourceFrag}, cteFragments...)
+		cteArgs = append([][]any{resourceArgs}, cteArgs...)
+	}
+
+	finalSQL := querybuilder.CombineCTEs(cteFragments) + mainSQL + " SETTINGS distributed_product_mode='allow', max_memory_usage=10000000000"
+	finalArgs := querybuilder.PrependArgs(cteArgs, mainArgs)
+
+	return &qbtypes.Statement{
+		Query:          finalSQL,
+		Args:           finalArgs,
+		Warnings:       fp.warnings,
+		WarningsDocURL: fp.warningsURL,
+	}, nil
+}
+
+// maybeAttachResourceFilter builds the __resource_filter CTE (fingerprints matching
+// the filter's resource conditions) and the predicate narrowing the span scan by
+// resource_fingerprint, mirroring the standard trace builder. With no resolver or no
+// resource conditions it returns empty fragments and the resource keys stay in the
+// span predicate (skipResourceFilter=false).
+func (b *scopedTraceStatementBuilder) maybeAttachResourceFilter(
+	ctx context.Context,
+	query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation],
+	start, end uint64,
+	variables map[string]qbtypes.VariableItem,
+) (cteFrag string, cteArgs []any, fingerprintPred string, skipResourceFilter bool, err error) {
+	if b.resourceFilterResolver == nil {
+		return "", nil, "", false, nil
+	}
+
+	if b.skipResourceFingerprintEnabled {
+		decision, err := b.resourceFilterResolver.Resolve(ctx, query, start, end, variables)
+		if err != nil {
+			return "", nil, "", true, err
+		}
+		switch decision {
+		case qbtypes.ResourceFilterResolveKindNoOp:
+			return "", nil, "", true, nil
+		case qbtypes.ResourceFilterResolveKindFallback:
+			return "", nil, "", false, nil
+		}
+	}
+
+	stmt, err := b.resourceFilterResolver.StatementBuilder().Build(
+		ctx, start, end, qbtypes.RequestTypeRaw, query, variables,
+	)
+	if err != nil {
+		return "", nil, "", true, err
+	}
+	if stmt == nil {
+		return "", nil, "", true, nil
+	}
+	return fmt.Sprintf("__resource_filter AS (%s)", stmt.Query), stmt.Args,
+		"resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter)", true, nil
+}
+
+// ---------------------------------------------------------------------------
+// RESOLVE — turn keys/columns into field-mapper-aware SQL
+// ---------------------------------------------------------------------------
+
+func (b *scopedTraceStatementBuilder) fetchKeys(ctx context.Context) (map[string][]*telemetrytypes.TelemetryFieldKey, error) {
+	fields := b.resolverFieldKeys()
+	selectors := make([]*telemetrytypes.FieldKeySelector, 0, len(fields))
+	for _, k := range fields {
+		selectors = append(selectors, &telemetrytypes.FieldKeySelector{
+			Name:         k.Name,
+			Signal:       k.Signal,
+			FieldContext: k.FieldContext,
+		})
+	}
+	keys, _, err := b.metadataStore.GetKeysMulti(ctx, selectors)
+	return keys, err
+}
+
+func (b *scopedTraceStatementBuilder) resolverFieldKeys() []*telemetrytypes.TelemetryFieldKey {
+	seen := make(map[string]struct{})
+	var out []*telemetrytypes.TelemetryFieldKey
+	add := func(k *telemetrytypes.TelemetryFieldKey) {
+		if k == nil {
+			return
+		}
+		if _, dup := seen[k.Name]; dup {
+			return
+		}
+		seen[k.Name] = struct{}{}
+		out = append(out, k)
+	}
+	for _, k := range b.baseCond.FieldKeys() {
+		add(k)
+	}
+	for _, c := range b.columnProvider.Columns() {
+		for _, k := range c.Expr.keys {
+			add(k)
+		}
+	}
+	return out
+}
+
+// resolveMask builds the per-span in-scope mask: OR of resolved EXISTS predicates
+// over the base condition's field keys.
+func (b *scopedTraceStatementBuilder) resolveMask(ctx context.Context, start, end uint64, keys map[string][]*telemetrytypes.TelemetryFieldKey) (string, []any, error) {
+	fieldKeys := b.baseCond.FieldKeys()
+	parts := make([]string, 0, len(fieldKeys))
+	var args []any
+	for _, key := range fieldKeys {
+		e, a, err := b.existsExpr(ctx, start, end, keys, key)
+		if err != nil {
+			return "", nil, err
+		}
+		parts = append(parts, e)
+		args = append(args, a...)
+	}
+	return "(" + strings.Join(parts, " OR ") + ")", args, nil
+}
+
+// existsExpr resolves an EXISTS predicate for key via the field mapper (materialized
+// column when present, else map access). Escaped once so it can be embedded in an
+// outer builder.
+func (b *scopedTraceStatementBuilder) existsExpr(ctx context.Context, start, end uint64, keys map[string][]*telemetrytypes.TelemetryFieldKey, key *telemetrytypes.TelemetryFieldKey) (string, []any, error) {
+	resolvedKey := key
+	cands := keys[key.Name]
+	if len(cands) == 0 {
+		cands = []*telemetrytypes.TelemetryFieldKey{key}
+	} else {
+		resolvedKey = cands[0]
+	}
+	sb := sqlbuilder.NewSelectBuilder()
+	conds, _, err := b.cb.ConditionFor(ctx, start, end, resolvedKey, cands, qbtypes.FilterOperatorExists, nil, sb)
+	if err != nil {
+		return "", nil, err
+	}
+	// One condition per candidate variant (a key can be ingested under several data
+	// types); OR them all, like the visitor does for EXISTS.
+	if len(conds) == 1 {
+		sb.Where(conds[0])
+	} else {
+		sb.Where(sb.Or(conds...))
+	}
+	expr, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	expr = strings.TrimPrefix(expr, "WHERE ")
+	return sqlbuilder.Escape(expr), args, nil
+}
+
+// resolvedColumn is a column resolved to SQL via the field mapper; expr is escaped
+// once, ready to embed in an outer SELECT.
+type resolvedColumn struct {
+	alias     string
+	expr      string
+	args      []any
+	orderable bool
+}
+
+// resolveColumns turns the declarative columns into SQL, resolving all
+// attribute access through the field mapper.
+func (b *scopedTraceStatementBuilder) resolveColumns(ctx context.Context, start, end uint64, keys map[string][]*telemetrytypes.TelemetryFieldKey, maskExpr string, maskArgs []any) ([]resolvedColumn, error) {
+	r := aggResolver{
+		exists: func(key *telemetrytypes.TelemetryFieldKey) (string, []any, error) {
+			return b.existsExpr(ctx, start, end, keys, key)
+		},
+		value: func(key *telemetrytypes.TelemetryFieldKey, dt telemetrytypes.FieldDataType) (string, []any, error) {
+			// Use the metadata variant, which carries Materialized — a provider's static
+			// definition never does, so a promoted attribute would otherwise fall back
+			// to map access. Mirrors existsExpr.
+			if cands := keys[key.Name]; len(cands) > 0 {
+				key = cands[0]
+			}
+			return querybuilder.CollisionHandledFinalExpr(ctx, start, end, key, b.fm, b.cb, keys, dt, nil, false)
+		},
+		maskExpr: maskExpr,
+		maskArgs: maskArgs,
+	}
+
+	cols := b.columnProvider.Columns()
+	out := make([]resolvedColumn, 0, len(cols))
+	for _, c := range cols {
+		expr, args, err := c.Expr.render(r)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, resolvedColumn{alias: c.Alias, expr: expr, args: args, orderable: c.Orderable})
+	}
+	return out, nil
+}
+
+// listOrder is a sort key resolved to a column alias + direction; both the matched
+// CTE and the enrichment ORDER BY it.
+type listOrder struct {
+	alias     string
+	direction string
+}
+
+// resolveListOrders maps order keys to the resolved orderable columns; non-orderable
+// columns are rejected. Defaults to the column provider's default order.
+func (b *scopedTraceStatementBuilder) resolveListOrders(order []qbtypes.OrderBy, resolved []resolvedColumn) ([]listOrder, error) {
+	byAlias := make(map[string]resolvedColumn, len(resolved))
+	orderable := make([]string, 0, len(resolved))
+	for _, rc := range resolved {
+		byAlias[rc.alias] = rc
+		if rc.orderable {
+			orderable = append(orderable, rc.alias)
+		}
+	}
+
+	if len(order) == 0 {
+		return []listOrder{{alias: b.columnProvider.DefaultOrderAlias(), direction: "DESC"}}, nil
+	}
+
+	orders := make([]listOrder, 0, len(order))
+	for _, o := range order {
+		direction := "DESC"
+		if o.Direction == qbtypes.OrderDirectionAsc {
+			direction = "ASC"
+		}
+		rc, ok := byAlias[o.Key.Name]
+		if !ok || !rc.orderable {
+			return nil, errors.NewInvalidInputf(errors.CodeInvalidInput,
+				"unsupported order key %q for the trace list; orderable keys: %s", o.Key.Name, strings.Join(orderable, ", "))
+		}
+		orders = append(orders, listOrder{alias: rc.alias, direction: direction})
+	}
+	return orders, nil
+}
+
+// filterParts is the user filter split into a span-level predicate (widens the
+// matched WHERE prune and becomes a countIf existence check in HAVING) and a
+// trace-level HAVING expression.
+type filterParts struct {
+	spanPred      string
+	spanArgs      []any
+	hasSpanFilter bool
+	havingExpr    string
+	warnings      []string
+	warningsURL   string
+}
+
+// splitFilter splits query.Filter into a span-level predicate and a trace-level
+// HAVING expression (an explicit query.Having is ANDed onto the latter), then
+// validates the trace-level part against the matched-pass aggregates.
+func (b *scopedTraceStatementBuilder) splitFilter(ctx context.Context, query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation], classifySet, orderableSet map[string]struct{}, start, end uint64, skipResourceFilter bool, variables map[string]qbtypes.VariableItem) (filterParts, error) {
+	var fp filterParts
+	if query.Filter != nil && strings.TrimSpace(query.Filter.Expression) != "" {
+		spanExpr, traceExpr, err := querybuilder.SplitFilterForAggregates(query.Filter.Expression, classifySet)
+		if err != nil {
+			return fp, err
+		}
+		fp.havingExpr = traceExpr
+		if strings.TrimSpace(spanExpr) != "" {
+			pred, args, warnings, url, err := b.resolveSpanPredicate(ctx, start, end, spanExpr, skipResourceFilter, variables)
+			if err != nil {
+				return fp, err
+			}
+			// pred is empty when the span-level keys were all resource attributes
+			// already handled by the __resource_filter CTE.
+			if strings.TrimSpace(pred) != "" {
+				fp.spanPred, fp.spanArgs, fp.hasSpanFilter = pred, args, true
+			}
+			fp.warnings, fp.warningsURL = warnings, url
+		}
+	}
+	if query.Having != nil && strings.TrimSpace(query.Having.Expression) != "" {
+		if fp.havingExpr != "" {
+			fp.havingExpr = fmt.Sprintf("(%s) AND (%s)", fp.havingExpr, query.Having.Expression)
+		} else {
+			fp.havingExpr = query.Having.Expression
+		}
+	}
+	havingExpr, err := substituteTraceLevelVariables(fp.havingExpr, variables)
+	if err != nil {
+		return fp, err
+	}
+	fp.havingExpr = havingExpr
+	if err := validateAggregateFilter(fp.havingExpr, orderableSet); err != nil {
+		return fp, err
+	}
+	return fp, nil
+}
+
+// resolveSpanPredicate resolves a span-level filter expression to a bare boolean
+// SQL predicate + args via the field mapper.
+func (b *scopedTraceStatementBuilder) resolveSpanPredicate(ctx context.Context, start, end uint64, expr string, skipResourceFilter bool, variables map[string]qbtypes.VariableItem) (string, []any, []string, string, error) {
+	selectors := querybuilder.QueryStringToKeysSelectors(expr)
+	for i := range selectors {
+		selectors[i].Signal = telemetrytypes.SignalTraces
+	}
+	keys, _, err := b.metadataStore.GetKeysMulti(ctx, selectors)
+	if err != nil {
+		return "", nil, nil, "", err
+	}
+	prepared, err := querybuilder.PrepareWhereClause(expr, querybuilder.FilterExprVisitorOpts{
+		Context:            ctx,
+		Logger:             b.logger,
+		FieldMapper:        b.fm,
+		ConditionBuilder:   b.cb,
+		FieldKeys:          keys,
+		SkipResourceFilter: skipResourceFilter,
+		Variables:          variables,
+		StartNs:            start,
+		EndNs:              end,
+	})
+	if err != nil {
+		return "", nil, nil, "", err
+	}
+	if prepared.IsEmpty() {
+		return "", nil, nil, "", nil
+	}
+	sb := sqlbuilder.NewSelectBuilder()
+	sb.Select("1")
+	sb.AddWhereClause(prepared.WhereClause)
+	sql, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	pred := sql[strings.Index(sql, "WHERE ")+len("WHERE "):]
+	return sqlbuilder.Escape(pred), args, prepared.Warnings, prepared.WarningsDocURL, nil
+}
+
+// buildMatchedCTE builds `matched`: the single windowed GROUP BY trace_id scan that
+// fuses gate + span filter + HAVING + ORDER BY + LIMIT/OFFSET, selecting only the
+// aliases the ORDER BY / HAVING reference.
+func (b *scopedTraceStatementBuilder) buildMatchedCTE(start, end, startBucket, endBucket uint64, resolved []resolvedColumn, orders []listOrder, orderableSet map[string]struct{}, maskExpr string, maskArgs []any, fp filterParts, resourcePred string, limit, offset int) (string, []any, error) {
+	sb := sqlbuilder.NewSelectBuilder()
+
+	// SELECT trace_id + only the aggregates ORDER BY / HAVING reference (as aliases).
+	needed := neededMatchedAliases(orders, fp.havingExpr, orderableSet)
+	selects := []string{"trace_id"}
+	for _, rc := range resolved {
+		if _, ok := needed[rc.alias]; !ok {
+			continue
+		}
+		colExpr, err := embedExpr(sb, rc.expr, rc.args)
+		if err != nil {
+			return "", nil, err
+		}
+		selects = append(selects, colExpr+" AS "+quoteAlias(rc.alias))
+	}
+	sb.Select(selects...)
+	sb.From(spanTable())
+
+	// WHERE: window + prune to in-scope spans, widened by the span filter so its
+	// spans survive for the countIf existence check below.
+	win := windowWhere(sb, start, end, startBucket, endBucket)
+	mask, err := embedExpr(sb, maskExpr, maskArgs)
+	if err != nil {
+		return "", nil, err
+	}
+	prune := "(" + mask
+	if fp.hasSpanFilter {
+		spanPred, err := embedExpr(sb, fp.spanPred, fp.spanArgs)
+		if err != nil {
+			return "", nil, err
+		}
+		prune += " OR " + spanPred
+	}
+	prune += ")"
+	where := append(win, prune)
+	if resourcePred != "" {
+		where = append(where, resourcePred)
+	}
+	sb.Where(where...)
+	sb.GroupBy("trace_id")
+
+	// HAVING: the gate/span existence checks are only needed when the WHERE was
+	// widened by a span filter; otherwise the mask alone already enforces the gate.
+	var having []string
+	if fp.hasSpanFilter {
+		havingMask, err := embedExpr(sb, maskExpr, maskArgs)
+		if err != nil {
+			return "", nil, err
+		}
+		havingPred, err := embedExpr(sb, fp.spanPred, fp.spanArgs)
+		if err != nil {
+			return "", nil, err
+		}
+		having = append(having, "countIf("+havingMask+") > 0")
+		having = append(having, "countIf("+havingPred+") > 0")
+	}
+	if strings.TrimSpace(fp.havingExpr) != "" {
+		hv, err := b.buildHaving(fp.havingExpr, orderableSet)
+		if err != nil {
+			return "", nil, err
+		}
+		if hv != "" {
+			having = append(having, hv)
+		}
+	}
+	if len(having) > 0 {
+		sb.Having(strings.Join(having, " AND "))
+	}
+
+	sb.OrderBy(orderClause(orders)...)
+	sb.Limit(limit)
+	if offset > 0 {
+		sb.Offset(offset)
+	}
+
+	sql, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	return fmt.Sprintf("matched AS (%s)", sql), args, nil
+}
+
+// buildRankedCTE builds `ranked`: [start,end] bounds per matched trace, read from the
+// small trace-summary table.
+func (b *scopedTraceStatementBuilder) buildRankedCTE(start, end uint64) (string, []any) {
+	sb := sqlbuilder.NewSelectBuilder()
+	sb.Select("trace_id", "min(start) AS t_start", "max(end) AS t_end")
+	sb.From(summaryTable())
+	sb.Where(
+		"trace_id GLOBAL IN (SELECT trace_id FROM matched)",
+		"end >= fromUnixTimestamp64Nano("+sb.Var(start)+")",
+		"start < fromUnixTimestamp64Nano("+sb.Var(end)+")",
+	)
+	sb.GroupBy("trace_id")
+	sql, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	return fmt.Sprintf("ranked AS (%s)", sql), args
+}
+
+// buildBucketsCTE builds `buckets`: the ts_bucket_start values the matched traces
+// span, so the enrichment scan is primary-key pruned. No args.
+func buildBucketsCTE() string {
+	adj := querybuilder.BucketAdjustment // 30-min bucket width in seconds
+	return fmt.Sprintf("buckets AS (SELECT DISTINCT b AS ts_bucket FROM ranked "+
+		"ARRAY JOIN range("+
+		"toUInt64(intDiv(toUnixTimestamp(t_start), %d) * %d - %d), "+
+		"toUInt64(intDiv(toUnixTimestamp(t_end), %d) * %d + %d), "+
+		"%d) AS b)", adj, adj, adj, adj, adj, adj, adj)
+}
+
+// buildEnrichmentSelect builds the final SELECT: every per-trace column for the
+// matched traces over their full extent, scanning only their buckets.
+//
+// Accepted discrepancy: matched ranks/paginates on window-clipped values, this pass
+// recomputes and ORDER BYs full-trace values, so a trace with activity outside the
+// window can sort differently than it ranked. Page membership is unaffected
+// (LIMIT/OFFSET runs only in matched); rows still sort by the values the user sees.
+// Ordering by matched's values instead would re-run the matched scan (ClickHouse
+// re-executes a CTE per reference) without fixing the visible cross-page artifact.
+func (b *scopedTraceStatementBuilder) buildEnrichmentSelect(resolved []resolvedColumn, orders []listOrder) (string, []any) {
+	sb := sqlbuilder.NewSelectBuilder()
+	selects, selectArgs := selectAllColumns(resolved)
+	sb.Select(selects...)
+	sb.From(spanTable())
+	sb.Where(
+		"ts_bucket_start GLOBAL IN (SELECT ts_bucket FROM buckets)",
+		"trace_id GLOBAL IN (SELECT trace_id FROM ranked)",
+	)
+	sb.GroupBy("trace_id")
+	sb.OrderBy(orderClause(orders)...)
+	sql, builtArgs := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	return sql, append(append([]any{}, selectArgs...), builtArgs...)
+}
+
+// buildHaving rewrites a trace-level HAVING expression to the matched-pass column
+// aliases; bare, trace., and tracefield. forms all map to the same alias.
+func (b *scopedTraceStatementBuilder) buildHaving(havingExpr string, orderableSet map[string]struct{}) (string, error) {
+	columnMap := make(map[string]string, len(orderableSet)*3)
+	for a := range orderableSet {
+		columnMap[a] = quoteAlias(a)
+		columnMap["trace."+a] = quoteAlias(a)
+		columnMap["tracefield."+a] = quoteAlias(a)
+	}
+	return querybuilder.NewHavingExpressionRewriter().Rewrite(havingExpr, columnMap)
+}
+
+// ---------------------------------------------------------------------------
+// Small shared SQL-builder utilities
+// ---------------------------------------------------------------------------
+
+// spanTable is the fully-qualified span index table.
+func spanTable() string {
+	return fmt.Sprintf("%s.%s", telemetrytraces.DBName, telemetrytraces.SpanIndexV3TableName)
+}
+
+// summaryTable is the fully-qualified trace-summary table.
+func summaryTable() string {
+	return fmt.Sprintf("%s.%s", telemetrytraces.DBName, telemetrytraces.TraceSummaryTableName)
+}
+
+// aggregateAliasSet is every trace-level column alias, used to classify filter keys
+// as trace-level vs span-level.
+func (b *scopedTraceStatementBuilder) aggregateAliasSet() map[string]struct{} {
+	set := make(map[string]struct{}, len(b.columnProvider.AggregateAliases()))
+	for _, a := range b.columnProvider.AggregateAliases() {
+		set[a] = struct{}{}
+	}
+	return set
+}
+
+// orderableAliasSet is the subset of aliases computable in the matched pass — the
+// only ones usable in ORDER BY and the aggregate filter.
+func orderableAliasSet(resolved []resolvedColumn) map[string]struct{} {
+	set := make(map[string]struct{})
+	for _, rc := range resolved {
+		if rc.orderable {
+			set[rc.alias] = struct{}{}
+		}
+	}
+	return set
+}
+
+// neededMatchedAliases is the minimal alias set the matched pass must select: those
+// in ORDER BY plus those in the aggregate HAVING. Everything else is left to the
+// enrichment scan.
+func neededMatchedAliases(orders []listOrder, havingExpr string, orderableSet map[string]struct{}) map[string]struct{} {
+	needed := make(map[string]struct{})
+	for _, o := range orders {
+		needed[o.alias] = struct{}{}
+	}
+	for _, sel := range querybuilder.QueryStringToKeysSelectors(havingExpr) {
+		name := strings.TrimPrefix(strings.TrimPrefix(sel.Name, "trace."), "tracefield.")
+		if _, ok := orderableSet[name]; ok {
+			needed[name] = struct{}{}
+		}
+	}
+	return needed
+}
+
+// validateAggregateFilter rejects a trace-level filter referencing an aggregate not
+// computable in the matched pass (e.g. span_count, duration_nano).
+func validateAggregateFilter(havingExpr string, orderableSet map[string]struct{}) error {
+	if strings.TrimSpace(havingExpr) == "" {
+		return nil
+	}
+	allowed := make([]string, 0, len(orderableSet))
+	for a := range orderableSet {
+		allowed = append(allowed, a)
+	}
+	sort.Strings(allowed)
+	for _, sel := range querybuilder.QueryStringToKeysSelectors(havingExpr) {
+		name := strings.TrimPrefix(strings.TrimPrefix(sel.Name, "trace."), "tracefield.")
+		if _, ok := orderableSet[name]; !ok {
+			return errors.NewInvalidInputf(errors.CodeInvalidInput,
+				"aggregate %q cannot be used in the trace-list filter; filterable aggregates: %s", name, strings.Join(allowed, ", "))
+		}
+	}
+	return nil
+}
+
+// embedExpr inlines a resolved expr into sb, replacing each `?` placeholder with a
+// builder Var so the args are tracked in appearance order. Resolved exprs carry
+// values only as bound args, so every `?` is a placeholder; a count mismatch would
+// silently shift args into the wrong slots — error out instead.
+func embedExpr(sb *sqlbuilder.SelectBuilder, expr string, args []any) (string, error) {
+	if n := strings.Count(expr, "?"); n != len(args) {
+		return "", errors.NewInternalf(errors.CodeInternal,
+			"scoped trace builder: %d placeholders != %d args embedding %q", n, len(args), expr)
+	}
+	var out strings.Builder
+	ai := 0
+	for i := 0; i < len(expr); i++ {
+		if expr[i] == '?' {
+			out.WriteString(sb.Var(args[ai]))
+			ai++
+			continue
+		}
+		out.WriteByte(expr[i])
+	}
+	return out.String(), nil
+}
+
+// windowWhere binds the time-window predicates to sb and returns them so the caller
+// can add its own predicates in the same Where call.
+func windowWhere(sb *sqlbuilder.SelectBuilder, start, end, startBucket, endBucket uint64) []string {
+	return []string{
+		sb.GE("timestamp", fmt.Sprintf("%d", start)),
+		sb.L("timestamp", fmt.Sprintf("%d", end)),
+		sb.GE("ts_bucket_start", startBucket),
+		sb.LE("ts_bucket_start", endBucket),
+	}
+}
+
+// orderClause renders the ORDER BY terms plus the trace_id tiebreak.
+func orderClause(orders []listOrder) []string {
+	out := make([]string, 0, len(orders)+1)
+	for _, o := range orders {
+		out = append(out, fmt.Sprintf("%s %s", quoteAlias(o.alias), o.direction))
+	}
+	return append(out, "trace_id DESC")
+}
+
+// selectAllColumns renders `expr AS alias` for every resolved column, args in select
+// order.
+func selectAllColumns(resolved []resolvedColumn) ([]string, []any) {
+	selects := []string{"trace_id"}
+	var args []any
+	for _, rc := range resolved {
+		selects = append(selects, rc.expr+" AS "+quoteAlias(rc.alias))
+		args = append(args, rc.args...)
+	}
+	return selects, args
+}
+
+// quoteAlias backticks an alias containing characters special to the SQL builder.
+func quoteAlias(alias string) string {
+	if strings.ContainsAny(alias, ".$`") {
+		return "`" + alias + "`"
+	}
+	return alias
+}

pkg/telemetryscopedtraces/statement_builder_test.go

@@ -0,0 +1,139 @@
+package telemetryscopedtraces
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/SigNoz/signoz/pkg/factory"
+	"github.com/SigNoz/signoz/pkg/instrumentation/instrumentationtest"
+	"github.com/SigNoz/signoz/pkg/telemetrytraces"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes/telemetrytypestest"
+	"github.com/huandu/go-sqlbuilder"
+	"github.com/stretchr/testify/require"
+)
+
+// The full-pipeline golden tests live in pkg/telemetryai, which exercises this
+// builder through its production provider pair. The tests here cover only what
+// needs the package internals: builder states not reachable through the
+// constructor.
+
+// stubGate scopes to spans carrying a single attribute key.
+type stubGate struct {
+	key *telemetrytypes.TelemetryFieldKey
+}
+
+func (s stubGate) FilterExpression() string { return s.key.Name + " EXISTS" }
+func (s stubGate) FieldKeys() []*telemetrytypes.TelemetryFieldKey {
+	return []*telemetrytypes.TelemetryFieldKey{s.key}
+}
+
+// stubColumns is the common columns plus one orderable scoped aggregate, the
+// minimum a column provider must supply (a default order key).
+type stubColumns struct {
+	key *telemetrytypes.TelemetryFieldKey
+}
+
+func (s stubColumns) Columns() []TraceColumn {
+	return append(CommonTraceColumns(),
+		TraceColumn{Alias: "scoped_span_count", Orderable: true, Expr: CountExists(s.key)})
+}
+func (s stubColumns) DefaultOrderAlias() string { return "scoped_span_count" }
+func (s stubColumns) AggregateAliases() []string {
+	aliases := make([]string, 0)
+	for _, c := range s.Columns() {
+		if !c.SpanLevel {
+			aliases = append(aliases, c.Alias)
+		}
+	}
+	return aliases
+}
+
+// renderSQL substitutes bound args into the `?` placeholders so assertions can
+// match the statement as one literal SQL string.
+func renderSQL(t *testing.T, stmt *qbtypes.Statement) string {
+	t.Helper()
+	var b strings.Builder
+	argi := 0
+	for i := 0; i < len(stmt.Query); i++ {
+		if stmt.Query[i] == '?' {
+			require.Less(t, argi, len(stmt.Args), "more ? than args in query")
+			if s, ok := stmt.Args[argi].(string); ok {
+				b.WriteString("'" + s + "'")
+			} else {
+				fmt.Fprintf(&b, "%v", stmt.Args[argi])
+			}
+			argi++
+			continue
+		}
+		b.WriteByte(stmt.Query[i])
+	}
+	require.Equal(t, len(stmt.Args), argi, "arg count does not match number of placeholders")
+	return b.String()
+}
+
+// With the resolver unset (nil), the resource filter falls back to being applied inline
+// on the span index — no fingerprint CTE — so existing behavior is preserved. The nil
+// state is not reachable through the constructor, hence the direct struct literal.
+func TestBuild_TraceList_ResourceFilter_NoResolver(t *testing.T) {
+	gateKey := &telemetrytypes.TelemetryFieldKey{
+		Name:          "scope.marker",
+		Signal:        telemetrytypes.SignalTraces,
+		FieldContext:  telemetrytypes.FieldContextAttribute,
+		FieldDataType: telemetrytypes.FieldDataTypeString,
+	}
+	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
+	mockMetadataStore.KeysMap = map[string][]*telemetrytypes.TelemetryFieldKey{
+		gateKey.Name: {gateKey},
+		"service.name": {{
+			Name:          "service.name",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+	}
+
+	settings := factory.NewScopedProviderSettings(instrumentationtest.New().ToProviderSettings(), "github.com/SigNoz/signoz/pkg/telemetryscopedtraces")
+	fm := telemetrytraces.NewFieldMapper()
+	b := &scopedTraceStatementBuilder{
+		logger:                 settings.Logger(),
+		metadataStore:          mockMetadataStore,
+		fm:                     fm,
+		cb:                     telemetrytraces.NewConditionBuilder(fm),
+		baseCond:               stubGate{key: gateKey},
+		columnProvider:         stubColumns{key: gateKey},
+		resourceFilterResolver: nil,
+	}
+
+	stmt, err := b.Build(context.Background(), 1747947419000, 1747983448000, qbtypes.RequestTypeTrace,
+		qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+			Signal: telemetrytypes.SignalTraces,
+			Filter: &qbtypes.Filter{Expression: "resource.service.name = 'checkout'"},
+			Limit:  10,
+		}, nil)
+	require.NoError(t, err)
+
+	got := renderSQL(t, stmt)
+	require.NotContains(t, got, "__resource_filter")
+	require.Contains(t, got, "resources_string['service.name']")
+}
+
+// embedExpr treats every `?` byte as a placeholder; a count/args mismatch (an expr
+// carrying a literal `?`, or a dropped arg) must fail loudly instead of silently
+// shifting every subsequent arg into the wrong placeholder.
+func TestEmbedExpr_PlaceholderArgMismatch(t *testing.T) {
+	sb := sqlbuilder.NewSelectBuilder()
+
+	out, err := embedExpr(sb, "x = ? AND y = ?", []any{1, 2})
+	require.NoError(t, err)
+	require.Equal(t, 2, strings.Count(out, "$"), "both placeholders bound as builder vars")
+
+	_, err = embedExpr(sb, "x = ? AND y LIKE 'a?b'", []any{1})
+	require.Error(t, err, "literal ? in the expr must not pass as a placeholder")
+
+	_, err = embedExpr(sb, "x = ?", []any{1, 2})
+	require.Error(t, err, "extra args must not be silently dropped")
+}

pkg/telemetrytraces/statement_builder.go

@@ -29,6 +29,9 @@ type traceQueryStatementBuilder struct {
 	resourceFilterResolver         *telemetryresourcefilter.ResourceFingerprintResolver[qbtypes.TraceAggregation]
 	aggExprRewriter                qbtypes.AggExprRewriter
 	skipResourceFingerprintEnabled bool
+	// traceScope is set only on the per-call copy made by BuildTraceScoped; it
+	// constrains the query to trace ids selected by the __trace_scope CTE.
+	traceScope *qbtypes.Statement
 }
 
 var _ qbtypes.StatementBuilder[qbtypes.TraceAggregation] = (*traceQueryStatementBuilder)(nil)
@@ -70,6 +73,32 @@ func NewTraceQueryStatementBuilder(
 	}
 }
 
+// BuildTraceScoped is Build additionally constrained to spans whose trace_id is
+// selected by traceScope. The receiver is copied so the shared builder stays stateless.
+func (b *traceQueryStatementBuilder) BuildTraceScoped(
+	ctx context.Context,
+	start uint64,
+	end uint64,
+	requestType qbtypes.RequestType,
+	query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation],
+	variables map[string]qbtypes.VariableItem,
+	traceScope *qbtypes.Statement,
+) (*qbtypes.Statement, error) {
+	scoped := *b
+	scoped.traceScope = traceScope
+	return scoped.Build(ctx, start, end, requestType, query, variables)
+}
+
+// attachTraceScope adds the trace-scope condition to sb and returns the CTE fragment
+// + args to prepend; both empty when no scope is set.
+func (b *traceQueryStatementBuilder) attachTraceScope(sb *sqlbuilder.SelectBuilder) (string, []any) {
+	if b.traceScope == nil {
+		return "", nil
+	}
+	sb.Where("trace_id GLOBAL IN (SELECT trace_id FROM __trace_scope)")
+	return fmt.Sprintf("__trace_scope AS (%s)", b.traceScope.Query), b.traceScope.Args
+}
+
 // Build builds a SQL query for traces based on the given parameters.
 func (b *traceQueryStatementBuilder) Build(
 	ctx context.Context,
@@ -292,6 +321,11 @@ func (b *traceQueryStatementBuilder) buildListQuery(
 		cteArgs = append(cteArgs, args)
 	}
 
+	if scopeFrag, scopeArgs := b.attachTraceScope(sb); scopeFrag != "" {
+		cteFragments = append(cteFragments, scopeFrag)
+		cteArgs = append(cteArgs, scopeArgs)
+	}
+
 	for _, field := range query.SelectFields {
 		colExpr, err := b.fm.ColumnExpressionFor(ctx, start, end, &field, keys)
 		if err != nil {

pkg/types/llmpricingruletypes/pricing.go

@@ -16,18 +16,10 @@ import (
 const (
 	LLMCostFeatureType agentConf.AgentFeatureType = "llm_pricing"
 
-	GenAIRequestModel                  = "gen_ai.request.model"
-	GenAIProviderName                  = "gen_ai.provider.name"
-	GenAIUsageInputTokens              = "gen_ai.usage.input_tokens"
-	GenAIUsageOutputTokens             = "gen_ai.usage.output_tokens"
-	GenAIUsageCacheReadInputTokens     = "gen_ai.usage.cache_read.input_tokens"
-	GenAIUsageCacheCreationInputTokens = "gen_ai.usage.cache_creation.input_tokens"
-
 	SignozGenAICostInput      = "_signoz.gen_ai.cost_input"
 	SignozGenAICostOutput     = "_signoz.gen_ai.cost_output"
 	SignozGenAICostCacheRead  = "_signoz.gen_ai.cost_cache_read"
 	SignozGenAICostCacheWrite = "_signoz.gen_ai.cost_cache_write"
-	SignozGenAITotalCost      = "_signoz.gen_ai.total_cost"
 )
 
 var (

pkg/types/llmpricingruletypes/processorconfig.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 
 	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"gopkg.in/yaml.v3"
 )
 
@@ -83,11 +84,11 @@ func buildProcessorConfig(rules []*LLMPricingRule) *LLMPricingRuleProcessorConfi
 
 	return &LLMPricingRuleProcessorConfig{
 		Attrs: LLMPricingRuleProcessorAttrs{
-			Model:      GenAIRequestModel,
-			In:         GenAIUsageInputTokens,
-			Out:        GenAIUsageOutputTokens,
-			CacheRead:  GenAIUsageCacheReadInputTokens,
-			CacheWrite: GenAIUsageCacheCreationInputTokens,
+			Model:      telemetrytypes.GenAIRequestModel,
+			In:         telemetrytypes.GenAIUsageInputTokens,
+			Out:        telemetrytypes.GenAIUsageOutputTokens,
+			CacheRead:  telemetrytypes.GenAIUsageCacheReadInputTokens,
+			CacheWrite: telemetrytypes.GenAIUsageCacheCreationInputTokens,
 		},
 		DefaultPricing: LLMPricingRuleProcessorDefaultPricing{
 			Rules: pricingRules,
@@ -97,7 +98,7 @@ func buildProcessorConfig(rules []*LLMPricingRule) *LLMPricingRuleProcessorConfi
 			Out:        SignozGenAICostOutput,
 			CacheRead:  SignozGenAICostCacheRead,
 			CacheWrite: SignozGenAICostCacheWrite,
-			Total:      SignozGenAITotalCost,
+			Total:      telemetrytypes.SignozGenAITotalCost,
 		},
 	}
 }

pkg/types/telemetrytypes/genai_semconv.go

@@ -0,0 +1,43 @@
+package telemetrytypes
+
+// OpenTelemetry gen_ai semantic-convention attribute keys. Single source of truth
+// shared by the AI query builder and the LLM pricing pipeline.
+const (
+	GenAIRequestModel = "gen_ai.request.model"
+	GenAIToolName     = "gen_ai.tool.name"
+	GenAIAgentName    = "gen_ai.agent.name"
+	GenAIProviderName = "gen_ai.provider.name"
+
+	GenAIUsageInputTokens              = "gen_ai.usage.input_tokens"
+	GenAIUsageOutputTokens             = "gen_ai.usage.output_tokens"
+	GenAIUsageCacheReadInputTokens     = "gen_ai.usage.cache_read.input_tokens"
+	GenAIUsageCacheCreationInputTokens = "gen_ai.usage.cache_creation.input_tokens"
+
+	GenAIInputMessages  = "gen_ai.input.messages"
+	GenAIOutputMessages = "gen_ai.output.messages"
+
+	// SignozGenAITotalCost is not OTel semconv: it is the per-span total cost the
+	// SigNoz LLM pricing processor computes and attaches (see llmpricingruletypes).
+	SignozGenAITotalCost = "_signoz.gen_ai.total_cost"
+)
+
+// GenAIFieldDefinitions are the gen_ai semantic-convention span attributes the AI
+// query builder relies on. They are surfaced by the metadata store for trace
+// queries regardless of whether they have been ingested yet, so the AI gate/columns
+// resolve on a fresh install (mirrors intrinsic metric keys). String keys are the
+// gate; the usage keys are numeric.
+var GenAIFieldDefinitions = map[string]TelemetryFieldKey{
+	GenAIRequestModel: {Name: GenAIRequestModel, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeString},
+	GenAIToolName:     {Name: GenAIToolName, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeString},
+	GenAIAgentName:    {Name: GenAIAgentName, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeString},
+	GenAIProviderName: {Name: GenAIProviderName, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeString},
+
+	GenAIUsageInputTokens:              {Name: GenAIUsageInputTokens, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeFloat64},
+	GenAIUsageOutputTokens:             {Name: GenAIUsageOutputTokens, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeFloat64},
+	GenAIUsageCacheReadInputTokens:     {Name: GenAIUsageCacheReadInputTokens, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeFloat64},
+	GenAIUsageCacheCreationInputTokens: {Name: GenAIUsageCacheCreationInputTokens, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeFloat64},
+	SignozGenAITotalCost:               {Name: SignozGenAITotalCost, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeFloat64},
+
+	GenAIInputMessages:  {Name: GenAIInputMessages, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeString},
+	GenAIOutputMessages: {Name: GenAIOutputMessages, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeString},
+}

pkg/types/telemetrytypes/source.go

@@ -9,6 +9,7 @@ type Source struct {
 var (
 	SourceAudit       = Source{valuer.NewString("audit")}
 	SourceMeter       = Source{valuer.NewString("meter")}
+	SourceAI          = Source{valuer.NewString("ai")}
 	SourceUnspecified = Source{valuer.NewString("")}
 )
 
@@ -17,5 +18,6 @@ var (
 func (Source) Enum() []any {
 	return []any{
 		SourceMeter,
+		SourceAI,
 	}
 }

tests/fixtures/querier.py

@@ -79,10 +79,13 @@ class BuilderQuery:
     name: str = "A"
     source: str | None = None
     limit: int | None = None
+    offset: int | None = None
     filter_expression: str | None = None
+    having_expression: str | None = None
     select_fields: list[TelemetryFieldKey] | None = None
     order: list[OrderBy] | None = None
     aggregations: list[Aggregation | MetricAggregation] | None = None
+    group_by: list[TelemetryFieldKey] | None = None
     step_interval: int | None = None
 
     def to_dict(self) -> dict:
@@ -94,14 +97,20 @@ class BuilderQuery:
             spec["source"] = self.source
         if self.limit is not None:
             spec["limit"] = self.limit
+        if self.offset is not None:
+            spec["offset"] = self.offset
         if self.filter_expression:
             spec["filter"] = {"expression": self.filter_expression}
+        if self.having_expression:
+            spec["having"] = {"expression": self.having_expression}
         if self.select_fields:
             spec["selectFields"] = [f.to_dict() for f in self.select_fields]
         if self.order:
             spec["order"] = [o.to_dict() if hasattr(o, "to_dict") else o for o in self.order]
         if self.aggregations:
             spec["aggregations"] = [agg.to_dict() if hasattr(agg, "to_dict") else agg for agg in self.aggregations]
+        if self.group_by:
+            spec["groupBy"] = [k.to_dict() for k in self.group_by]
         if self.step_interval is not None:
             spec["stepInterval"] = self.step_interval
 

tests/integration/tests/querierai/01_ai_traces.py

@@ -0,0 +1,881 @@
+"""
+Integration tests for source="ai" over the traces signal.
+
+Data shape (generic OTel gen_ai semantic conventions):
+  - a root span (no gen_ai attributes)
+  - an LLM span carrying gen_ai.request.model (str) and numeric usage attributes
+    (gen_ai.usage.input_tokens / output_tokens / cost) plus gen_ai.user.id
+Each test tags its spans with a unique service.name and filters on it, so tests do
+not interfere with each other's data.
+"""
+
+import json
+from collections.abc import Callable
+from datetime import UTC, datetime, timedelta
+from http import HTTPStatus
+
+import pytest
+
+from fixtures import types
+from fixtures.auth import USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD
+from fixtures.querier import (
+    BuilderQuery,
+    OrderBy,
+    RequestType,
+    TelemetryFieldKey,
+    make_query_request,
+)
+from fixtures.traces import TraceIdGenerator, Traces, TracesKind, TracesStatusCode
+
+
+def _ai_trace(
+    *,
+    now: datetime,
+    service: str,
+    user: str,
+    in_tokens: int | None,
+    out_tokens: int,
+    cost: float,
+    model: str = "gpt-4o-mini",
+    llm_duration_s: float = 1.0,
+    error: bool = False,
+    environment: str = "production",
+) -> list[Traces]:
+    """A minimal AI trace: root span + one LLM span with gen_ai attributes.
+    in_tokens=None omits the input-tokens attribute entirely (not zero)."""
+    trace_id = TraceIdGenerator.trace_id()
+    root_id = TraceIdGenerator.span_id()
+    llm_id = TraceIdGenerator.span_id()
+    resources = {"service.name": service, "deployment.environment": environment}
+
+    root = Traces(
+        timestamp=now - timedelta(seconds=5),
+        duration=timedelta(seconds=llm_duration_s + 0.1),
+        trace_id=trace_id,
+        span_id=root_id,
+        parent_span_id="",
+        name="POST /api/chat",
+        kind=TracesKind.SPAN_KIND_SERVER,
+        status_code=TracesStatusCode.STATUS_CODE_OK,
+        resources=resources,
+        attributes={"http.request.method": "POST"},
+    )
+    attributes = {
+        "gen_ai.request.model": model,
+        "gen_ai.system": "openai",
+        "gen_ai.user.id": user,
+        # numeric values land in attributes_number
+        "gen_ai.usage.output_tokens": out_tokens,
+        "_signoz.gen_ai.total_cost": cost,
+    }
+    if in_tokens is not None:
+        attributes["gen_ai.usage.input_tokens"] = in_tokens
+    llm = Traces(
+        timestamp=now - timedelta(seconds=4),
+        duration=timedelta(seconds=llm_duration_s),
+        trace_id=trace_id,
+        span_id=llm_id,
+        parent_span_id=root_id,
+        name="chat gpt-4o-mini",
+        kind=TracesKind.SPAN_KIND_CLIENT,
+        status_code=(TracesStatusCode.STATUS_CODE_ERROR if error else TracesStatusCode.STATUS_CODE_OK),
+        resources=resources,
+        attributes=attributes,
+    )
+    return [root, llm]
+
+
+def _non_ai_trace(*, now: datetime, service: str) -> list[Traces]:
+    """A plain HTTP trace with no gen_ai attributes; must be excluded by the AI gate."""
+    trace_id = TraceIdGenerator.trace_id()
+    span_id = TraceIdGenerator.span_id()
+    return [
+        Traces(
+            timestamp=now - timedelta(seconds=4),
+            duration=timedelta(seconds=1),
+            trace_id=trace_id,
+            span_id=span_id,
+            parent_span_id="",
+            name="GET /health",
+            kind=TracesKind.SPAN_KIND_SERVER,
+            status_code=TracesStatusCode.STATUS_CODE_OK,
+            resources={"service.name": service},
+            attributes={"http.request.method": "GET"},
+        )
+    ]
+
+
+def _window_ms(now: datetime) -> tuple[int, int]:
+    start_ms = int((now - timedelta(minutes=10)).timestamp() * 1000)
+    end_ms = int((now + timedelta(minutes=1)).timestamp() * 1000)
+    return start_ms, end_ms
+
+
+def test_ai_list_excludes_non_ai(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_traces: Callable[[list[Traces]], None],
+) -> None:
+    """
+    Trace-list panel (requestType="trace"): returns AI traces and excludes the
+    non-AI trace. Asserts on the raw response payload to stay agnostic to the exact
+    row schema.
+    """
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+    service = "ai-it-list"
+
+    ai = _ai_trace(now=now, service=service, user="alice", in_tokens=100, out_tokens=20, cost=0.5)
+    non_ai = _non_ai_trace(now=now, service=service)
+    ai_trace_id = ai[0].trace_id
+    non_ai_trace_id = non_ai[0].trace_id
+    insert_traces(ai + non_ai)
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    start_ms, end_ms = _window_ms(now)
+
+    query = BuilderQuery(
+        signal="traces",
+        source="ai",
+        name="A",
+        filter_expression=f"service.name = '{service}'",
+        limit=10,
+    )
+
+    response = make_query_request(signoz, token, start_ms, end_ms, [query.to_dict()], request_type="trace")
+    assert response.status_code == HTTPStatus.OK, response.text
+
+    body = json.dumps(response.json())
+    assert ai_trace_id in body, f"expected AI trace {ai_trace_id} in list response"
+    assert non_ai_trace_id not in body, f"non-AI trace {non_ai_trace_id} should be excluded by the gate"
+
+
+def _ai_trace_mixed_spans(*, now: datetime, service: str, user: str) -> list[Traces]:
+    """
+    Root + one LLM span + one tool span + one agent span. The gate matches all three
+    child spans, but only the LLM span carries gen_ai.request.model.
+    """
+    trace_id = TraceIdGenerator.trace_id()
+    root_id = TraceIdGenerator.span_id()
+    resources = {"service.name": service, "deployment.environment": "production"}
+
+    def _span(name, kind, attributes, offset_s):
+        return Traces(
+            timestamp=now - timedelta(seconds=offset_s),
+            duration=timedelta(seconds=0.5),
+            trace_id=trace_id,
+            span_id=TraceIdGenerator.span_id(),
+            parent_span_id=root_id,
+            name=name,
+            kind=kind,
+            status_code=TracesStatusCode.STATUS_CODE_OK,
+            resources=resources,
+            attributes=attributes,
+        )
+
+    root = Traces(
+        timestamp=now - timedelta(seconds=5),
+        duration=timedelta(seconds=4),
+        trace_id=trace_id,
+        span_id=root_id,
+        parent_span_id="",
+        name="POST /api/chat",
+        kind=TracesKind.SPAN_KIND_SERVER,
+        status_code=TracesStatusCode.STATUS_CODE_OK,
+        resources=resources,
+        attributes={"http.request.method": "POST"},
+    )
+    llm = _span(
+        "chat gpt-4o-mini",
+        TracesKind.SPAN_KIND_CLIENT,
+        {
+            "gen_ai.request.model": "gpt-4o-mini",
+            "gen_ai.system": "openai",
+            "gen_ai.user.id": user,
+            "gen_ai.usage.input_tokens": 100,
+            "gen_ai.usage.output_tokens": 20,
+        },
+        4,
+    )
+    tool = _span(
+        "execute_tool",
+        TracesKind.SPAN_KIND_INTERNAL,
+        {
+            "gen_ai.tool.name": "get_weather",
+            "gen_ai.tool.type": "function",
+        },
+        3,
+    )
+    agent = _span(
+        "agent.step",
+        TracesKind.SPAN_KIND_INTERNAL,
+        {
+            "gen_ai.agent.name": "chat-agent",
+        },
+        2,
+    )
+    return [root, llm, tool, agent]
+
+
+def test_ai_list_having_aggregate_filter(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_traces: Callable[[list[Traces]], None],
+) -> None:
+    """
+    Aggregate filter written in the SAME filter box: the span-level predicate narrows
+    to the service, the trace-level `output_tokens > 100` keeps the large-token
+    trace and drops the small one (split internally into WHERE + HAVING). All three
+    spellings of a trace-level aggregate — bare, `trace.`, `tracefield.` — behave
+    identically (unit tests pin them to byte-identical SQL; this covers the wiring
+    once end-to-end). An output-only aggregate is rejected under any spelling.
+    """
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+    service = "ai-it-having"
+
+    small = _ai_trace(now=now, service=service, user="alice", in_tokens=10, out_tokens=20, cost=0.1)
+    large = _ai_trace(now=now, service=service, user="bob", in_tokens=10, out_tokens=500, cost=0.2)
+    small_id = small[0].trace_id
+    large_id = large[0].trace_id
+    insert_traces(small + large)
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    start_ms, end_ms = _window_ms(now)
+
+    for spelling in ("output_tokens", "trace.output_tokens", "tracefield.output_tokens"):
+        query = BuilderQuery(
+            signal="traces",
+            source="ai",
+            name="A",
+            filter_expression=f"service.name = '{service}' AND {spelling} > 100",
+            limit=10,
+        )
+        response = make_query_request(signoz, token, start_ms, end_ms, [query.to_dict()], request_type="trace")
+        assert response.status_code == HTTPStatus.OK, f"{spelling}: {response.text}"
+
+        body = json.dumps(response.json())
+        assert large_id in body, f"{spelling}: trace with 500 out-tokens should pass > 100"
+        assert small_id not in body, f"{spelling}: trace with 20 out-tokens should be filtered out by HAVING"
+
+    # output-only aggregate gets the targeted rejection, also under the explicit context.
+    bad = BuilderQuery(
+        signal="traces",
+        source="ai",
+        name="A",
+        filter_expression="tracefield.span_count > 3",
+        limit=10,
+    )
+    response = make_query_request(signoz, token, start_ms, end_ms, [bad.to_dict()], request_type="trace")
+    assert response.status_code == HTTPStatus.BAD_REQUEST, response.text
+    assert "cannot be used" in response.text
+
+
+def test_ai_list_order_limit_offset(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_traces: Callable[[list[Traces]], None],
+) -> None:
+    """Trace list honors order by (aggregate column) + limit + offset (pagination)."""
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+    service = "ai-it-order"
+
+    traces: list[Traces] = []
+    for out in (100, 200, 300, 400, 500):
+        traces += _ai_trace(now=now, service=service, user="u", in_tokens=10, out_tokens=out, cost=0.1)
+    insert_traces(traces)
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    start_ms, end_ms = _window_ms(now)
+
+    def page(offset: int) -> list[int]:
+        query = BuilderQuery(
+            signal="traces",
+            source="ai",
+            name="A",
+            filter_expression=f"service.name = '{service}'",
+            order=[OrderBy(key=TelemetryFieldKey(name="output_tokens"), direction="desc")],
+            limit=2,
+            offset=offset,
+        )
+        resp = make_query_request(signoz, token, start_ms, end_ms, [query.to_dict()], request_type="trace")
+        assert resp.status_code == HTTPStatus.OK, resp.text
+        rows = resp.json()["data"]["data"]["results"][0]["rows"]
+        return [int(r["data"]["output_tokens"]) for r in rows]
+
+    assert page(0) == [500, 400], "first page: highest output_tokens, desc"
+    assert page(2) == [300, 200], "second page (offset 2): next two, desc"
+
+
+def test_ai_span_list_limit(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_traces: Callable[[list[Traces]], None],
+) -> None:
+    """Span list honors limit (delegated raw path): 6 gen_ai spans available, capped to 4."""
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+    service = "ai-it-spanlimit"
+    insert_traces(_ai_trace_mixed_spans(now=now, service=service, user="a") + _ai_trace_mixed_spans(now=now, service=service, user="b"))
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    start_ms, end_ms = _window_ms(now)
+
+    query = BuilderQuery(
+        signal="traces",
+        source="ai",
+        name="A",
+        filter_expression=f"service.name = '{service}'",
+        limit=4,
+    )
+    resp = make_query_request(signoz, token, start_ms, end_ms, [query.to_dict()], request_type=RequestType.RAW)
+    assert resp.status_code == HTTPStatus.OK, resp.text
+    rows = resp.json()["data"]["data"]["results"][0]["rows"]
+    assert len(rows) == 4, f"limit should cap at 4 (6 gen_ai spans available), got {len(rows)}"
+
+
+def test_ai_span_list_excludes_non_gen_ai_spans(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_traces: Callable[[list[Traces]], None],
+) -> None:
+    """
+    Span list (requestType=raw): returns only the gen_ai spans (LLM/tool/agent); the
+    root span of the same trace (no gen_ai attributes) is excluded by the span-level gate.
+    """
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+    service = "ai-it-spanlist"
+    insert_traces(_ai_trace_mixed_spans(now=now, service=service, user="alice"))
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    start_ms, end_ms = _window_ms(now)
+
+    query = BuilderQuery(
+        signal="traces",
+        source="ai",
+        name="A",
+        filter_expression=f"service.name = '{service}'",
+        select_fields=[TelemetryFieldKey(name="name", field_context="span")],
+        limit=50,
+    )
+    response = make_query_request(signoz, token, start_ms, end_ms, [query.to_dict()], request_type=RequestType.RAW)
+    assert response.status_code == HTTPStatus.OK, response.text
+
+    rows = response.json()["data"]["data"]["results"][0]["rows"]
+    names = sorted(r["data"]["name"] for r in rows)
+    assert names == ["agent.step", "chat gpt-4o-mini", "execute_tool"], names
+    assert "POST /api/chat" not in names  # root span excluded
+
+
+def test_ai_span_list_trace_level_filter(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_traces: Callable[[list[Traces]], None],
+) -> None:
+    """
+    Span list (raw) with a trace-level condition: only gen_ai spans of traces whose
+    window-clipped aggregates qualify come back (the __trace_scope qualification on
+    the delegated path). Two traces with out-tokens 100 / 300: `trace.output_tokens
+    > 100` keeps only the large trace's LLM span.
+    """
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+    service = "ai-it-spanlist-tracefilter"
+    small = _ai_trace(now=now, service=service, user="a", in_tokens=10, out_tokens=100, cost=0.1)
+    large = _ai_trace(now=now, service=service, user="b", in_tokens=30, out_tokens=300, cost=0.2)
+    insert_traces(small + large)
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    start_ms, end_ms = _window_ms(now)
+
+    query = BuilderQuery(
+        signal="traces",
+        source="ai",
+        name="A",
+        filter_expression=f"service.name = '{service}' AND trace.output_tokens > 100",
+        limit=10,
+    )
+    resp = make_query_request(signoz, token, start_ms, end_ms, [query.to_dict()], request_type=RequestType.RAW)
+    assert resp.status_code == HTTPStatus.OK, resp.text
+
+    rows = resp.json()["data"]["data"]["results"][0]["rows"]
+    assert len(rows) == 1, f"expected only the large trace's LLM span, got {len(rows)} rows"
+    body = json.dumps(rows)
+    assert large[0].trace_id in body
+    assert small[0].trace_id not in body
+
+
+def test_ai_list_having_or_aggregates(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_traces: Callable[[list[Traces]], None],
+) -> None:
+    """
+    Two trace-level aggregates OR-ed within the filter box (regression guard for OR-group
+    whitespace handling): output_tokens > 100 OR input_tokens > 1000 keeps only the
+    large-output trace (input_tokens is 10 for both, so that branch never matches).
+    """
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+    service = "ai-it-having-or"
+
+    small = _ai_trace(now=now, service=service, user="a", in_tokens=10, out_tokens=20, cost=0.1)
+    large = _ai_trace(now=now, service=service, user="b", in_tokens=10, out_tokens=500, cost=0.2)
+    small_id, large_id = small[0].trace_id, large[0].trace_id
+    insert_traces(small + large)
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    start_ms, end_ms = _window_ms(now)
+
+    query = BuilderQuery(
+        signal="traces",
+        source="ai",
+        name="A",
+        filter_expression=f"service.name = '{service}' AND (output_tokens > 100 OR input_tokens > 1000)",
+        limit=10,
+    )
+    response = make_query_request(signoz, token, start_ms, end_ms, [query.to_dict()], request_type="trace")
+    assert response.status_code == HTTPStatus.OK, response.text
+
+    body = json.dumps(response.json())
+    assert large_id in body
+    assert small_id not in body
+
+
+def test_ai_list_resource_filter_isolates_by_fingerprint(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_traces: Callable[[list[Traces]], None],
+) -> None:
+    """
+    A resource attribute in the filter is pulled into the __resource_filter fingerprint
+    CTE (see maybeAttachResourceFilter). Two traces on the same service but different
+    deployment.environment: `resource.deployment.environment = 'production'` must keep
+    the production trace and drop the staging one — the fingerprint prune isolates by
+    the resource, not by any span attribute.
+    """
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+    service = "ai-it-resfilter"
+
+    prod = _ai_trace(now=now, service=service, user="a", in_tokens=10, out_tokens=20, cost=0.1, environment="production")
+    stag = _ai_trace(now=now, service=service, user="b", in_tokens=10, out_tokens=20, cost=0.1, environment="staging")
+    prod_id, stag_id = prod[0].trace_id, stag[0].trace_id
+    insert_traces(prod + stag)
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    start_ms, end_ms = _window_ms(now)
+
+    query = BuilderQuery(
+        signal="traces",
+        source="ai",
+        name="A",
+        filter_expression=(f"resource.service.name = '{service}' AND resource.deployment.environment = 'production'"),
+        limit=10,
+    )
+    response = make_query_request(signoz, token, start_ms, end_ms, [query.to_dict()], request_type="trace")
+    assert response.status_code == HTTPStatus.OK, response.text
+
+    body = json.dumps(response.json())
+    assert prod_id in body, "production trace should match the resource filter"
+    assert stag_id not in body, "staging trace should be excluded by the resource fingerprint prune"
+
+
+def test_ai_list_rejects_aggregate_or_span_filter(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_traces: Callable[[list[Traces]], None],
+) -> None:
+    """
+    Aggregate (HAVING) columns may not be OR-ed with span-level keys in the trace
+    list; a span-OR-span filter is fine.
+    """
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+    service = "ai-it-orfilter"
+    # seed a trace so service.name resolves as a known key in this window (resource
+    # keys are discovered from ingested data).
+    insert_traces(_ai_trace(now=now, service=service, user="a", in_tokens=10, out_tokens=20, cost=0.1))
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    start_ms, end_ms = _window_ms(now)
+
+    # aggregate OR span -> rejected
+    bad = BuilderQuery(
+        signal="traces",
+        source="ai",
+        name="A",
+        limit=10,
+        filter_expression=f"output_tokens > 1000 OR service.name = '{service}'",
+    )
+    response = make_query_request(signoz, token, start_ms, end_ms, [bad.to_dict()], request_type="trace")
+    assert response.status_code == HTTPStatus.BAD_REQUEST, response.text
+    assert "cannot be combined" in response.text
+
+    # span OR span -> accepted (result content doesn't matter; just not an error)
+    ok = BuilderQuery(
+        signal="traces",
+        source="ai",
+        name="A",
+        limit=10,
+        filter_expression=f"service.name = '{service}' OR has_error = true",
+    )
+    response = make_query_request(signoz, token, start_ms, end_ms, [ok.to_dict()], request_type="trace")
+    assert response.status_code == HTTPStatus.OK, response.text
+
+
+def test_ai_list_nested_group_span_or_and_aggregate(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_traces: Callable[[list[Traces]], None],
+) -> None:
+    """
+    A complex filter that mixes all three routing paths in one expression:
+        service.name = X AND (has_error = true OR gen_ai.request.model = 'gpt-4o') AND total_tokens > 100
+    The nested (span OR span) group must not flatten (precedence), the span predicates
+    go to WHERE as a trace-existence check, and the new `total_tokens` aggregate goes to
+    HAVING. Three traces isolate each discriminator:
+      - t_ok:      gpt-4o, out=500 -> OR matches (model) AND total_tokens>100  -> IN
+      - t_or_miss: gpt-4o-mini, out=500 -> OR fails (no error, wrong model)    -> OUT
+      - t_agg_miss: gpt-4o, out=20  -> OR matches but total_tokens<=100         -> OUT
+    """
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+    service = "ai-it-nested"
+
+    t_ok = _ai_trace(now=now, service=service, user="a", model="gpt-4o", in_tokens=10, out_tokens=500, cost=0.1)
+    t_or_miss = _ai_trace(now=now, service=service, user="b", model="gpt-4o-mini", in_tokens=10, out_tokens=500, cost=0.1)
+    t_agg_miss = _ai_trace(now=now, service=service, user="c", model="gpt-4o", in_tokens=10, out_tokens=20, cost=0.1)
+    insert_traces(t_ok + t_or_miss + t_agg_miss)
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    start_ms, end_ms = _window_ms(now)
+
+    query = BuilderQuery(
+        signal="traces",
+        source="ai",
+        name="A",
+        filter_expression=(f"service.name = '{service}' AND (has_error = true OR gen_ai.request.model = 'gpt-4o') AND total_tokens > 100"),
+        limit=10,
+    )
+    response = make_query_request(signoz, token, start_ms, end_ms, [query.to_dict()], request_type="trace")
+    assert response.status_code == HTTPStatus.OK, response.text
+
+    body = json.dumps(response.json())
+    assert t_ok[0].trace_id in body
+    assert t_or_miss[0].trace_id not in body, "nested (span OR span) group must exclude the wrong-model, no-error trace"
+    assert t_agg_miss[0].trace_id not in body, "HAVING total_tokens > 100 must exclude the low-token trace"
+
+
+def test_ai_list_rejects_unknown_aggregate_key(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+) -> None:
+    """A trace-level filter on an unknown aggregate name is rejected, not silently run."""
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    start_ms, end_ms = _window_ms(now)
+
+    query = BuilderQuery(
+        signal="traces",
+        source="ai",
+        name="A",
+        limit=10,
+        filter_expression="trace.bogus_tokens > 1",
+    )
+    response = make_query_request(signoz, token, start_ms, end_ms, [query.to_dict()], request_type="trace")
+    assert response.status_code == HTTPStatus.BAD_REQUEST, response.text
+
+
+def test_ai_list_rejects_order_by_span_attribute(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+) -> None:
+    """Only gen_ai-scoped aggregates are orderable; ordering by a span/resource key errors."""
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    start_ms, end_ms = _window_ms(now)
+
+    query = BuilderQuery(
+        signal="traces",
+        source="ai",
+        name="A",
+        limit=5,
+        order=[OrderBy(key=TelemetryFieldKey(name="service.name"), direction="asc")],
+    )
+    response = make_query_request(signoz, token, start_ms, end_ms, [query.to_dict()], request_type="trace")
+    assert response.status_code == HTTPStatus.BAD_REQUEST, response.text
+    assert "order key" in response.text
+
+
+def test_ai_list_total_tokens_output_only(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_traces: Callable[[list[Traces]], None],
+) -> None:
+    """
+    A trace whose LLM span carries only output tokens (no input-tokens attribute at
+    all) must still total: total_tokens is coalesce(sum(in),0)+coalesce(sum(out),0),
+    since sum over an absent attribute is NULL and NULL + n = NULL in ClickHouse.
+    """
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+    service = "ai-it-total-coalesce"
+    insert_traces(_ai_trace(now=now, service=service, user="a", in_tokens=None, out_tokens=300, cost=0.1))
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    start_ms, end_ms = _window_ms(now)
+
+    query = BuilderQuery(
+        signal="traces",
+        source="ai",
+        name="A",
+        filter_expression=f"service.name = '{service}'",
+        limit=10,
+    )
+    response = make_query_request(signoz, token, start_ms, end_ms, [query.to_dict()], request_type="trace")
+    assert response.status_code == HTTPStatus.OK, response.text
+
+    rows = response.json()["data"]["data"]["results"][0]["rows"]
+    assert len(rows) == 1, f"expected one trace, got: {rows}"
+    data = rows[0]["data"]
+    assert data["input_tokens"] is None, data  # attribute absent -> NULL, not 0
+    assert data["output_tokens"] == 300, data
+    assert data["total_tokens"] == 300, f"total must coalesce the missing input side: {data}"
+
+
+def test_ai_list_variable_in_aggregate_filter(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_traces: Callable[[list[Traces]], None],
+) -> None:
+    """A query variable in a trace-level condition is substituted into the HAVING."""
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+    service = "ai-it-having-var"
+
+    small = _ai_trace(now=now, service=service, user="a", in_tokens=10, out_tokens=20, cost=0.1)
+    large = _ai_trace(now=now, service=service, user="b", in_tokens=10, out_tokens=500, cost=0.2)
+    small_id, large_id = small[0].trace_id, large[0].trace_id
+    insert_traces(small + large)
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    start_ms, end_ms = _window_ms(now)
+
+    query = BuilderQuery(
+        signal="traces",
+        source="ai",
+        name="A",
+        filter_expression=f"service.name = '{service}' AND trace.output_tokens > $threshold",
+        limit=10,
+    )
+    response = make_query_request(
+        signoz,
+        token,
+        start_ms,
+        end_ms,
+        [query.to_dict()],
+        request_type="trace",
+        variables={"threshold": {"type": "custom", "value": 100}},
+    )
+    assert response.status_code == HTTPStatus.OK, response.text
+
+    body = json.dumps(response.json())
+    assert large_id in body
+    assert small_id not in body
+
+
+def _ai_trace_two_llm(*, now: datetime, service: str) -> list[Traces]:
+    """Root + two LLM spans at different times, each with distinct input/output messages."""
+    trace_id = TraceIdGenerator.trace_id()
+    root_id = TraceIdGenerator.span_id()
+    resources = {"service.name": service}
+
+    def _llm(offset_s: float, prompt: str, answer: str) -> Traces:
+        return Traces(
+            timestamp=now - timedelta(seconds=offset_s),
+            duration=timedelta(seconds=1),
+            trace_id=trace_id,
+            span_id=TraceIdGenerator.span_id(),
+            parent_span_id=root_id,
+            name="chat",
+            kind=TracesKind.SPAN_KIND_CLIENT,
+            status_code=TracesStatusCode.STATUS_CODE_OK,
+            resources=resources,
+            attributes={
+                "gen_ai.request.model": "gpt-4o-mini",
+                "gen_ai.input.messages": prompt,
+                "gen_ai.output.messages": answer,
+            },
+        )
+
+    root = Traces(
+        timestamp=now - timedelta(seconds=5),
+        duration=timedelta(seconds=4),
+        trace_id=trace_id,
+        span_id=root_id,
+        parent_span_id="",
+        name="POST /api/chat",
+        kind=TracesKind.SPAN_KIND_SERVER,
+        status_code=TracesStatusCode.STATUS_CODE_OK,
+        resources=resources,
+        attributes={"http.request.method": "POST"},
+    )
+    # earlier call is the "first" (its input is the prompt), later call is the "last"
+    # (its output is the final answer).
+    first = _llm(4, "first prompt", "first answer")
+    last = _llm(2, "second prompt", "second answer")
+    return [root, first, last]
+
+
+def test_ai_list_messages_first_input_last_output(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_traces: Callable[[list[Traces]], None],
+) -> None:
+    """
+    `input` is the FIRST LLM span's prompt (argMin over timestamp) and `output` is the
+    LAST LLM span's answer (argMax) — the question -> final-answer preview.
+    """
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+    service = "ai-it-messages"
+    insert_traces(_ai_trace_two_llm(now=now, service=service))
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    start_ms, end_ms = _window_ms(now)
+
+    query = BuilderQuery(
+        signal="traces",
+        source="ai",
+        name="A",
+        limit=10,
+        filter_expression=f"service.name = '{service}'",
+    )
+    response = make_query_request(signoz, token, start_ms, end_ms, [query.to_dict()], request_type="trace")
+    assert response.status_code == HTTPStatus.OK, response.text
+
+    rows = response.json()["data"]["data"]["results"][0]["rows"]
+    assert len(rows) == 1, f"expected one trace, got: {rows}"
+    data = rows[0]["data"]
+    assert data["input"] == "first prompt", f"input should be the earliest call's prompt: {data}"
+    assert data["output"] == "second answer", f"output should be the latest call's answer: {data}"
+
+
+def _ai_trace_for_metrics(*, now: datetime, service: str) -> list[Traces]:
+    """
+    Root + one errored LLM span (tokens/cost) + three tool spans (two 'get_weather',
+    one 'get_time') + one agent span, so the derived per-trace metrics have distinct
+    expected values. The agent span is in the gen_ai gate but carries no request.model,
+    so it must NOT count toward llm_call_count (only span_count / last_activity_time).
+    """
+    trace_id = TraceIdGenerator.trace_id()
+    root_id = TraceIdGenerator.span_id()
+    resources = {"service.name": service}
+
+    def _tool(name: str, offset_s: float) -> Traces:
+        return Traces(
+            timestamp=now - timedelta(seconds=offset_s),
+            duration=timedelta(seconds=0.2),
+            trace_id=trace_id,
+            span_id=TraceIdGenerator.span_id(),
+            parent_span_id=root_id,
+            name="execute_tool",
+            kind=TracesKind.SPAN_KIND_INTERNAL,
+            status_code=TracesStatusCode.STATUS_CODE_OK,
+            resources=resources,
+            attributes={"gen_ai.tool.name": name, "gen_ai.tool.type": "function"},
+        )
+
+    root = Traces(
+        timestamp=now - timedelta(seconds=5),
+        duration=timedelta(seconds=4),
+        trace_id=trace_id,
+        span_id=root_id,
+        parent_span_id="",
+        name="POST /api/chat",
+        kind=TracesKind.SPAN_KIND_SERVER,
+        status_code=TracesStatusCode.STATUS_CODE_OK,
+        resources=resources,
+        attributes={"http.request.method": "POST"},
+    )
+    llm = Traces(
+        timestamp=now - timedelta(seconds=4),
+        duration=timedelta(seconds=2),
+        trace_id=trace_id,
+        span_id=TraceIdGenerator.span_id(),
+        parent_span_id=root_id,
+        name="chat gpt-4o-mini",
+        kind=TracesKind.SPAN_KIND_CLIENT,
+        status_code=TracesStatusCode.STATUS_CODE_ERROR,  # -> has_error, drives error_count
+        resources=resources,
+        attributes={
+            "gen_ai.request.model": "gpt-4o-mini",
+            "gen_ai.usage.input_tokens": 100,
+            "gen_ai.usage.output_tokens": 20,
+            "_signoz.gen_ai.total_cost": 0.5,
+        },
+    )
+    agent = Traces(
+        timestamp=now - timedelta(seconds=1),
+        duration=timedelta(seconds=0.5),
+        trace_id=trace_id,
+        span_id=TraceIdGenerator.span_id(),
+        parent_span_id=root_id,
+        name="agent.step",
+        kind=TracesKind.SPAN_KIND_INTERNAL,
+        status_code=TracesStatusCode.STATUS_CODE_OK,
+        resources=resources,
+        attributes={"gen_ai.agent.name": "chat-agent"},
+    )
+    return [root, llm, _tool("get_weather", 3), _tool("get_weather", 2.5), _tool("get_time", 2), agent]
+
+
+def test_ai_list_enrichment_values(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_traces: Callable[[list[Traces]], None],
+) -> None:
+    """
+    End-to-end values of the derived per-trace columns (only integration can check that
+    ClickHouse computes uniqIf / sum+sum / countIf(predicate) correctly, not just that
+    the SQL is shaped right). One trace: root + 1 errored LLM + 3 tool spans
+    (get_weather x2, get_time x1) + 1 agent span. The tool and agent spans are in the
+    gen_ai gate but carry no request.model, so llm_call_count stays 1 while span_count
+    counts them all.
+    """
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+    service = "ai-it-metrics"
+    insert_traces(_ai_trace_for_metrics(now=now, service=service))
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    start_ms, end_ms = _window_ms(now)
+
+    query = BuilderQuery(
+        signal="traces",
+        source="ai",
+        name="A",
+        limit=10,
+        filter_expression=f"service.name = '{service}'",
+    )
+    response = make_query_request(signoz, token, start_ms, end_ms, [query.to_dict()], request_type="trace")
+    assert response.status_code == HTTPStatus.OK, response.text
+
+    rows = response.json()["data"]["data"]["results"][0]["rows"]
+    assert len(rows) == 1, f"expected one trace, got: {rows}"
+    data = rows[0]["data"]
+
+    assert data["span_count"] == 6, data  # root + llm + 3 tools + agent
+    assert data["llm_call_count"] == 1, data  # only the request.model span, not tool/agent
+    assert data["tool_call_count"] == 3, data  # all three tool spans
+    assert data["distinct_tool_count"] == 2, data  # get_weather, get_time
+    assert data["input_tokens"] == 100, data
+    assert data["output_tokens"] == 20, data
+    assert data["total_tokens"] == 120, data  # input + output
+    assert data["estimated_cost_usd"] == pytest.approx(0.5), data
+    assert data["error_count"] == 1, data  # the errored LLM span
+    assert data["max_llm_latency_ns"] > 0, data  # scoped max over LLM spans

tests/integration/tests/querierai/conftest.py

@@ -0,0 +1,38 @@
+import pytest
+from testcontainers.core.container import Network
+
+from fixtures import types
+from fixtures.signoz import create_signoz
+
+
+@pytest.fixture(name="signoz", scope="package")
+def signoz_ai_observability(
+    network: Network,
+    migrator: types.Operation,  # pylint: disable=unused-argument
+    zeus: types.TestContainerDocker,
+    gateway: types.TestContainerDocker,
+    sqlstore: types.TestContainerSQL,
+    clickhouse: types.TestContainerClickhouse,
+    request: pytest.FixtureRequest,
+    pytestconfig: pytest.Config,
+) -> types.SigNoz:
+    """
+    Package-scoped SigNoz instance with AI observability enabled. source=ai
+    queries rely on the metadata store surfacing the static gen_ai key
+    definitions (enrichWithGenAIKeys), which is gated on this flag — without it
+    the gate keys (gen_ai.tool.name, gen_ai.agent.name, ...) only resolve once
+    a span carrying them has been ingested.
+    """
+    return create_signoz(
+        network=network,
+        zeus=zeus,
+        gateway=gateway,
+        sqlstore=sqlstore,
+        clickhouse=clickhouse,
+        request=request,
+        pytestconfig=pytestconfig,
+        cache_key="signoz-ai-observability",
+        env_overrides={
+            "SIGNOZ_FLAGGER_CONFIG_BOOLEAN_ENABLE__AI__OBSERVABILITY": True,
+        },
+    )