refactor(traces-qb): drop logicalForResolvedColumn

Its family branch is unreachable now that select asks metadata first. Reaching
it requires FieldFor to succeed, which requires a context on the key (getColumn
declines an unspecified one); a key carrying a context has already been put to
MatchingLogicalFields, and only lands here when that came back empty. Calling
the same function again with the same arguments therefore cannot match, and the
method reduces to the single-member field it falls back to.

Instrumenting the branch and running the traces suites confirms it: no call
reaches it with a non-empty match set.

Assisted-by: Claude Opus 5

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

@@ -182,10 +182,6 @@ func (m *fieldMapper) getColumn(
 	case telemetrytypes.FieldContextResource:
 		return []*schema.Column{indexV3Columns["resource"], indexV3Columns["resources_string"]}, nil
 	case telemetrytypes.FieldContextScope:
-		// scope attributes with same name as declared paths create ambiguity and can't be queried directly.
-		if key.Name == "name" || key.Name == "version" {
-			return nil, qbtypes.ErrColumnNotFound
-		}
 		return []*schema.Column{indexV3Columns["scope"]}, nil
 	case telemetrytypes.FieldContextAttribute:
 		switch key.FieldDataType {
@@ -357,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
@@ -431,19 +413,32 @@ func (m *fieldMapper) ColumnExpressionFor(
 	keys map[string][]*telemetrytypes.TelemetryFieldKey,
 ) (string, error) {
 
-	// Resolve the candidate logical field(s).
+	// Resolve the candidate logical field(s). A key carrying a context is asked of metadata
+	// first, the way the filter path asks: the probe below only answers whether a key
+	// resolves to a column and stands in for whether it names one field, so a column that
+	// resolves for either of two homes -- a declared scope path or a same-named scope
+	// attribute -- would be reported as resolved while still being ambiguous. A bare key
+	// cannot resolve through the probe at all (getColumn needs a context), so it already
+	// reaches CandidateKeys, which consults metadata itself, and is left alone here.
 	var candidates []*telemetrytypes.LogicalField
-	switch _, err := m.FieldFor(ctx, orgID, startNs, endNs, field); {
-	case err == nil:
-		candidates = []*telemetrytypes.LogicalField{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))...)
+	if field.FieldContext != telemetrytypes.FieldContextUnspecified {
+		candidates = querybuilder.MatchingLogicalFields(ctx, orgID, m.fl, field, keys)
+	}
+	if len(candidates) == 0 {
+		switch _, err := m.FieldFor(ctx, orgID, startNs, endNs, field); {
+		case err == nil:
+			// Metadata knows nothing about this name (it was asked above, or the key is
+			// bare and cannot resolve here at all), so the column stands alone.
+			candidates = []*telemetrytypes.LogicalField{telemetrytypes.SingleLogicalField(field.Name, field)}
+		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
 		}
-		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
@@ -590,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

@@ -405,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 {