refactor(traces-qb): keep every metadata match for a resolved column

Resolving select through metadata before the probe worked, but it reordered
resolution for every context-carrying key to fix one thing: a key that resolves
to a column is not necessarily one field.

Say that where it belongs instead. logicalForResolvedColumn already asks
metadata; it just threw away all but a family and fell back to the key itself.
Returning every match it finds fixes the same ambiguity without moving
resolution around: ColumnExpressionFor keeps its probe-first shape and differs
from main by a single line.

The scope column resolves for both a declared path and a same-named scope
attribute, so `scope.name` with such an attribute present now yields both homes
rather than one. Output is identical to the reordered version on every case
that motivated it -- declared-only, attribute-shadowed, materialized attribute,
and an undeclared scope attribute.

Assisted-by: Claude Opus 5

pkg/statementbuilder/tracesstatementbuilder/stmt_builder_test.go

@@ -369,7 +369,7 @@ func TestStatementBuilder(t *testing.T) {
 				},
 			},
 			expected: qbtypes.Statement{
-				Query: "WITH __resource_filter AS (SELECT fingerprint FROM signoz_traces.distributed_traces_v3_resource WHERE (simpleJSONExtractString(labels, 'service.name') = ? AND labels LIKE ? AND labels LIKE ?) AND seen_at_ts_bucket_start >= ? AND seen_at_ts_bucket_start <= ? GROUP BY fingerprint), __limit_cte AS (SELECT toString(multiIf(response_status_code <> '', response_status_code, NULL)) AS `__GROUP_BY_KEY_0_responseStatusCode`, quantile(0.90)(multiIf(duration_nano <> 0, toFloat64(duration_nano), NULL)) AS __result_0 FROM signoz_traces.distributed_signoz_index_v3 WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter) AND timestamp >= ? AND timestamp < ? AND ts_bucket_start >= ? AND ts_bucket_start <= ? GROUP BY `__GROUP_BY_KEY_0_responseStatusCode` ORDER BY __result_0 DESC LIMIT ?) SELECT toStartOfInterval(timestamp, INTERVAL 30 SECOND) AS ts, toString(multiIf(response_status_code <> '', response_status_code, NULL)) AS `__GROUP_BY_KEY_0_responseStatusCode`, quantile(0.90)(multiIf(duration_nano <> 0, toFloat64(duration_nano), NULL)) AS __result_0 FROM signoz_traces.distributed_signoz_index_v3 WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter) AND timestamp >= ? AND timestamp < ? AND ts_bucket_start >= ? AND ts_bucket_start <= ? AND (`__GROUP_BY_KEY_0_responseStatusCode`) GLOBAL IN (SELECT `__GROUP_BY_KEY_0_responseStatusCode` FROM __limit_cte) GROUP BY ts, `__GROUP_BY_KEY_0_responseStatusCode`",
+				Query: "WITH __resource_filter AS (SELECT fingerprint FROM signoz_traces.distributed_traces_v3_resource WHERE (simpleJSONExtractString(labels, 'service.name') = ? AND labels LIKE ? AND labels LIKE ?) AND seen_at_ts_bucket_start >= ? AND seen_at_ts_bucket_start <= ? GROUP BY fingerprint), __limit_cte AS (SELECT toString(multiIf(response_status_code <> '', response_status_code, NULL)) AS `__GROUP_BY_KEY_0_responseStatusCode`, quantile(0.90)(multiIf(duration_nano <> 0, accurateCastOrNull(duration_nano, 'Float64'), NULL)) AS __result_0 FROM signoz_traces.distributed_signoz_index_v3 WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter) AND timestamp >= ? AND timestamp < ? AND ts_bucket_start >= ? AND ts_bucket_start <= ? GROUP BY `__GROUP_BY_KEY_0_responseStatusCode` ORDER BY __result_0 DESC LIMIT ?) SELECT toStartOfInterval(timestamp, INTERVAL 30 SECOND) AS ts, toString(multiIf(response_status_code <> '', response_status_code, NULL)) AS `__GROUP_BY_KEY_0_responseStatusCode`, quantile(0.90)(multiIf(duration_nano <> 0, accurateCastOrNull(duration_nano, 'Float64'), NULL)) AS __result_0 FROM signoz_traces.distributed_signoz_index_v3 WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter) AND timestamp >= ? AND timestamp < ? AND ts_bucket_start >= ? AND ts_bucket_start <= ? AND (`__GROUP_BY_KEY_0_responseStatusCode`) GLOBAL IN (SELECT `__GROUP_BY_KEY_0_responseStatusCode` FROM __limit_cte) GROUP BY ts, `__GROUP_BY_KEY_0_responseStatusCode`",
 				Args:  []any{"redis-manual", "%service.name%", "%service.name\":\"redis-manual%", uint64(1747945619), uint64(1747983448), "1747947419000000000", "1747983448000000000", uint64(1747945619), uint64(1747983448), 10, "1747947419000000000", "1747983448000000000", uint64(1747945619), uint64(1747983448)},
 			},
 			expectedErr: nil,
