chore: add initial version of query range design principles doc

deploy/docker-swarm/otel-collector-config.yaml

@@ -82,6 +82,12 @@ exporters:
     timeout: 45s
     sending_queue:
       enabled: false
+  metadataexporter:
+    cache:
+      provider: in_memory
+    dsn: tcp://clickhouse:9000/signoz_metadata
+    enabled: true
+    timeout: 45s
 service:
   telemetry:
     logs:
@@ -93,19 +99,19 @@ service:
     traces:
       receivers: [otlp]
       processors: [signozspanmetrics/delta, batch]
-      exporters: [clickhousetraces, signozmeter]
+      exporters: [clickhousetraces, metadataexporter, signozmeter]
     metrics:
       receivers: [otlp]
       processors: [batch]
-      exporters: [signozclickhousemetrics, signozmeter]
+      exporters: [signozclickhousemetrics, metadataexporter, signozmeter]
     metrics/prometheus:
       receivers: [prometheus]
       processors: [batch]
-      exporters: [signozclickhousemetrics, signozmeter]
+      exporters: [signozclickhousemetrics, metadataexporter, signozmeter]
     logs:
       receivers: [otlp]
       processors: [batch]
-      exporters: [clickhouselogsexporter, signozmeter]
+      exporters: [clickhouselogsexporter, metadataexporter, signozmeter]
     metrics/meter:
       receivers: [signozmeter]
       processors: [batch/meter]

deploy/docker/otel-collector-config.yaml

@@ -82,6 +82,12 @@ exporters:
     timeout: 45s
     sending_queue:
       enabled: false
+  metadataexporter:
+    cache:
+      provider: in_memory
+    dsn: tcp://clickhouse:9000/signoz_metadata
+    enabled: true
+    timeout: 45s
 service:
   telemetry:
     logs:
@@ -93,19 +99,19 @@ service:
     traces:
       receivers: [otlp]
       processors: [signozspanmetrics/delta, batch]
-      exporters: [clickhousetraces, signozmeter]
+      exporters: [clickhousetraces, metadataexporter, signozmeter]
     metrics:
       receivers: [otlp]
       processors: [batch]
-      exporters: [signozclickhousemetrics, signozmeter]
+      exporters: [signozclickhousemetrics, metadataexporter, signozmeter]
     metrics/prometheus:
       receivers: [prometheus]
       processors: [batch]
-      exporters: [signozclickhousemetrics, signozmeter]
+      exporters: [signozclickhousemetrics, metadataexporter, signozmeter]
     logs:
       receivers: [otlp]
       processors: [batch]
-      exporters: [clickhouselogsexporter, signozmeter]
+      exporters: [clickhouselogsexporter, metadataexporter, signozmeter]
     metrics/meter:
       receivers: [signozmeter]
       processors: [batch/meter]

docs/contributing/query-range.md

