test(traces-qb): correct the scope declared-path doc comment

More than one home under one name is the general case; scope is one instance.
Also fold the two rewritten cases back onto single lines, as the rest of the
table is.

Assisted-by: Claude Opus 5

pkg/querybuilder/query_to_keys.go

@@ -1,8 +1,6 @@
 package querybuilder
 
 import (
-	"strings"
-
 	grammar "github.com/SigNoz/signoz/pkg/parser/filterquery/grammar"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"github.com/antlr4-go/antlr/v4"
@@ -61,16 +59,11 @@ func QueryStringToKeysSelectors(query string) []*telemetrytypes.FieldKeySelector
 
 			// todo(tushar): consider reverting changes done to this method in below PR to avoid scope specific checks
 			// https://github.com/SigNoz/signoz/issues/11374
-			//
-			// A scope attribute lets its `scope.`-prefixed name resolve under other contexts too.
-			// Declared paths (scope.name/scope.version) keep their compound name after
-			// normalization and address the scope field only, so they get no such selector.
-			scopePrefix := telemetrytypes.FieldContextScope.StringValue() + "."
-			if key.FieldContext == telemetrytypes.FieldContextScope && !strings.HasPrefix(key.Name, scopePrefix) {
+			if key.FieldContext == telemetrytypes.FieldContextScope {
 				keys = append(keys, &telemetrytypes.FieldKeySelector{
-					Name:          scopePrefix + key.Name,
+					Name:          key.FieldContext.StringValue() + "." + key.Name,
 					Signal:        key.Signal,
-					FieldContext:  telemetrytypes.FieldContextUnspecified,
+					FieldContext:  telemetrytypes.FieldContextUnspecified, // this allows 'scope.' prefix for keys with other context as well
 					FieldDataType: key.FieldDataType,
 				})
 			}

pkg/querybuilder/query_to_keys_test.go

@@ -73,17 +73,20 @@ func TestQueryToKeys(t *testing.T) {
 			},
 		},
 		{
-			// A declared scope path keeps its compound name and addresses the scope field
-			// only, so it yields a single scope-context selector (no `scope.`-prefixed
-			// cross-context companion).
 			query: `scope.version = '1.0.0'`,
 			expectedKeys: []telemetrytypes.FieldKeySelector{
 				{
-					Name:          "scope.version",
+					Name:          "version",
 					Signal:        telemetrytypes.SignalUnspecified,
 					FieldContext:  telemetrytypes.FieldContextScope,
 					FieldDataType: telemetrytypes.FieldDataTypeUnspecified,
 				},
+				{
+					Name:          "scope.version",
+					Signal:        telemetrytypes.SignalUnspecified,
+					FieldContext:  telemetrytypes.FieldContextUnspecified,
+					FieldDataType: telemetrytypes.FieldDataTypeUnspecified,
+				},
 			},
 		},
 		{

pkg/statementbuilder/tracesstatementbuilder/statement_builder.go

@@ -163,31 +163,15 @@ func getKeySelectors(query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation])
 	}
 
 	for idx := range query.GroupBy {
-		groupBy := query.GroupBy[idx]
-		keySelectors = append(keySelectors, &telemetrytypes.FieldKeySelector{
-			Name:          groupBy.Name,
-			Signal:        telemetrytypes.SignalTraces,
-			FieldContext:  groupBy.FieldContext,
-			FieldDataType: groupBy.FieldDataType,
-		})
+		keySelectors = append(keySelectors, keySelectorsForField(query.GroupBy[idx].TelemetryFieldKey)...)
 	}
 
 	for idx := range query.SelectFields {
-		keySelectors = append(keySelectors, &telemetrytypes.FieldKeySelector{
-			Name:          query.SelectFields[idx].Name,
-			Signal:        telemetrytypes.SignalTraces,
-			FieldContext:  query.SelectFields[idx].FieldContext,
-			FieldDataType: query.SelectFields[idx].FieldDataType,
-		})
+		keySelectors = append(keySelectors, keySelectorsForField(query.SelectFields[idx])...)
 	}
 
 	for idx := range query.Order {
-		keySelectors = append(keySelectors, &telemetrytypes.FieldKeySelector{
-			Name:          query.Order[idx].Key.Name,
-			Signal:        telemetrytypes.SignalTraces,
-			FieldContext:  query.Order[idx].Key.FieldContext,
-			FieldDataType: query.Order[idx].Key.FieldDataType,
-		})
+		keySelectors = append(keySelectors, keySelectorsForField(query.Order[idx].Key.TelemetryFieldKey)...)
 	}
 
 	for idx := range keySelectors {
@@ -198,6 +182,26 @@ func getKeySelectors(query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation])
 	return keySelectors
 }
 
