fix: skip resource filter if it exceeds a threshold

.github/workflows/integrationci.yaml

@@ -52,6 +52,7 @@ jobs:
           - rootuser
           - serviceaccount
           - querier_json_body
+          - querier_skip_resource_fingerprint
           - ttl
         sqlstore-provider:
           - postgres

pkg/querier/config.go

@@ -7,6 +7,12 @@ import (
 	"github.com/SigNoz/signoz/pkg/factory"
 )
 
+type SkipResourceFingerprint struct {
+	Enabled bool `yaml:"enabled" mapstructure:"enabled"`
+	// If count of fingerprint is above threshold, skip the fingerprint subquery and filter on main table instead.
+	Threshold uint64 `yaml:"threshold" mapstructure:"threshold"`
+}
+
 // Config represents the configuration for the querier.
 type Config struct {
 	// CacheTTL is the TTL for cached query results
@@ -15,6 +21,8 @@ type Config struct {
 	FluxInterval time.Duration `yaml:"flux_interval" mapstructure:"flux_interval"`
 	// MaxConcurrentQueries is the maximum number of concurrent queries for missing ranges
 	MaxConcurrentQueries int `yaml:"max_concurrent_queries" mapstructure:"max_concurrent_queries"`
+	// SkipResourceFingerprint configures when the resource fingerprint subquery is skipped in favor of main-table filtering.
+	SkipResourceFingerprint SkipResourceFingerprint `yaml:"skip_resource_fingerprint" mapstructure:"skip_resource_fingerprint"`
 }
 
 // NewConfigFactory creates a new config factory for querier.
@@ -28,6 +36,10 @@ func newConfig() factory.Config {
 		CacheTTL:             168 * time.Hour,
 		FluxInterval:         5 * time.Minute,
 		MaxConcurrentQueries: 4,
+		SkipResourceFingerprint: SkipResourceFingerprint{
+			Enabled:   false,
+			Threshold: 100000,
+		},
 	}
 }
 
@@ -42,6 +54,9 @@ func (c Config) Validate() error {
 	if c.MaxConcurrentQueries <= 0 {
 		return errors.NewInvalidInputf(errors.CodeInvalidInput, "max_concurrent_queries must be positive, got %v", c.MaxConcurrentQueries)
 	}
+	if c.SkipResourceFingerprint.Enabled && c.SkipResourceFingerprint.Threshold == 0 {
+		return errors.NewInvalidInputf(errors.CodeInvalidInput, "skip_resource_fingerprint.threshold must be > 0 when enabled")
+	}
 	return nil
 }
 

pkg/querier/signozquerier/provider.go

@@ -88,6 +88,8 @@ func newProvider(
 		traceAggExprRewriter,
 		telemetryStore,
 		flagger,
+		cfg.SkipResourceFingerprint.Enabled,
+		cfg.SkipResourceFingerprint.Threshold,
 	)
 
 	// Create trace operator statement builder
@@ -121,6 +123,9 @@ func newProvider(
 		telemetrylogs.DefaultFullTextColumn,
 		telemetrylogs.GetBodyJSONKey,
 		flagger,
+		telemetryStore,
+		cfg.SkipResourceFingerprint.Enabled,
+		cfg.SkipResourceFingerprint.Threshold,
 	)
 
 	// Create audit statement builder

pkg/query-service/rules/setups_test.go