@@ -671,7 +671,7 @@ func TestStatementBuilderListQuery(t *testing.T) {
 				Limit: 10,
 			},
 			expected: qbtypes.Statement{
-				Query: "WITH __resource_filter AS (SELECT fingerprint FROM signoz_traces.distributed_traces_v3_resource WHERE (simpleJSONExtractString(labels, 'service.name') = ? AND labels LIKE ? AND labels LIKE ?) AND seen_at_ts_bucket_start >= ? AND seen_at_ts_bucket_start <= ? GROUP BY fingerprint) SELECT timestamp AS `__SELECT_KEY_0_timestamp`, trace_id AS `__SELECT_KEY_1_trace_id`, span_id AS `__SELECT_KEY_2_span_id`, name AS `__SELECT_KEY_3_name`, resource_string_service$$name AS `__SELECT_KEY_4_serviceName`, duration_nano AS `__SELECT_KEY_5_durationNano`, http_method AS `__SELECT_KEY_6_httpMethod`, multiIf(resource.`mixed.materialization.key` IS NOT NULL, resource.`mixed.materialization.key`::String, mapContains(resources_string, 'mixed.materialization.key'), resources_string['mixed.materialization.key'], NULL) AS `__SELECT_KEY_7_mixed.materialization.key` FROM signoz_traces.distributed_signoz_index_v3 WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter) AND timestamp >= ? AND timestamp < ? AND ts_bucket_start >= ? AND ts_bucket_start <= ? LIMIT ?",
+				Query: "WITH __resource_filter AS (SELECT fingerprint FROM signoz_traces.distributed_traces_v3_resource WHERE (simpleJSONExtractString(labels, 'service.name') = ? AND labels LIKE ? AND labels LIKE ?) AND seen_at_ts_bucket_start >= ? AND seen_at_ts_bucket_start <= ? GROUP BY fingerprint) SELECT timestamp AS `__SELECT_KEY_0_timestamp`, trace_id AS `__SELECT_KEY_1_trace_id`, span_id AS `__SELECT_KEY_2_span_id`, name AS `__SELECT_KEY_3_name`, resource_string_service$$name AS `__SELECT_KEY_4_serviceName`, duration_nano AS `__SELECT_KEY_5_durationNano`, http_method AS `__SELECT_KEY_6_httpMethod`, multiIf(`attribute_string_mixed$$materialization$$key_exists`, toString(`attribute_string_mixed$$materialization$$key`), multiIf(resource.`mixed.materialization.key` IS NOT NULL, resource.`mixed.materialization.key`::String, mapContains(resources_string, 'mixed.materialization.key'), resources_string['mixed.materialization.key'], NULL) IS NOT NULL, toString(multiIf(resource.`mixed.materialization.key` IS NOT NULL, resource.`mixed.materialization.key`::String, mapContains(resources_string, 'mixed.materialization.key'), resources_string['mixed.materialization.key'], NULL)), NULL) AS `__SELECT_KEY_7_mixed.materialization.key` FROM signoz_traces.distributed_signoz_index_v3 WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter) AND timestamp >= ? AND timestamp < ? AND ts_bucket_start >= ? AND ts_bucket_start <= ? LIMIT ?",
 				Args:  []any{"redis-manual", "%service.name%", "%service.name\":\"redis-manual%", uint64(1747945619), uint64(1747983448), "1747947419000000000", "1747983448000000000", uint64(1747945619), uint64(1747983448), 10},
 			},
 			expectedErr: nil,