+func keySelectorsForField(key telemetrytypes.TelemetryFieldKey) []*telemetrytypes.FieldKeySelector {
+	selectors := []*telemetrytypes.FieldKeySelector{
+		{
+			Name:          key.Name,
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  key.FieldContext,
+			FieldDataType: key.FieldDataType,
+		},
+	}
+	if key.FieldContext != telemetrytypes.FieldContextUnspecified {
+		selectors = append(selectors, &telemetrytypes.FieldKeySelector{
+			Name:          key.FieldContext.StringValue() + "." + key.Name,
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextUnspecified,
+			FieldDataType: key.FieldDataType,
+		})
+	}
+	return selectors
+}
+
 // mergeDeprecatedTraceKeys prepends deprecated intrinsic/calculated trace field
 // definitions to the keys map. We do this during statement building, not at
 // metadata fetch time, because:

pkg/statementbuilder/tracesstatementbuilder/stmt_builder_test.go

@@ -934,13 +934,63 @@ func TestStatementBuilderListQueryWithCorruptData(t *testing.T) {
 				Args:  []any{"1747947419000000000", "1747983448000000000", uint64(1747945619), uint64(1747983448), 10},
 			},
 		},
+		{
+			// A scope attribute whose own name literally carries a `scope.` prefix (`scope.prefixed`,
+			// normalized to {prefixed, scope}) resolves to that attribute in a SELECT even without a
+			// filter: getKeySelectors emits the reconstructed `scope.prefixed` selector so the metadata
+			// fetch surfaces it and AdjustKey recovers the full name. Without it the `scope.` prefix is
+			// lost and it wrongly reads `scope.attributes.prefixed`.
+			name:        "scope-prefixed attribute in selectFields resolves without a filter",
+			requestType: qbtypes.RequestTypeRaw,
+			keysMap: map[string][]*telemetrytypes.TelemetryFieldKey{
+				"scope.prefixed": {
+					{
+						Name:          "scope.prefixed",
+						Signal:        telemetrytypes.SignalTraces,
+						FieldContext:  telemetrytypes.FieldContextScope,
+						FieldDataType: telemetrytypes.FieldDataTypeString,
+					},
+				},
+			},
+			query: qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+				Signal:       telemetrytypes.SignalTraces,
+				StepInterval: qbtypes.Step{Duration: 30 * time.Second},
+				Filter:       &qbtypes.Filter{},
+				SelectFields: []telemetrytypes.TelemetryFieldKey{
+					{Name: "prefixed", FieldContext: telemetrytypes.FieldContextScope},
+				},
+				Limit: 10,
+			},
+			expected: qbtypes.Statement{
+				Query: "SELECT timestamp AS `__SELECT_KEY_0_timestamp`, trace_id AS `__SELECT_KEY_1_trace_id`, span_id AS `__SELECT_KEY_2_span_id`, multiIf(scope.attributes.`scope.prefixed` IS NOT NULL, scope.attributes.`scope.prefixed`::String, NULL) AS `__SELECT_KEY_3_scope.prefixed` FROM signoz_traces.distributed_signoz_index_v3 WHERE timestamp >= ? AND timestamp < ? AND ts_bucket_start >= ? AND ts_bucket_start <= ? LIMIT ?",
+				Args:  []any{"1747947419000000000", "1747983448000000000", uint64(1747945619), uint64(1747983448), 10},
+			},
+		},
 		{
 			// A scope-context key whose name matches a declared scope path resolves to that
 			// declared path (scope.name), not the span `name` column and not an undeclared
-			// scope attribute, even with no metadata.
-			name:        "scope-context name with no metadata resolves to the declared scope path",
+			// scope attribute. getTracesKeys surfaces the declared path as an intrinsic key
+			// (metadata.go), which shadows the same-named span intrinsic.
+			name:        "scope-context name resolves to the declared scope path",
 			requestType: qbtypes.RequestTypeRaw,
-			keysMap:     map[string][]*telemetrytypes.TelemetryFieldKey{},
+			keysMap: map[string][]*telemetrytypes.TelemetryFieldKey{
+				"scope.name": {
+					{
+						Name:          "scope.name",
+						Signal:        telemetrytypes.SignalTraces,
+						FieldContext:  telemetrytypes.FieldContextScope,
+						FieldDataType: telemetrytypes.FieldDataTypeString,
+					},
+				},
+				"name": {
+					{
+						Name:          "name",
+						Signal:        telemetrytypes.SignalTraces,
+						FieldContext:  telemetrytypes.FieldContextSpan,
+						FieldDataType: telemetrytypes.FieldDataTypeString,
+					},
+				},
+			},
 			query: qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
 				Signal:       telemetrytypes.SignalTraces,
 				StepInterval: qbtypes.Step{Duration: 30 * time.Second},
@@ -956,41 +1006,22 @@ func TestStatementBuilderListQueryWithCorruptData(t *testing.T) {
 			},
 		},
 		{
-			// A scope name that collides with a declared path: even with a scope attribute
-			// literally named `version` in metadata alongside the declared scope.version, a
-			// select on `{version, scope}` binds to the declared path only. The reserved-name
-			// attribute is addressed separately as scope.attribute.version.
-			name:        "scope select field binds to the declared path, ignoring a same-named scope attribute",
+			// span.scope.name (span context, name "scope.name") resolves to the declared
+			// scope path scope.name, not a span attribute literally named scope.name.
+			name:        "span-context scope.name in selectFields resolves to the declared scope path",
 			requestType: qbtypes.RequestTypeRaw,
-			keysMap: map[string][]*telemetrytypes.TelemetryFieldKey{
-				"scope.version": {
-					{
-						Name:          "scope.version",
-						Signal:        telemetrytypes.SignalTraces,
-						FieldContext:  telemetrytypes.FieldContextScope,
-						FieldDataType: telemetrytypes.FieldDataTypeString,
-					},
-				},
-				"version": {
-					{
-						Name:          "version",
-						Signal:        telemetrytypes.SignalTraces,
-						FieldContext:  telemetrytypes.FieldContextScope,
-						FieldDataType: telemetrytypes.FieldDataTypeString,
-					},
-				},
-			},
+			keysMap:     map[string][]*telemetrytypes.TelemetryFieldKey{},
 			query: qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
 				Signal:       telemetrytypes.SignalTraces,
 				StepInterval: qbtypes.Step{Duration: 30 * time.Second},
 				Filter:       &qbtypes.Filter{},
 				SelectFields: []telemetrytypes.TelemetryFieldKey{
-					{Name: "version", FieldContext: telemetrytypes.FieldContextScope},
+					{Name: "scope.name", FieldContext: telemetrytypes.FieldContextSpan},
 				},
 				Limit: 10,
 			},
 			expected: qbtypes.Statement{
-				Query: "SELECT timestamp AS `__SELECT_KEY_0_timestamp`, trace_id AS `__SELECT_KEY_1_trace_id`, span_id AS `__SELECT_KEY_2_span_id`, multiIf(scope.version::String <> '', scope.version::String, NULL) AS `__SELECT_KEY_3_version` FROM signoz_traces.distributed_signoz_index_v3 WHERE timestamp >= ? AND timestamp < ? AND ts_bucket_start >= ? AND ts_bucket_start <= ? LIMIT ?",
+				Query: "SELECT timestamp AS `__SELECT_KEY_0_timestamp`, trace_id AS `__SELECT_KEY_1_trace_id`, span_id AS `__SELECT_KEY_2_span_id`, multiIf(scope.name::String <> '', scope.name::String, NULL) AS `__SELECT_KEY_3_scope.name` FROM signoz_traces.distributed_signoz_index_v3 WHERE timestamp >= ? AND timestamp < ? AND ts_bucket_start >= ? AND ts_bucket_start <= ? LIMIT ?",
 				Args:  []any{"1747947419000000000", "1747983448000000000", uint64(1747945619), uint64(1747983448), 10},
 			},
 		},