@@ -89,6 +89,9 @@ func prepareQuerierForLogs(t *testing.T, telemetryStore telemetrystore.Telemetry
 		telemetrylogs.DefaultFullTextColumn,
 		telemetrylogs.GetBodyJSONKey,
 		fl,
+		nil,
+		false,
+		100000,
 	)
 
 	return querier.New(
@@ -134,6 +137,8 @@ func prepareQuerierForTraces(t *testing.T, telemetryStore telemetrystore.Telemet
 		traceAggExprRewriter,
 		telemetryStore,
 		fl,
+		false,
+		100000,
 	)
 
 	return querier.New(

pkg/telemetrylogs/json_stmt_builder_test.go

@@ -1205,6 +1205,9 @@ func buildJSONTestStatementBuilder(t *testing.T, addIndexes bool) (*logQueryStat
 		DefaultFullTextColumn,
 		GetBodyJSONKey,
 		fl,
+		nil,
+		false,
+		100000,
 	)
 
 	return statementBuilder, mockMetadataStore

pkg/telemetrylogs/statement_builder.go

@@ -11,6 +11,7 @@ import (
 	"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/types/featuretypes"
 	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
@@ -19,13 +20,14 @@ import (
 )
 
 type logQueryStatementBuilder struct {
-	logger                    *slog.Logger
-	metadataStore             telemetrytypes.MetadataStore
-	fm                        qbtypes.FieldMapper
-	cb                        qbtypes.ConditionBuilder
-	resourceFilterStmtBuilder qbtypes.StatementBuilder[qbtypes.LogAggregation]
-	aggExprRewriter           qbtypes.AggExprRewriter
-	fl                        flagger.Flagger
+	logger                         *slog.Logger
+	metadataStore                  telemetrytypes.MetadataStore
+	fm                             qbtypes.FieldMapper
+	cb                             qbtypes.ConditionBuilder
+	resourceFilterResolver         *telemetryresourcefilter.ResourceFingerprintResolver[qbtypes.LogAggregation]
+	aggExprRewriter                qbtypes.AggExprRewriter
+	fl                             flagger.Flagger
+	skipResourceFingerprintEnabled bool
 
 	fullTextColumn *telemetrytypes.TelemetryFieldKey
 	jsonKeyToKey   qbtypes.JsonKeyToFieldFunc
@@ -42,10 +44,13 @@ func NewLogQueryStatementBuilder(
 	fullTextColumn *telemetrytypes.TelemetryFieldKey,
 	jsonKeyToKey qbtypes.JsonKeyToFieldFunc,
 	fl flagger.Flagger,
+	telemetryStore telemetrystore.TelemetryStore,
+	skipResourceFingerprintEnable bool,
+	skipResourceFingerprintThreshold uint64,
 ) *logQueryStatementBuilder {
 	logsSettings := factory.NewScopedProviderSettings(settings, "github.com/SigNoz/signoz/pkg/telemetrylogs")
 
-	resourceFilterStmtBuilder := telemetryresourcefilter.New[qbtypes.LogAggregation](
+	resourceFilterResolver := telemetryresourcefilter.NewResolver[qbtypes.LogAggregation](
 		settings,
 		DBName,
 		LogsResourceV2TableName,
@@ -55,18 +60,21 @@ func NewLogQueryStatementBuilder(
 		fullTextColumn,
 		jsonKeyToKey,
 		fl,
+		telemetryStore,
+		skipResourceFingerprintThreshold,
 	)
 
 	return &logQueryStatementBuilder{
-		logger:                    logsSettings.Logger(),
-		metadataStore:             metadataStore,
-		fm:                        fieldMapper,
-		cb:                        conditionBuilder,
-		resourceFilterStmtBuilder: resourceFilterStmtBuilder,
-		aggExprRewriter:           aggExprRewriter,
-		fl:                        fl,
-		fullTextColumn:            fullTextColumn,
-		jsonKeyToKey:              jsonKeyToKey,
+		logger:                         logsSettings.Logger(),
+		metadataStore:                  metadataStore,
+		fm:                             fieldMapper,
+		cb:                             conditionBuilder,
+		resourceFilterResolver:         resourceFilterResolver,
+		aggExprRewriter:                aggExprRewriter,
+		fl:                             fl,
+		skipResourceFingerprintEnabled: skipResourceFingerprintEnable,
+		fullTextColumn:                 fullTextColumn,
+		jsonKeyToKey:                   jsonKeyToKey,
 	}
 }
 
@@ -271,9 +279,11 @@ func (b *logQueryStatementBuilder) buildListQuery(
 		bodyJSONEnabled = b.fl.BooleanOrEmpty(ctx, flagger.FeatureUseJSONBody, featuretypes.NewFlaggerEvaluationContext(valuer.UUID{}))
 	)
 
-	if frag, args, err := b.maybeAttachResourceFilter(ctx, sb, query, start, end, variables); err != nil {
+	frag, args, skipResourceFilter, err := b.maybeAttachResourceFilter(ctx, sb, query, start, end, variables)
+	if err != nil {
 		return nil, err
-	} else if frag != "" {
+	}
+	if frag != "" {
 		cteFragments = append(cteFragments, frag)
 		cteArgs = append(cteArgs, args)
 	}
@@ -315,7 +325,7 @@ func (b *logQueryStatementBuilder) buildListQuery(
 
 	sb.From(fmt.Sprintf("%s.%s", DBName, LogsV2TableName))
 	// Add filter conditions
-	preparedWhereClause, err := b.addFilterCondition(ctx, sb, start, end, query, keys, variables)
+	preparedWhereClause, err := b.addFilterCondition(ctx, sb, start, end, query, keys, variables, skipResourceFilter)
 
 	if err != nil {
 		return nil, err
@@ -373,9 +383,11 @@ func (b *logQueryStatementBuilder) buildTimeSeriesQuery(
 		bodyJSONEnabled = b.fl.BooleanOrEmpty(ctx, flagger.FeatureUseJSONBody, featuretypes.NewFlaggerEvaluationContext(valuer.UUID{}))
 	)
 
-	if frag, args, err := b.maybeAttachResourceFilter(ctx, sb, query, start, end, variables); err != nil {
+	frag, args, skipResourceFilter, err := b.maybeAttachResourceFilter(ctx, sb, query, start, end, variables)
+	if err != nil {
 		return nil, err
-	} else if frag != "" {
+	}
+	if frag != "" {
 		cteFragments = append(cteFragments, frag)
 		cteArgs = append(cteArgs, args)
 	}
@@ -419,7 +431,7 @@ func (b *logQueryStatementBuilder) buildTimeSeriesQuery(
 	// Add FROM clause
 	sb.From(fmt.Sprintf("%s.%s", DBName, LogsV2TableName))
 
-	preparedWhereClause, err := b.addFilterCondition(ctx, sb, start, end, query, keys, variables)
+	preparedWhereClause, err := b.addFilterCondition(ctx, sb, start, end, query, keys, variables, skipResourceFilter)
 
 	if err != nil {
 		return nil, err
@@ -531,9 +543,11 @@ func (b *logQueryStatementBuilder) buildScalarQuery(
 		bodyJSONEnabled = b.fl.BooleanOrEmpty(ctx, flagger.FeatureUseJSONBody, featuretypes.NewFlaggerEvaluationContext(valuer.UUID{}))
 	)
 
-	if frag, args, err := b.maybeAttachResourceFilter(ctx, sb, query, start, end, variables); err != nil {
+	frag, args, skipResourceFilter, err := b.maybeAttachResourceFilter(ctx, sb, query, start, end, variables)
+	if err != nil {
 		return nil, err
-	} else if frag != "" && !skipResourceCTE {
+	}
+	if frag != "" && !skipResourceCTE {
 		cteFragments = append(cteFragments, frag)
 		cteArgs = append(cteArgs, args)
 	}
@@ -576,7 +590,7 @@ func (b *logQueryStatementBuilder) buildScalarQuery(
 	sb.From(fmt.Sprintf("%s.%s", DBName, LogsV2TableName))
 
 	// Add filter conditions
-	preparedWhereClause, err := b.addFilterCondition(ctx, sb, start, end, query, keys, variables)
+	preparedWhereClause, err := b.addFilterCondition(ctx, sb, start, end, query, keys, variables, skipResourceFilter)
 
 	if err != nil {
 		return nil, err
@@ -640,6 +654,7 @@ func (b *logQueryStatementBuilder) addFilterCondition(
 	query qbtypes.QueryBuilderQuery[qbtypes.LogAggregation],
 	keys map[string][]*telemetrytypes.TelemetryFieldKey,
 	variables map[string]qbtypes.VariableItem,
+	skipResourceFilter bool,
 ) (querybuilder.PreparedWhereClause, error) {
 
 	var preparedWhereClause querybuilder.PreparedWhereClause
@@ -656,7 +671,7 @@ func (b *logQueryStatementBuilder) addFilterCondition(
 			ConditionBuilder:   b.cb,
 			FieldKeys:          keys,
 			BodyJSONEnabled:    bodyJSONEnabled,
-			SkipResourceFilter: true,
+			SkipResourceFilter: skipResourceFilter,
 			FullTextColumn:     b.fullTextColumn,
 			JsonKeyToKey:       b.jsonKeyToKey,
 			Variables:          variables,
@@ -707,33 +722,30 @@ func (b *logQueryStatementBuilder) maybeAttachResourceFilter(
 	query qbtypes.QueryBuilderQuery[qbtypes.LogAggregation],
 	start, end uint64,
 	variables map[string]qbtypes.VariableItem,
-) (cteSQL string, cteArgs []any, err error) {
+) (cteSQL string, cteArgs []any, skipResourceFilter bool, err error) {
 
-	stmt, err := b.buildResourceFilterCTE(ctx, query, start, end, variables)
+	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, err
+		return "", nil, true, err
 	}
 	if stmt == nil {
-		return "", nil, nil
+		return "", nil, true, nil
 	}
-
 	sb.Where("resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter)")
-
-	return fmt.Sprintf("__resource_filter AS (%s)", stmt.Query), stmt.Args, nil
-}
-
-func (b *logQueryStatementBuilder) buildResourceFilterCTE(
-	ctx context.Context,
-	query qbtypes.QueryBuilderQuery[qbtypes.LogAggregation],
-	start, end uint64,
-	variables map[string]qbtypes.VariableItem,
-) (*qbtypes.Statement, error) {
-	return b.resourceFilterStmtBuilder.Build(
-		ctx,
-		start,
-		end,
-		qbtypes.RequestTypeRaw,
-		query,
-		variables,
-	)
+	return fmt.Sprintf("__resource_filter AS (%s)", stmt.Query), stmt.Args, true, nil
 }

pkg/telemetrylogs/stmt_builder_test.go

@@ -2,19 +2,36 @@ package telemetrylogs
 
 import (
 	"context"
+	"regexp"
 	"testing"
 	"time"
 
+	cmock "github.com/SigNoz/clickhouse-go-mock"
 	"github.com/SigNoz/signoz/pkg/errors"
 	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
 	"github.com/SigNoz/signoz/pkg/instrumentation/instrumentationtest"
 	"github.com/SigNoz/signoz/pkg/querybuilder"
+	"github.com/SigNoz/signoz/pkg/telemetrystore"
+	"github.com/SigNoz/signoz/pkg/telemetrystore/telemetrystoretest"
 	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"
 )
 
+type regexQueryMatcher struct{}
+
+func (m *regexQueryMatcher) Match(expectedSQL, actualSQL string) error {
+	re, err := regexp.Compile(expectedSQL)
+	if err != nil {
+		return err
+	}
+	if !re.MatchString(actualSQL) {
+		return errors.NewInvalidInputf(errors.CodeInvalidInput, "expected query to match %s, got %s", expectedSQL, actualSQL)
+	}
+	return nil
+}
+
 func TestStatementBuilderTimeSeries(t *testing.T) {
 	// Create a test release time
 	releaseTime := time.Date(2024, 1, 15, 10, 0, 0, 0, time.UTC)
@@ -212,6 +229,9 @@ func TestStatementBuilderTimeSeries(t *testing.T) {
 		DefaultFullTextColumn,
 		GetBodyJSONKey,
 		fl,
+		nil,
+		false,
+		100000,
 	)
 
 	for _, c := range cases {
@@ -353,6 +373,9 @@ func TestStatementBuilderListQuery(t *testing.T) {
 		DefaultFullTextColumn,
 		GetBodyJSONKey,
 		fl,
+		nil,
+		false,
+		100000,
 	)
 
 	for _, c := range cases {
@@ -499,6 +522,9 @@ func TestStatementBuilderListQueryResourceTests(t *testing.T) {
 		DefaultFullTextColumn,
 		GetBodyJSONKey,
 		fl,
+		nil,
+		false,
+		100000,
 	)
 
 	for _, c := range cases {
@@ -575,6 +601,9 @@ func TestStatementBuilderTimeSeriesBodyGroupBy(t *testing.T) {
 		DefaultFullTextColumn,
 		GetBodyJSONKey,
 		fl,
+		nil,
+		false,
+		100000,
 	)
 
 	for _, c := range cases {
@@ -670,6 +699,9 @@ func TestStatementBuilderListQueryServiceCollision(t *testing.T) {
 		DefaultFullTextColumn,
 		GetBodyJSONKey,
 		fl,
+		nil,
+		false,
+		100000,
 	)
 
 	for _, c := range cases {
@@ -894,6 +926,9 @@ func TestAdjustKey(t *testing.T) {
 		DefaultFullTextColumn,
 		GetBodyJSONKey,
 		fl,
+		nil,
+		false,
+		100000,
 	)
 
 	for _, c := range cases {
@@ -1039,6 +1074,9 @@ func TestStmtBuilderBodyField(t *testing.T) {
 				DefaultFullTextColumn,
 				GetBodyJSONKey,
 				fl,
+				nil,
+				false,
+				100000,
 			)
 
 			q, err := statementBuilder.Build(context.Background(), 1747947419000, 1747983448000, c.requestType, c.query, nil)
@@ -1138,6 +1176,9 @@ func TestStmtBuilderBodyFullTextSearch(t *testing.T) {
 				DefaultFullTextColumn,
 				GetBodyJSONKey,
 				fl,
+				nil,
+				false,
+				100000,
 			)
 
 			q, err := statementBuilder.Build(context.Background(), 1747947419000, 1747983448000, c.requestType, c.query, nil)
@@ -1157,3 +1198,110 @@ func TestStmtBuilderBodyFullTextSearch(t *testing.T) {
 		})
 	}
 }
+
+// TestSkipResourceFingerprintLogs exercises the three resolver outcomes for
+// logs: use-CTE (count < threshold), fallback (count >= threshold), and the
+// legacy path (feature disabled).
+func TestSkipResourceFingerprintLogs(t *testing.T) {
+	const (
+		startMs   = uint64(1747947419000)
+		endMs     = uint64(1747983448000)
+		threshold = uint64(10)
+	)
+
+	query := qbtypes.QueryBuilderQuery[qbtypes.LogAggregation]{
+		Signal: telemetrytypes.SignalLogs,
+		Filter: &qbtypes.Filter{
+			Expression: "service.name = 'redis-manual'",
+		},
+		Limit: 5,
+	}
+
+	t.Run("disabled uses the legacy CTE", func(t *testing.T) {
+		sb := newSkipResourceFingerprintLogsBuilder(t, nil, false, threshold)
+
+		stmt, err := sb.Build(context.Background(), startMs, endMs, qbtypes.RequestTypeRaw, query, nil)
+		require.NoError(t, err)
+		require.Contains(t, stmt.Query, "__resource_filter AS (SELECT fingerprint")
+		require.Contains(t, stmt.Query, "resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter)")
+	})
+
+	t.Run("CTE attached when count below threshold", func(t *testing.T) {
+		mockStore := telemetrystoretest.New(telemetrystore.Config{}, &regexQueryMatcher{})
+		mock := mockStore.Mock()
+
+		mock.ExpectQueryRow(`SELECT count\(\) FROM \(SELECT fingerprint FROM signoz_logs\.distributed_logs_v2_resource`).
+			WillReturnRow(cmock.NewRow([]cmock.ColumnType{
+				{Name: "count", Type: "UInt64"},
+			}, []any{uint64(2)}))
+
+		sb := newSkipResourceFingerprintLogsBuilder(t, mockStore, true, threshold)
+
+		stmt, err := sb.Build(context.Background(), startMs, endMs, qbtypes.RequestTypeRaw, query, nil)
+		require.NoError(t, err)
+
+		require.Contains(t, stmt.Query, "__resource_filter AS (SELECT fingerprint")
+		require.Contains(t, stmt.Query, "resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter)")
+
+		require.NoError(t, mock.ExpectationsWereMet())
+	})
+
+	t.Run("fallback when count at or above threshold", func(t *testing.T) {
+		mockStore := telemetrystoretest.New(telemetrystore.Config{}, &regexQueryMatcher{})
+		mock := mockStore.Mock()
+
+		mock.ExpectQueryRow(`SELECT count\(\) FROM \(SELECT fingerprint FROM signoz_logs\.distributed_logs_v2_resource`).
+			WillReturnRow(cmock.NewRow([]cmock.ColumnType{
+				{Name: "count", Type: "UInt64"},
+			}, []any{threshold}))
+
+		sb := newSkipResourceFingerprintLogsBuilder(t, mockStore, true, threshold)
+
+		stmt, err := sb.Build(context.Background(), startMs, endMs, qbtypes.RequestTypeRaw, query, nil)
+		require.NoError(t, err)
+
+		require.NotContains(t, stmt.Query, "__resource_filter AS")
+		require.NotContains(t, stmt.Query, "resource_fingerprint")
+		require.Contains(t, stmt.Query, "service.name")
+
+		require.NoError(t, mock.ExpectationsWereMet())
+	})
+}
+
+func newSkipResourceFingerprintLogsBuilder(
+	t *testing.T,
+	telemetryStore telemetrystore.TelemetryStore,
+	skipEnable bool,
+	threshold uint64,
+) *logQueryStatementBuilder {
+	t.Helper()
+
+	fl := flaggertest.New(t)
+	fm := NewFieldMapper(fl)
+	cb := NewConditionBuilder(fm, fl)
+	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
+	mockMetadataStore.KeysMap = buildCompleteFieldKeyMap(time.Date(2024, 1, 15, 10, 0, 0, 0, time.UTC))
+
+	aggExprRewriter := querybuilder.NewAggExprRewriter(
+		instrumentationtest.New().ToProviderSettings(),
+		DefaultFullTextColumn,
+		fm,
+		cb,
+		GetBodyJSONKey,
+		fl,
+	)
+
+	return NewLogQueryStatementBuilder(
+		instrumentationtest.New().ToProviderSettings(),
+		mockMetadataStore,
+		fm,
+		cb,
+		aggExprRewriter,
+		DefaultFullTextColumn,
+		GetBodyJSONKey,
+		fl,
+		telemetryStore,
+		skipEnable,
+		threshold,
+	)
+}

pkg/telemetryresourcefilter/fingerprint_resolver.go

@@ -0,0 +1,77 @@
+package telemetryresourcefilter
+
+import (
+	"context"
+
+	"github.com/SigNoz/signoz/pkg/factory"
+	"github.com/SigNoz/signoz/pkg/flagger"
+	"github.com/SigNoz/signoz/pkg/telemetrystore"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+)
+
+type ResourceFingerprintResolver[T any] struct {
+	stmtBuilder    *resourceFilterStatementBuilder[T]
+	telemetryStore telemetrystore.TelemetryStore
+	threshold      uint64
+}
+
+func NewResolver[T any](
+	settings factory.ProviderSettings,
+	dbName string,
+	tableName string,
+	signal telemetrytypes.Signal,
+	source telemetrytypes.Source,
+	metadataStore telemetrytypes.MetadataStore,
+	fullTextColumn *telemetrytypes.TelemetryFieldKey,
+	jsonKeyToKey qbtypes.JsonKeyToFieldFunc,
+	fl flagger.Flagger,
+	telemetryStore telemetrystore.TelemetryStore,
+	threshold uint64,
+) *ResourceFingerprintResolver[T] {
+	return &ResourceFingerprintResolver[T]{
+		stmtBuilder: New[T](
+			settings,
+			dbName,
+			tableName,
+			signal,
+			source,
+			metadataStore,
+			fullTextColumn,
+			jsonKeyToKey,
+			fl,
+		),
+		telemetryStore: telemetryStore,
+		threshold:      threshold,
+	}
+}
+
+func (r *ResourceFingerprintResolver[T]) StatementBuilder() qbtypes.StatementBuilder[T] {
+	return r.stmtBuilder
+}
+
+func (r *ResourceFingerprintResolver[T]) Resolve(
+	ctx context.Context,
+	query qbtypes.QueryBuilderQuery[T],
+	start, end uint64,
+	variables map[string]qbtypes.VariableItem,
+) (qbtypes.ResourceFilterResolveKind, error) {
+	countStmt, err := r.stmtBuilder.BuildCount(ctx, start, end, query, variables)
+	if err != nil {
+		return qbtypes.ResourceFilterResolveKindNoOp, err
+	}
+	if countStmt == nil {
+		return qbtypes.ResourceFilterResolveKindNoOp, nil
+	}
+
+	var count uint64
+	row := r.telemetryStore.ClickhouseDB().QueryRow(ctx, countStmt.Query, countStmt.Args...)
+	if err := row.Scan(&count); err != nil {
+		return qbtypes.ResourceFilterResolveKindNoOp, err
+	}
+
+	if count >= r.threshold {
+		return qbtypes.ResourceFilterResolveKindFallback, nil
+	}
+	return qbtypes.ResourceFilterResolveKindUseCTE, nil
+}

pkg/telemetryresourcefilter/statement_builder.go

@@ -127,6 +127,25 @@ func (b *resourceFilterStatementBuilder[T]) Build(
 	}, nil
 }
 
+// BuildCount returns a statement that counts the distinct fingerprints matching
+// the resource filter. Returns (nil, nil) when the filter is a no-op.
+func (b *resourceFilterStatementBuilder[T]) BuildCount(
+	ctx context.Context,
+	start uint64,
+	end uint64,
+	query qbtypes.QueryBuilderQuery[T],
+	variables map[string]qbtypes.VariableItem,
+) (*qbtypes.Statement, error) {
+	inner, err := b.Build(ctx, start, end, qbtypes.RequestTypeRaw, query, variables)
+	if err != nil || inner == nil {
+		return nil, err
+	}
+	return &qbtypes.Statement{
+		Query: fmt.Sprintf("SELECT count() FROM (%s)", inner.Query),
+		Args:  inner.Args,
+	}, nil
+}
+
 // addConditions adds both filter and time conditions to the query.
 // Returns true (isNoOp) when the filter expression evaluated to no resource conditions,
 // meaning the CTE would select all fingerprints and should be skipped entirely.

pkg/telemetrytraces/statement_builder.go

@@ -24,13 +24,13 @@ var (
 )
 
 type traceQueryStatementBuilder struct {
-	logger                    *slog.Logger
-	metadataStore             telemetrytypes.MetadataStore
-	fm                        qbtypes.FieldMapper
-	cb                        qbtypes.ConditionBuilder
-	resourceFilterStmtBuilder qbtypes.StatementBuilder[qbtypes.TraceAggregation]
-	aggExprRewriter           qbtypes.AggExprRewriter
-	telemetryStore            telemetrystore.TelemetryStore
+	logger                         *slog.Logger
+	metadataStore                  telemetrytypes.MetadataStore
+	fm                             qbtypes.FieldMapper
+	cb                             qbtypes.ConditionBuilder
+	resourceFilterResolver         *telemetryresourcefilter.ResourceFingerprintResolver[qbtypes.TraceAggregation]
+	aggExprRewriter                qbtypes.AggExprRewriter
+	skipResourceFingerprintEnabled bool
 }
 
 var _ qbtypes.StatementBuilder[qbtypes.TraceAggregation] = (*traceQueryStatementBuilder)(nil)
@@ -43,10 +43,12 @@ func NewTraceQueryStatementBuilder(
 	aggExprRewriter qbtypes.AggExprRewriter,
 	telemetryStore telemetrystore.TelemetryStore,
 	flagger flagger.Flagger,
+	skipResourceFingerprintEnable bool,
+	skipResourceFingerprintThreshold uint64,
 ) *traceQueryStatementBuilder {
 	tracesSettings := factory.NewScopedProviderSettings(settings, "github.com/SigNoz/signoz/pkg/telemetrytraces")
 
-	resourceFilterStmtBuilder := telemetryresourcefilter.New[qbtypes.TraceAggregation](
+	resourceFilterResolver := telemetryresourcefilter.NewResolver[qbtypes.TraceAggregation](
 		settings,
 		DBName,
 		TracesResourceV3TableName,
@@ -56,16 +58,18 @@ func NewTraceQueryStatementBuilder(
 		nil,
 		nil,
 		flagger,
+		telemetryStore,
+		skipResourceFingerprintThreshold,
 	)
 
 	return &traceQueryStatementBuilder{
-		logger:                    tracesSettings.Logger(),
-		metadataStore:             metadataStore,
-		fm:                        fieldMapper,
-		cb:                        conditionBuilder,
-		resourceFilterStmtBuilder: resourceFilterStmtBuilder,
-		aggExprRewriter:           aggExprRewriter,
-		telemetryStore:            telemetryStore,
+		logger:                         tracesSettings.Logger(),
+		metadataStore:                  metadataStore,
+		fm:                             fieldMapper,
+		cb:                             conditionBuilder,
+		resourceFilterResolver:         resourceFilterResolver,
+		aggExprRewriter:                aggExprRewriter,
+		skipResourceFingerprintEnabled: skipResourceFingerprintEnable,
 	}
 }
 
@@ -302,9 +306,11 @@ func (b *traceQueryStatementBuilder) buildListQuery(
 		cteArgs      [][]any
 	)
 
-	if frag, args, err := b.maybeAttachResourceFilter(ctx, sb, query, start, end, variables); err != nil {
+	frag, args, skipResourceFilter, err := b.maybeAttachResourceFilter(ctx, sb, query, start, end, variables)
+	if err != nil {
 		return nil, err
-	} else if frag != "" {
+	}
+	if frag != "" {
 		cteFragments = append(cteFragments, frag)
 		cteArgs = append(cteArgs, args)
 	}
@@ -322,7 +328,7 @@ func (b *traceQueryStatementBuilder) buildListQuery(
 	sb.From(fmt.Sprintf("%s.%s", DBName, SpanIndexV3TableName))
 
 	// Add filter conditions
-	preparedWhereClause, err := b.addFilterCondition(ctx, sb, start, end, query, keys, variables)
+	preparedWhereClause, err := b.addFilterCondition(ctx, sb, start, end, query, keys, variables, skipResourceFilter)
 	if err != nil {
 		return nil, err
 	}
@@ -383,15 +389,17 @@ func (b *traceQueryStatementBuilder) buildTraceQuery(
 		cteArgs      [][]any
 	)
 
-	if frag, args, err := b.maybeAttachResourceFilter(ctx, distSB, query, start, end, variables); err != nil {
+	frag, args, skipResourceFilter, err := b.maybeAttachResourceFilter(ctx, distSB, query, start, end, variables)
+	if err != nil {
 		return nil, err
-	} else if frag != "" {
+	}
+	if frag != "" {
 		cteFragments = append(cteFragments, frag)
 		cteArgs = append(cteArgs, args)
 	}
 
 	// Add filter conditions
-	preparedWhereClause, err := b.addFilterCondition(ctx, distSB, start, end, query, keys, variables)
+	preparedWhereClause, err := b.addFilterCondition(ctx, distSB, start, end, query, keys, variables, skipResourceFilter)
 	if err != nil {
 		return nil, err
 	}
@@ -492,9 +500,11 @@ func (b *traceQueryStatementBuilder) buildTimeSeriesQuery(
 		cteArgs      [][]any
 	)
 
-	if frag, args, err := b.maybeAttachResourceFilter(ctx, sb, query, start, end, variables); err != nil {
+	frag, args, skipResourceFilter, err := b.maybeAttachResourceFilter(ctx, sb, query, start, end, variables)
+	if err != nil {
 		return nil, err
-	} else if frag != "" {
+	}
+	if frag != "" {
 		cteFragments = append(cteFragments, frag)
 		cteArgs = append(cteArgs, args)
 	}
@@ -535,7 +545,7 @@ func (b *traceQueryStatementBuilder) buildTimeSeriesQuery(
 	}
 
 	sb.From(fmt.Sprintf("%s.%s", DBName, SpanIndexV3TableName))
-	preparedWhereClause, err := b.addFilterCondition(ctx, sb, start, end, query, keys, variables)
+	preparedWhereClause, err := b.addFilterCondition(ctx, sb, start, end, query, keys, variables, skipResourceFilter)
 	if err != nil {
 		return nil, err
 	}
@@ -644,9 +654,11 @@ func (b *traceQueryStatementBuilder) buildScalarQuery(
 		cteArgs      [][]any
 	)
 
-	if frag, args, err := b.maybeAttachResourceFilter(ctx, sb, query, start, end, variables); err != nil {
+	frag, args, skipResourceFilter, err := b.maybeAttachResourceFilter(ctx, sb, query, start, end, variables)
+	if err != nil {
 		return nil, err
-	} else if frag != "" && !skipResourceCTE {
+	}
+	if frag != "" && !skipResourceCTE {
 		cteFragments = append(cteFragments, frag)
 		cteArgs = append(cteArgs, args)
 	}
@@ -688,7 +700,7 @@ func (b *traceQueryStatementBuilder) buildScalarQuery(
 	sb.From(fmt.Sprintf("%s.%s", DBName, SpanIndexV3TableName))
 
 	// Add filter conditions
-	preparedWhereClause, err := b.addFilterCondition(ctx, sb, start, end, query, keys, variables)
+	preparedWhereClause, err := b.addFilterCondition(ctx, sb, start, end, query, keys, variables, skipResourceFilter)
 	if err != nil {
 		return nil, err
 	}
@@ -751,6 +763,7 @@ func (b *traceQueryStatementBuilder) addFilterCondition(
 	query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation],
 	keys map[string][]*telemetrytypes.TelemetryFieldKey,
 	variables map[string]qbtypes.VariableItem,
+	skipResourceFilter bool,
 ) (querybuilder.PreparedWhereClause, error) {
 
 	var preparedWhereClause querybuilder.PreparedWhereClause
@@ -764,7 +777,7 @@ func (b *traceQueryStatementBuilder) addFilterCondition(
 			FieldMapper:        b.fm,
 			ConditionBuilder:   b.cb,
 			FieldKeys:          keys,
-			SkipResourceFilter: true,
+			SkipResourceFilter: skipResourceFilter,
 			Variables:          variables,
 			StartNs:            start,
 			EndNs:              end,
@@ -805,34 +818,30 @@ func (b *traceQueryStatementBuilder) maybeAttachResourceFilter(
 	query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation],
 	start, end uint64,
 	variables map[string]qbtypes.VariableItem,
-) (cteSQL string, cteArgs []any, err error) {
+) (cteSQL string, cteArgs []any, skipResourceFilter bool, err error) {
 
-	stmt, err := b.buildResourceFilterCTE(ctx, query, start, end, variables)
+	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, err
+		return "", nil, true, err
 	}
 	if stmt == nil {
-		return "", nil, nil
+		return "", nil, true, nil
 	}
-
 	sb.Where("resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter)")
-
-	return fmt.Sprintf("__resource_filter AS (%s)", stmt.Query), stmt.Args, nil
-}
-
-func (b *traceQueryStatementBuilder) buildResourceFilterCTE(
-	ctx context.Context,
-	query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation],
-	start, end uint64,
-	variables map[string]qbtypes.VariableItem,
-) (*qbtypes.Statement, error) {
-
-	return b.resourceFilterStmtBuilder.Build(
-		ctx,
-		start,
-		end,
-		qbtypes.RequestTypeRaw,
-		query,
-		variables,
-	)
+	return fmt.Sprintf("__resource_filter AS (%s)", stmt.Query), stmt.Args, true, nil
 }

pkg/telemetrytraces/stmt_builder_test.go

@@ -2,19 +2,36 @@ package telemetrytraces
 
 import (
 	"context"
+	"regexp"
 	"testing"
 	"time"
 
+	cmock "github.com/SigNoz/clickhouse-go-mock"
 	"github.com/SigNoz/signoz/pkg/errors"
 	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
 	"github.com/SigNoz/signoz/pkg/instrumentation/instrumentationtest"
 	"github.com/SigNoz/signoz/pkg/querybuilder"
+	"github.com/SigNoz/signoz/pkg/telemetrystore"
+	"github.com/SigNoz/signoz/pkg/telemetrystore/telemetrystoretest"
 	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"
 )
 
+type regexQueryMatcher struct{}
+
+func (m *regexQueryMatcher) Match(expectedSQL, actualSQL string) error {
+	re, err := regexp.Compile(expectedSQL)
+	if err != nil {
+		return err
+	}
+	if !re.MatchString(actualSQL) {
+		return errors.NewInvalidInputf(errors.CodeInvalidInput, "expected query to match %s, got %s", expectedSQL, actualSQL)
+	}
+	return nil
+}
+
 func TestStatementBuilder(t *testing.T) {
 	cases := []struct {
 		name        string
@@ -367,6 +384,8 @@ func TestStatementBuilder(t *testing.T) {
 		aggExprRewriter,
 		nil,
 		fl,
+		false,
+		100000,
 	)
 
 	vars := map[string]qbtypes.VariableItem{
@@ -662,6 +681,8 @@ func TestStatementBuilderListQuery(t *testing.T) {
 		aggExprRewriter,
 		nil,
 		fl,
+		false,
+		100000,
 	)
 
 	for _, c := range cases {
@@ -771,6 +792,8 @@ func TestStatementBuilderListQueryWithCorruptData(t *testing.T) {
 				aggExprRewriter,
 				nil,
 				fl,
+				false,
+				100000,
 			)
 
 			q, err := statementBuilder.Build(context.Background(), 1747947419000, 1747983448000, c.requestType, c.query, nil)
@@ -923,6 +946,8 @@ func TestStatementBuilderTraceQuery(t *testing.T) {
 		aggExprRewriter,
 		nil,
 		fl,
+		false,
+		100000,
 	)
 
 	for _, c := range cases {
@@ -1138,6 +1163,8 @@ func TestAdjustKey(t *testing.T) {
 		aggExprRewriter,
 		nil,
 		fl,
+		false,
+		100000,
 	)
 
 	for _, c := range cases {
@@ -1412,6 +1439,8 @@ func TestAdjustKeys(t *testing.T) {
 		aggExprRewriter,
 		nil,
 		fl,
+		false,
+		100000,
 	)
 
 	for _, c := range cases {
@@ -1483,3 +1512,114 @@ func TestAdjustKeys(t *testing.T) {
 		})
 	}
 }
+
+// TestSkipResourceFingerprint exercises the three resolver outcomes when
+// skip_resource_fingerprint is enabled: use-CTE (count < threshold),
+// fallback (count >= threshold), and the legacy path (feature disabled).
+func TestSkipResourceFingerprint(t *testing.T) {
+	const (
+		startMs   = uint64(1747947419000)
+		endMs     = uint64(1747983448000)
+		threshold = uint64(10)
+	)
+
+	query := qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+		Signal: telemetrytypes.SignalTraces,
+		Filter: &qbtypes.Filter{
+			Expression: "service.name = 'redis-manual'",
+		},
+		SelectFields: []telemetrytypes.TelemetryFieldKey{
+			{
+				Name:          "name",
+				FieldContext:  telemetrytypes.FieldContextSpan,
+				FieldDataType: telemetrytypes.FieldDataTypeString,
+			},
+		},
+		Limit: 5,
+	}
+
+	t.Run("disabled uses the legacy CTE", func(t *testing.T) {
+		sb := newSkipResourceFingerprintBuilder(t, nil, false, threshold)
+
+		stmt, err := sb.Build(context.Background(), startMs, endMs, qbtypes.RequestTypeRaw, query, nil)
+		require.NoError(t, err)
+		require.Contains(t, stmt.Query, "__resource_filter AS (SELECT fingerprint")
+		require.Contains(t, stmt.Query, "resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter)")
+	})
+
+	t.Run("CTE attached when count below threshold", func(t *testing.T) {
+		mockStore := telemetrystoretest.New(telemetrystore.Config{}, &regexQueryMatcher{})
+		mock := mockStore.Mock()
+
+		// Only the count query runs against the telemetry store; the CTE
+		// itself is embedded as SQL in the main query (no extra round trip).
+		mock.ExpectQueryRow(`SELECT count\(\) FROM \(SELECT fingerprint FROM signoz_traces\.distributed_traces_v3_resource`).
+			WillReturnRow(cmock.NewRow([]cmock.ColumnType{
+				{Name: "count", Type: "UInt64"},
+			}, []any{uint64(2)}))
+
+		sb := newSkipResourceFingerprintBuilder(t, mockStore, true, threshold)
+
+		stmt, err := sb.Build(context.Background(), startMs, endMs, qbtypes.RequestTypeRaw, query, nil)
+		require.NoError(t, err)
+
+		require.Contains(t, stmt.Query, "__resource_filter AS (SELECT fingerprint")
+		require.Contains(t, stmt.Query, "resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter)")
+
+		require.NoError(t, mock.ExpectationsWereMet())
+	})
+
+	t.Run("fallback when count at or above threshold", func(t *testing.T) {
+		mockStore := telemetrystoretest.New(telemetrystore.Config{}, &regexQueryMatcher{})
+		mock := mockStore.Mock()
+
+		mock.ExpectQueryRow(`SELECT count\(\) FROM \(SELECT fingerprint FROM signoz_traces\.distributed_traces_v3_resource`).
+			WillReturnRow(cmock.NewRow([]cmock.ColumnType{
+				{Name: "count", Type: "UInt64"},
+			}, []any{threshold}))
+
+		sb := newSkipResourceFingerprintBuilder(t, mockStore, true, threshold)
+
+		stmt, err := sb.Build(context.Background(), startMs, endMs, qbtypes.RequestTypeRaw, query, nil)
+		require.NoError(t, err)
+
+		require.NotContains(t, stmt.Query, "__resource_filter AS")
+		require.NotContains(t, stmt.Query, "resource_fingerprint")
+		// resource conditions are pushed onto the main table via the
+		// resource.`service.name` / resources_string lookup
+		require.Contains(t, stmt.Query, "service.name")
+
+		require.NoError(t, mock.ExpectationsWereMet())
+	})
+}
+
+func newSkipResourceFingerprintBuilder(
+	t *testing.T,
+	telemetryStore telemetrystore.TelemetryStore,
+	skipEnable bool,
+	threshold uint64,
+) *traceQueryStatementBuilder {
+	t.Helper()
+
+	fm := NewFieldMapper()
+	cb := NewConditionBuilder(fm)
+	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
+	mockMetadataStore.KeysMap = buildCompleteFieldKeyMap()
+
+	fl := flaggertest.New(t)
+	aggExprRewriter := querybuilder.NewAggExprRewriter(
+		instrumentationtest.New().ToProviderSettings(), nil, fm, cb, nil, fl,
+	)
+
+	return NewTraceQueryStatementBuilder(
+		instrumentationtest.New().ToProviderSettings(),
+		mockMetadataStore,
+		fm,
+		cb,
+		aggExprRewriter,
+		telemetryStore,
+		fl,
+		skipEnable,
+		threshold,
+	)
+}

pkg/telemetrytraces/trace_operator_cte_builder_test.go

@@ -478,6 +478,8 @@ func TestTraceOperatorStatementBuilder(t *testing.T) {
 		aggExprRewriter,
 		nil,
 		fl,
+		false,
+		100000,
 	)
 
 	statementBuilder := NewTraceOperatorStatementBuilder(
@@ -594,6 +596,8 @@ func TestTraceOperatorStatementBuilderErrors(t *testing.T) {
 		aggExprRewriter,
 		nil,
 		fl,
+		false,
+		100000,
 	)
 
 	statementBuilder := NewTraceOperatorStatementBuilder(

pkg/telemetrytraces/trace_time_range_test.go

@@ -5,13 +5,13 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
 	"github.com/SigNoz/signoz/pkg/instrumentation/instrumentationtest"
 	"github.com/SigNoz/signoz/pkg/querybuilder"
 	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/assert"
-	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
 	"github.com/stretchr/testify/require"
 )
 
@@ -44,8 +44,10 @@ func TestTraceTimeRangeOptimization(t *testing.T) {
 		fm,
 		cb,
 		aggExprRewriter,
-		nil, // telemetryStore is nil - optimization won't happen but code path is tested
+		nil, // telemetryStore is nil - adaptive path is disabled
 		fl,
+		false,
+		100000,
 	)
 
 	tests := []struct {

pkg/types/querybuildertypes/querybuildertypesv5/resource_filter_resolve.go

@@ -0,0 +1,9 @@
+package querybuildertypesv5
+
+type ResourceFilterResolveKind int
+
+const (
+	ResourceFilterResolveKindNoOp ResourceFilterResolveKind = iota
+	ResourceFilterResolveKindUseCTE
+	ResourceFilterResolveKindFallback
+)

tests/integration/tests/querier_skip_resource_fingerprint/01_skip_resource_fingerprint_traces.py

@@ -0,0 +1,191 @@
+"""
+End-to-end coverage for the skip_resource_fingerprint querier optimization.
+
+The conftest in this package boots SigNoz with:
+  - skip_resource_fingerprint.enabled = true
+  - skip_resource_fingerprint.threshold = 2
+
+With that configuration the two non-trivial resolver branches are reachable
+from a single SigNoz instance:
+
+  - count < 2  -> the resolver attaches the fingerprint CTE (same shape as the
+    legacy path; cheap because the fingerprint set is small).
+  - count >= 2 -> fallback path: no fingerprint subquery, resource conditions
+    are evaluated directly on the main spans table.
+
+These tests assert end-to-end correctness — the optimization must be
+semantically transparent.
+"""
+
+from collections.abc import Callable
+from datetime import UTC, datetime, timedelta
+from http import HTTPStatus
+
+from fixtures import types
+from fixtures.auth import USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD
+from fixtures.querier import make_query_request
+from fixtures.traces import TraceIdGenerator, Traces, TracesKind, TracesStatusCode
+
+
+def _span(
+    *,
+    timestamp: datetime,
+    service_name: str,
+    name: str = "span",
+    duration_seconds: float = 1.0,
+    extra_resources: dict | None = None,
+    attributes: dict | None = None,
+) -> Traces:
+    resources = {"service.name": service_name}
+    if extra_resources:
+        resources.update(extra_resources)
+    return Traces(
+        timestamp=timestamp,
+        duration=timedelta(seconds=duration_seconds),
+        trace_id=TraceIdGenerator.trace_id(),
+        span_id=TraceIdGenerator.span_id(),
+        parent_span_id="",
+        name=name,
+        kind=TracesKind.SPAN_KIND_SERVER,
+        status_code=TracesStatusCode.STATUS_CODE_OK,
+        status_message="",
+        resources=resources,
+        attributes=attributes or {},
+    )
+
+
+def test_skip_resource_fingerprint_use_cte_path(
+    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 filter that matches a single unique resource fingerprint (count = 1 < 2)
+    keeps the legacy CTE attached. The query should still return only the rows
+    belonging to that resource.
+    """
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+
+    insert_traces(
+        [
+            _span(timestamp=now - timedelta(seconds=10), service_name="skip-cte-svc", name="span-1"),
+            _span(timestamp=now - timedelta(seconds=8), service_name="skip-cte-svc", name="span-2"),
+            # Noise from a different resource — must be filtered out.
+            _span(timestamp=now - timedelta(seconds=6), service_name="skip-cte-noise", name="span-noise"),
+        ]
+    )
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+
+    response = make_query_request(
+        signoz,
+        token,
+        start_ms=int((datetime.now(tz=UTC) - timedelta(minutes=5)).timestamp() * 1000),
+        end_ms=int(datetime.now(tz=UTC).timestamp() * 1000),
+        request_type="raw",
+        queries=[
+            {
+                "type": "builder_query",
+                "spec": {
+                    "name": "A",
+                    "signal": "traces",
+                    "limit": 50,
+                    "order": [{"key": {"name": "timestamp"}, "direction": "asc"}],
+                    "filter": {"expression": "service.name = 'skip-cte-svc'"},
+                    "selectFields": [
+                        {
+                            "name": "service.name",
+                            "fieldDataType": "string",
+                            "fieldContext": "resource",
+                        },
+                        {"name": "name", "fieldContext": "span"},
+                    ],
+                    "aggregations": [{"expression": "count()"}],
+                },
+            }
+        ],
+    )
+
+    assert response.status_code == HTTPStatus.OK
+    assert response.json()["status"] == "success"
+
+    rows = response.json()["data"]["data"]["results"][0]["rows"]
+    assert len(rows) == 2, f"expected only the 2 'skip-cte-svc' spans, got {len(rows)}"
+
+    names = [row["data"]["name"] for row in rows]
+    assert names == ["span-1", "span-2"]
+
+    services = {row["data"]["service.name"] for row in rows}
+    assert services == {"skip-cte-svc"}
+
+
+def test_skip_resource_fingerprint_fallback_path(
+    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 filter that matches multiple unique resource fingerprints (count >= 2)
+    drives the resolver down the fallback path: no fingerprint subquery, and
+    the resource condition is evaluated directly on the main spans table.
+    The result must still be correct (no over- or under-matching).
+    """
+    now = datetime.now(tz=UTC).replace(second=0, microsecond=0)
+
+    # 3 services share the same deployment.environment, so the resource filter
+    # selects 3 fingerprints, exceeding our threshold of 2.
+    fallback_env = {"deployment.environment": "skip-fallback"}
+    insert_traces(
+        [
+            _span(timestamp=now - timedelta(seconds=10), service_name="skip-fb-svc-a", extra_resources=fallback_env),
+            _span(timestamp=now - timedelta(seconds=9), service_name="skip-fb-svc-b", extra_resources=fallback_env),
+            _span(timestamp=now - timedelta(seconds=8), service_name="skip-fb-svc-c", extra_resources=fallback_env),
+            # Noise without the fallback env — must be filtered out.
+            _span(
+                timestamp=now - timedelta(seconds=7),
+                service_name="skip-fb-other",
+                extra_resources={"deployment.environment": "skip-other"},
+            ),
+        ]
+    )
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+
+    response = make_query_request(
+        signoz,
+        token,
+        start_ms=int((datetime.now(tz=UTC) - timedelta(minutes=5)).timestamp() * 1000),
+        end_ms=int(datetime.now(tz=UTC).timestamp() * 1000),
+        request_type="raw",
+        queries=[
+            {
+                "type": "builder_query",
+                "spec": {
+                    "name": "A",
+                    "signal": "traces",
+                    "limit": 50,
+                    "order": [{"key": {"name": "timestamp"}, "direction": "asc"}],
+                    "filter": {"expression": "deployment.environment = 'skip-fallback'"},
+                    "selectFields": [
+                        {
+                            "name": "service.name",
+                            "fieldDataType": "string",
+                            "fieldContext": "resource",
+                        },
+                    ],
+                    "aggregations": [{"expression": "count()"}],
+                },
+            }
+        ],
+    )
+
+    assert response.status_code == HTTPStatus.OK
+    assert response.json()["status"] == "success"
+
+    rows = response.json()["data"]["data"]["results"][0]["rows"]
+    assert len(rows) == 3, f"expected 3 spans tagged with skip-fallback, got {len(rows)}"
+
+    services = sorted(row["data"]["service.name"] for row in rows)
+    assert services == ["skip-fb-svc-a", "skip-fb-svc-b", "skip-fb-svc-c"]

tests/integration/tests/querier_skip_resource_fingerprint/02_skip_resource_fingerprint_logs.py

@@ -0,0 +1,175 @@
+"""
+End-to-end coverage for the skip_resource_fingerprint optimization on logs.
+
+The conftest boots SigNoz with threshold=2, so:
+  - count < 2  -> resolver attaches the fingerprint CTE (same shape as legacy).
+  - count >= 2 -> fallback: resource conditions evaluated on the main logs table.
+
+Both branches must return the same correct rows.
+"""
+
+from collections.abc import Callable
+from datetime import UTC, datetime, timedelta
+from http import HTTPStatus
+
+from fixtures import types
+from fixtures.auth import USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD
+from fixtures.logs import Logs
+from fixtures.querier import make_query_request
+
+
+def _log(
+    *,
+    timestamp: datetime,
+    service_name: str,
+    body: str,
+    extra_resources: dict | None = None,
+) -> Logs:
+    resources = {"service.name": service_name}
+    if extra_resources:
+        resources.update(extra_resources)
+    return Logs(
+        timestamp=timestamp,
+        resources=resources,
+        attributes={},
+        body=body,
+        severity_text="INFO",
+    )
+
+
+def test_skip_resource_fingerprint_logs_use_cte_path(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_logs: Callable[[list[Logs]], None],
+) -> None:
+    """
+    A filter matching a single resource fingerprint (count = 1 < 2) keeps the
+    legacy CTE attached. The result must only include rows for that resource.
+    """
+    now = datetime.now(tz=UTC)
+
+    insert_logs(
+        [
+            _log(timestamp=now - timedelta(seconds=10), service_name="skip-logs-cte-svc", body="log-1"),
+            _log(timestamp=now - timedelta(seconds=8), service_name="skip-logs-cte-svc", body="log-2"),
+            # Noise from a different resource — must not appear.
+            _log(timestamp=now - timedelta(seconds=6), service_name="skip-logs-cte-noise", body="noise"),
+        ]
+    )
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+
+    response = make_query_request(
+        signoz,
+        token,
+        start_ms=int((datetime.now(tz=UTC) - timedelta(minutes=5)).timestamp() * 1000),
+        end_ms=int(datetime.now(tz=UTC).timestamp() * 1000),
+        request_type="raw",
+        queries=[
+            {
+                "type": "builder_query",
+                "spec": {
+                    "name": "A",
+                    "signal": "logs",
+                    "limit": 50,
+                    "order": [{"key": {"name": "timestamp"}, "direction": "asc"}],
+                    "filter": {"expression": "service.name = 'skip-logs-cte-svc'"},
+                    "selectFields": [
+                        {
+                            "name": "service.name",
+                            "fieldDataType": "string",
+                            "fieldContext": "resource",
+                        },
+                        {"name": "body"},
+                    ],
+                    "aggregations": [{"expression": "count()"}],
+                },
+            }
+        ],
+    )
+
+    assert response.status_code == HTTPStatus.OK
+    assert response.json()["status"] == "success"
+
+    rows = response.json()["data"]["data"]["results"][0]["rows"]
+    assert len(rows) == 2, f"expected 2 'skip-logs-cte-svc' rows, got {len(rows)}"
+
+    bodies = [row["data"]["body"] for row in rows]
+    assert bodies == ["log-1", "log-2"]
+
+    services = {row["data"]["service.name"] for row in rows}
+    assert services == {"skip-logs-cte-svc"}
+
+
+def test_skip_resource_fingerprint_logs_fallback_path(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_logs: Callable[[list[Logs]], None],
+) -> None:
+    """
+    A filter matching multiple resource fingerprints (count >= 2) drives the
+    fallback path: no CTE, resource conditions evaluated on the main logs
+    table. Result must still be correct (no over- or under-matching).
+    """
+    now = datetime.now(tz=UTC)
+
+    fallback_env = {"deployment.environment": "skip-logs-fallback"}
+    insert_logs(
+        [
+            _log(timestamp=now - timedelta(seconds=10), service_name="skip-logs-fb-svc-a", body="a", extra_resources=fallback_env),
+            _log(timestamp=now - timedelta(seconds=9), service_name="skip-logs-fb-svc-b", body="b", extra_resources=fallback_env),
+            _log(timestamp=now - timedelta(seconds=8), service_name="skip-logs-fb-svc-c", body="c", extra_resources=fallback_env),
+            # Noise without the fallback env — must be filtered out.
+            _log(
+                timestamp=now - timedelta(seconds=7),
+                service_name="skip-logs-fb-other",
+                body="noise",
+                extra_resources={"deployment.environment": "skip-logs-other"},
+            ),
+        ]
+    )
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+
+    response = make_query_request(
+        signoz,
+        token,
+        start_ms=int((datetime.now(tz=UTC) - timedelta(minutes=5)).timestamp() * 1000),
+        end_ms=int(datetime.now(tz=UTC).timestamp() * 1000),
+        request_type="raw",
+        queries=[
+            {
+                "type": "builder_query",
+                "spec": {
+                    "name": "A",
+                    "signal": "logs",
+                    "limit": 50,
+                    "order": [{"key": {"name": "timestamp"}, "direction": "asc"}],
+                    "filter": {"expression": "deployment.environment = 'skip-logs-fallback'"},
+                    "selectFields": [
+                        {
+                            "name": "service.name",
+                            "fieldDataType": "string",
+                            "fieldContext": "resource",
+                        },
+                        {"name": "body"},
+                    ],
+                    "aggregations": [{"expression": "count()"}],
+                },
+            }
+        ],
+    )
+
+    assert response.status_code == HTTPStatus.OK
+    assert response.json()["status"] == "success"
+
+    rows = response.json()["data"]["data"]["results"][0]["rows"]
+    assert len(rows) == 3, f"expected 3 fallback rows, got {len(rows)}"
+
+    services = sorted(row["data"]["service.name"] for row in rows)
+    assert services == ["skip-logs-fb-svc-a", "skip-logs-fb-svc-b", "skip-logs-fb-svc-c"]
+
+    bodies = sorted(row["data"]["body"] for row in rows)
+    assert bodies == ["a", "b", "c"]

tests/integration/tests/querier_skip_resource_fingerprint/conftest.py

@@ -0,0 +1,37 @@
+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_skip_resource_fingerprint(
+    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 the skip_resource_fingerprint
+    optimization enabled and a low threshold so both the materialized and
+    fallback resolver paths are exercised by sibling tests.
+    """
+    return create_signoz(
+        network=network,
+        zeus=zeus,
+        gateway=gateway,
+        sqlstore=sqlstore,
+        clickhouse=clickhouse,
+        request=request,
+        pytestconfig=pytestconfig,
+        cache_key="signoz-skip-resource-fingerprint",
+        env_overrides={
+            "SIGNOZ_QUERIER_SKIP__RESOURCE__FINGERPRINT_ENABLED": True,
+            "SIGNOZ_QUERIER_SKIP__RESOURCE__FINGERPRINT_THRESHOLD": 2,
+        },
+    )