pkg/statementbuilder/tracesstatementbuilder/trace_operator_cte_builder_test.go

@@ -344,7 +344,7 @@ func TestTraceOperatorStatementBuilder(t *testing.T) {
 				},
 			},
 			expected: qbtypes.Statement{
-				Query: "WITH toDateTime64(1747947419000000000, 9) AS t_from, toDateTime64(1747983448000000000, 9) AS t_to, 1747945619 AS bucket_from, 1747983448 AS bucket_to, all_spans AS (SELECT *, resource_string_service$$name AS `service.name` FROM signoz_traces.distributed_signoz_index_v3 WHERE timestamp >= ? AND timestamp < ? AND ts_bucket_start >= ? AND ts_bucket_start <= ?), __resource_filter_A AS (SELECT fingerprint FROM signoz_traces.distributed_traces_v3_resource WHERE (simpleJSONExtractString(labels, 'service.name') = ? AND labels LIKE ? AND labels LIKE ?) AND seen_at_ts_bucket_start >= ? AND seen_at_ts_bucket_start <= ? GROUP BY fingerprint), A AS (SELECT * FROM signoz_traces.distributed_signoz_index_v3 WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter_A) AND timestamp >= ? AND timestamp < ? AND ts_bucket_start >= ? AND ts_bucket_start <= ?), B AS (SELECT * FROM signoz_traces.distributed_signoz_index_v3 WHERE timestamp >= ? AND timestamp < ? AND ts_bucket_start >= ? AND ts_bucket_start <= ? AND toFloat64(response_status_code) < ?), A_AND_B AS (SELECT l.* FROM A AS l INNER JOIN B AS r ON l.trace_id = r.trace_id) SELECT toString(multiIf(multiIf(resource.`service.name` IS NOT NULL, resource.`service.name`::String, mapContains(resources_string, 'service.name'), resources_string['service.name'], NULL) IS NOT NULL, multiIf(resource.`service.name` IS NOT NULL, resource.`service.name`::String, mapContains(resources_string, 'service.name'), resources_string['service.name'], NULL), NULL)) AS `service.name`, avg(multiIf(duration_nano <> 0, toFloat64(duration_nano), mapContains(attributes_number, 'duration_nano'), toFloat64(attributes_number['duration_nano']), NULL)) AS __result_0 FROM A_AND_B GROUP BY `service.name` ORDER BY __result_0 desc SETTINGS distributed_product_mode='allow', max_memory_usage=10000000000",
+				Query: "WITH toDateTime64(1747947419000000000, 9) AS t_from, toDateTime64(1747983448000000000, 9) AS t_to, 1747945619 AS bucket_from, 1747983448 AS bucket_to, all_spans AS (SELECT *, resource_string_service$$name AS `service.name` FROM signoz_traces.distributed_signoz_index_v3 WHERE timestamp >= ? AND timestamp < ? AND ts_bucket_start >= ? AND ts_bucket_start <= ?), __resource_filter_A AS (SELECT fingerprint FROM signoz_traces.distributed_traces_v3_resource WHERE (simpleJSONExtractString(labels, 'service.name') = ? AND labels LIKE ? AND labels LIKE ?) AND seen_at_ts_bucket_start >= ? AND seen_at_ts_bucket_start <= ? GROUP BY fingerprint), A AS (SELECT * FROM signoz_traces.distributed_signoz_index_v3 WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter_A) AND timestamp >= ? AND timestamp < ? AND ts_bucket_start >= ? AND ts_bucket_start <= ?), B AS (SELECT * FROM signoz_traces.distributed_signoz_index_v3 WHERE timestamp >= ? AND timestamp < ? AND ts_bucket_start >= ? AND ts_bucket_start <= ? AND toFloat64(response_status_code) < ?), A_AND_B AS (SELECT l.* FROM A AS l INNER JOIN B AS r ON l.trace_id = r.trace_id) SELECT toString(multiIf(multiIf(resource.`service.name` IS NOT NULL, resource.`service.name`::String, mapContains(resources_string, 'service.name'), resources_string['service.name'], NULL) IS NOT NULL, multiIf(resource.`service.name` IS NOT NULL, resource.`service.name`::String, mapContains(resources_string, 'service.name'), resources_string['service.name'], NULL), NULL)) AS `service.name`, avg(multiIf(duration_nano <> 0, accurateCastOrNull(duration_nano, 'Float64'), mapContains(attributes_number, 'duration_nano'), toFloat64(attributes_number['duration_nano']), NULL)) AS __result_0 FROM A_AND_B GROUP BY `service.name` ORDER BY __result_0 desc SETTINGS distributed_product_mode='allow', max_memory_usage=10000000000",
 				Args:  []any{"1747947419000000000", "1747983448000000000", uint64(1747945619), uint64(1747983448), "frontend", "%service.name%", "%service.name\":\"frontend%", uint64(1747945619), uint64(1747983448), "1747947419000000000", "1747983448000000000", uint64(1747945619), uint64(1747983448), "1747947419000000000", "1747983448000000000", uint64(1747945619), uint64(1747983448), float64(400)},
 			},
 			expectedErr: nil,