pkg/telemetryschema/tracestelemetryschema/condition_builder_test.go

@@ -453,6 +453,19 @@ func TestConditionForScopeIntrinsicFields(t *testing.T) {
 			value:       nil,
 			expectedSQL: "scope.version::String = ''",
 		},
+		{
+			// `scope.attribute.name` (normalized to {attribute.name, scope}) addresses the scope
+			// attribute named `name` — the declared `scope.name` path is never reached this way.
+			name: "Equal - scope.attribute.name reaches the named scope attribute",
+			key: telemetrytypes.TelemetryFieldKey{
+				Name:          "attribute.name",
+				FieldContext:  telemetrytypes.FieldContextScope,
+				FieldDataType: telemetrytypes.FieldDataTypeString,
+			},
+			operator:    qbtypes.FilterOperatorEqual,
+			value:       "io.signoz.checkout",
+			expectedSQL: "(scope.attributes.`name`::String = ? AND scope.attributes.`name` IS NOT NULL)",
+		},
 	}
 
 	for _, tc := range testCases {
@@ -491,6 +504,17 @@ func TestConditionForSynthesizedKeys(t *testing.T) {
 		assert.Contains(t, args, "timeout")
 	})
 
+	t.Run("scope context with no metadata -> scope attribute", func(t *testing.T) {
+		sb := sqlbuilder.NewSelectBuilder()
+		key := telemetrytypes.TelemetryFieldKey{Name: "custom.attr", FieldContext: telemetrytypes.FieldContextScope}
+		conds, warnings, err := cb.ConditionFor(ctx, valuer.UUID{}, 0, 0, &key, noMatches, qbtypes.ConditionBuilderOptions{}, qbtypes.FilterOperatorEqual, "v", sb)
+		assert.NoError(t, err, "an undeclared scope attribute must still be filterable")
+		assert.NotEmpty(t, warnings)
+		sb.Where(conds...)
+		sql, _ := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+		assert.Contains(t, sql, "scope.attributes.`custom.attr`")
+	})
+
 	t.Run("bare key with number operand -> attribute number", func(t *testing.T) {
 		sb := sqlbuilder.NewSelectBuilder()
 		key := telemetrytypes.TelemetryFieldKey{Name: "http.status"}

pkg/telemetryschema/tracestelemetryschema/field_mapper.go

@@ -300,16 +300,17 @@ func (m *fieldMapper) resolveColumnExprs(
 				exprs = append(exprs, fmt.Sprintf("%s.`%s`::String", columnName, key.Name))
 				existExprs = append(existExprs, fmt.Sprintf("%s.`%s` IS NOT NULL", columnName, key.Name))
 			case telemetrytypes.FieldContextScope:
-				if path, ok := declaredScopePath(key); ok {
+				if f, ok := IntrinsicFields[key.Name]; ok && f.FieldContext == telemetrytypes.FieldContextScope {
 					// declared String paths on the scope column read '' for the missing case
-					exprs = append(exprs, fmt.Sprintf("%s::String", path))
-					existExprs = append(existExprs, fmt.Sprintf("%s <> ''", path))
+					exprs = append(exprs, fmt.Sprintf("%s::String", key.Name))
+					existExprs = append(existExprs, fmt.Sprintf("%s <> ''", key.Name))
 				} else {
-					exprs = append(exprs, fmt.Sprintf("%s.attributes.`%s`::String", columnName, key.Name))
-					existExprs = append(existExprs, fmt.Sprintf("%s.attributes.`%s` IS NOT NULL", columnName, key.Name))
+					attributeName := strings.TrimPrefix(key.Name, "attribute.") // literal "attribute" prefix in attribute keys needs double prefix
+					exprs = append(exprs, fmt.Sprintf("%s.attributes.%s::String", columnName, querybuilder.ClickHouseIdentifier(attributeName)))
+					existExprs = append(existExprs, fmt.Sprintf("%s.attributes.%s IS NOT NULL", columnName, querybuilder.ClickHouseIdentifier(attributeName)))
 				}
 			default:
-				return nil, nil, nil, errors.Newf(errors.TypeInvalidInput, errors.CodeInvalidInput, "only resource and scope context fields are supported for json columns, got %s", key.FieldContext.String)
+				return nil, nil, nil, errors.NewInternalf(errors.CodeInternal, "only resource and scope context fields are supported for json columns, got %s", key.FieldContext.String)
 			}
 		case schema.ColumnTypeEnumString,
 			schema.ColumnTypeEnumUInt64,
@@ -352,20 +353,6 @@ func (m *fieldMapper) resolveColumnExprs(
 	return exprs, existExprs, columns, nil
 }
 
-// logicalForResolvedColumn returns the logical field for a directly-resolvable key: its
-// semantic-convention family when the metadata map proves membership, otherwise the
-// single-member field for the key as given.
-func (m *fieldMapper) logicalForResolvedColumn(ctx context.Context, orgID valuer.UUID, field *telemetrytypes.TelemetryFieldKey, keys map[string][]*telemetrytypes.TelemetryFieldKey) *telemetrytypes.LogicalField {
-	for _, logical := range querybuilder.MatchingLogicalFields(ctx, orgID, m.fl, field, keys) {
-		if logical.IsFamily() &&
-			logical.FieldContext == field.FieldContext &&
-			(field.FieldDataType == telemetrytypes.FieldDataTypeUnspecified || logical.FieldDataType == field.FieldDataType) {
-			return logical
-		}
-	}
-	return telemetrytypes.SingleLogicalField(field.Name, field)
-}
-
 // upgradeToFamilies swaps single-member candidates for their family when the
 // metadata map proves membership. Candidate order and every non-family
 // candidate stay exactly as the legacy flow produced them; sibling candidates
@@ -430,13 +417,12 @@ func (m *fieldMapper) ColumnExpressionFor(
 	var candidates []*telemetrytypes.LogicalField
 	switch _, err := m.FieldFor(ctx, orgID, startNs, endNs, field); {
 	case err == nil:
-		// A directly-resolvable key upgrades to its family when the metadata
-		// map proves membership; otherwise it stays single-member.
-		candidates = []*telemetrytypes.LogicalField{m.logicalForResolvedColumn(ctx, orgID, field, keys)}
+		// Every match from metadata is kept, similar to the filter path.
+		candidates = querybuilder.MatchingLogicalFields(ctx, orgID, m.fl, field, keys)
+		if len(candidates) == 0 {
+			candidates = []*telemetrytypes.LogicalField{telemetrytypes.SingleLogicalField(field.Name, field)}
+		}
 	case errors.Is(err, qbtypes.ErrColumnNotFound):
-		// The legacy candidate flow: column (when the bare name is one) plus metadata
-		// matches, else synthesized type-variant keys. The family step only swaps candidates
-		// for their family; it never changes candidate order or non-family behavior.
 		raw := m.CandidateKeys(ctx, orgID, field, nil, keys)
 		if len(raw) == 0 {
 			return "", errors.Wrapf(err, errors.TypeInvalidInput, errors.CodeInvalidInput, "field `%s` not found", field.Name).WithSuggestions(errors.NewSuggestionsOnLevenshteinDistance(field.Name, errors.NounKeys, maps.Keys(keys))...)
@@ -610,43 +596,14 @@ func (m *fieldMapper) CandidateKeys(ctx context.Context, _ valuer.UUID, field *t
 		literal := telemetrytypes.NewTelemetryFieldKey(field.FieldContext.StringValue()+"."+field.Name, field.FieldContext, field.FieldDataType)
 		return append(querybuilder.SynthesizeKeys(field, value), querybuilder.SynthesizeKeys(literal, value)...)
 	case telemetrytypes.FieldContextScope:
-		// A short scope name that names a declared scope path (e.g. {name, scope} -> scope.name)
-		// resolves to that declared path, not an undeclared scope attribute.
-		if compound := field.FieldContext.StringValue() + "." + field.Name; isDeclaredScopePath(compound) {
-			return []*telemetrytypes.TelemetryFieldKey{telemetrytypes.NewTelemetryFieldKey(compound, telemetrytypes.FieldContextScope, telemetrytypes.FieldDataTypeString)}
-		}
-		return []*telemetrytypes.TelemetryFieldKey{synthScopeAttributeKey(field)}
+		// Declared scope paths (scope.name / scope.version) arrive via metadata as intrinsics;
+		// anything reaching synth is an undeclared scope attribute.
+		return []*telemetrytypes.TelemetryFieldKey{telemetrytypes.NewTelemetryFieldKey(field.Name, telemetrytypes.FieldContextScope, telemetrytypes.FieldDataTypeString)}
 	}
 	// contexts that don't exist on spans (log, body, …) have nothing to synthesize
 	return nil
 }
 
-// synthScopeAttributeKey guesses a scope attribute (scope.attributes.<name>) for a name absent
-// from metadata — the scope analog of querybuilder.SynthesizeKeys.
-func synthScopeAttributeKey(field *telemetrytypes.TelemetryFieldKey) *telemetrytypes.TelemetryFieldKey {
-	return telemetrytypes.NewTelemetryFieldKey(field.Name, telemetrytypes.FieldContextScope, telemetrytypes.FieldDataTypeString)
-}
-
-func isDeclaredScopePath(name string) bool {
-	f, ok := IntrinsicFields[name]
-	return ok && f.FieldContext == telemetrytypes.FieldContextScope
-}
-
-// declaredScopePath returns the compound declared scope path (e.g. `scope.name`) for a scope
-// key given in either its short ({name, scope}) or already-compound ({scope.name, scope})
-// form, and whether it names a declared path at all. Normalization strips the `scope.` prefix,
-// so the declared paths reach the renderers in short form; IntrinsicFields keys them compound.
-func declaredScopePath(key *telemetrytypes.TelemetryFieldKey) (string, bool) {
-	if isDeclaredScopePath(key.Name) {
-		return key.Name, true
-	}
-	compound := telemetrytypes.FieldContextScope.StringValue() + "." + key.Name
-	if isDeclaredScopePath(compound) {
-		return compound, true
-	}
-	return "", false
-}
-
 // scopeJSONExistsExpression renders the existence predicate for the scope JSON column, the one
 // signal-specific case the generic querybuilder.ExistsExpression must not carry.
 func scopeJSONExistsExpression(key *telemetrytypes.TelemetryFieldKey, fieldExpression string, exists bool) (string, bool) {
@@ -654,7 +611,7 @@ func scopeJSONExistsExpression(key *telemetrytypes.TelemetryFieldKey, fieldExpre
 		return "", false
 	}
 	// Declared String paths are non-Nullable (absent reads '' not NULL).
-	if _, ok := declaredScopePath(key); ok {
+	if f, ok := IntrinsicFields[key.Name]; ok && f.FieldContext == telemetrytypes.FieldContextScope {
 		if exists {
 			return fieldExpression + " <> ''", true
 		}

pkg/telemetryschema/tracestelemetryschema/field_mapper_test.go

@@ -111,6 +111,18 @@ func TestGetFieldKeyName(t *testing.T) {
 			expectedResult: "scope.attributes.`custom.attr`::String",
 			expectedError:  nil,
 		},
+		{
+			// `scope.attribute.name` normalizes to {attribute.name, scope}; the literal
+			// `attribute.` prefix is dropped so it addresses the scope attribute named `name`
+			// (which the declared `scope.name` path deliberately does not).
+			name: "Scope field - attribute prefix addresses the named scope attribute",
+			key: telemetrytypes.TelemetryFieldKey{
+				Name:         "attribute.name",
+				FieldContext: telemetrytypes.FieldContextScope,
+			},
+			expectedResult: "scope.attributes.`name`::String",
+			expectedError:  nil,
+		},
 		{
 			// Query like `attribute.attribute_string:string` should resolve to `attributes_string['attribute_string']`.
 			name: "Attribute key whose name collides with contextual map column resolves as a map lookup",
@@ -332,12 +344,13 @@ func TestColumnExpressionForTimestampAttributeCollision(t *testing.T) {
 	})
 }
 
-// TestColumnExpressionForScopeUnion covers select-side resolution of scope names that
+// TestColumnExpressionForScopeDeclaredPath covers select-side resolution of scope names that
 // collide with a declared scope path. A short name under scope context (or the bare
-// `scope.<x>` spelling that normalizes to it) binds to the declared path, and unions a
-// same-named scope attribute when one is also in metadata. The full `scope.<x>` name under
-// explicit scope context addresses the declared path alone.
-func TestColumnExpressionForScopeUnion(t *testing.T) {
+// `scope.<x>` spelling that normalizes to it) names both homes and coalesces them when
+// metadata knows a same-named scope attribute, and binds to the declared path alone when it
+// does not. The full `scope.<x>` name under explicit scope context addresses the declared
+// path alone; the explicit `scope.attribute.` prefix addresses the attribute alone.
+func TestColumnExpressionForScopeDeclaredPath(t *testing.T) {
 	ctx := context.Background()
 
 	scopeKey := func(name string) *telemetrytypes.TelemetryFieldKey {
@@ -371,30 +384,50 @@ func TestColumnExpressionForScopeUnion(t *testing.T) {
 			keys:           declaredOnly,
 			expectedResult: "multiIf(scope.version::String <> '', scope.version::String, NULL)",
 		},
-		{
-			name:           "short name binds to the declared path only, ignoring a same-named scope attribute",
-			key:            telemetrytypes.TelemetryFieldKey{Name: "version", FieldContext: telemetrytypes.FieldContextScope},
-			keys:           withAttr,
-			expectedResult: "multiIf(scope.version::String <> '', scope.version::String, NULL)",
-		},
 		{
 			name:           "full scope.version name under scope context addresses the declared path alone",
 			key:            telemetrytypes.TelemetryFieldKey{Name: "scope.version", FieldContext: telemetrytypes.FieldContextScope},
 			keys:           withAttr,
 			expectedResult: "multiIf(scope.version::String <> '', scope.version::String, NULL)",
 		},
-		{
-			name:           "short scope name binds to the declared scope.name only, ignoring a same-named attribute",
-			key:            telemetrytypes.TelemetryFieldKey{Name: "name", FieldContext: telemetrytypes.FieldContextScope},
-			keys:           withAttr,
-			expectedResult: "multiIf(scope.name::String <> '', scope.name::String, NULL)",
-		},
 		{
 			name:           "full scope.name name under scope context addresses the declared path alone",
 			key:            telemetrytypes.TelemetryFieldKey{Name: "scope.name", FieldContext: telemetrytypes.FieldContextScope},
 			keys:           withAttr,
 			expectedResult: "multiIf(scope.name::String <> '', scope.name::String, NULL)",
 		},
+		{
+			// `scope.attribute.name` normalizes to {attribute.name, scope}; the `attribute.`
+			// prefix is dropped so it addresses the scope attribute named `name` — the only
+			// way to reach it, since `scope.name` is reserved for the declared path.
+			name:           "attribute prefix reaches the named scope attribute",
+			key:            telemetrytypes.TelemetryFieldKey{Name: "attribute.name", FieldContext: telemetrytypes.FieldContextScope},
+			keys:           withAttr,
+			expectedResult: "multiIf(scope.attributes.`name` IS NOT NULL, scope.attributes.`name`::String, NULL)",
+		},
+		{
+			// the caller supplied the context, so `scope.` is part of the name rather than a
+			// prefix to strip: this addresses a scope attribute literally named
+			// `scope.testing.env`, not the attribute `testing.env`
+			name:           "explicit context keeps a scope-prefixed name intact",
+			key:            telemetrytypes.TelemetryFieldKey{Name: "scope.testing.env", FieldContext: telemetrytypes.FieldContextScope},
+			keys:           declaredOnly,
+			expectedResult: "multiIf(scope.attributes.`scope.testing.env` IS NOT NULL, scope.attributes.`scope.testing.env`::String, NULL)",
+		},
+		{
+			// metadata knows both homes under this name, so the short spelling coalesces
+			// them instead of being rejected as ambiguous
+			name:           "short name coalesces a known scope attribute with the declared path",
+			key:            telemetrytypes.TelemetryFieldKey{Name: "name", FieldContext: telemetrytypes.FieldContextScope},
+			keys:           withAttr,
+			expectedResult: "multiIf(scope.attributes.`name` IS NOT NULL, toString(scope.attributes.`name`::String), scope.name::String <> '', toString(scope.name::String), NULL)",
+		},
+		{
+			name:           "short version coalesces a known scope attribute with the declared path",
+			key:            telemetrytypes.TelemetryFieldKey{Name: "version", FieldContext: telemetrytypes.FieldContextScope},
+			keys:           withAttr,
+			expectedResult: "multiIf(scope.attributes.`version` IS NOT NULL, toString(scope.attributes.`version`::String), scope.version::String <> '', toString(scope.version::String), NULL)",
+		},
 	}
 
 	for _, tc := range testCases {

pkg/types/telemetrytypes/field.go

@@ -145,19 +145,6 @@ func (f *TelemetryFieldKey) Equal(key *TelemetryFieldKey) bool {
 //	key := &TelemetryFieldKey{Name: "resource.service.name:string"}
 //	key.Normalize()
 //	// Result: Name: "service.name", FieldContext: FieldContextResource, FieldDataType: FieldDataTypeString
-// declaredScopePathSuffixes are the OTel InstrumentationScope fields that address a
-// declared top-level path on the scope column rather than a scope attribute. They keep
-// their compound `scope.<suffix>` name through normalization.
-var declaredScopePathSuffixes = map[string]struct{}{
-	"name":    {},
-	"version": {},
-}
-
-func isDeclaredScopePathSuffix(name string) bool {
-	_, ok := declaredScopePathSuffixes[name]
-	return ok
-}
-
 func (f *TelemetryFieldKey) Normalize() {
 
 	// Step 1: Parse data type from the right (after the last ":") if not already specified
@@ -176,17 +163,9 @@ func (f *TelemetryFieldKey) Normalize() {
 		if dotIdx := strings.Index(f.Name, "."); dotIdx != -1 {
 			potentialContext := f.Name[:dotIdx]
 			if fc, ok := fieldContexts[potentialContext]; ok && fc != FieldContextUnspecified {
-				remainder := f.Name[dotIdx+1:]
+				f.Name = f.Name[dotIdx+1:]
 				f.FieldContext = fc
 
-				// The declared scope paths (scope.name / scope.version) keep their compound
-				// name so they stay distinct from a scope attribute of the same short name.
-				if fc == FieldContextScope && isDeclaredScopePathSuffix(remainder) {
-					// f.Name stays as the compound `scope.<suffix>`
-				} else {
-					f.Name = remainder
-				}
-
 				// Step 2a: Handle special case for log.body.* fields
 				if f.FieldContext == FieldContextLog && strings.HasPrefix(f.Name, BodyJSONStringSearchPrefix) {
 					f.FieldContext = FieldContextBody

pkg/types/telemetrytypes/field_test.go

@@ -22,7 +22,7 @@ func TestGetFieldKeyFromKeyText(t *testing.T) {
 		{
 			keyText: "scope.name",
 			expected: TelemetryFieldKey{
-				Name:          "scope.name",
+				Name:          "name",
 				FieldContext:  FieldContextScope,
 				FieldDataType: FieldDataTypeUnspecified,
 			},
@@ -30,7 +30,7 @@ func TestGetFieldKeyFromKeyText(t *testing.T) {
 		{
 			keyText: "scope.version",
 			expected: TelemetryFieldKey{
-				Name:          "scope.version",
+				Name:          "version",
 				FieldContext:  FieldContextScope,
 				FieldDataType: FieldDataTypeUnspecified,
 			},

tests/integration/tests/queriertraces/01_list.py

@@ -1308,19 +1308,24 @@ def test_traces_list_with_corrupt_data(
         # The explicit `scope.` prefix forces scope context only, so span 0's
         # span attribute is ignored — only span 1 matches.
         pytest.param("scope.env.tier = 'gold'", [1], id="scope_prefixed_cross_context"),
-        # `scope.name` binds to the declared scope.name field only (span 0). A scope
-        # attribute literally named `name` (span 1) is reserved-shadowed and is addressed
-        # separately as scope.attribute.name, so it does not match here.
-        pytest.param("scope.name = 'io.signoz.checkout'", [0], id="scope_name_reserved_declared_only"),
-        # A span attribute literally named `scope.name` is addressed with an explicit
-        # attribute context; the scope-prefixed spelling binds to the declared field only.
-        # Span 2 carries attribute scope.name='attr-scope-name'.
-        pytest.param("attribute.scope.name = 'attr-scope-name'", [2], id="scope_name_attribute_explicit_context"),
-        # An unprefixed `name` resolves to the intrinsic span `name` column and a
-        # `name` scope attribute, but NOT the scope.name field. Span 2's span
-        # name and span 1's scope attribute `name` both equal 'io.signoz.checkout';
-        # span 0's scope.name field equals it too but is NOT matched.
-        pytest.param("name = 'io.signoz.checkout'", [1, 2], id="bare_name_excludes_scope_name_field"),
+        # `scope.name` names both homes it can resolve to: the declared scope.name field
+        # (span 0) and a same-named `name` scope attribute (span 1), the same way any
+        # other name colliding across contexts unions. `scope.attribute.name` addresses
+        # the attribute alone.
+        pytest.param("scope.name = 'io.signoz.checkout'", [0, 1], id="scope_name_unions_attribute"),
+        # The `scope.name` spelling is also a real stored key: span 2 carries a span
+        # attribute literally named `scope.name`, so it matches too.
+        pytest.param("scope.name = 'attr-scope-name'", [2], id="scope_name_matches_stored_spelling"),
+        # The explicit `scope.attribute.` prefix addresses the scope attribute alone, without
+        # the declared path. Span 1 has a `name` scope attribute = 'io.signoz.checkout'.
+        pytest.param("scope.attribute.name = 'io.signoz.checkout'", [1], id="scope_attribute_name"),
+        # `version` as a scope attribute: no span carries one (span 1's 4.5.6 is the declared
+        # scope.version, not a scope attribute), so this matches nothing.
+        pytest.param("scope.attribute.version = '4.5.6'", [], id="scope_attribute_version_none"),
+        # An unprefixed `name` is checked in every applicable context: the span `name`
+        # column (span 2) and a `name` scope attribute (span 1). It does not reach the
+        # declared scope.name field (span 0), which only the `scope.` prefix addresses.
+        pytest.param("name = 'io.signoz.checkout'", [1, 2], id="bare_name_unions_scope_attribute"),
         # A value that no resolvable key holds (scope.name/scope.version field,
         # a `name`/`version` scope attribute, or a same-named attribute/resource)
         # returns nothing.
@@ -1350,10 +1355,11 @@ def test_traces_list_with_scope_filter(
     - Filtering on scope.name / scope.version / a scope attribute.
     - An unprefixed key is resolved across contexts (scope checked alongside
       attribute / intrinsic), while a `scope.`-prefixed key is scope-only.
-    - `scope.name` hits the declared scope.name field only, not a `name` scope
-      attribute (reserved-shadowed) nor a span attribute literally named
-      `scope.name` (addressed as `attribute.scope.name`); a bare `name` hits the
-      span name column and a `name` scope attribute but never the scope.name field.
+    - `scope.name`/`scope.version` name every home they resolve to: the declared JSON
+      sub-column and a same-named `name`/`version` scope attribute. The explicit
+      `scope.attribute.` prefix addresses the attribute alone.
+    - a bare `name` reaches the span `name` column and a `name` scope attribute, but
+      never the declared scope.name field.
     """
     now = datetime.now(tz=UTC).replace(microsecond=0)
     trace_id = TraceIdGenerator.trace_id()