@@ -0,0 +1,216 @@
+# Query Range v5 — Design Principles & Architectural Contracts
+
+## Purpose of This Document
+
+This document defines the design principles, invariants, and architectural contracts of the Query Range v5 system. It is intended for the authors working on the querier and querier related parts codebase. Any change to the system must align with the principles described here. If a change would violate a principle, it must be flagged and discussed.
+
+---
+
+## Core Architectural Principle
+
+**The user speaks OpenTelemetry. The storage speaks ClickHouse. The system translates between them. These two worlds must never leak into each other.**
+
+Every design choice in Query Range flows from this separation. The user-facing API surface deals exclusively in `TelemetryFieldKey`: a representation of fields as they exist in the OpenTelemetry data model. The storage layer deals in ClickHouse column expressions, table names, and SQL fragments. The translation between them is mediated by a small set of composable abstractions with strict boundaries.
+
+---
+
+## The Central Type: `TelemetryFieldKey`
+
+`TelemetryFieldKey` is the atomic unit of the entire query system. Every filter, aggregation, group-by, order-by, and select operation is expressed in terms of field keys. Understanding its design contracts is non-negotiable.
+
+### Identity
+
+A field key is identified by three dimensions:
+
+- **Name** — the field name as the user knows it (`service.name`, `http.method`, `trace_id`)
+- **FieldContext** — where the field lives in the OTel model (`resource`, `attribute`, `span`, `log`, `body`, `scope`, `event`, `metric`)
+- **FieldDataType** — the data type (`string`, `bool`, `number`/`float64`/`int64`, array variants)
+
+### Invariant: Same name does not mean same field
+
+`status` as an attribute, `status` as a body JSON key, and `status` as a span-level field are **three different fields**. The context disambiguates. Code that resolves or compares field keys must always consider all three dimensions, never just the name.
+
+### Invariant: Normalization happens once, at the boundary
+
+`TelemetryFieldKey.Normalize()` is called during JSON unmarshaling. After normalization, the text representation `resource.service.name:string` and the programmatic construction `{Name: "service.name", FieldContext: Resource, FieldDataType: String}` are identical.
+
+**Consequence:** Downstream code must never re-parse or re-normalize field keys. If you find yourself splitting on `.` or `:` deep in the pipeline, something is wrong — the normalization should have already happened.
+
+### Invariant: The text format is `context.name:datatype`
+
+Parsing rules (implemented in `GetFieldKeyFromKeyText` and `Normalize`):
+
+1. Data type is extracted from the right, after the last `:`.
+2. Field context is extracted from the left, before the first `.`, if it matches a known context prefix.
+3. Everything remaining is the name.
+
+Special case: `log.body.X` normalizes to `{FieldContext: body, Name: X}` — the `log.body.` prefix collapses because body fields under log are a nested context.
+
+### Invariant: Historical aliases must be preserved
+
+The `fieldContexts` map includes aliases (`tag` -> `attribute`, `spanfield` -> `span`, `logfield` -> `log`). These exist because older database entries use these names. Removing or changing these aliases will break existing saved queries and dashboard configurations.
+
+---
+
+## The Abstraction Stack
+
+The query pipeline is built from four interfaces that compose vertically. Each layer has a single responsibility. Each layer depends only on the layers below it. This layering is intentional and must be preserved.
+
+```
+StatementBuilder          <- Orchestrates everything into executable SQL
+  ├── AggExprRewriter     <- Rewrites aggregation expressions (maps field refs to columns)
+  ├── ConditionBuilder    <- Builds WHERE predicates (field + operator + value -> SQL)
+  └── FieldMapper         <- Maps TelemetryFieldKey -> ClickHouse column expression
+```
+
+### FieldMapper
+
+**Contract:** Given a `TelemetryFieldKey`, return a ClickHouse column expression that yields the value for that field when used in a SELECT.
+
+**Principle:** This is the *only* place where field-to-column translation happens. No other layer should contain knowledge of how fields map to storage. If you need a column expression, go through the FieldMapper.
+
+**Why:** The user says `http.request.method`. ClickHouse might store it as `attributes_string['http.request.method']`, or as a materialized column `` `attribute_string_http$$request$$method` ``, or via a JSON access path in a body column. This variation is entirely contained within the FieldMapper. Everything above it is storage-agnostic.
+
+### ConditionBuilder
+
+**Contract:** Given a field key, an operator, and a value, produce a valid SQL predicate for a WHERE clause.
+
+**Dependency:** Uses FieldMapper for the left-hand side of the condition.
+
+**Principle:** The ConditionBuilder owns all the complexity of operator semantics, i.e type casting, array operators (`hasAny`/`hasAll` vs `=`), existence checks, and negative operator behavior. This complexity must not leak upward into the StatementBuilder.
+
+### AggExprRewriter
+
+**Contract:** Given a user-facing aggregation expression like `sum(duration_nano)`, resolve field references within it and produce valid ClickHouse SQL.
+
+**Dependency:** Uses FieldMapper to resolve field names within expressions.
+
+**Principle:** Aggregation expressions are user-authored strings that contain field references. The rewriter parses them, identifies field references, resolves each through the FieldMapper, and reassembles the expression.
+
+### StatementBuilder
+
+**Contract:** Given a complete `QueryBuilderQuery`, a time range, and a request type, produces an executable SQL statement.
+
+**Dependency:** Uses all three abstractions above.
+
+**Principle:** This is the composition layer. It does not contain field mapping logic, condition building logic, or expression rewriting logic. It orchestrates the other abstractions. If you find storage-specific logic creeping into the StatementBuilder, push it down into the appropriate abstraction.
+
+### Invariant: No layer skipping
+
+The StatementBuilder must not call FieldMapper directly to build conditions, it goes through the ConditionBuilder. The AggExprRewriter must not hardcode column names, it goes through the FieldMapper. Skipping layers creates hidden coupling and makes the system fragile to storage changes.
+
+---
+
+## Design Decisions as Constraints
+
+### Constraint: Formula evaluation happens in Go, not in ClickHouse
+
+Formulas (`A + B`, `A / B`, `sqrt(A*A + B*B)`) are evaluated application-side by `FormulaEvaluator`, not via ClickHouse JOINs.
+
+**Why this is a constraint, not just an implementation choice:** The original JOIN-based approach was abandoned because ClickHouse evaluates joins right-to-left, serializing execution unnecessarily. Running queries independently allows parallelism and caching of intermediate results. Any future optimization must not reintroduce the JOIN pattern without solving the serialization problem.
+
+**Consequence:** Individual query results must be independently cacheable. Formula evaluation must handle label matching, timestamp alignment, and missing values without requiring the queries to coordinate at the SQL level.
+
+### Constraint: Zero-defaulting is aggregation-dependent
+
+Only additive/counting aggregations (`count`, `count_distinct`, `sum`, `rate`) default missing values to zero. Statistical aggregations (`avg`, `min`, `max`, percentiles) must show gaps.
+
+**Why:** Absence of data has different meanings. No error requests in a time bucket means error count = 0. No requests at all means average latency is *unknown*, not 0. Conflating these is a correctness bug, not a display preference.
+
+**Enforcement:** `GetQueriesSupportingZeroDefault` determines which queries can default to zero. The `FormulaEvaluator` consumes this via `canDefaultZero`. Changes to aggregation handling must preserve this distinction.
+
+### Constraint: Existence semantics differ for positive vs negative operators
+
+- **Positive operators** (`=`, `>`, `LIKE`, `IN`, etc.) implicitly assert field existence. `http.method = GET` means "the field exists AND equals GET".
+- **Negative operators** (`!=`, `NOT IN`, `NOT LIKE`, etc.) do **not** add an existence check. `http.method != GET` includes records where the field doesn't exist at all.
+
+**Why:** The user's intent with negative operators is ambiguous. Rather than guess, we take the broader interpretation. Users can add an explicit `EXISTS` filter if they want the narrower one. This is documented in `AddDefaultExistsFilter`.
+
+**Consequence:** Any new operator must declare its existence behavior in `AddDefaultExistsFilter`. Do not add operators without considering this.
+
+### Constraint: Post-processing functions operate on result sets, not in SQL
+
+Functions like `cutOffMin`, `ewma`, `median`, `timeShift`, `fillZero`, `runningDiff`, and `cumulativeSum` are applied in Go on the returned time series, not pushed into ClickHouse SQL.
+
+**Why:** These are sequential time-series transformations that require complete, ordered result sets. Pushing them into SQL would complicate query generation, prevent caching of raw results, and make the functions harder to test. They are applied via `ApplyFunctions` after query execution.
+
+**Consequence:** New time-series transformation functions should follow this pattern i.e implement them as Go functions on `*TimeSeries`, not as SQL modifications.
+
+### Constraint: The API surface rejects unknown fields with suggestions
+
+All request types use custom `UnmarshalJSON` that calls `DisallowUnknownFields`. Unknown fields trigger error messages with Levenshtein-based suggestions ("did you mean: 'groupBy'?").
+
+**Why:** Silent acceptance of unknown fields causes subtle bugs. A misspelled `groupBy` results in ungrouped data with no indication of what went wrong. Failing fast with suggestions turns errors into actionable feedback.
+
+**Consequence:** Any new request type or query spec struct must implement custom unmarshaling with `UnmarshalJSONWithContext`. Do not use default `json.Unmarshal` for user-facing types.
+
+### Constraint: Validation is context-sensitive to request type
+
+What's valid depends on the `RequestType`. For aggregation requests (`time_series`, `scalar`, `distribution`), fields like `groupBy`, `aggregations`, `having`, and aggregation-referenced `orderBy` are validated. For non-aggregation requests (`raw`, `raw_stream`, `trace`), these fields are ignored.
+
+**Why:** A raw log query doesn't have aggregations, so requiring `aggregations` would be wrong. But a time-series query without aggregations is meaningless. The validation rules are request-type-aware to avoid both false positives and false negatives.
+
+**Consequence:** When adding new fields to query specs, consider which request types they apply to and gate validation accordingly.
+
+---
+
+## The Composite Query Model
+
+### Structure
+
+A `QueryRangeRequest` contains a `CompositeQuery` which holds `[]QueryEnvelope`. Each envelope is a discriminated union: a `Type` field determines how `Spec` is decoded.
+
+### Invariant: Query names are unique within a composite query
+
+Builder queries must have unique names. Formulas reference queries by name (`A`, `B`, `A.0`, `A.my_alias`). Duplicate names would make formula evaluation ambiguous.
+
+### Invariant: Multi-aggregation uses indexed or aliased references
+
+A single builder query can have multiple aggregations. They are accessed in formulas via:
+- Index: `A.0`, `A.1` (zero-based)
+- Alias: `A.total`, `A.error_count`
+
+The default (just `A`) resolves to index 0. This is the formula evaluation contract and must be preserved.
+
+### Invariant: Type-specific decoding through signal detection
+
+Builder queries are decoded by first peeking at the `signal` field in the raw JSON, then unmarshaling into the appropriate generic type (`QueryBuilderQuery[TraceAggregation]`, `QueryBuilderQuery[LogAggregation]`, `QueryBuilderQuery[MetricAggregation]`). This two-pass decoding is intentional — it allows each signal to have its own aggregation schema while sharing the query structure.
+
+---
+
+## The Metadata Layer
+
+### MetadataStore
+
+The `MetadataStore` interface provides runtime field discovery and type resolution. It answers questions like "what fields exist for this signal?" and "what are the data types of field X?".
+
+### Principle: Fields can be ambiguous until resolved
+
+The same name can map to multiple `TelemetryFieldKey` variants (different contexts, different types). The metadata store returns *all* variants. Resolution to a single field happens during query building, using the query's signal and any explicit context/type hints from the user.
+
+**Consequence:** Code that calls `GetKey` or `GetKeys` must handle multiple results. Do not assume a name maps to a single field.
+
+### Principle: Materialized fields are a performance optimization, not a semantic distinction
+
+A materialized field and its non-materialized equivalent represent the same logical field. The `Materialized` flag tells the FieldMapper to generate a simpler column expression. The user should never need to know whether a field is materialized.
+
+### Principle: JSON body fields require access plans
+
+Fields inside JSON body columns (`body.response.errors[].code`) need pre-computed `JSONAccessPlan` trees that encode the traversal path, including branching at array boundaries between `Array(JSON)` and `Array(Dynamic)` representations. These plans are computed during metadata resolution, not during query execution.
+
+---
+
+## Summary of Inviolable Rules
+
+1. **User-facing types never contain ClickHouse column names or SQL fragments.**
+2. **Field-to-column translation only happens in FieldMapper.**
+3. **Normalization happens once at the API boundary, never deeper.**
+4. **Historical aliases in fieldContexts and fieldDataTypes must not be removed.**
+5. **Formula evaluation stays in Go — do not push it into ClickHouse JOINs.**
+6. **Zero-defaulting is aggregation-type-dependent — do not universally default to zero.**
+7. **Positive operators imply existence, negative operators do not.**
+8. **Post-processing functions operate on Go result sets, not in SQL.**
+9. **All user-facing types reject unknown JSON fields with suggestions.**
+10. **Validation rules are gated by request type.**
+11. **Query names must be unique within a composite query.**
+12. **The four-layer abstraction stack (FieldMapper -> ConditionBuilder -> AggExprRewriter -> StatementBuilder) must not be bypassed or flattened.**