pkg/telemetryschema/tracestelemetryschema/condition_builder.go

@@ -199,71 +199,6 @@ func candidateLookupKeys(key *telemetrytypes.TelemetryFieldKey, fieldKeys map[st
 	return nil
 }
 
-// resolveLogicalFields resolves a referenced key to the logical field(s) it names. Metadata
-// decides first; a bare key that also names a real column gets the column prepended, keeping
-// only same-named metadata matches whose type the column allows; a key metadata does not know
-// falls through to CandidateKeys and is reported as synthesized.
-//
-// The select and the filter path both resolve through here, so a key names the same field
-// whether it is read or filtered on. Callers own the not-found error: no match returns nil
-// fields and no error.
-func resolveLogicalFields(
-	ctx context.Context,
-	orgID valuer.UUID,
-	fm qbtypes.FieldMapper,
-	fl flagger.Flagger,
-	startNs, endNs uint64,
-	key *telemetrytypes.TelemetryFieldKey,
-	fieldKeys map[string][]*telemetrytypes.TelemetryFieldKey,
-	value any,
-) (logicalFields []*telemetrytypes.LogicalField, synthesized bool, warnings []string) {
-
-	matches := querybuilder.MatchingLogicalFields(ctx, orgID, fl, key, fieldKeys)
-
-	logicalFields, warning := querybuilder.ResolveLogicalFields(key, matches)
-	if warning != "" {
-		warnings = append(warnings, warning)
-	}
-
-	if key.FieldContext == telemetrytypes.FieldContextUnspecified && len(logicalFields) > 0 {
-		hasColumn := false
-		for _, logical := range logicalFields {
-			if logical.FieldContext == telemetrytypes.FieldContextSpan {
-				hasColumn = true
-				break
-			}
-		}
-		probe := telemetrytypes.NewTelemetryFieldKey(key.Name, telemetrytypes.FieldContextSpan, key.FieldDataType)
-		if cols, colErr := fm.ColumnFor(ctx, orgID, startNs, endNs, probe); colErr == nil && len(cols) > 0 {
-			// The column is the field; a same-named metadata key only joins it where the
-			// column's type allows, so a corrupt entry can neither shadow nor degrade it.
-			// The column is prepended only when metadata did not already surface it.
-			combined := make([]*telemetrytypes.LogicalField, 0, len(logicalFields)+1)
-			if !hasColumn {
-				combined = append(combined, telemetrytypes.SingleLogicalField(key.Name, probe))
-			}
-			for _, logical := range logicalFields {
-				if logical.FieldContext == telemetrytypes.FieldContextSpan ||
-					columnMatchesDataType(cols[0], logical.FieldDataType) {
-					combined = append(combined, logical)
-				}
-			}
-			logicalFields = combined
-		}
-	}
-
-	if len(logicalFields) == 0 {
-		logicalFields = querybuilder.WrapAsLogicalFields(key.Name, fm.CandidateKeys(ctx, orgID, key, value, candidateLookupKeys(key, fieldKeys)))
-		if len(logicalFields) == 0 {
-			return nil, false, warnings
-		}
-		synthesized = true
-		warnings = append(warnings, querybuilder.NewKeyNotFoundWarning(key.Name))
-	}
-
-	return logicalFields, synthesized, warnings
-}
-
 // ConditionFor resolves the referenced key to the key(s) to filter on (ResolveKeys, else
 // synthesized keys with a warning) and builds one condition per resolved key. fieldKeys is
 // the full metadata map; the builder owns key resolution.
@@ -285,11 +220,51 @@ func (c *conditionBuilder) ConditionFor(
 		return nil, nil, err
 	}
 
+	matches := querybuilder.MatchingLogicalFields(ctx, orgID, c.fl, key, fieldKeys)
 	skipResourceFilter := options.SkipResourceFilter
 
-	logicalFields, synthesized, warnings := resolveLogicalFields(ctx, orgID, c.fm, c.fl, startNs, endNs, key, fieldKeys, value)
+	logicalFields, warning := querybuilder.ResolveLogicalFields(key, matches)
+	var warnings []string
+	if warning != "" {
+		warnings = append(warnings, warning)
+	}
+	// A bare key that names a real column filters on the column too — first. When metadata
+	// only knows the name under other contexts, prepend the column and keep metadata matches
+	// only where their type is consistent with it (a corrupt entry can't degrade the column).
+	if key.FieldContext == telemetrytypes.FieldContextUnspecified && len(logicalFields) > 0 {
+		hasColumn := false
+		for _, logical := range logicalFields {
+			if logical.FieldContext == telemetrytypes.FieldContextSpan {
+				hasColumn = true
+				break
+			}
+		}
+		if !hasColumn {
+			probe := telemetrytypes.NewTelemetryFieldKey(key.Name, telemetrytypes.FieldContextSpan, key.FieldDataType)
+			if cols, colErr := c.fm.ColumnFor(ctx, orgID, startNs, endNs, probe); colErr == nil && len(cols) > 0 {
+				combined := make([]*telemetrytypes.LogicalField, 0, len(logicalFields)+1)
+				combined = append(combined, telemetrytypes.SingleLogicalField(key.Name, probe))
+				for _, logical := range logicalFields {
+					if columnMatchesDataType(cols[0], logical.FieldDataType) {
+						combined = append(combined, logical)
+					}
+				}
+				logicalFields = combined
+			}
+		}
+	}
+
+	synthesized := false
 	if len(logicalFields) == 0 {
-		return nil, warnings, querybuilder.NewKeyNotFoundError(key.Name)
+		// Not in metadata. CandidateKeys resolves it: fold contexts (span/trace) get the
+		// metadata map so it can honor a real column, correct to a stripped-name metadata
+		// match, or synthesize; strict contexts pass nil and keep their synthesize path.
+		logicalFields = querybuilder.WrapAsLogicalFields(key.Name, c.fm.CandidateKeys(ctx, orgID, key, value, candidateLookupKeys(key, fieldKeys)))
+		if len(logicalFields) == 0 {
+			return nil, warnings, querybuilder.NewKeyNotFoundError(key.Name)
+		}
+		synthesized = true
+		warnings = append(warnings, querybuilder.NewKeyNotFoundWarning(key.Name))
 	}
 
 	// When a resource sub-query already covers the term, drop resource fields from the main

pkg/telemetryschema/tracestelemetryschema/condition_builder_test.go

@@ -504,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/family_test.go

@@ -236,8 +236,30 @@ func TestColumnExpressionForFamilyGroupBy(t *testing.T) {
 	}
 	fm := NewFieldMapper(familyFlagOn(t))
 
-	expr, err := fm.ColumnExpressionFor(context.Background(), valuer.UUID{}, startNs, endNs,
-		&telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"}, telemetrytypes.FieldDataTypeString, fieldKeys)
-	require.NoError(t, err)
-	require.Equal(t, "multiIf((multiIf(resource.`deployment.environment.name` IS NOT NULL, resource.`deployment.environment.name`::String, mapContains(resources_string, 'deployment.environment.name'), resources_string['deployment.environment.name'], NULL) IS NOT NULL OR multiIf(resource.`deployment.environment` IS NOT NULL, resource.`deployment.environment`::String, mapContains(resources_string, 'deployment.environment'), resources_string['deployment.environment'], NULL) IS NOT NULL), COALESCE(NULLIF(multiIf(resource.`deployment.environment.name` IS NOT NULL, resource.`deployment.environment.name`::String, mapContains(resources_string, 'deployment.environment.name'), resources_string['deployment.environment.name'], NULL), ''), NULLIF(multiIf(resource.`deployment.environment` IS NOT NULL, resource.`deployment.environment`::String, mapContains(resources_string, 'deployment.environment'), resources_string['deployment.environment'], NULL), ''), ''), NULL)", expr)
+	// The family must be reached whether or not the key carries a context: a bare key
+	// resolves through the candidate path, a context-carrying one through metadata.
+	keys := []struct {
+		name string
+		key  telemetrytypes.TelemetryFieldKey
+	}{
+		{"bare", telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"}},
+		{"with context", telemetrytypes.TelemetryFieldKey{
+			Name:         "deployment.environment.name",
+			FieldContext: telemetrytypes.FieldContextResource,
+		}},
+		{"with context and data type", telemetrytypes.TelemetryFieldKey{
+			Name:          "deployment.environment.name",
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+	}
+	for _, tc := range keys {
+		t.Run(tc.name, func(t *testing.T) {
+			key := tc.key
+			expr, err := fm.ColumnExpressionFor(context.Background(), valuer.UUID{}, startNs, endNs,
+				&key, telemetrytypes.FieldDataTypeString, fieldKeys)
+			require.NoError(t, err)
+			require.Equal(t, "multiIf((multiIf(resource.`deployment.environment.name` IS NOT NULL, resource.`deployment.environment.name`::String, mapContains(resources_string, 'deployment.environment.name'), resources_string['deployment.environment.name'], NULL) IS NOT NULL OR multiIf(resource.`deployment.environment` IS NOT NULL, resource.`deployment.environment`::String, mapContains(resources_string, 'deployment.environment'), resources_string['deployment.environment'], NULL) IS NOT NULL), COALESCE(NULLIF(multiIf(resource.`deployment.environment.name` IS NOT NULL, resource.`deployment.environment.name`::String, mapContains(resources_string, 'deployment.environment.name'), resources_string['deployment.environment.name'], NULL), ''), NULLIF(multiIf(resource.`deployment.environment` IS NOT NULL, resource.`deployment.environment`::String, mapContains(resources_string, 'deployment.environment'), resources_string['deployment.environment'], NULL), ''), ''), NULL)", expr)
+		})
+	}
 }

pkg/telemetryschema/tracestelemetryschema/field_mapper.go

@@ -353,6 +353,67 @@ func (m *fieldMapper) resolveColumnExprs(
 	return exprs, existExprs, columns, nil
 }
 
+// logicalForResolvedColumn returns the logical field(s) a directly-resolvable key names.
+// Resolving to a column answers only that the key is addressable, not that it names one
+// field: the scope JSON column resolves for both a declared path and a same-named scope
+// attribute. Metadata is what tells those homes apart, so every match it reports is kept,
+// the way the filter path keeps them. Only a name metadata does not know falls back to
+// the key as given.
+func (m *fieldMapper) logicalForResolvedColumn(ctx context.Context, orgID valuer.UUID, field *telemetrytypes.TelemetryFieldKey, keys map[string][]*telemetrytypes.TelemetryFieldKey) []*telemetrytypes.LogicalField {
+	if matches := querybuilder.MatchingLogicalFields(ctx, orgID, m.fl, field, keys); len(matches) > 0 {
+		return matches
+	}
+	return []*telemetrytypes.LogicalField{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
+// of an already-emitted family are dropped rather than duplicated.
+func (m *fieldMapper) upgradeToFamilies(ctx context.Context, orgID valuer.UUID, field *telemetrytypes.TelemetryFieldKey, candidates []*telemetrytypes.LogicalField, keys map[string][]*telemetrytypes.TelemetryFieldKey) []*telemetrytypes.LogicalField {
+	var families []*telemetrytypes.LogicalField
+	for _, logical := range querybuilder.MatchingLogicalFields(ctx, orgID, m.fl, field, keys) {
+		if logical.IsFamily() {
+			families = append(families, logical)
+		}
+	}
+	if len(families) == 0 {
+		return candidates
+	}
+
+	out := make([]*telemetrytypes.LogicalField, 0, len(candidates))
+	emitted := make(map[*telemetrytypes.LogicalField]bool)
+	for _, candidate := range candidates {
+		var family *telemetrytypes.LogicalField
+		for _, fam := range families {
+			if fam.FieldContext != candidate.FieldContext || fam.FieldDataType != candidate.FieldDataType {
+				continue
+			}
+			memberOfFamily := candidate.Single().Name == field.Name
+			for _, member := range fam.Members {
+				if member.Name == candidate.Single().Name {
+					memberOfFamily = true
+					break
+				}
+			}
+			if memberOfFamily {
+				family = fam
+				break
+			}
+		}
+		if family == nil {
+			out = append(out, candidate)
+			continue
+		}
+		if emitted[family] {
+			continue
+		}
+		emitted[family] = true
+		out = append(out, family)
+	}
+	return out
+}
+
 // ColumnExpressionFor returns the bare (unaliased) SQL expression for the field, resolving
 // unknown keys via CandidateKeys and wrapping guardable columns with exists-guard multiIfs
 // so an absent key yields NULL.
@@ -365,11 +426,19 @@ func (m *fieldMapper) ColumnExpressionFor(
 	keys map[string][]*telemetrytypes.TelemetryFieldKey,
 ) (string, error) {
 
-	// Resolve the candidate logical field(s) the same way the filter path does, so a key
-	// names the same field whether it is selected or filtered on.
-	candidates, _, _ := resolveLogicalFields(ctx, orgID, m, m.fl, startNs, endNs, field, keys, nil)
-	if len(candidates) == 0 {
-		return "", errors.Newf(errors.TypeInvalidInput, errors.CodeInvalidInput, "field `%s` not found", field.Name).WithSuggestions(errors.NewSuggestionsOnLevenshteinDistance(field.Name, errors.NounKeys, maps.Keys(keys))...)
+	// Resolve the candidate logical field(s).
+	var candidates []*telemetrytypes.LogicalField
+	switch _, err := m.FieldFor(ctx, orgID, startNs, endNs, field); {
+	case err == nil:
+		candidates = m.logicalForResolvedColumn(ctx, orgID, field, keys)
+	case errors.Is(err, qbtypes.ErrColumnNotFound):
+		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))...)
+		}
+		candidates = m.upgradeToFamilies(ctx, orgID, field, querybuilder.WrapAsLogicalFields(field.Name, raw), keys)
+	default:
+		return "", err
 	}
 
 	// Group-by/order (String) and aggregation (String/Float64): every candidate is
@@ -516,28 +585,10 @@ func (m *fieldMapper) CandidateKeys(ctx context.Context, _ valuer.UUID, field *t
 	// Metadata match by name, then the literal `{context}.{name}` spelling (a context can be
 	// a legitimate prefix in user data, e.g. `metric.max_count`). For a forgiving context
 	// this is the correction step (span.http.method -> attribute http.method).
-	matches := keys[field.Name]
-	if field.FieldContext != telemetrytypes.FieldContextUnspecified {
-		// A bare-name match must agree on context; a same-named key under a different
-		// context is a different field. The literal `{context}.{name}` spelling is a real
-		// key in whatever context it was stored (e.g. an attribute named `span.test`), so
-		// it is taken regardless of context.
-		validMatches := make([]*telemetrytypes.TelemetryFieldKey, 0, len(matches))
-		for _, match := range matches {
-			if match.FieldContext == field.FieldContext {
-				validMatches = append(validMatches, match)
-			}
-		}
-		compoundName := fmt.Sprintf("%s.%s", field.FieldContext.StringValue(), field.Name)
-		compoundMatches := keys[compoundName]
-		validMatches = append(validMatches, compoundMatches...)
-		matches = append(matches, compoundMatches...)
-		if len(validMatches) > 0 {
-			return validMatches
-		}
+	if matches := keys[field.Name]; len(matches) > 0 {
+		return matches
 	}
-
-	if len(matches) > 0 {
+	if matches := keys[fmt.Sprintf("%s.%s", field.FieldContext.StringValue(), field.Name)]; len(matches) > 0 {
 		return matches
 	}
 

pkg/telemetryschema/tracestelemetryschema/field_mapper_test.go

@@ -282,8 +282,6 @@ func TestColumnExpressionForTemporalColumn(t *testing.T) {
 			expectedResult:   "multiIf(name <> '', accurateCastOrNull(name, 'Float64'), NULL)",
 		},
 		{
-			// absent from metadata, so both spellings a strict context can mean are
-			// tried, exactly as a filter on the same key does
 			name: "map-backed attribute keeps its exists guard",
 			key: telemetrytypes.TelemetryFieldKey{
 				Name:          "user.id",
@@ -291,7 +289,7 @@ func TestColumnExpressionForTemporalColumn(t *testing.T) {
 				FieldDataType: telemetrytypes.FieldDataTypeString,
 			},
 			requiredDataType: telemetrytypes.FieldDataTypeString,
-			expectedResult:   "multiIf(mapContains(attributes_string, 'user.id'), attributes_string['user.id'], mapContains(attributes_string, 'attribute.user.id'), attributes_string['attribute.user.id'], NULL)",
+			expectedResult:   "multiIf(mapContains(attributes_string, 'user.id'), attributes_string['user.id'], NULL)",
 		},
 	}
 
@@ -407,6 +405,20 @@ func TestColumnExpressionForScopeDeclaredPath(t *testing.T) {
 			keys:           withAttr,
 			expectedResult: "multiIf(scope.attributes.`name` IS NOT NULL, scope.attributes.`name`::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 {