feat: improved keys adjustment logic

[tushar-signoz]

📄 Summary

This pull request introduces a new utility file, collision.go, to the querybuilder package, which provides robust logic for handling duplicate and ambiguous field keys in query builder queries. The new functions ensure that queries are more resilient to naming collisions and ambiguities, especially when dealing with JSON and promoted fields. Additionally, several test cases have been updated to reflect improved handling and warning messages for ambiguous keys.

Key changes include:

New functionality for key handling:

• Added collision.go to pkg/querybuilder, introducing functions like AdjustDuplicateKeys, AdjustKey, and AdjustKeysForAliasExpressions to deduplicate keys, resolve ambiguities, and adjust key representations in queries. These utilities ensure that each key in SelectFields, GroupBy, and OrderBy is unique and as generic as possible, and help clarify ambiguous or aliased fields.

Test updates for improved key handling:

• Updated test cases in json_stmt_builder_test.go to use unprefixed field names (e.g., "user.age" instead of "body.user.age") in group by clauses, reflecting changes in how keys are handled and represented in queries. [1] [2] [3]
• Enhanced warning messages in test expectations to include jsondatatype information, making ambiguity warnings more descriptive and aligned with the new key handling logic. [1] [2] [3]

---

✅ Changes

• Feature: Brief description
• Bug fix: Brief description

---

🏷️ Required: Add Relevant Labels

⚠️ Manually add appropriate labels in the PR sidebar
Please select one or more labels (as applicable):

ex:

• frontend
• backend
• devops
• bug
• enhancement
• ui
• test

---

👥 Reviewers

Tag the relevant teams for review:

• frontend / backend / devops

---

🧪 How to Test

1. ...
2. ...
3. ...

---

🔍 Related Issues

Closes #
https://github.com/SigNoz/engineering-pod/issues/3189

📸 Screenshots / Screen Recording (if applicable / mandatory for UI related changes)

---

📋 Checklist

• Dev Review
• Test cases added (Unit/ Integration / E2E)
• Manually tested the changes

---

👀 Notes for Reviewers

---

Note

Introduces generic key normalization/deduplication and smarter key resolution across queries.

• Adds pkg/querybuilder/collision.go with AdjustDuplicateKeys, AdjustKey, and alias-aware AdjustKeysForAliasExpressions to merge conflicting contexts/data types and reconcile intrinsic/calculated vs metadata keys
• Refactors logs/traces statement builders to use the new adjustors, return the adjusted query, and build precise key selectors (including context/data type); logs key/action telemetry
• Enhances validation to accept context-prefixed aggregation aliases in orderBy; adjusts orderBy keys to alias form for non-raw requests
• Enriches TelemetryFieldKey.String() and adds Equal, enabling clearer ambiguity warnings (now include jsondatatype, materialized, indexes)
• Updates tests (unit, integration) and test data to reflect new key handling, alias behavior, and improved warnings (e.g., remove body. prefixes, add mixed materialization cases)

^{Written by Cursor Bugbot for commit afea85a. This will update automatically on new commits. Configure here.}

[Copilot]

Pull request overview

This pull request refactors the field key adjustment logic in both logs and traces query statement builders by extracting the inline matching logic into a dedicated adjustKey method. The refactoring improves modularity and testability while maintaining the same functional behavior.

Key changes:

• Introduced new adjustKey method in both logQueryStatementBuilder and traceQueryStatementBuilder to handle key matching, context/type adjustment, and materialization logic in a modular way
• Added comprehensive test coverage with TestAdjustKey and TestAdjustKeys tests covering edge cases like intrinsic field collisions, mixed materialization states, and unknown fields
• Expanded test data to include new scenarios such as mixed.materialization.key, severity_text attribute collision, and various multi-context field cases

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
pkg/telemetrylogs/statement_builder.go	Extracts inline key adjustment logic into new adjustKey method for logs query builder
pkg/telemetrytraces/statement_builder.go	Extracts inline key adjustment logic into new adjustKey method for traces query builder; includes minor formatting fix
pkg/telemetrylogs/stmt_builder_test.go	Adds TestAdjustKey with 11 test cases covering various key adjustment scenarios
pkg/telemetrytraces/stmt_builder_test.go	Adds TestAdjustKey (15 cases) and TestAdjustKeys (4 cases), plus 3 new integration test cases
pkg/telemetrylogs/test_data.go	Adds test data for severity_text, mixed.materialization.key, multi.mat.key, mat.key, and materialized.key.name
pkg/telemetrytraces/test_data.go	Adds test data for duration_nano attribute and mixed.materialization.key scenarios

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 7 comments.

Comments suppressed due to low confidence (1)

pkg/telemetrylogs/statement_builder.go:132

• getKeySelectors now passes FieldDataType/FieldContext from the request into metadata key lookup. The metadata store uses these selector fields to filter which key tables are queried and which rows match; if a saved dashboard/query has an incorrect context/data type, the correct keys may not be returned and later key-adjustment logic can’t recover. Consider leaving selector context/data type unspecified for this prefetch (broad match), then resolving the exact key after adjustment (or refetching with narrowed selectors).

	for idx := range query.GroupBy {
		groupBy := query.GroupBy[idx]
		keySelectors = append(keySelectors, &telemetrytypes.FieldKeySelector{
			Name:          groupBy.Name,
			Signal:        telemetrytypes.SignalLogs,
			FieldContext:  groupBy.FieldContext,
			FieldDataType: groupBy.FieldDataType,
		})
	}

	for idx := range query.SelectFields {
		selectField := query.SelectFields[idx]
		keySelectors = append(keySelectors, &telemetrytypes.FieldKeySelector{
			Name:          selectField.Name,
			Signal:        telemetrytypes.SignalLogs,
			FieldContext:  selectField.FieldContext,
			FieldDataType: selectField.FieldDataType,
		})
	}

	for idx := range query.Order {
		keySelectors = append(keySelectors, &telemetrytypes.FieldKeySelector{
			Name:          query.Order[idx].Key.Name,
			Signal:        telemetrytypes.SignalLogs,
			FieldContext:  query.Order[idx].Key.FieldContext,
			FieldDataType: query.Order[idx].Key.FieldDataType,
		})
	}

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[srikanthccv]

Thanks!