frontend/.cursor/rules/state-management.mdc

@@ -1,97 +0,0 @@
----
-globs: **/*.store.ts
-alwaysApply: false
----
-# State Management: React Query, nuqs, Zustand
-
-Use the following stack. Do **not** introduce or recommend Redux or React Context for shared/global state.
-
-## Server state → React Query
-
-- **Use for:** API responses, time-series data, caching, background refetch, retries, stale/refresh.
-- **Do not use Redux/Context** to store or mirror data that comes from React Query (e.g. do not dispatch API results into Redux).
-- Prefer generated React Query hooks from `frontend/src/api/generated` when available.
-- Keep server state in React Query; expose it via hooks that return the query result (and optionally memoized derived values). Do not duplicate it in Redux or Context.
-
-```tsx
-// ✅ GOOD: single source of truth from React Query
-export function useAppStateHook() {
-  const { data, isError } = useQuery(...)
-  const memoizedConfigs = useMemo(() => ({ ... }), [data?.configs])
-  return { configs: memoizedConfigs, isError, ... }
-}
-
-// ❌ BAD: copying React Query result into Redux
-dispatch({ type: UPDATE_LATEST_VERSION, payload: queryResponse.data })
-```
-
-## URL state → nuqs
-
-- **Use for:** shareable state, filters, time range, selected values, pagination, view state that belongs in the URL.
-- **Do not use Redux/Context** for state that should be shareable or reflected in the URL.
-- Use [nuqs](https://nuqs.dev/docs/basic-usage) for typed, type-safe URL search params. Avoid ad-hoc `useSearchParams` encoding/decoding.
-- Keep URL payload small; respect browser URL length limits (e.g. Chrome ~2k chars). Do not put large datasets or sensitive data in query params.
-
-```tsx
-// ✅ GOOD: nuqs for filters / time range / selection
-const [timeRange, setTimeRange] = useQueryState('timeRange', parseAsString.withDefault('1h'))
-const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))
-
-// ❌ BAD: Redux/Context for shareable or URL-synced state
-const { timeRange } = useContext(SomeContext)
-```
-
-## Client state → Zustand
-
-- **Use for:** global/client state, cross-component state, feature flags, complex or large client objects (e.g. dashboard state, query builder state).
-- **Do not use Redux or React Context** for global or feature-level client state.
-- Prefer small, domain-scoped stores (e.g. DashboardStore, QueryBuilderStore).
-
-### Zustand best practices (align with eslint-plugin-zustand-rules)
-
-- **One store per module.** Do not define multiple `create()` calls in the same file; use one store per module (or compose slices into one store).
-- **Always use selectors.** Call the store hook with a selector so only the used slice triggers re-renders. Never use `useStore()` with no selector.
-
-```tsx
-// ✅ GOOD: selector — re-renders only when isDashboardLocked changes
-const isLocked = useDashboardStore(state => state.isDashboardLocked)
-
-// ❌ BAD: no selector — re-renders on any store change
-const state = useDashboardStore()
-```
-
-- **Never mutate state directly.** Update only via `set` or `setState` (or `getState()` + `set` for reads). No `state.foo = x` or `state.bears += 1` inside actions.
-
-```tsx
-// ✅ GOOD: use set
-increment: () => set(state => ({ bears: state.bears + 1 }))
-
-// ❌ BAD: direct mutation
-increment: () => { state.bears += 1 }
-```
-
-- **State properties before actions.** In the store object, list all state fields first, then action functions.
-- **Split into slices when state is large.** If a store has many top-level properties (e.g. more than 5–10), split into slice factories and combine with one `create()`.
-
-```tsx
-// ✅ GOOD: slices for large state
-const createBearSlice = set => ({ bears: 0, addBear: () => set(s => ({ bears: s.bears + 1 })) })
-const createFishSlice = set => ({ fish: 0, addFish: () => set(s => ({ fish: s.fish + 1 })) })
-const useStore = create(set => ({ ...createBearSlice(set), ...createFishSlice(set) }))
-```
-
-- **In projects using Zustand:** add `eslint-plugin-zustand-rules` and extend `plugin:zustand-rules/recommended` to enforce these rules automatically.
-
-## Local state → React state only
-
-- **Use useState/useReducer** for: component-local UI state, form inputs, toggles, hover state, data that never leaves the component.
-- Do not use Zustand, Redux, or Context for state that is purely local to one component or a small subtree.
-
-## Summary
-
-| State type        | Use              | Avoid              |
-|-------------------|------------------|--------------------|
-| Server / API      | React Query      | Redux, Context     |
-| URL / shareable   | nuqs             | Redux, Context     |
-| Global client     | Zustand          | Redux, Context     |
-| Local UI          | useState/useReducer | Zustand, Redux, Context |

frontend/.cursor/skills/migrate-state-management/SKILL.md

@@ -1,150 +0,0 @@
----
-name: migrate-state-management
-description: Migrate Redux or React Context to the correct state option (React Query for server state, nuqs for URL/shareable state, Zustand for global client state). Use when refactoring away from Redux/Context, moving state to the right store, or when the user asks to migrate state management.
----
-
-# Migrate State: Redux/Context → React Query, nuqs, Zustand
-
-Do **not** introduce or recommend Redux or React Context. Migrate existing usage to the stack below.
-
-## 1. Classify the state
-
-Before changing code, classify what the state represents:
-
-| If the state is… | Migrate to | Do not use |
-|------------------|------------|------------|
-| From API / server (versions, configs, fetched lists, time-series) | **React Query** | Redux, Context |
-| Shareable via URL (filters, time range, page, selected ids) | **nuqs** | Redux, Context |
-| Global/client UI (dashboard lock, query builder, feature flags, large client objects) | **Zustand** | Redux, Context |
-| Local to one component (inputs, toggles, hover) | **useState / useReducer** | Zustand, Redux, Context |
-
-If one slice mixes concerns (e.g. Redux has both API data and pagination), split: API → React Query, pagination → nuqs, rest → Zustand or local state.
-
-## 2. Migrate to React Query (server state)
-
-**When:** State comes from or mirrors an API response (e.g. `currentVersion`, `latestVersion`, `configs`, lists).
-
-**Steps:**
-
-1. Find where the data is fetched (existing `useQuery`/API call) and where it is dispatched or set in Context/Redux.
-2. Remove the dispatch/set that writes API results into Redux/Context.
-3. Expose a single hook that uses the query and returns the same shape consumers expect (use `useMemo` for derived objects like `configs` to avoid unnecessary re-renders).
-4. Replace Redux/Context consumption with the new hook. Prefer generated React Query hooks from `frontend/src/api/generated` when available.
-5. Configure cache/refetch (e.g. `refetchOnMount: false`, `staleTime`) so behavior matches previous “single source” expectations.
-
-**Before (Redux mirroring React Query):**
-
-```tsx
-if (getUserLatestVersionResponse.isFetched && getUserLatestVersionResponse.isSuccess && getUserLatestVersionResponse.data?.payload) {
-  dispatch({ type: UPDATE_LATEST_VERSION, payload: { latestVersion: getUserLatestVersionResponse.data.payload.tag_name } })
-}
-```
-
-**After (single source in React Query):**
-
-```tsx
-export function useAppStateHook() {
-  const { data, isError } = useQuery(...)
-  const memoizedConfigs = useMemo(() => ({ ... }), [data?.configs])
-  return {
-    latestVersion: data?.payload?.tag_name,
-    configs: memoizedConfigs,
-    isError,
-  }
-}
-```
-
-Consumers use `useAppStateHook()` instead of `useSelector` or Context. Do not copy React Query result into Redux or Context.
-
-## 3. Migrate to nuqs (URL / shareable state)
-
-**When:** State should be in the URL: filters, time range, pagination, selected values, view state. Keep payload small (e.g. Chrome ~2k chars); no large datasets or sensitive data.
-
-**Steps:**
-
-1. Identify which Redux/Context fields are shareable or already reflected in the URL (e.g. `currentPage`, `timeRange`, `selectedFilter`).
-2. Add nuqs (or use existing): `useQueryState('param', parseAsString.withDefault('…'))` (or `parseAsInteger`, etc.).
-3. Replace reads/writes of those fields with nuqs hooks. Use typed parsers; avoid ad-hoc `useSearchParams` encoding/decoding.
-4. Remove the same fields from Redux/Context and their reducers/providers.
-
-**Before (Context/Redux):**
-
-```tsx
-const { timeRange } = useContext(SomeContext)
-const [page, setPage] = useDispatch(...)
-```
-
-**After (nuqs):**
-
-```tsx
-const [timeRange, setTimeRange] = useQueryState('timeRange', parseAsString.withDefault('1h'))
-const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))
-```
-
-## 4. Migrate to Zustand (global client state)
-
-**When:** State is global or cross-component client state: feature flags, dashboard state, query builder state, complex/large client objects (e.g. up to ~1.5–2MB). Not for server cache or local-only UI.
-
-**Steps:**
-
-1. Create one store per domain (e.g. `DashboardStore`, `QueryBuilderStore`). One `create()` per module; for large state use slice factories and combine.
-2. Put state properties first, then actions. Use `set` (or `setState` / `getState()` + `set`) for updates; never mutate state directly.
-3. Replace Context/Redux consumption with the store hook **and a selector** so only the used slice triggers re-renders.
-4. Remove the old Context provider / Redux slice and related dispatches.
-
-**Selector (required):**
-
-```tsx
-const isLocked = useDashboardStore(state => state.isDashboardLocked)
-```
-
-Never use `useStore()` with no selector. Never do `state.foo = x` inside actions; use `set(state => ({ ... }))`.
-
-**Before (Context/Redux):**
-
-```tsx
-const { isDashboardLocked, setLocked } = useContext(DashboardContext)
-```
-
-**After (Zustand):**
-
-```tsx
-const isLocked = useDashboardStore(state => state.isDashboardLocked)
-const setLocked = useDashboardStore(state => state.setLocked)
-```
-
-For large stores (many top-level fields), split into slices and combine:
-
-```tsx
-const createBearSlice = set => ({ bears: 0, addBear: () => set(s => ({ bears: s.bears + 1 })) })
-const useStore = create(set => ({ ...createBearSlice(set), ...createFishSlice(set) }))
-```
-
-Add `eslint-plugin-zustand-rules` with `plugin:zustand-rules/recommended` to enforce selectors and no direct mutation.
-
-## 5. Migrate to local state (useState / useReducer)
-
-**When:** State is used only inside one component or a small subtree (form inputs, toggles, hover, panel selection). No URL sync, no cross-feature sharing.
-
-**Steps:**
-
-1. Move the state into the component that owns it (or the smallest common parent).
-2. Use `useState` or `useReducer` (useReducer when multiple related fields change together).
-3. Remove from Redux/Context and any provider/slice.
-
-Do not use Zustand, Redux, or Context for purely local UI state.
-
-## 6. Migration checklist
-
-- [ ] Classify each piece of state (server / URL / global client / local).
-- [ ] Server state: move to React Query; expose via hook; remove Redux/Context mirroring.
-- [ ] URL state: move to nuqs; remove from Redux/Context; keep URL payload small.
-- [ ] Global client state: move to Zustand with selectors and immutable updates; one store per domain.
-- [ ] Local state: move to useState/useReducer in the owning component.
-- [ ] Remove old Redux slices / Context providers and all dispatches/consumers for migrated state.
-- [ ] Do not duplicate the same data in multiple places (e.g. React Query + Redux).
-
-## Additional resources
-
-- Project rule: [.cursor/rules/state-management.mdc](../../rules/state-management.mdc)
-- Detailed patterns and rationale: [reference.md](reference.md)

frontend/.cursor/skills/migrate-state-management/reference.md

@@ -1,50 +0,0 @@
-# State migration reference
-
-## Why migrate
-
-- **Context:** Re-renders all consumers on any change; no granular subscriptions; becomes brittle at scale.
-- **Redux:** Heavy boilerplate (actions, reducers, selectors, Provider); slower onboarding; often used to mirror React Query or URL state.
-- **Goal:** Fewer mechanisms, domain isolation, granular subscriptions, single source of truth per state type.
-
-## React Query migration (server state)
-
-Typical anti-pattern: API is called via React Query, then result is dispatched to Redux. Flow becomes: Component → useQueries → API → dispatch → Reducer → Redux state → useSelector.
-
-Correct flow: Component → useQuery (or custom hook wrapping it) → same component reads from hook. No Redux/Context in between.
-
-- Prefer generated hooks from `frontend/src/api/generated`.
-- For “app state” that is just API data (versions, configs), one hook that returns `{ ...data, configs: useMemo(...) }` is enough. No selectors needed for plain data; useMemo only where the value is used as dependency (e.g. in useState).
-- Set `staleTime` / `refetchOnMount` etc. so refetch behavior matches previous expectations.
-
-## nuqs migration (URL state)
-
-Redux/Context often hold pagination, filters, time range, selected values that are shareable. Those belong in the URL.
-
-- Use [nuqs](https://nuqs.dev/docs/basic-usage) for typed search params. Avoid ad-hoc `useSearchParams` + manual encoding.
-- Browser limits: Chrome ~2k chars practical; keep payload small; no large datasets or secrets in query params.
-- If the app uses TanStack Router, search params can be handled there; otherwise nuqs is the standard.
-
-## Zustand migration (client state)
-
-- One store per domain (e.g. DashboardStore, QueryBuilderStore). Multiple `create()` in one file is disallowed; use one store or composed slices.
-- Always use a selector: `useStore(s => s.field)` so only that field drives re-renders.
-- Never mutate: update only via `set(state => ({ ... }))` or `setState` / `getState()` + `set`.
-- State properties first, then actions. For 5–10+ top-level fields, split into slice factories and combine with one `create()`.
-- Large client objects: Zustand is for “large” in the ~1.5–2MB range; above that, optimize at API/store design.
-- Testing: no Provider; stores are plain functions; easy to reset and mock.
-
-## What not to use
-
-- **Redux / Context** for new or migrated shared/global state.
-- **Redux / Context** to store or mirror React Query results.
-- **Redux / Context** for state that should live in the URL (use nuqs).
-- **Zustand / Redux / Context** for component-local UI (use useState/useReducer).
-
-## Summary table
-
-| State type   | Use                | Avoid           |
-|-------------|--------------------|-----------------|
-| Server/API  | React Query        | Redux, Context  |
-| URL/shareable | nuqs             | Redux, Context  |
-| Global client | Zustand          | Redux, Context  |
-| Local UI    | useState/useReducer | Zustand, Redux, Context |

pkg/signoz/provider.go

@@ -169,6 +169,7 @@ func NewSQLMigrationProviderFactories(
 		sqlmigration.NewAddAnonymousPublicDashboardTransactionFactory(sqlstore),
 		sqlmigration.NewAddRootUserFactory(sqlstore, sqlschema),
 		sqlmigration.NewAddUserEmailOrgIDIndexFactory(sqlstore, sqlschema),
+		sqlmigration.NewMigrateRulesV4ToV5Factory(sqlstore, telemetryStore),
 	)
 }
 

pkg/sqlmigration/066_migrate_rules_v4_to_v5_post_deprecation.go

@@ -0,0 +1,209 @@
+package sqlmigration
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"log/slog"
+
+	"github.com/SigNoz/signoz/pkg/factory"
+	"github.com/SigNoz/signoz/pkg/sqlstore"
+	"github.com/SigNoz/signoz/pkg/telemetrystore"
+	"github.com/SigNoz/signoz/pkg/transition"
+	"github.com/uptrace/bun"
+	"github.com/uptrace/bun/migrate"
+)
+
+type migrateRulesV4ToV5 struct {
+	store          sqlstore.SQLStore
+	telemetryStore telemetrystore.TelemetryStore
+	logger         *slog.Logger
+}
+
+func NewMigrateRulesV4ToV5Factory(
+	store sqlstore.SQLStore,
+	telemetryStore telemetrystore.TelemetryStore,
+) factory.ProviderFactory[SQLMigration, Config] {
+	return factory.NewProviderFactory(
+		factory.MustNewName("migrate_rules_post_deprecation"),
+		func(ctx context.Context, ps factory.ProviderSettings, c Config) (SQLMigration, error) {
+			return &migrateRulesV4ToV5{
+				store:          store,
+				telemetryStore: telemetryStore,
+				logger:         ps.Logger,
+			}, nil
+		})
+}
+
+func (migration *migrateRulesV4ToV5) Register(migrations *migrate.Migrations) error {
+	if err := migrations.Register(migration.Up, migration.Down); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (migration *migrateRulesV4ToV5) getLogDuplicateKeys(ctx context.Context) ([]string, error) {
+	query := `
+		SELECT name
+		FROM (
+			SELECT DISTINCT name FROM signoz_logs.distributed_logs_attribute_keys
+			INTERSECT
+			SELECT DISTINCT name FROM signoz_logs.distributed_logs_resource_keys
+		)
+		ORDER BY name
+	`
+
+	rows, err := migration.telemetryStore.ClickhouseDB().Query(ctx, query)
+	if err != nil {
+		migration.logger.WarnContext(ctx, "failed to query log duplicate keys", "error", err)
+		return nil, nil
+	}
+	defer rows.Close()
+
+	var keys []string
+	for rows.Next() {
+		var key string
+		if err := rows.Scan(&key); err != nil {
+			migration.logger.WarnContext(ctx, "failed to scan log duplicate key", "error", err)
+			continue
+		}
+		keys = append(keys, key)
+	}
+
+	return keys, nil
+}
+
+func (migration *migrateRulesV4ToV5) getTraceDuplicateKeys(ctx context.Context) ([]string, error) {
+	query := `
+		SELECT tagKey
+		FROM signoz_traces.distributed_span_attributes_keys
+		WHERE tagType IN ('tag', 'resource')
+		GROUP BY tagKey
+		HAVING COUNT(DISTINCT tagType) > 1
+		ORDER BY tagKey
+	`
+
+	rows, err := migration.telemetryStore.ClickhouseDB().Query(ctx, query)
+	if err != nil {
+		migration.logger.WarnContext(ctx, "failed to query trace duplicate keys", "error", err)
+		return nil, nil
+	}
+	defer rows.Close()
+
+	var keys []string
+	for rows.Next() {
+		var key string
+		if err := rows.Scan(&key); err != nil {
+			migration.logger.WarnContext(ctx, "failed to scan trace duplicate key", "error", err)
+			continue
+		}
+		keys = append(keys, key)
+	}
+
+	return keys, nil
+}
+
+func (migration *migrateRulesV4ToV5) Up(ctx context.Context, db *bun.DB) error {
+	logsKeys, err := migration.getLogDuplicateKeys(ctx)
+	if err != nil {
+		return err
+	}
+
+	tracesKeys, err := migration.getTraceDuplicateKeys(ctx)
+	if err != nil {
+		return err
+	}
+
+	tx, err := db.BeginTx(ctx, nil)
+	if err != nil {
+		return err
+	}
+
+	defer func() {
+		_ = tx.Rollback()
+	}()
+
+	var rules []struct {
+		ID   string         `bun:"id"`
+		Data map[string]any `bun:"data"`
+	}
+
+	err = tx.NewSelect().
+		Table("rule").
+		Column("id", "data").
+		Scan(ctx, &rules)
+	if err != nil {
+		if err == sql.ErrNoRows {
+			return nil
+		}
+		return err
+	}
+
+	alertsMigrator := transition.NewAlertMigrateV5(migration.logger, logsKeys, tracesKeys)
+
+	count := 0
+
+	for _, rule := range rules {
+		version, _ := rule.Data["version"].(string)
+
+		if version == "v5" {
+			continue
+		}
+
+		if version == "" {
+			migration.logger.WarnContext(ctx, "unexpected empty version for rule", "rule_id", rule.ID)
+		}
+
+		migration.logger.InfoContext(ctx, "migrating rule v4 to v5", "rule_id", rule.ID, "current_version", version)
+
+		// Check if the queries envelope already exists and is non-empty
+		hasQueriesEnvelope := false
+		if condition, ok := rule.Data["condition"].(map[string]any); ok {
+			if compositeQuery, ok := condition["compositeQuery"].(map[string]any); ok {
+				if queries, ok := compositeQuery["queries"].([]any); ok && len(queries) > 0 {
+					hasQueriesEnvelope = true
+				}
+			}
+		}
+
+		if hasQueriesEnvelope {
+			// already has queries envelope, just bump version
+			// this is because user made a mistake of choosing version
+			migration.logger.InfoContext(ctx, "rule already has queries envelope, bumping version", "rule_id", rule.ID)
+			rule.Data["version"] = "v5"
+		} else {
+			// old format, run full migration
+			migration.logger.InfoContext(ctx, "rule has old format, running full migration", "rule_id", rule.ID)
+			updated := alertsMigrator.Migrate(ctx, rule.Data)
+			if !updated {
+				migration.logger.WarnContext(ctx, "expected updated to be true but got false", "rule_id", rule.ID)
+				continue
+			}
+			rule.Data["version"] = "v5"
+		}
+
+		dataJSON, err := json.Marshal(rule.Data)
+		if err != nil {
+			return err
+		}
+
+		_, err = tx.NewUpdate().
+			Table("rule").
+			Set("data = ?", string(dataJSON)).
+			Where("id = ?", rule.ID).
+			Exec(ctx)
+		if err != nil {
+			return err
+		}
+		count++
+	}
+	if count != 0 {
+		migration.logger.InfoContext(ctx, "migrate v4 alerts", "count", count)
+	}
+
+	return tx.Commit()
+}
+
+func (migration *migrateRulesV4ToV5) Down(ctx context.Context, db *bun.DB) error {
+	return nil
+}

pkg/types/ruletypes/api_params.go

@@ -355,6 +355,10 @@ func (r *PostableRule) validate() error {
 		errs = append(errs, signozError.NewInvalidInputf(signozError.CodeInvalidInput, "composite query is required"))
 	}
 
+	if r.Version != "v5" {
+		errs = append(errs, signozError.NewInvalidInputf(signozError.CodeInvalidInput, "only version v5 is supported, got %q", r.Version))
+	}
+
 	if isAllQueriesDisabled(r.RuleCondition.CompositeQuery) {
 		errs = append(errs, signozError.NewInvalidInputf(signozError.CodeInvalidInput, "all queries are disabled in rule condition"))
 	}

pkg/types/ruletypes/api_params_test.go

@@ -108,6 +108,7 @@ func TestParseIntoRule(t *testing.T) {
 				"ruleType": "threshold_rule",
 				"evalWindow": "5m",
 				"frequency": "1m",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "builder",
@@ -150,6 +151,7 @@ func TestParseIntoRule(t *testing.T) {
 			content: []byte(`{
 				"alert": "DefaultsRule",
 				"ruleType": "threshold_rule",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "builder",
@@ -187,6 +189,7 @@ func TestParseIntoRule(t *testing.T) {
 			initRule: PostableRule{},
 			content: []byte(`{
 				"alert": "PromQLRule",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "promql",
@@ -256,6 +259,7 @@ func TestParseIntoRuleSchemaVersioning(t *testing.T) {
 			content: []byte(`{
 				"alert": "SeverityLabelTest",
 				"schemaVersion": "v1",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "builder",
@@ -344,6 +348,7 @@ func TestParseIntoRuleSchemaVersioning(t *testing.T) {
 			content: []byte(`{
 				"alert": "NoLabelsTest",
 				"schemaVersion": "v1",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "builder",
@@ -384,6 +389,7 @@ func TestParseIntoRuleSchemaVersioning(t *testing.T) {
 			content: []byte(`{
 				"alert": "OverwriteTest",
 				"schemaVersion": "v1",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "builder",
@@ -474,6 +480,7 @@ func TestParseIntoRuleSchemaVersioning(t *testing.T) {
 			content: []byte(`{
 				"alert": "V2Test",
 				"schemaVersion": "v2",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "builder",
@@ -517,6 +524,7 @@ func TestParseIntoRuleSchemaVersioning(t *testing.T) {
 			initRule: PostableRule{},
 			content: []byte(`{
 				"alert": "DefaultSchemaTest",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "builder",
@@ -569,6 +577,7 @@ func TestParseIntoRuleSchemaVersioning(t *testing.T) {
 func TestParseIntoRuleThresholdGeneration(t *testing.T) {
 	content := []byte(`{
 		"alert": "TestThresholds",
+		"version": "v5",
 		"condition": {
 			"compositeQuery": {
 				"queryType": "builder",
@@ -639,6 +648,7 @@ func TestParseIntoRuleMultipleThresholds(t *testing.T) {
 		"schemaVersion": "v2",
 		"alert": "MultiThresholdAlert",
 		"ruleType": "threshold_rule",
+		"version": "v5",
 		"condition": {
 			"compositeQuery": {
 				"queryType": "builder",
@@ -732,6 +742,7 @@ func TestAnomalyNegationEval(t *testing.T) {
 			ruleJSON: []byte(`{
 				"alert": "AnomalyBelowTest",
 				"ruleType": "anomaly_rule",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "builder",
@@ -766,6 +777,7 @@ func TestAnomalyNegationEval(t *testing.T) {
 			ruleJSON: []byte(`{
 				"alert": "AnomalyBelowTest",
 				"ruleType": "anomaly_rule",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "builder",
@@ -799,6 +811,7 @@ func TestAnomalyNegationEval(t *testing.T) {
 			ruleJSON: []byte(`{
 				"alert": "AnomalyAboveTest",
 				"ruleType": "anomaly_rule",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "builder",
@@ -833,6 +846,7 @@ func TestAnomalyNegationEval(t *testing.T) {
 			ruleJSON: []byte(`{
 				"alert": "AnomalyAboveTest",
 				"ruleType": "anomaly_rule",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "builder",
@@ -866,6 +880,7 @@ func TestAnomalyNegationEval(t *testing.T) {
 			ruleJSON: []byte(`{
 				"alert": "AnomalyBelowAllTest",
 				"ruleType": "anomaly_rule",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "builder",
@@ -901,6 +916,7 @@ func TestAnomalyNegationEval(t *testing.T) {
 			ruleJSON: []byte(`{
 				"alert": "AnomalyBelowAllTest",
 				"ruleType": "anomaly_rule",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "builder",
@@ -935,6 +951,7 @@ func TestAnomalyNegationEval(t *testing.T) {
 			ruleJSON: []byte(`{
 				"alert": "AnomalyOutOfBoundsTest",
 				"ruleType": "anomaly_rule",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "builder",
@@ -969,6 +986,7 @@ func TestAnomalyNegationEval(t *testing.T) {
 			ruleJSON: []byte(`{
 				"alert": "ThresholdTest",
 				"ruleType": "threshold_rule",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "builder",
@@ -1003,6 +1021,7 @@ func TestAnomalyNegationEval(t *testing.T) {
 			ruleJSON: []byte(`{
 				"alert": "ThresholdTest",
 				"ruleType": "threshold_rule",
+				"version": "v5",
 				"condition": {
 					"compositeQuery": {
 						"queryType": "builder",