refactor(qb): quote field names with the ClickHouse quoting helpers

Every plain field-name literal and identifier in the statement-builder
layer now goes through querybuilder.ClickHouseStringLiteral and
querybuilder.ClickHouseIdentifier: map reads, mapContains, JSON
subcolumn paths, JSONExtractString and JSONExtractKeys on labels,
simpleJSONExtractString and simpleJSONHas on the fingerprint labels,
and the column aliases.

The helpers escape backslashes, quotes, and backticks, so a field name
that contains a quote or a backtick can no longer break out of its
literal or identifier. For every other name the output is byte
identical, and the full test suite passes unchanged.

Out of scope, on purpose: LIKE index-hint fragments and body JSON path
builders (they have pattern and path semantics, not plain literals),
and the materialized-column name builders in telemetrytypes (importing
querybuilder there is an import cycle).

Assisted-by: Claude Fable 5

frontend/package.json

@@ -197,7 +197,7 @@
     "oxfmt": "0.54.0",
     "oxlint": "1.69.0",
     "oxlint-tsgolint": "0.23.0",
-    "postcss": "8.5.14",
+    "postcss": "8.5.26",
     "postcss-scss": "4.0.9",
     "react-resizable": "3.0.4",
     "redux-mock-store": "1.5.4",

frontend/pnpm-lock.yaml

@@ -6,12 +6,19 @@ settings:
 
 overrides:
   '@babel/core@<=7.29.0': '>=7.29.6 <8'
-  '@istanbuljs/load-nyc-config>js-yaml': '>=4.2.0 <5'
+  '@istanbuljs/load-nyc-config>js-yaml': '>=4.3.1 <5'
+  brace-expansion@<1.1.18: '>=1.1.18 <2'
+  brace-expansion@>=2.0.0 <2.1.4: '>=2.1.4 <3'
+  brace-expansion@>=5.0.0 <5.0.9: '>=5.0.9 <6'
   cookie@<0.7.0: '>=0.7.1 <1'
   dompurify@<=3.4.10: '>=3.4.11 <4'
   esbuild@>=0.27.3 <0.28.1: '>=0.28.1 <0.29.0'
+  fast-uri@<3.1.5: '>=3.1.5 <4'
+  immutable@<5.1.8: '>=5.1.8 <6'
   js-cookie@<=3.0.5: '>=3.0.7 <4'
-  js-yaml@>=4.0.0 <=4.1.1: '>=4.2.0 <5'
+  js-yaml@>=4.0.0 <4.3.1: '>=4.3.1 <5'
+  less@<4.5.0: '>=4.5.0 <5'
+  nanoid@<3.3.18: '>=3.3.18 <4'
   prismjs@<1.30.0: '>=1.30.0 <2'
   react-router@>=6.7.0 <6.30.4: '>=6.30.4 <7'
   tmp@<0.2.6: '>=0.2.6 <0.3.0'
@@ -98,7 +105,7 @@ importers:
         version: 3.3.0(react-dom@18.2.0(react@18.2.0))(react@18.2.0)
       '@vitejs/plugin-react':
         specifier: 5.1.4
-        version: 5.1.4(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))
+        version: 5.1.4(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))
       ansi-to-html:
         specifier: 0.7.2
         version: 0.7.2
@@ -311,10 +318,10 @@ importers:
         version: 14.0.1
       vite:
         specifier: npm:rolldown-vite@7.3.1
-        version: rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)
+        version: rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)
       vite-plugin-html:
         specifier: 3.2.2
-        version: 3.2.2(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))
+        version: 3.2.2(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))
       zod:
         specifier: 4.3.6
         version: 4.3.6
@@ -467,11 +474,11 @@ importers:
         specifier: 0.23.0
         version: 0.23.0
       postcss:
-        specifier: 8.5.14
-        version: 8.5.14
+        specifier: 8.5.26
+        version: 8.5.26
       postcss-scss:
         specifier: 4.0.9
-        version: 4.0.9(postcss@8.5.14)
+        version: 4.0.9(postcss@8.5.26)
       react-resizable:
         specifier: 3.0.4
         version: 3.0.4(react-dom@18.2.0(react@18.2.0))(react@18.2.0)
@@ -501,16 +508,16 @@ importers:
         version: 1.6.0(react@18.2.0)
       vite-plugin-checker:
         specifier: 0.12.0
-        version: 0.12.0(eslint@10.2.1(jiti@2.6.1))(meow@13.2.0)(optionator@0.9.4)(oxlint@1.69.0(oxlint-tsgolint@0.23.0))(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))(stylelint@17.7.0(typescript@5.9.3))(typescript@5.9.3)
+        version: 0.12.0(eslint@10.2.1(jiti@2.6.1))(meow@13.2.0)(optionator@0.9.4)(oxlint@1.69.0(oxlint-tsgolint@0.23.0))(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))(stylelint@17.7.0(typescript@5.9.3))(typescript@5.9.3)
       vite-plugin-compression:
         specifier: 0.5.1
-        version: 0.5.1(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))
+        version: 0.5.1(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))
       vite-plugin-image-optimizer:
         specifier: 2.0.3
-        version: 2.0.3(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))(sharp@0.35.0)(svgo@4.0.2)
+        version: 2.0.3(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))(sharp@0.35.0)(svgo@4.0.2)
       vite-tsconfig-paths:
         specifier: 6.1.1
-        version: 6.1.1(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))(typescript@5.9.3)
+        version: 6.1.1(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))(typescript@5.9.3)
 
 packages:
 
@@ -4159,15 +4166,15 @@ packages:
   boolbase@1.0.0:
     resolution: {integrity: sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==}
 
-  brace-expansion@1.1.15:
-    resolution: {integrity: sha512-EwOCDEex4quD37XhqM3omwtMoJjr//isUZz1JopUNWms+4Z2ViyM/k1YIRePpoVNnQhENnxtFjLaxNHrT7xIUg==}
+  brace-expansion@1.1.18:
+    resolution: {integrity: sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==}
 
-  brace-expansion@2.1.1:
-    resolution: {integrity: sha512-WR1cURNjuvBLMZBMbqM0UoE+WAfdUcEV1ccD8PVBVOI+Z3ND4+SZbN8RsfT2bMuG1qwz5RFvPukSZm5fF2D5eA==}
+  brace-expansion@2.1.4:
+    resolution: {integrity: sha512-hGfVzPxthbf3+2yjg/RBs60cB0FhqBS/zvdV/4wn4/BmN0bNMMHPc4V/BbFieqf1TKAGGAHnY4eSjajCl0f2Xg==}
 
-  brace-expansion@5.0.7:
-    resolution: {integrity: sha512-7oFy703dxfY3/NLxC1fh2SUCQ0H9rmAY+5EpDVfXjUTTs+HEwR2nYaqLv+GWcTsumwxPfiz6CzCNkwXwBUwqCA==}
-    engines: {node: 18 || 20 || >=22}
+  brace-expansion@5.0.9:
+    resolution: {integrity: sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==}
+    engines: {node: 20 || >=22}
 
   braces@3.0.3:
     resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==}
@@ -4459,8 +4466,9 @@ packages:
     resolution: {integrity: sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==}
     engines: {node: '>= 0.6'}
 
-  copy-anything@2.0.6:
-    resolution: {integrity: sha512-1j20GZTsvKNkc4BY3NpMOM8tt///wY3FpIzozTOFO2ffuZcV61nojHXVKIy3WM+7ADCy5FVhdZYHYDdgTU0yJw==}
+  copy-anything@3.0.5:
+    resolution: {integrity: sha512-yCEafptTtb4bk7GLEQoM8KVJpxAfdBJYaXyzQEgQQQgYrZiDp8SJmGKlYza6CYjEDNstAdNdKA3UuoULlEbS6w==}
+    engines: {node: '>=12.13'}
 
   copy-text-to-clipboard@3.2.2:
     resolution: {integrity: sha512-T6SqyLd1iLuqPA90J5N4cTalrtovCySh58iiZDGJ6FGznbclKh4UI+FGacQSgFzwKG77W7XT5gwbVEbd9cIH1A==}
@@ -4707,6 +4715,14 @@ packages:
   debounce@1.2.1:
     resolution: {integrity: sha512-XRRe6Glud4rd/ZGQfiV1ruXSfbvfJedlV9Y6zOlP+2K04vBYiJEte6stfFkCP03aMnY5tsipamumUjL14fofug==}
 
+  debug@2.6.9:
+    resolution: {integrity: sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
   debug@3.2.7:
     resolution: {integrity: sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ==}
     peerDependencies:
@@ -5100,8 +5116,8 @@ packages:
   fast-shallow-equal@1.0.0:
     resolution: {integrity: sha512-HPtaa38cPgWvaCFmRNhlc6NG7pv6NUHqjPgVAkWGoB9mQMwYB27/K0CvOM5Czy+qpT3e8XJ6Q4aPAnzpNpzNaw==}
 
-  fast-uri@3.1.2:
-    resolution: {integrity: sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ==}
+  fast-uri@3.1.5:
+    resolution: {integrity: sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw==}
 
   fast_array_intersect@1.1.0:
     resolution: {integrity: sha512-/DCilZlUdz2XyNDF+ASs0PwY+RKG9Y4Silp/gbS72Cvbg4oibc778xcecg+pnNyiNHYgh/TApsiDTjpdniyShw==}
@@ -5556,19 +5572,14 @@ packages:
     resolution: {integrity: sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==}
     engines: {node: '>= 4'}
 
-  image-size@0.5.5:
-    resolution: {integrity: sha512-6TDAlDPZxUFCv+fuOkIoXT/V/f3Qbq8e37p+YOiYrUv3v9cc3/6x78VdfPgFVaB9dZYeLUfKgHRebpkm/oP2VQ==}
-    engines: {node: '>=0.10.0'}
-    hasBin: true
-
   immediate@3.0.6:
     resolution: {integrity: sha512-XXOFtyqDjNDAQxVfYxuF7g9Il/IbWmmlQg2MYKOH8ExIT1qg6xc4zyS3HaEEATgs1btfzxq15ciUiY7gjSXRGQ==}
 
   immer@11.1.3:
     resolution: {integrity: sha512-6jQTc5z0KJFtr1UgFpIL3N9XSC3saRaI9PwWtzM2pSqkNGtiNkYY2OSwkOGDK2XcTRcLb1pi/aNkKZz0nxVH4Q==}
 
-  immutable@5.1.5:
-    resolution: {integrity: sha512-t7xcm2siw+hlUM68I+UEOK+z84RzmN59as9DZ7P1l0994DKUWV7UXBMQZVxaoMSRQ+PBZbHCOoBt7a2wxOMt+A==}
+  immutable@5.1.9:
+    resolution: {integrity: sha512-m8nVez3rwrgmWxtLMt1ZYXB2Lv7OKYn/disyxAlSDYAlKSlFoPPfIAmAM/M5xqL4m4C/wAPw7S2/CNaUii1Hxg==}
 
   import-fresh@3.3.1:
     resolution: {integrity: sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ==}
@@ -5811,8 +5822,9 @@ packages:
     resolution: {integrity: sha512-mfcwb6IzQyOKTs84CQMrOwW4gQcaTOAWJ0zzJCl2WSPDrWk/OzDaImWFH3djXhb24g4eudZfLRozAvPGw4d9hQ==}
     engines: {node: '>= 0.4'}
 
-  is-what@3.14.1:
-    resolution: {integrity: sha512-sNxgpk9793nzSs7bA6JQJGeIuRBQhAaNGG77kzYQgMkrID+lS6SlK07K5LaptscDlSaIgH+GPFzf+d75FVxozA==}
+  is-what@4.1.16:
+    resolution: {integrity: sha512-ZhMwEosbFJkA0YhFnNDgTM4ZxDRsS6HqTo7qsZM08fehyRYIYa0yHu5R6mgo1n/8MgaPBXiPimPD77baVFYg+A==}
+    engines: {node: '>=12.13'}
 
   is-wsl@3.1.1:
     resolution: {integrity: sha512-e6rvdUCiQCAuumZslxRJWR/Doq4VpPR82kqclvcS0efgt430SlGIk05vdCN58+VrzgtIcfNODjozVielycD4Sw==}
@@ -6089,8 +6101,8 @@ packages:
   js-tokens@4.0.0:
     resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
 
-  js-yaml@4.3.0:
-    resolution: {integrity: sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==}
+  js-yaml@4.3.1:
+    resolution: {integrity: sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==}
     hasBin: true
 
   jsdom@20.0.3:
@@ -6173,9 +6185,9 @@ packages:
   lerc@3.0.0:
     resolution: {integrity: sha512-Rm4J/WaHhRa93nCN2mwWDZFoRVF18G1f47C+kvQWyHGEZxFpTUi73p7lMVSAndyxGt6lJ2/CFbOcf9ra5p8aww==}
 
-  less@4.4.0:
-    resolution: {integrity: sha512-kdTwsyRuncDfjEs0DlRILWNvxhDG/Zij4YLO4TMJgDLW+8OzpfkdPnRgrsRuY1o+oaxJGWsps5f/RVBgGmmN0w==}
-    engines: {node: '>=14'}
+  less@4.9.0:
+    resolution: {integrity: sha512-umRhrCH7fCi8Uj2RcwKjJdvUORTjeWqkdKx0LbcZvjIwsAVsnIAGcxHaqowPeBFBjQuWOeC/bve0AlpFzF/+SQ==}
+    engines: {node: '>=18'}
     hasBin: true
 
   leven@3.1.0:
@@ -6364,14 +6376,14 @@ packages:
     resolution: {integrity: sha512-ISQTe55T2ao7XtlAStud6qwYPZjE4GK1S/BeVPus4jrq6JuOnQ00YKQC581RWhR122W7msZV263KzVeLoqidyQ==}
     engines: {node: '>=12'}
 
-  make-dir@2.1.0:
-    resolution: {integrity: sha512-LS9X+dc8KLxXCb8dni79fLIIUA5VyZoyjSMCwTluaXA0o27cCK0bhXkpgw+sTXVpPy/lSO57ilRixqk0vDmtRA==}
-    engines: {node: '>=6'}
-
   make-dir@3.1.0:
     resolution: {integrity: sha512-g3FeP20LNwhALb/6Cz6Dd4F2ngze0jz7tbzrD2wAV+o9FeNHe4rL+yK2md0J/fiSf1sa1ADhXqi5+oVwOM/eGw==}
     engines: {node: '>=8'}
 
+  make-dir@5.1.0:
+    resolution: {integrity: sha512-IfpFq6UM39dUNiphpA6uDezNx/AvWyhwfICWPR3t1VspkgkMZrL+Rk1RbN1bx+aeNYwOrqGJgEgV3yotk+ZUVw==}
+    engines: {node: '>=18'}
+
   make-error@1.3.6:
     resolution: {integrity: sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==}
 
@@ -6691,6 +6703,9 @@ packages:
     resolution: {integrity: sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==}
     engines: {node: '>=4'}
 
+  ms@2.0.0:
+    resolution: {integrity: sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==}
+
   ms@2.1.2:
     resolution: {integrity: sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==}
 
@@ -6719,8 +6734,8 @@ packages:
   nano-time@1.0.0:
     resolution: {integrity: sha512-flnngywOoQ0lLQOTRNexn2gGSNuM9bKj9RZAWSzhQ+UJYaAFG9bac4DW9VHjUAzrOaIcajHybCTHe/bkvozQqA==}
 
-  nanoid@3.3.11:
-    resolution: {integrity: sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==}
+  nanoid@3.3.18:
+    resolution: {integrity: sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==}
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
     hasBin: true
 
@@ -6732,6 +6747,11 @@ packages:
   natural-compare@1.4.0:
     resolution: {integrity: sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==}
 
+  needle@2.9.1:
+    resolution: {integrity: sha512-6R9fqJ5Zcmf+uYaFgdIHmLwNldn5HbK8L5ybn7Uz+ylX/rnOsSp1AHcvQSrCaFN+qNM1wpymHqD7mVasEOlHGQ==}
+    engines: {node: '>= 4.4.x'}
+    hasBin: true
+
   needle@3.2.0:
     resolution: {integrity: sha512-oUvzXnyLiVyVGoianLijF9O/RecZUf7TkBfimjGrLM4eQhXyeJwM6GeAWccwfQ9aa4gMCZKqhAOuLaMIcQxajQ==}
     engines: {node: '>= 4.4.x'}
@@ -7066,10 +7086,6 @@ packages:
     resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==}
     engines: {node: '>=12'}
 
-  pify@4.0.1:
-    resolution: {integrity: sha512-uB80kBFb/tfd68bVleG9T5GGsGPjJrLAUpR5PZIrhBnIaRTQRjqdJSsIKkOP6OAIFbj7GOrcudc5pNjZ+geV2g==}
-    engines: {node: '>=6'}
-
   pirates@4.0.7:
     resolution: {integrity: sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==}
     engines: {node: '>= 6'}
@@ -7131,8 +7147,8 @@ packages:
   postcss-value-parser@4.2.0:
     resolution: {integrity: sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==}
 
-  postcss@8.5.14:
-    resolution: {integrity: sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==}
+  postcss@8.5.26:
+    resolution: {integrity: sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==}
     engines: {node: ^10 || ^12 || >=14}
 
   posthog-js@1.298.0:
@@ -7178,6 +7194,9 @@ packages:
     resolution: {integrity: sha512-DEvV2ZF2r2/63V+tK8hQvrR2ZGn10srHbXviTlcv7Kpzw8jWiNTqbVgjO3IY8RxrrOUF8VPMQQFysYYYv0YZxw==}
     engines: {node: '>=6'}
 
+  probe-image-size@7.4.0:
+    resolution: {integrity: sha512-cdEprVtZxV+awMde9X+4jILBFYh4CARxVrQaMl4wY4YcPWbul9jntXrIW95NInBDyJwcVUP3U0T6yukN8rMBaQ==}
+
   process-nextick-args@2.0.1:
     resolution: {integrity: sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==}
 
@@ -7924,7 +7943,7 @@ packages:
       '@types/node': ^20.19.0 || >=22.12.0
       esbuild: '>=0.28.1 <0.29.0'
       jiti: '>=1.21.0'
-      less: ^4.0.0
+      less: '>=4.5.0 <5'
       sass: ^1.70.0
       sass-embedded: ^1.70.0
       stylus: '>=0.54.8'
@@ -8044,10 +8063,6 @@ packages:
     resolution: {integrity: sha512-3A6sD0WYP7+QrjbfNA2FN3FsOaGGFoekCVgTyypy53gPxhbkCIjtO6YWgdrfM+n/8sI8JeXZOIxsHjMTNxQ4nQ==}
     engines: {node: ^14.0.0 || >=16.0.0}
 
-  semver@5.7.2:
-    resolution: {integrity: sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g==}
-    hasBin: true
-
   semver@6.3.1:
     resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==}
     hasBin: true
@@ -8205,6 +8220,9 @@ packages:
     resolution: {integrity: sha512-eLoXW/DHyl62zxY4SCaIgnRhuMr6ri4juEYARS8E6sCEqzKpOiE521Ucofdx+KnDZl5xmvGYaaKCk5FEOxJCoQ==}
     engines: {node: '>= 0.4'}
 
+  stream-parser@0.3.1:
+    resolution: {integrity: sha512-bJ/HgKq41nlKvlhccD5kaCr/P+Hu0wPNKPJOH7en+YrJu/9EgqUF+88w5Jb6KNcjOFMhfX4B2asfeAtIGuHObQ==}
+
   strict-event-emitter@0.2.8:
     resolution: {integrity: sha512-KDf/ujU8Zud3YaLtMCcTI4xkZlZVIYxTLr+XIULexP+77EEVWixeXroLUXQXiVtH4XH2W7jr/3PT1v3zBuvc3A==}
 
@@ -9069,7 +9087,7 @@ snapshots:
     dependencies:
       '@jsdevtools/ono': 7.1.3
       '@types/json-schema': 7.0.15
-      js-yaml: 4.3.0
+      js-yaml: 4.3.1
 
   '@babel/code-frame@7.29.0':
     dependencies:
@@ -10569,7 +10587,7 @@ snapshots:
       camelcase: 5.3.1
       find-up: 4.1.0
       get-package-type: 0.1.0
-      js-yaml: 4.3.0
+      js-yaml: 4.3.1
       resolve-from: 5.0.0
 
   '@istanbuljs/schema@0.1.3': {}
@@ -12428,11 +12446,11 @@ snapshots:
 
   '@types/postcss-modules-local-by-default@4.0.2':
     dependencies:
-      postcss: 8.5.14
+      postcss: 8.5.26
 
   '@types/postcss-modules-scope@3.0.4':
     dependencies:
-      postcss: 8.5.14
+      postcss: 8.5.26
 
   '@types/prop-types@15.7.5': {}
 
@@ -12761,7 +12779,7 @@ snapshots:
       d3-time-format: 4.1.0
       internmap: 2.0.3
 
-  '@vitejs/plugin-react@5.1.4(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))':
+  '@vitejs/plugin-react@5.1.4(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))':
     dependencies:
       '@babel/core': 7.29.7
       '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.29.7)
@@ -12769,7 +12787,7 @@ snapshots:
       '@rolldown/pluginutils': 1.0.0-rc.3
       '@types/babel__core': 7.20.5
       react-refresh: 0.18.0
-      vite: rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)
+      vite: rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)
     transitivePeerDependencies:
       - supports-color
 
@@ -12823,7 +12841,7 @@ snapshots:
   ajv@8.18.0:
     dependencies:
       fast-deep-equal: 3.1.3
-      fast-uri: 3.1.2
+      fast-uri: 3.1.5
       json-schema-traverse: 1.0.0
       require-from-string: 2.0.2
 
@@ -13134,16 +13152,16 @@ snapshots:
 
   boolbase@1.0.0: {}
 
-  brace-expansion@1.1.15:
+  brace-expansion@1.1.18:
     dependencies:
       balanced-match: 1.0.2
       concat-map: 0.0.1
 
-  brace-expansion@2.1.1:
+  brace-expansion@2.1.4:
     dependencies:
       balanced-match: 1.0.2
 
-  brace-expansion@5.0.7:
+  brace-expansion@5.0.9:
     dependencies:
       balanced-match: 4.0.4
 
@@ -13432,9 +13450,9 @@ snapshots:
 
   cookie@0.7.2: {}
 
-  copy-anything@2.0.6:
+  copy-anything@3.0.5:
     dependencies:
-      is-what: 3.14.1
+      is-what: 4.1.16
 
   copy-text-to-clipboard@3.2.2: {}
 
@@ -13472,7 +13490,7 @@ snapshots:
     dependencies:
       env-paths: 2.2.1
       import-fresh: 3.3.1
-      js-yaml: 4.3.0
+      js-yaml: 4.3.1
       parse-json: 5.2.0
     optionalDependencies:
       typescript: 5.9.3
@@ -13682,6 +13700,11 @@ snapshots:
 
   debounce@1.2.1: {}
 
+  debug@2.6.9:
+    dependencies:
+      ms: 2.0.0
+    optional: true
+
   debug@3.2.7:
     dependencies:
       ms: 2.1.3
@@ -14141,7 +14164,7 @@ snapshots:
 
   fast-shallow-equal@1.0.0: {}
 
-  fast-uri@3.1.2: {}
+  fast-uri@3.1.5: {}
 
   fast_array_intersect@1.1.0: {}
 
@@ -14556,7 +14579,7 @@ snapshots:
 
   history@5.3.0:
     dependencies:
-      '@babel/runtime': 7.28.2
+      '@babel/runtime': 7.29.2
 
   hoist-non-react-statics@3.3.2:
     dependencies:
@@ -14635,9 +14658,9 @@ snapshots:
     dependencies:
       safer-buffer: 2.1.2
 
-  icss-utils@5.1.0(postcss@8.5.14):
+  icss-utils@5.1.0(postcss@8.5.26):
     dependencies:
-      postcss: 8.5.14
+      postcss: 8.5.26
 
   ieee754@1.2.1: {}
 
@@ -14645,14 +14668,11 @@ snapshots:
 
   ignore@7.0.5: {}
 
-  image-size@0.5.5:
-    optional: true
-
   immediate@3.0.6: {}
 
   immer@11.1.3: {}
 
-  immutable@5.1.5: {}
+  immutable@5.1.9: {}
 
   import-fresh@3.3.1:
     dependencies:
@@ -14871,7 +14891,7 @@ snapshots:
       call-bound: 1.0.4
       get-intrinsic: 1.3.0
 
-  is-what@3.14.1: {}
+  is-what@4.1.16: {}
 
   is-wsl@3.1.1:
     dependencies:
@@ -15429,7 +15449,7 @@ snapshots:
 
   js-tokens@4.0.0: {}
 
-  js-yaml@4.3.0:
+  js-yaml@4.3.1:
     dependencies:
       argparse: 2.0.1
 
@@ -15478,7 +15498,7 @@ snapshots:
       '@types/json-schema': 7.0.15
       '@types/lodash': 4.17.24
       is-glob: 4.0.3
-      js-yaml: 4.3.0
+      js-yaml: 4.3.1
       lodash: 4.18.1
       minimist: 1.2.8
       prettier: 3.8.3
@@ -15533,18 +15553,17 @@ snapshots:
 
   lerc@3.0.0: {}
 
-  less@4.4.0:
+  less@4.9.0:
     dependencies:
-      copy-anything: 2.0.6
+      copy-anything: 3.0.5
       parse-node-version: 1.0.1
-      tslib: 2.8.1
     optionalDependencies:
       errno: 0.1.8
       graceful-fs: 4.2.11
-      image-size: 0.5.5
-      make-dir: 2.1.0
+      make-dir: 5.1.0
       mime: 1.6.0
       needle: 3.2.0
+      probe-image-size: 7.4.0
       source-map: 0.6.1
     transitivePeerDependencies:
       - supports-color
@@ -15710,16 +15729,13 @@ snapshots:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
 
-  make-dir@2.1.0:
-    dependencies:
-      pify: 4.0.1
-      semver: 5.7.2
-    optional: true
-
   make-dir@3.1.0:
     dependencies:
       semver: 6.3.1
 
+  make-dir@5.1.0:
+    optional: true
+
   make-error@1.3.6: {}
 
   makeerror@1.0.12:
@@ -16123,19 +16139,19 @@ snapshots:
 
   minimatch@10.2.5:
     dependencies:
-      brace-expansion: 5.0.7
+      brace-expansion: 5.0.9
 
   minimatch@3.1.5:
     dependencies:
-      brace-expansion: 1.1.15
+      brace-expansion: 1.1.18
 
   minimatch@5.1.9:
     dependencies:
-      brace-expansion: 2.1.1
+      brace-expansion: 2.1.4
 
   minimatch@9.0.9:
     dependencies:
-      brace-expansion: 2.1.1
+      brace-expansion: 2.1.4
 
   minimist@1.2.8: {}
 
@@ -16184,6 +16200,9 @@ snapshots:
 
   mri@1.2.0: {}
 
+  ms@2.0.0:
+    optional: true
+
   ms@2.1.2: {}
 
   ms@2.1.3: {}
@@ -16234,12 +16253,21 @@ snapshots:
     dependencies:
       big-integer: 1.6.51
 
-  nanoid@3.3.11: {}
+  nanoid@3.3.18: {}
 
   napi-postinstall@0.3.4: {}
 
   natural-compare@1.4.0: {}
 
+  needle@2.9.1:
+    dependencies:
+      debug: 3.2.7
+      iconv-lite: 0.4.24
+      sax: 1.6.0
+    transitivePeerDependencies:
+      - supports-color
+    optional: true
+
   needle@3.2.0:
     dependencies:
       debug: 3.2.7
@@ -16412,7 +16440,7 @@ snapshots:
       find-up: 8.0.0
       fs-extra: 11.3.3
       jiti: 2.6.1
-      js-yaml: 4.3.0
+      js-yaml: 4.3.1
       remeda: 2.34.0
       string-argv: 0.3.2
       tsconfck: 3.1.6(typescript@5.9.3)
@@ -16611,9 +16639,6 @@ snapshots:
 
   picomatch@4.0.4: {}
 
-  pify@4.0.1:
-    optional: true
-
   pirates@4.0.7: {}
 
   pkg-dir@4.2.0:
@@ -16622,37 +16647,37 @@ snapshots:
 
   possible-typed-array-names@1.1.0: {}
 
-  postcss-load-config@3.1.4(postcss@8.5.14)(ts-node@10.9.1(@types/node@16.18.25)(typescript@5.9.3)):
+  postcss-load-config@3.1.4(postcss@8.5.26)(ts-node@10.9.1(@types/node@16.18.25)(typescript@5.9.3)):
     dependencies:
       lilconfig: 2.1.0
       yaml: 1.10.3
     optionalDependencies:
-      postcss: 8.5.14
+      postcss: 8.5.26
       ts-node: 10.9.1(@types/node@16.18.25)(typescript@5.9.3)
 
-  postcss-modules-extract-imports@3.0.0(postcss@8.5.14):
+  postcss-modules-extract-imports@3.0.0(postcss@8.5.26):
     dependencies:
-      postcss: 8.5.14
+      postcss: 8.5.26
 
-  postcss-modules-local-by-default@4.2.0(postcss@8.5.14):
+  postcss-modules-local-by-default@4.2.0(postcss@8.5.26):
     dependencies:
-      icss-utils: 5.1.0(postcss@8.5.14)
-      postcss: 8.5.14
+      icss-utils: 5.1.0(postcss@8.5.26)
+      postcss: 8.5.26
       postcss-selector-parser: 7.1.1
       postcss-value-parser: 4.2.0
 
-  postcss-modules-scope@3.2.1(postcss@8.5.14):
+  postcss-modules-scope@3.2.1(postcss@8.5.26):
     dependencies:
-      postcss: 8.5.14
+      postcss: 8.5.26
       postcss-selector-parser: 7.1.1
 
-  postcss-safe-parser@7.0.1(postcss@8.5.14):
+  postcss-safe-parser@7.0.1(postcss@8.5.26):
     dependencies:
-      postcss: 8.5.14
+      postcss: 8.5.26
 
-  postcss-scss@4.0.9(postcss@8.5.14):
+  postcss-scss@4.0.9(postcss@8.5.26):
     dependencies:
-      postcss: 8.5.14
+      postcss: 8.5.26
 
   postcss-selector-parser@7.1.1:
     dependencies:
@@ -16661,9 +16686,9 @@ snapshots:
 
   postcss-value-parser@4.2.0: {}
 
-  postcss@8.5.14:
+  postcss@8.5.26:
     dependencies:
-      nanoid: 3.3.11
+      nanoid: 3.3.18
       picocolors: 1.1.1
       source-map-js: 1.2.1
 
@@ -16714,6 +16739,15 @@ snapshots:
 
   prismjs@1.30.0: {}
 
+  probe-image-size@7.4.0:
+    dependencies:
+      lodash.merge: 4.6.2
+      needle: 2.9.1
+      stream-parser: 0.3.1
+    transitivePeerDependencies:
+      - supports-color
+    optional: true
+
   process-nextick-args@2.0.1: {}
 
   progress@2.0.3: {}
@@ -17616,13 +17650,13 @@ snapshots:
 
   robust-predicates@3.0.2: {}
 
-  rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4):
+  rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4):
     dependencies:
       '@oxc-project/runtime': 0.101.0
       fdir: 6.5.0(picomatch@4.0.4)
       lightningcss: 1.31.1
       picomatch: 4.0.4
-      postcss: 8.5.14
+      postcss: 8.5.26
       rolldown: 1.0.0-beta.53
       tinyglobby: 0.2.15
     optionalDependencies:
@@ -17630,7 +17664,7 @@ snapshots:
       esbuild: 0.28.1
       fsevents: 2.3.3
       jiti: 2.6.1
-      less: 4.4.0
+      less: 4.9.0
       sass: 1.97.3
       stylus: 0.62.0
       terser: 5.46.2
@@ -17705,7 +17739,7 @@ snapshots:
   sass@1.97.3:
     dependencies:
       chokidar: 4.0.3
-      immutable: 5.1.5
+      immutable: 5.1.9
       source-map-js: 1.2.1
     optionalDependencies:
       '@parcel/watcher': 2.5.1
@@ -17735,9 +17769,6 @@ snapshots:
       refa: 0.12.1
       regexp-ast-analysis: 0.7.1
 
-  semver@5.7.2:
-    optional: true
-
   semver@6.3.1: {}
 
   semver@7.8.5: {}
@@ -17924,6 +17955,13 @@ snapshots:
       es-errors: 1.3.0
       internal-slot: 1.1.0
 
+  stream-parser@0.3.1:
+    dependencies:
+      debug: 2.6.9
+    transitivePeerDependencies:
+      - supports-color
+    optional: true
+
   strict-event-emitter@0.2.8:
     dependencies:
       events: 3.3.0
@@ -18045,8 +18083,8 @@ snapshots:
       micromatch: 4.0.8
       normalize-path: 3.0.0
       picocolors: 1.1.1
-      postcss: 8.5.14
-      postcss-safe-parser: 7.0.1(postcss@8.5.14)
+      postcss: 8.5.26
+      postcss-safe-parser: 7.0.1(postcss@8.5.26)
       postcss-selector-parser: 7.1.1
       postcss-value-parser: 4.2.0
       string-width: 8.2.0
@@ -18287,14 +18325,14 @@ snapshots:
       '@types/postcss-modules-local-by-default': 4.0.2
       '@types/postcss-modules-scope': 3.0.4
       dotenv: 16.6.1
-      icss-utils: 5.1.0(postcss@8.5.14)
-      less: 4.4.0
+      icss-utils: 5.1.0(postcss@8.5.26)
+      less: 4.9.0
       lodash.camelcase: 4.3.0
-      postcss: 8.5.14
-      postcss-load-config: 3.1.4(postcss@8.5.14)(ts-node@10.9.1(@types/node@16.18.25)(typescript@5.9.3))
-      postcss-modules-extract-imports: 3.0.0(postcss@8.5.14)
-      postcss-modules-local-by-default: 4.2.0(postcss@8.5.14)
-      postcss-modules-scope: 3.2.1(postcss@8.5.14)
+      postcss: 8.5.26
+      postcss-load-config: 3.1.4(postcss@8.5.26)(ts-node@10.9.1(@types/node@16.18.25)(typescript@5.9.3))
+      postcss-modules-extract-imports: 3.0.0(postcss@8.5.26)
+      postcss-modules-local-by-default: 4.2.0(postcss@8.5.26)
+      postcss-modules-scope: 3.2.1(postcss@8.5.26)
       reserved-words: 0.1.2
       sass: 1.97.3
       source-map-js: 1.2.1
@@ -18519,7 +18557,7 @@ snapshots:
       unist-util-stringify-position: 4.0.0
       vfile-message: 4.0.2
 
-  vite-plugin-checker@0.12.0(eslint@10.2.1(jiti@2.6.1))(meow@13.2.0)(optionator@0.9.4)(oxlint@1.69.0(oxlint-tsgolint@0.23.0))(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))(stylelint@17.7.0(typescript@5.9.3))(typescript@5.9.3):
+  vite-plugin-checker@0.12.0(eslint@10.2.1(jiti@2.6.1))(meow@13.2.0)(optionator@0.9.4)(oxlint@1.69.0(oxlint-tsgolint@0.23.0))(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))(stylelint@17.7.0(typescript@5.9.3))(typescript@5.9.3):
     dependencies:
       '@babel/code-frame': 7.29.0
       chokidar: 4.0.3
@@ -18528,7 +18566,7 @@ snapshots:
       picomatch: 4.0.4
       tiny-invariant: 1.3.3
       tinyglobby: 0.2.15
-      vite: rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)
+      vite: rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)
       vscode-uri: 3.1.0
     optionalDependencies:
       eslint: 10.2.1(jiti@2.6.1)
@@ -18538,16 +18576,16 @@ snapshots:
       stylelint: 17.7.0(typescript@5.9.3)
       typescript: 5.9.3
 
-  vite-plugin-compression@0.5.1(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)):
+  vite-plugin-compression@0.5.1(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)):
     dependencies:
       chalk: 4.1.2
       debug: 4.3.4
       fs-extra: 10.1.0
-      vite: rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)
+      vite: rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)
     transitivePeerDependencies:
       - supports-color
 
-  vite-plugin-html@3.2.2(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)):
+  vite-plugin-html@3.2.2(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)):
     dependencies:
       '@rollup/pluginutils': 4.2.1
       colorette: 2.0.20
@@ -18561,23 +18599,23 @@ snapshots:
       html-minifier-terser: 6.1.0
       node-html-parser: 5.4.2
       pathe: 0.2.0
-      vite: rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)
+      vite: rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)
 
-  vite-plugin-image-optimizer@2.0.3(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))(sharp@0.35.0)(svgo@4.0.2):
+  vite-plugin-image-optimizer@2.0.3(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))(sharp@0.35.0)(svgo@4.0.2):
     dependencies:
       ansi-colors: 4.1.3
       pathe: 2.0.3
-      vite: rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)
+      vite: rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)
     optionalDependencies:
       sharp: 0.35.0
       svgo: 4.0.2
 
-  vite-tsconfig-paths@6.1.1(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))(typescript@5.9.3):
+  vite-tsconfig-paths@6.1.1(rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4))(typescript@5.9.3):
     dependencies:
       debug: 4.3.4
       globrex: 0.1.2
       tsconfck: 3.1.6(typescript@5.9.3)
-      vite: rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.4.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)
+      vite: rolldown-vite@7.3.1(@types/node@16.18.25)(esbuild@0.28.1)(jiti@2.6.1)(less@4.9.0)(sass@1.97.3)(stylus@0.62.0)(terser@5.46.2)(yaml@2.8.4)
     transitivePeerDependencies:
       - supports-color
       - typescript

frontend/pnpm-workspace.yaml

@@ -13,7 +13,16 @@ overrides:
  '@babel/core@<=7.29.0': '>=7.29.6 <8'
  # via: jest > babel-plugin-istanbul > @istanbuljs/load-nyc-config@1.1.0 (js-yaml ^3.13.1)
  # remove: blocked — 1.1.0 is latest and still depends on js-yaml 3.x
- '@istanbuljs/load-nyc-config>js-yaml': '>=4.2.0 <5'
+ '@istanbuljs/load-nyc-config>js-yaml': '>=4.3.1 <5'
+ # via: babel-plugin-istanbul > test-exclude@6 > minimatch@3.1.5 (^1.1.7); also glob@7
+ # remove: blocked — babel-plugin-istanbul pins test-exclude@6, which pins minimatch@3
+ brace-expansion@<1.1.18: '>=1.1.18 <2'
+ # via: jest > glob@10 > minimatch@9.0.9 (^2.0.1); also minimatch@5.1.9 (^2.0.1)
+ # remove: blocked — jest 30 resolves glob@10 > minimatch@9 internally
+ 'brace-expansion@>=2.0.0 <2.1.4': '>=2.1.4 <3'
+ # via: eslint-plugin-sonarjs@4.0.2 (minimatch ^10.2.4) > minimatch@10.2.5 (^5.0.5)
+ # remove: blocked — minimatch@10.2.6 (latest) only widens to ^5.0.8, still vulnerable
+ 'brace-expansion@>=5.0.0 <5.0.9': '>=5.0.9 <6'
  # via: msw@1.3.2 (devDep) > cookie ^0.4.2
  # remove: upgrade msw to >=2 (ships cookie ^1). Do NOT open the cap: cookie >=1 is
  # ESM-only and breaks msw under jest's CJS sandbox (kills every test suite)
@@ -27,13 +36,26 @@ overrides:
  # remove: blocked on rolldown-vite (7.3.1 is latest, still ^0.27.0);
  #         orval >=8.20.0 and ts-jest >=29.4.11 already fixed on their side
  esbuild@>=0.27.3 <0.28.1: '>=0.28.1 <0.29.0'
+ # via: @commitlint/cli > @commitlint/config-validator > ajv@8 (fast-uri ^3.0.1)
+ # remove: blocked — ajv@8 caps fast-uri at ^3, and only 3.1.5 carries the fix
+ fast-uri@<3.1.5: '>=3.1.5 <4'
+ # via: direct devDep sass@1.97.3 (immutable ^5.0.2)
+ # remove: blocked — plain sass bumps stay within ^5, so the floor is what pulls 5.1.8
+ immutable@<5.1.8: '>=5.1.8 <6'
  # via: react-use@17.5.1 (direct, js-cookie ^2.2.1); @grafana/data > react-use@17.6.0
  # remove: bump react-use to >=17.6.1 (js-cookie ^3); @grafana/data side blocked
  js-cookie@<=3.0.5: '>=3.0.7 <4'
  # via: @orval/core@8.9.1 (devDep, js-yaml 4.1.1 EXACT pin — not deletable);
  #      json-schema-to-typescript@15 > @apidevtools/json-schema-ref-parser (^4.1.0)
  # remove: upgrade orval to >=8.20.0 (drops js-yaml dependency entirely)
- js-yaml@>=4.0.0 <=4.1.1: '>=4.2.0 <5'
+ 'js-yaml@>=4.0.0 <4.3.1': '>=4.3.1 <5'
+ # via: typescript-plugin-css-modules@5.2.0 (less ^4.2.0) > less@4.4.0 (image-size ~0.5.0)
+ # remove: bump typescript-plugin-css-modules once it floors less itself; image-size has
+ #         no patched release at all, so dropping the dep is the only fix — less@4.5.0 did
+ less@<4.5.0: '>=4.5.0 <5'
+ # via: direct dep postcss (nanoid ^3.3.17)
+ # remove: blocked — postcss 8.5.26 (latest) caps nanoid at ^3, fix landed in 3.3.18
+ nanoid@<3.3.18: '>=3.3.18 <4'
  # via: react-syntax-highlighter@15.5.0 (prismjs ^1.27.0 + refractor@3 ~1.27.0 tilde-pinned)
  # remove: bump react-syntax-highlighter to >=16.1.1 (prismjs ^1.30.0, refractor@5)
  prismjs@<1.30.0: '>=1.30.0 <2'

frontend/src/components/QueryBuilderV2/QueryV2/__tests__/RecentSearches.test.tsx

@@ -107,14 +107,38 @@ async function renderAndFocus(
 	return editor;
 }
 
-function openRecents(): Promise<void> {
+// Re-requests completions while waiting: typing and the async fetches can close the popup.
+function waitForRecents(
+	assertLabels: (labels: string[]) => void,
+): Promise<void> {
 	return waitFor(
 		() => {
 			const view = getEditorView();
 			if (view && !isCompletionOpen()) {
 				startCompletion(view);
 			}
-			expect(getRecentLabels().length).toBeGreaterThan(0);
+			assertLabels(getRecentLabels());
+		},
+		{ timeout: 3000 },
+	);
+}
+
+function openRecents(): Promise<void> {
+	return waitForRecents((labels) => expect(labels.length).toBeGreaterThan(0));
+}
+
+function waitForPopupElement(
+	find: () => HTMLElement | null | undefined,
+): Promise<HTMLElement> {
+	return waitFor(
+		() => {
+			const view = getEditorView();
+			if (view && !isCompletionOpen()) {
+				startCompletion(view);
+			}
+			const node = find();
+			expect(node).toBeTruthy();
+			return node as HTMLElement;
 		},
 		{ timeout: 3000 },
 	);
@@ -132,11 +156,8 @@ describe('QuerySearch recent searches', () => {
 		await renderAndFocus();
 		await openRecents();
 
-		await waitFor(
-			() => {
-				expect(getRecentLabels()).toStrictEqual([FRONTEND_FILTER]);
-			},
-			{ timeout: 3000 },
+		await waitForRecents((labels) =>
+			expect(labels).toStrictEqual([FRONTEND_FILTER]),
 		);
 
 		const view = getEditorView() as EditorView;
@@ -152,11 +173,8 @@ describe('QuerySearch recent searches', () => {
 		await openRecents();
 		await userEvent.type(editor, 'status_code');
 
-		await waitFor(
-			() => {
-				expect(getRecentLabels()).toStrictEqual([STATUS_CODE_FILTER]);
-			},
-			{ timeout: 3000 },
+		await waitForRecents((labels) =>
+			expect(labels).toStrictEqual([STATUS_CODE_FILTER]),
 		);
 	});
 
@@ -170,11 +188,8 @@ describe('QuerySearch recent searches', () => {
 		await renderAndFocus();
 		await openRecents();
 
-		await waitFor(
-			() => {
-				expect(getRecentLabels()).toStrictEqual([FRONTEND_FILTER]);
-			},
-			{ timeout: 3000 },
+		await waitForRecents((labels) =>
+			expect(labels).toStrictEqual([FRONTEND_FILTER]),
 		);
 	});
 
@@ -187,11 +202,8 @@ describe('QuerySearch recent searches', () => {
 		await openRecents();
 		await userEvent.type(editor, FRONTEND_FILTER);
 
-		await waitFor(
-			() => {
-				expect(getRecentLabels()).toStrictEqual([supersetFilter]);
-			},
-			{ timeout: 3000 },
+		await waitForRecents((labels) =>
+			expect(labels).toStrictEqual([supersetFilter]),
 		);
 	});
 
@@ -206,11 +218,8 @@ describe('QuerySearch recent searches', () => {
 		await renderAndFocus();
 		await openRecents();
 
-		await waitFor(
-			() => {
-				expect(getRecentLabels()).toStrictEqual(expectedLabels);
-			},
-			{ timeout: 3000 },
+		await waitForRecents((labels) =>
+			expect(labels).toStrictEqual(expectedLabels),
 		);
 	});
 
@@ -221,17 +230,13 @@ describe('QuerySearch recent searches', () => {
 		await renderAndFocus(onChange);
 		await openRecents();
 
-		const option = await waitFor(
-			() => {
-				const node = Array.from(
-					document.querySelectorAll<HTMLElement>(COMPLETION_LABEL_SELECTOR),
-				).find((element) => element.textContent === FRONTEND_FILTER);
-				expect(node).toBeDefined();
-				return node as HTMLElement;
-			},
-			{ timeout: 3000 },
+		const option = await waitForPopupElement(() =>
+			Array.from(
+				document.querySelectorAll<HTMLElement>(COMPLETION_LABEL_SELECTOR),
+			).find((element) => element.textContent === FRONTEND_FILTER),
 		);
-		await userEvent.click(option);
+		// fireEvent: userEvent's pointerdown blurs the editor, closing the popup before CM's mousedown apply.
+		fireEvent.mouseDown(option);
 
 		await waitFor(
 			() => {
@@ -256,13 +261,8 @@ describe('QuerySearch recent searches', () => {
 		await renderAndFocus();
 		await openRecents();
 
-		const deleteButton = await waitFor(
-			() => {
-				const button = document.querySelector(DELETE_BUTTON_SELECTOR);
-				expect(button).toBeInTheDocument();
-				return button as HTMLElement;
-			},
-			{ timeout: 3000 },
+		const deleteButton = await waitForPopupElement(() =>
+			document.querySelector<HTMLElement>(DELETE_BUTTON_SELECTOR),
 		);
 
 		// fireEvent: the button preventDefaults pointerdown, which makes userEvent.click drop the mouse chain.

frontend/src/components/ServiceAccountDrawer/__tests__/ServiceAccountDrawer.authz.test.tsx

@@ -1,4 +1,7 @@
-import { listRolesSuccessResponse } from 'mocks-server/__mockdata__/roles';
+import {
+	listRolesSuccessResponse,
+	managedRoles,
+} from 'mocks-server/__mockdata__/roles';
 import { rest, server } from 'mocks-server/server';
 import { NuqsTestingAdapter } from 'nuqs/adapters/testing';
 import { fireEvent, render, screen, waitFor } from 'tests/test-utils';
@@ -18,17 +21,24 @@ const ROLES_ENDPOINT = '*/api/v1/roles';
 const SA_KEYS_ENDPOINT = '*/api/v1/service_accounts/:id/keys';
 const SA_ENDPOINT = '*/api/v1/service_accounts/sa-1';
 const SA_DELETE_ENDPOINT = '*/api/v1/service_accounts/sa-1';
-const SA_ROLES_ENDPOINT = '*/api/v1/service_accounts/:id/roles';
-const SA_ROLE_DELETE_ENDPOINT = '*/api/v1/service_accounts/:id/roles/:rid';
+const SA_ROLES_ENDPOINT = '*/api/v1/service_account_roles';
+const SA_ROLE_DELETE_ENDPOINT = '*/api/v1/service_account_roles/:id';
 
 const activeAccountResponse = {
 	id: 'sa-1',
 	name: 'CI Bot',
 	email: 'ci-bot@signoz.io',
-	roles: ['signoz-admin'],
 	status: 'ACTIVE',
 	createdAt: '2026-01-01T00:00:00Z',
 	updatedAt: '2026-01-02T00:00:00Z',
+	serviceAccountRoles: [
+		{
+			id: 'sar-admin-1',
+			serviceAccountId: 'sa-1',
+			roleId: managedRoles[0].id,
+			role: { ...managedRoles[0], transactionGroups: [] },
+		},
+	],
 };
 
 function renderDrawer(
@@ -58,22 +68,13 @@ function setupBaseHandlers(): void {
 		rest.delete(SA_DELETE_ENDPOINT, (_, res, ctx) =>
 			res(ctx.status(200), ctx.json({ status: 'success', data: {} })),
 		),
-		rest.get(SA_ROLES_ENDPOINT, (_, res, ctx) =>
+		rest.post(SA_ROLES_ENDPOINT, (_, res, ctx) =>
 			res(
-				ctx.status(200),
-				ctx.json({
-					data: listRolesSuccessResponse.data.filter(
-						(r) => r.name === 'signoz-admin',
-					),
-				}),
+				ctx.status(201),
+				ctx.json({ status: 'success', data: { id: 'sar-new' } }),
 			),
 		),
-		rest.post(SA_ROLES_ENDPOINT, (_, res, ctx) =>
-			res(ctx.status(200), ctx.json({ status: 'success', data: {} })),
-		),
-		rest.delete(SA_ROLE_DELETE_ENDPOINT, (_, res, ctx) =>
-			res(ctx.status(200), ctx.json({ status: 'success', data: {} })),
-		),
+		rest.delete(SA_ROLE_DELETE_ENDPOINT, (_, res, ctx) => res(ctx.status(204))),
 	);
 }
 

frontend/src/components/ServiceAccountDrawer/__tests__/ServiceAccountDrawer.test.tsx

@@ -1,4 +1,7 @@
-import { listRolesSuccessResponse } from 'mocks-server/__mockdata__/roles';
+import {
+	listRolesSuccessResponse,
+	managedRoles,
+} from 'mocks-server/__mockdata__/roles';
 import { rest, server } from 'mocks-server/server';
 import { NuqsTestingAdapter } from 'nuqs/adapters/testing';
 import { render, screen, userEvent, waitFor } from 'tests/test-utils';
@@ -10,23 +13,33 @@ const ROLES_ENDPOINT = '*/api/v1/roles';
 const SA_KEYS_ENDPOINT = '*/api/v1/service_accounts/:id/keys';
 const SA_ENDPOINT = '*/api/v1/service_accounts/sa-1';
 const SA_DELETE_ENDPOINT = '*/api/v1/service_accounts/sa-1';
-const SA_ROLES_ENDPOINT = '*/api/v1/service_accounts/:id/roles';
-const SA_ROLE_DELETE_ENDPOINT = '*/api/v1/service_accounts/:id/roles/:rid';
+const SA_ROLES_ENDPOINT = '*/api/v1/service_account_roles';
+const SA_ROLE_DELETE_ENDPOINT = '*/api/v1/service_account_roles/:id';
+
+const ADMIN_ASSIGNMENT_ID = 'sar-admin-1';
 
 const activeAccountResponse = {
 	id: 'sa-1',
 	name: 'CI Bot',
 	email: 'ci-bot@signoz.io',
-	roles: ['signoz-admin'],
 	status: 'ACTIVE',
 	createdAt: '2026-01-01T00:00:00Z',
 	updatedAt: '2026-01-02T00:00:00Z',
+	serviceAccountRoles: [
+		{
+			id: ADMIN_ASSIGNMENT_ID,
+			serviceAccountId: 'sa-1',
+			roleId: managedRoles[0].id,
+			role: { ...managedRoles[0], transactionGroups: [] },
+		},
+	],
 };
 
 const deletedAccountResponse = {
 	...activeAccountResponse,
 	id: 'sa-2',
 	status: 'DELETED',
+	serviceAccountRoles: [],
 };
 
 function renderDrawer(
@@ -58,22 +71,13 @@ describe('ServiceAccountDrawer', () => {
 			rest.delete(SA_DELETE_ENDPOINT, (_, res, ctx) =>
 				res(ctx.status(200), ctx.json({ status: 'success', data: {} })),
 			),
-			rest.get(SA_ROLES_ENDPOINT, (_, res, ctx) =>
+			rest.post(SA_ROLES_ENDPOINT, (_, res, ctx) =>
 				res(
-					ctx.status(200),
-					ctx.json({
-						data: listRolesSuccessResponse.data.filter(
-							(r) => r.name === 'signoz-admin',
-						),
-					}),
+					ctx.status(201),
+					ctx.json({ status: 'success', data: { id: 'sar-new' } }),
 				),
 			),
-			rest.post(SA_ROLES_ENDPOINT, (_, res, ctx) =>
-				res(ctx.status(200), ctx.json({ status: 'success', data: {} })),
-			),
-			rest.delete(SA_ROLE_DELETE_ENDPOINT, (_, res, ctx) =>
-				res(ctx.status(200), ctx.json({ status: 'success', data: {} })),
-			),
+			rest.delete(SA_ROLE_DELETE_ENDPOINT, (_, res, ctx) => res(ctx.status(204))),
 			setupAuthzAdmin(),
 		);
 	});
@@ -136,11 +140,14 @@ describe('ServiceAccountDrawer', () => {
 		server.use(
 			rest.post(SA_ROLES_ENDPOINT, async (req, res, ctx) => {
 				roleSpy(await req.json());
-				return res(ctx.status(200), ctx.json({ status: 'success', data: {} }));
+				return res(
+					ctx.status(201),
+					ctx.json({ status: 'success', data: { id: 'sar-new' } }),
+				);
 			}),
 			rest.delete(SA_ROLE_DELETE_ENDPOINT, (_, res, ctx) => {
 				deleteSpy();
-				return res(ctx.status(200), ctx.json({ status: 'success', data: {} }));
+				return res(ctx.status(204));
 			}),
 		);
 
@@ -159,7 +166,8 @@ describe('ServiceAccountDrawer', () => {
 		await waitFor(() => {
 			expect(roleSpy).toHaveBeenCalledWith(
 				expect.objectContaining({
-					id: '019c24aa-2248-7585-a129-4188b3473c27',
+					serviceAccountId: 'sa-1',
+					roleId: '019c24aa-2248-7585-a129-4188b3473c27',
 				}),
 			);
 			expect(deleteSpy).not.toHaveBeenCalled();
@@ -174,11 +182,14 @@ describe('ServiceAccountDrawer', () => {
 		server.use(
 			rest.post(SA_ROLES_ENDPOINT, async (req, res, ctx) => {
 				roleSpy(await req.json());
-				return res(ctx.status(200), ctx.json({ status: 'success', data: {} }));
+				return res(
+					ctx.status(201),
+					ctx.json({ status: 'success', data: { id: 'sar-new' } }),
+				);
 			}),
-			rest.delete(SA_ROLE_DELETE_ENDPOINT, (_, res, ctx) => {
-				deleteSpy();
-				return res(ctx.status(200), ctx.json({ status: 'success', data: {} }));
+			rest.delete(SA_ROLE_DELETE_ENDPOINT, (req, res, ctx) => {
+				deleteSpy(req.params.id);
+				return res(ctx.status(204));
 			}),
 		);
 
@@ -198,7 +209,7 @@ describe('ServiceAccountDrawer', () => {
 		await user.click(saveBtn);
 
 		await waitFor(() => {
-			expect(deleteSpy).toHaveBeenCalled();
+			expect(deleteSpy).toHaveBeenCalledWith(ADMIN_ASSIGNMENT_ID);
 			expect(roleSpy).not.toHaveBeenCalled();
 		});
 	});
@@ -246,9 +257,6 @@ describe('ServiceAccountDrawer', () => {
 			rest.get('*/api/v1/service_accounts/sa-2/keys', (_, res, ctx) =>
 				res(ctx.status(200), ctx.json({ data: [] })),
 			),
-			rest.get('*/api/v1/service_accounts/sa-2/roles', (_, res, ctx) =>
-				res(ctx.status(200), ctx.json({ data: [] })),
-			),
 		);
 
 		renderDrawer({ account: 'sa-2' });
@@ -312,22 +320,13 @@ describe('ServiceAccountDrawer – save-error UX', () => {
 			rest.delete(SA_DELETE_ENDPOINT, (_, res, ctx) =>
 				res(ctx.status(200), ctx.json({ status: 'success', data: {} })),
 			),
-			rest.get(SA_ROLES_ENDPOINT, (_, res, ctx) =>
+			rest.post(SA_ROLES_ENDPOINT, (_, res, ctx) =>
 				res(
-					ctx.status(200),
-					ctx.json({
-						data: listRolesSuccessResponse.data.filter(
-							(r) => r.name === 'signoz-admin',
-						),
-					}),
+					ctx.status(201),
+					ctx.json({ status: 'success', data: { id: 'sar-new' } }),
 				),
 			),
-			rest.post(SA_ROLES_ENDPOINT, (_, res, ctx) =>
-				res(ctx.status(200), ctx.json({ status: 'success', data: {} })),
-			),
-			rest.delete(SA_ROLE_DELETE_ENDPOINT, (_, res, ctx) =>
-				res(ctx.status(200), ctx.json({ status: 'success', data: {} })),
-			),
+			rest.delete(SA_ROLE_DELETE_ENDPOINT, (_, res, ctx) => res(ctx.status(204))),
 			setupAuthzAdmin(),
 		);
 	});
@@ -410,14 +409,17 @@ describe('ServiceAccountDrawer – save-error UX', () => {
 		const user = userEvent.setup({ pointerEventsCheck: 0 });
 		let roleAddCallCount = 0;
 
-		// First call → 429, second call → 200
+		// First call → 429, second call → 201
 		server.use(
 			rest.post(SA_ROLES_ENDPOINT, (_, res, ctx) => {
 				roleAddCallCount += 1;
 				if (roleAddCallCount === 1) {
 					return res(ctx.status(429), ctx.json({ message: 'Too Many Requests' }));
 				}
-				return res(ctx.status(200), ctx.json({ status: 'success', data: {} }));
+				return res(
+					ctx.status(201),
+					ctx.json({ status: 'success', data: { id: 'sar-new' } }),
+				);
 			}),
 		);
 

frontend/src/container/InfraMonitoringK8sV2/Base/K8sEmptyState.module.scss

@@ -51,4 +51,5 @@
 	gap: var(--spacing-3);
 	max-width: 500px;
 	padding: 24px;
+	max-height: 100%;
 }

frontend/src/container/InfraMonitoringK8sV2/Base/K8sExpandedRow.tsx

@@ -37,7 +37,7 @@ import { useInfraMonitoringFontSize } from './useInfraMonitoringTablePreferences
 import styles from './K8sExpandedRow.module.scss';
 import { buildExpressionFromGroupMeta } from './utils';
 import { logInfraColumnSortedEvent } from 'container/InfraMonitoringK8sV2/Base/events';
-import { getUnstableCurrentSearchParams } from 'utils/getUnstableCurrentSearchParams';
+import { getUnstableCurrentSearchParams } from 'container/TopNav/DateTimeSelectionV2/utils/getUnstableCurrentSearchParams';
 import { QueryParams } from 'constants/query';
 
 const EXPANDED_ROW_LIMIT = 10;

frontend/src/container/LogDetailedView/InfraMetrics/constants.ts

@@ -2806,8 +2806,8 @@ export const hostWidgetInfo = [
 			'The 1m, 5m and 15m load averages together; 1m above 15m means load is building.',
 	},
 	{
-		title: 'Network usage (bytes)',
-		yAxisUnit: 'bytes',
+		title: 'Network usage',
+		yAxisUnit: 'binBps',
 		docPath: '/infrastructure-monitoring/host-monitoring/#network-usage-bytes',
 		description:
 			'Throughput in bytes/s per interface and direction, to spot NICs nearing rated bandwidth.',
@@ -2841,8 +2841,8 @@ export const hostWidgetInfo = [
 			'Active connection counts per protocol and state (ESTABLISHED, TIME_WAIT, SYN_RECV) to spot leaks and churn.',
 	},
 	{
-		title: 'System disk io (bytes transferred)',
-		yAxisUnit: 'bytes',
+		title: 'System disk IO',
+		yAxisUnit: 'binBps',
 		docPath: '/infrastructure-monitoring/host-monitoring/#system-disk-io-bytes',
 		description:
 			'Disk throughput in bytes/s per device and direction, tracking heavy file I/O or database flushes.',

frontend/src/container/ServiceAccountsSettings/__tests__/ServiceAccountsSettings.authz.integration.test.tsx

@@ -10,7 +10,6 @@ import ServiceAccountsSettings from '../ServiceAccountsSettings';
 const SA_LIST_ENDPOINT = '*/api/v1/service_accounts';
 const SA_ENDPOINT = '*/api/v1/service_accounts/:id';
 const SA_KEYS_ENDPOINT = '*/api/v1/service_accounts/:id/keys';
-const SA_ROLES_ENDPOINT = '*/api/v1/service_accounts/:id/roles';
 const ROLES_ENDPOINT = '*/api/v1/roles';
 
 const mockServiceAccountsAPI = [
@@ -18,7 +17,7 @@ const mockServiceAccountsAPI = [
 		id: 'sa-1',
 		name: 'CI Bot',
 		email: 'ci-bot@signoz.io',
-		roles: ['signoz-admin'],
+		serviceAccountRoles: [],
 		status: 'ACTIVE',
 		createdAt: 1700000000,
 		updatedAt: 1700000001,
@@ -27,7 +26,7 @@ const mockServiceAccountsAPI = [
 		id: 'sa-2',
 		name: 'Monitoring Agent',
 		email: 'monitor@signoz.io',
-		roles: ['signoz-viewer'],
+		serviceAccountRoles: [],
 		status: 'ACTIVE',
 		createdAt: 1700000002,
 		updatedAt: 1700000003,
@@ -36,7 +35,7 @@ const mockServiceAccountsAPI = [
 		id: 'sa-3',
 		name: 'Legacy Bot',
 		email: 'legacy@signoz.io',
-		roles: ['signoz-editor'],
+		serviceAccountRoles: [],
 		status: 'DISABLED',
 		createdAt: 1700000004,
 		updatedAt: 1700000005,
@@ -61,9 +60,6 @@ describe('ServiceAccountsSettings (integration)', () => {
 			rest.get(SA_KEYS_ENDPOINT, (_, res, ctx) =>
 				res(ctx.status(200), ctx.json({ data: [] })),
 			),
-			rest.get(SA_ROLES_ENDPOINT, (_, res, ctx) =>
-				res(ctx.status(200), ctx.json({ data: [] })),
-			),
 			rest.get(ROLES_ENDPOINT, (_, res, ctx) =>
 				res(ctx.status(200), ctx.json(listRolesSuccessResponse)),
 			),

frontend/src/container/TopNav/DateTimeSelectionV2/__tests__/DateTimeSelectionV2.edge-cases.test.tsx

@@ -10,7 +10,7 @@ import DateTimeSelection from '../index';
 import {
 	__resetSearchParamsGetter,
 	__setSearchParamsGetterForTest,
-} from 'utils/getUnstableCurrentSearchParams';
+} from '../utils/getUnstableCurrentSearchParams';
 import { queryClient, TestWrapper } from './testUtils';
 
 const mockSafeNavigate = jest.fn();

frontend/src/container/TopNav/DateTimeSelectionV2/__tests__/DateTimeSelectionV2.modal-mode.test.tsx

@@ -10,7 +10,7 @@ import DateTimeSelection from '../index';
 import {
 	__resetSearchParamsGetter,
 	__setSearchParamsGetterForTest,
-} from 'utils/getUnstableCurrentSearchParams';
+} from '../utils/getUnstableCurrentSearchParams';
 import { queryClient, TestWrapper } from './testUtils';
 
 const mockSafeNavigate = jest.fn();

frontend/src/container/TopNav/DateTimeSelectionV2/__tests__/DateTimeSelectionV2.regression.test.tsx

@@ -24,7 +24,7 @@ import DateTimeSelection from '../index';
 import {
 	__resetSearchParamsGetter,
 	__setSearchParamsGetterForTest,
-} from 'utils/getUnstableCurrentSearchParams';
+} from '../utils/getUnstableCurrentSearchParams';
 
 const queryClient = new QueryClient({
 	defaultOptions: {

frontend/src/container/TopNav/DateTimeSelectionV2/__tests__/DateTimeSelectionV2.routes.test.tsx

@@ -5,7 +5,7 @@ import DateTimeSelection from '../index';
 import {
 	__resetSearchParamsGetter,
 	__setSearchParamsGetterForTest,
-} from 'utils/getUnstableCurrentSearchParams';
+} from '../utils/getUnstableCurrentSearchParams';
 import { queryClient, TestWrapper } from './testUtils';
 
 const mockSafeNavigate = jest.fn();

frontend/src/container/TopNav/DateTimeSelectionV2/__tests__/DateTimeSelectionV2.time-selection.test.tsx

@@ -10,7 +10,7 @@ import DateTimeSelection from '../index';
 import {
 	__resetSearchParamsGetter,
 	__setSearchParamsGetterForTest,
-} from 'utils/getUnstableCurrentSearchParams';
+} from '../utils/getUnstableCurrentSearchParams';
 import { queryClient, TestWrapper, createMockMoment } from './testUtils';
 
 const mockSafeNavigate = jest.fn();

frontend/src/container/TopNav/DateTimeSelectionV2/index.tsx

@@ -54,7 +54,7 @@ import {
 	Time,
 	TimeRange,
 } from './types';
-import { getUnstableCurrentSearchParams } from 'utils/getUnstableCurrentSearchParams';
+import { getUnstableCurrentSearchParams } from './utils/getUnstableCurrentSearchParams';
 
 import './DateTimeSelectionV2.styles.scss';
 

frontend/src/hooks/serviceAccount/useServiceAccountRoleManager.ts

@@ -1,19 +1,23 @@
 import { useCallback, useMemo } from 'react';
-import { useQueryClient } from 'react-query';
 import {
-	getGetServiceAccountRolesQueryKey,
-	useCreateServiceAccountRoleDeprecated,
-	useDeleteServiceAccountRoleDeprecated,
-	useGetServiceAccountRoles,
+	useCreateServiceAccountRole,
+	useDeleteServiceAccountRole,
+	useGetServiceAccount,
 } from 'api/generated/services/serviceaccount';
-import type { AuthtypesGettableRoleDTO } from 'api/generated/services/sigNoz.schemas';
+import type {
+	AuthtypesGettableRoleDTO,
+	ServiceaccounttypesServiceAccountRoleDTO,
+} from 'api/generated/services/sigNoz.schemas';
 import { retryOn429 } from 'utils/errorUtils';
 
 const enum PromiseStatus {
-	Fulfilled = 'fulfilled',
 	Rejected = 'rejected',
 }
 
+// Stable identity so the memos below do not recompute on every render.
+const EMPTY_SERVICE_ACCOUNT_ROLES: ServiceaccounttypesServiceAccountRoleDTO[] =
+	[];
+
 export interface RoleUpdateFailure {
 	roleName: string;
 	error: unknown;
@@ -33,34 +37,40 @@ export function useServiceAccountRoleManager(
 	accountId: string,
 	options?: { enabled?: boolean },
 ): UseServiceAccountRoleManagerResult {
-	const queryClient = useQueryClient();
-
-	const { data, isLoading } = useGetServiceAccountRoles(
+	const { data, isLoading } = useGetServiceAccount(
 		{ id: accountId },
 		{ query: { enabled: options?.enabled ?? true } },
 	);
 
+	const serviceAccountRoles =
+		data?.data?.serviceAccountRoles ?? EMPTY_SERVICE_ACCOUNT_ROLES;
+
 	const currentRoles = useMemo<AuthtypesGettableRoleDTO[]>(
-		() => data?.data ?? [],
-		[data?.data],
+		() =>
+			serviceAccountRoles.map((serviceAccountRole) => serviceAccountRole.role),
+		[serviceAccountRoles],
+	);
+
+	// DELETE /api/v1/service_account_roles/{id} is keyed by the join row, not the role.
+	const assignmentIdByRoleId = useMemo(
+		() =>
+			new Map(
+				serviceAccountRoles.map((serviceAccountRole) => [
+					serviceAccountRole.roleId,
+					serviceAccountRole.id,
+				]),
+			),
+		[serviceAccountRoles],
 	);
 
 	// the retry for these mutations is safe due to being idempotent on backend
-	const { mutateAsync: createRole } = useCreateServiceAccountRoleDeprecated({
+	const { mutateAsync: createRole } = useCreateServiceAccountRole({
 		mutation: { retry: retryOn429 },
 	});
-	const { mutateAsync: deleteRole } = useDeleteServiceAccountRoleDeprecated({
+	const { mutateAsync: deleteRole } = useDeleteServiceAccountRole({
 		mutation: { retry: retryOn429 },
 	});
 
-	const invalidateRoles = useCallback(
-		() =>
-			queryClient.invalidateQueries(
-				getGetServiceAccountRolesQueryKey({ id: accountId }),
-			),
-		[accountId, queryClient],
-	);
-
 	const applyDiff = useCallback(
 		async (
 			localRoleIds: string[],
@@ -84,26 +94,34 @@ export function useServiceAccountRoleManager(
 				...addedRoles.map((role) => ({
 					role,
 					run: (): ReturnType<typeof createRole> =>
-						createRole({ pathParams: { id: accountId }, data: { id: role.id } }),
-				})),
-				...removedRoles.map((role) => ({
-					role,
-					run: (): ReturnType<typeof deleteRole> =>
-						deleteRole({ pathParams: { id: accountId, rid: role.id ?? '' } }),
+						createRole({
+							data: { serviceAccountId: accountId, roleId: role.id ?? '' },
+						}),
 				})),
+				...removedRoles
+					.map((role) => ({
+						role,
+						assignmentId: assignmentIdByRoleId.get(role.id ?? ''),
+					}))
+					.filter(
+						(
+							entry,
+						): entry is {
+							role: AuthtypesGettableRoleDTO;
+							assignmentId: string;
+						} => !!entry.assignmentId,
+					)
+					.map(({ role, assignmentId }) => ({
+						role,
+						run: (): ReturnType<typeof deleteRole> =>
+							deleteRole({ pathParams: { id: assignmentId } }),
+					})),
 			];
 
 			const results = await Promise.allSettled(
 				allOperations.map((op) => op.run()),
 			);
 
-			const successCount = results.filter(
-				(r) => r.status === PromiseStatus.Fulfilled,
-			).length;
-			if (successCount > 0) {
-				await invalidateRoles();
-			}
-
 			const failures: RoleUpdateFailure[] = [];
 			results.forEach((result, index) => {
 				if (result.status === PromiseStatus.Rejected) {
@@ -113,7 +131,6 @@ export function useServiceAccountRoleManager(
 						error: result.reason,
 						onRetry: async (): Promise<void> => {
 							await run();
-							await invalidateRoles();
 						},
 					});
 				}
@@ -121,7 +138,7 @@ export function useServiceAccountRoleManager(
 
 			return failures;
 		},
-		[accountId, currentRoles, createRole, deleteRole, invalidateRoles],
+		[accountId, currentRoles, assignmentIdByRoleId, createRole, deleteRole],
 	);
 
 	return {

frontend/src/pages/DashboardPageV2/DashboardContainer/PanelsAndSectionsLayout/Panel/__tests__/useViewPanel.addons.test.tsx

@@ -46,11 +46,23 @@ beforeAll(() => {
 });
 
 // jest.config maps the real hook to a no-op mock; this suite needs real navigation.
-jest.mock('hooks/useSafeNavigate', () =>
-	jest
-		.requireActual('tests/browser-history-safe-navigate')
-		.createBrowserHistorySafeNavigateMock(),
-);
+jest.mock('hooks/useSafeNavigate', () => {
+	const { useHistory } = jest.requireActual('react-router-dom');
+	return {
+		useSafeNavigate: (): unknown => {
+			const history = useHistory();
+			return {
+				safeNavigate: (to: string, opts?: { replace?: boolean }): void => {
+					if (opts?.replace) {
+						history.replace(to);
+					} else {
+						history.push(to);
+					}
+				},
+			};
+		},
+	};
+});
 
 jest.mock('api/querySuggestions/getKeySuggestions', () => ({
 	getKeySuggestions: jest
@@ -192,12 +204,9 @@ function Harness(): JSX.Element {
 	);
 }
 
-const INITIAL_ROUTE = '/dashboard/dash-1';
-
 const renderHarness = (): void => {
-	window.history.replaceState(null, '', INITIAL_ROUTE);
 	render(
-		<MemoryRouter initialEntries={[INITIAL_ROUTE]}>
+		<MemoryRouter initialEntries={['/dashboard/dash-1']}>
 			<CompatRouter>
 				<QueryClientProvider client={new QueryClient()}>
 					<ReduxProvider store={configureStore([])(appStore.getState())}>

frontend/src/pages/DashboardPageV2/DashboardContainer/PanelsAndSectionsLayout/Panel/__tests__/useViewPanel.promql.test.tsx

@@ -16,11 +16,23 @@ import ViewPanelModal from '../ViewPanelModal/ViewPanelModal';
 import { useViewPanel } from '../hooks/useViewPanel';
 
 // jest.config maps the real hook to a no-op mock; this suite needs real navigation.
-jest.mock('hooks/useSafeNavigate', () =>
-	jest
-		.requireActual('tests/browser-history-safe-navigate')
-		.createBrowserHistorySafeNavigateMock(),
-);
+jest.mock('hooks/useSafeNavigate', () => {
+	const { useHistory } = jest.requireActual('react-router-dom');
+	return {
+		useSafeNavigate: (): unknown => {
+			const history = useHistory();
+			return {
+				safeNavigate: (to: string, opts?: { replace?: boolean }): void => {
+					if (opts?.replace) {
+						history.replace(to);
+					} else {
+						history.push(to);
+					}
+				},
+			};
+		},
+	};
+});
 
 jest.mock(
 	'pages/DashboardPageV2/DashboardContainer/hooks/usePanelQuery',
@@ -138,12 +150,9 @@ function Harness(): JSX.Element {
 	);
 }
 
-const INITIAL_ROUTE = '/dashboard/dash-1';
-
 const renderHarness = (): void => {
-	window.history.replaceState(null, '', INITIAL_ROUTE);
 	render(
-		<MemoryRouter initialEntries={[INITIAL_ROUTE]}>
+		<MemoryRouter initialEntries={['/dashboard/dash-1']}>
 			<CompatRouter>
 				<QueryClientProvider client={new QueryClient()}>
 					<ReduxProvider store={configureStore([])(appStore.getState())}>

frontend/src/pages/DashboardPageV2/DashboardContainer/PanelsAndSectionsLayout/Panel/__tests__/useViewPanel.test.tsx

@@ -14,11 +14,23 @@ import { useViewPanelMode } from '../ViewPanelModal/useViewPanelMode';
 import { useViewPanel } from '../hooks/useViewPanel';
 
 // jest.config maps the real hook to a no-op mock; this suite needs real navigation.
-jest.mock('hooks/useSafeNavigate', () =>
-	jest
-		.requireActual('tests/browser-history-safe-navigate')
-		.createBrowserHistorySafeNavigateMock(),
-);
+jest.mock('hooks/useSafeNavigate', () => {
+	const { useHistory } = jest.requireActual('react-router-dom');
+	return {
+		useSafeNavigate: (): unknown => {
+			const history = useHistory();
+			return {
+				safeNavigate: (to: string, opts?: { replace?: boolean }): void => {
+					if (opts?.replace) {
+						history.replace(to);
+					} else {
+						history.push(to);
+					}
+				},
+			};
+		},
+	};
+});
 
 jest.mock(
 	'pages/DashboardPageV2/DashboardContainer/hooks/usePanelQuery',
@@ -172,12 +184,9 @@ function Harness(): JSX.Element {
 	);
 }
 
-const INITIAL_ROUTE = '/dashboard/dash-1';
-
 const renderHarness = (): void => {
-	window.history.replaceState(null, '', INITIAL_ROUTE);
 	render(
-		<MemoryRouter initialEntries={[INITIAL_ROUTE]}>
+		<MemoryRouter initialEntries={['/dashboard/dash-1']}>
 			<CompatRouter>
 				<QueryBuilderProvider>
 					<Harness />

frontend/src/providers/QueryBuilder.tsx

@@ -37,6 +37,7 @@ import { OptionsQuery } from 'container/OptionsMenu/types';
 import { useGetCompositeQueryParam } from 'hooks/queryBuilder/useGetCompositeQueryParam';
 import { updateStepInterval } from 'hooks/queryBuilder/useStepInterval';
 import { useSafeNavigate } from 'hooks/useSafeNavigate';
+import useUrlQuery from 'hooks/useUrlQuery';
 import { createIdFromObjectFields } from 'lib/createIdFromObjectFields';
 import { createNewBuilderItemName } from 'lib/newQueryBuilder/createNewBuilderItemName';
 import { getOperatorsBySourceAndPanelType } from 'lib/newQueryBuilder/getOperatorsBySourceAndPanelType';
@@ -65,7 +66,6 @@ import {
 } from 'types/common/queryBuilder';
 import { sanitizeOrderByForExplorer } from 'utils/sanitizeOrderBy';
 import { v4 as uuid } from 'uuid';
-import { getUnstableCurrentSearchParams } from 'utils/getUnstableCurrentSearchParams';
 
 export const QueryBuilderContext = createContext<QueryBuilderContextType>({
 	currentQuery: initialQueriesMap.metrics,
@@ -105,6 +105,7 @@ export const QueryBuilderContext = createContext<QueryBuilderContextType>({
 export function QueryBuilderProvider({
 	children,
 }: PropsWithChildren): JSX.Element {
+	const urlQuery = useUrlQuery();
 	const location = useLocation();
 
 	const currentPathnameRef = useRef<string | null>(location.pathname);
@@ -121,7 +122,7 @@ export function QueryBuilderProvider({
 		null,
 	);
 
-	const panelTypeQueryParams = getUnstableCurrentSearchParams().get(
+	const panelTypeQueryParams = urlQuery.get(
 		QueryParams.panelTypes,
 	) as PANEL_TYPES | null;
 
@@ -975,7 +976,6 @@ export function QueryBuilderProvider({
 				unit: query.unit || initialQueryState.unit,
 			};
 
-			const urlQuery = getUnstableCurrentSearchParams();
 			const pagination = urlQuery.get(QueryParams.pagination);
 
 			if (pagination) {
@@ -1014,7 +1014,7 @@ export function QueryBuilderProvider({
 
 			safeNavigate(generatedUrl, { newTab });
 		},
-		[location.pathname, safeNavigate],
+		[location.pathname, safeNavigate, urlQuery],
 	);
 
 	const handleSetConfig = useCallback(

frontend/src/tests/browser-history-safe-navigate.ts

@@ -1,54 +0,0 @@
-// Mock factory for suites that need `useSafeNavigate` to navigate for real.
-//
-// `jest.config.ts` maps every `hooks/useSafeNavigate` import to the no-op
-// `__tests__/safeNavigateMock.ts`, so a suite that drives navigation has to opt
-// out with its own `jest.mock`.
-//
-// In production `safeNavigate` goes through `createBrowserHistory`, which writes
-// `window.location` as well as notifying the router. `MemoryRouter` never touches
-// `window`, so anything reading `getUnstableCurrentSearchParams()` sees an empty
-// search and drops the params the test just navigated with. This mock writes both.
-//
-// The `jest.mock` factory is hoisted above imports, so require it inside:
-//
-//   jest.mock('hooks/useSafeNavigate', () =>
-//     jest
-//       .requireActual('tests/browser-history-safe-navigate')
-//       .createBrowserHistorySafeNavigateMock(),
-//   );
-
-import type { History } from 'history';
-
-interface SafeNavigateOptions {
-	replace?: boolean;
-}
-
-interface UseSafeNavigateModule {
-	useSafeNavigate: () => {
-		safeNavigate: (to: string, options?: SafeNavigateOptions) => void;
-	};
-}
-
-export function createBrowserHistorySafeNavigateMock(): UseSafeNavigateModule {
-	const { useHistory } = jest.requireActual<{ useHistory: () => History }>(
-		'react-router-dom',
-	);
-
-	return {
-		useSafeNavigate: () => {
-			const history = useHistory();
-
-			return {
-				safeNavigate: (to: string, options?: SafeNavigateOptions): void => {
-					if (options?.replace) {
-						window.history.replaceState(null, '', to);
-						history.replace(to);
-					} else {
-						window.history.pushState(null, '', to);
-						history.push(to);
-					}
-				},
-			};
-		},
-	};
-}

pkg/flagger/registry.go

@@ -3,16 +3,17 @@ package flagger
 import "github.com/SigNoz/signoz/pkg/types/featuretypes"
 
 var (
-	FeatureUseSpanMetrics         = featuretypes.MustNewName("use_span_metrics")
-	FeatureKafkaSpanEval          = featuretypes.MustNewName("kafka_span_eval")
-	FeatureHideRootUser           = featuretypes.MustNewName("hide_root_user")
-	FeatureGetMetersFromZeus      = featuretypes.MustNewName("get_meters_from_zeus")
-	FeaturePutMetersInZeus        = featuretypes.MustNewName("put_meters_in_zeus")
-	FeatureUseMeterReporter       = featuretypes.MustNewName("use_meter_reporter")
-	FeatureUseJSONBody            = featuretypes.MustNewName("use_json_body")
-	FeatureEnableAIObservability  = featuretypes.MustNewName("enable_ai_observability")
-	FeatureEnableMetricsReduction = featuretypes.MustNewName("enable_metrics_reduction")
+	FeatureUseSpanMetrics            = featuretypes.MustNewName("use_span_metrics")
+	FeatureKafkaSpanEval             = featuretypes.MustNewName("kafka_span_eval")
+	FeatureHideRootUser              = featuretypes.MustNewName("hide_root_user")
+	FeatureGetMetersFromZeus         = featuretypes.MustNewName("get_meters_from_zeus")
+	FeaturePutMetersInZeus           = featuretypes.MustNewName("put_meters_in_zeus")
+	FeatureUseMeterReporter          = featuretypes.MustNewName("use_meter_reporter")
+	FeatureUseJSONBody               = featuretypes.MustNewName("use_json_body")
+	FeatureEnableAIObservability     = featuretypes.MustNewName("enable_ai_observability")
+	FeatureEnableMetricsReduction    = featuretypes.MustNewName("enable_metrics_reduction")
 	FeatureUsePrometheusClickhouseV2 = featuretypes.MustNewName("use_prometheus_clickhouse_v2")
+	FeatureResolveSemconvFamilies    = featuretypes.MustNewName("resolve_semconv_families")
 )
 
 func MustNewRegistry() featuretypes.Registry {
@@ -97,6 +98,14 @@ func MustNewRegistry() featuretypes.Registry {
 			DefaultVariant: featuretypes.MustNewName("disabled"),
 			Variants:       featuretypes.NewBooleanVariants(),
 		},
+		&featuretypes.Feature{
+			Name:           FeatureResolveSemconvFamilies,
+			Kind:           featuretypes.KindBoolean,
+			Stage:          featuretypes.StageExperimental,
+			Description:    "Controls whether trace queries resolve a semantic-convention name to all the spellings of its family",
+			DefaultVariant: featuretypes.MustNewName("disabled"),
+			Variants:       featuretypes.NewBooleanVariants(),
+		},
 	)
 	if err != nil {
 		panic(err)

pkg/modules/rulestatehistory/implrulestatehistory/condition_builder.go

@@ -40,7 +40,10 @@ func (c *conditionBuilder) ConditionFor(
 		return nil, nil, err
 	}
 
-	keys, warning := querybuilder.ResolveKeys(key, querybuilder.MatchingFieldKeys(key, fieldKeys))
+	// Rule state history fields have no family support, so every logical field
+	// is single-member and flattens losslessly to its physical key.
+	resolved, warning := querybuilder.ResolveLogicalFields(key, querybuilder.MatchingLogicalFields(ctx, orgID, nil, key, fieldKeys))
+	keys := querybuilder.SingleKeys(resolved)
 	var warnings []string
 	if warning != "" {
 		warnings = append(warnings, warning)
@@ -138,9 +141,9 @@ func (c *conditionBuilder) conditionForKey(
 			return "true", nil
 		}
 		if operator == qbtypes.FilterOperatorExists {
-			return fmt.Sprintf("has(JSONExtractKeys(labels), %s)", sb.Var(key.Name)), nil
+			return fmt.Sprintf("JSONHas(labels, %s)", sb.Var(key.Name)), nil
 		}
-		return fmt.Sprintf("not has(JSONExtractKeys(labels), %s)", sb.Var(key.Name)), nil
+		return fmt.Sprintf("not JSONHas(labels, %s)", sb.Var(key.Name)), nil
 	}
 
 	return "", errors.NewInvalidInputf(errors.CodeInvalidInput, "unsupported operator: %v", operator)

pkg/modules/rulestatehistory/implrulestatehistory/field_mapper.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 
 	schema "github.com/SigNoz/signoz-otel-collector/cmd/signozschemamigrator/schema_migrator"
+	"github.com/SigNoz/signoz/pkg/querybuilder"
 	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"github.com/SigNoz/signoz/pkg/valuer"
@@ -51,7 +52,7 @@ func (m *fieldMapper) FieldFor(ctx context.Context, _ valuer.UUID, _, _ uint64,
 		return "", err
 	}
 	if col.Name == "labels" && key.Name != "labels" {
-		return fmt.Sprintf("JSONExtractString(labels, '%s')", strings.ReplaceAll(key.Name, "'", "\\'")), nil
+		return fmt.Sprintf("JSONExtractString(labels, %s)", querybuilder.ClickHouseStringLiteral(key.Name)), nil
 	}
 	return col.Name, nil
 }
@@ -64,10 +65,28 @@ func (m *fieldMapper) ColumnFor(ctx context.Context, _ valuer.UUID, _, _ uint64,
 	return []*schema.Column{col}, nil
 }
 
+// ExistsFor implements the per-key existence primitive of qbtypes.FieldMapper.
+// A label inside the JSON gets a membership check, with the same condition
+// that FieldFor uses for extraction; every real column always exists.
+func (m *fieldMapper) ExistsFor(ctx context.Context, _ valuer.UUID, _, _ uint64, key *telemetrytypes.TelemetryFieldKey, exists bool) (string, error) {
+	col, err := m.getColumn(ctx, key)
+	if err != nil {
+		return "", err
+	}
+	if col.Name == "labels" && key.Name != "labels" {
+		pred := fmt.Sprintf("JSONHas(labels, %s)", querybuilder.ClickHouseStringLiteral(key.Name))
+		if exists {
+			return pred, nil
+		}
+		return "not " + pred, nil
+	}
+	return "true", nil
+}
+
 func (m *fieldMapper) ColumnExpressionFor(ctx context.Context, orgID valuer.UUID, tsStart, tsEnd uint64, field *telemetrytypes.TelemetryFieldKey, _ telemetrytypes.FieldDataType, _ map[string][]*telemetrytypes.TelemetryFieldKey) (string, error) {
 	colName, err := m.FieldFor(ctx, orgID, tsStart, tsEnd, field)
 	if err != nil {
 		return "", err
 	}
-	return fmt.Sprintf("%s AS `%s`", sqlbuilder.Escape(colName), field.Name), nil
+	return fmt.Sprintf("%s AS %s", sqlbuilder.Escape(colName), querybuilder.ClickHouseIdentifier(field.Name)), nil
 }

pkg/modules/user/impluser/store.go

@@ -274,6 +274,15 @@ func (store *store) SoftDeleteUser(ctx context.Context, orgID string, id string)
 		return errors.Wrapf(err, errors.TypeInternal, errors.CodeInternal, "failed to delete tokens")
 	}
 
+	// delete user_role assignments so the roles can be deleted later
+	_, err = tx.NewDelete().
+		Model(new(authtypes.UserRole)).
+		Where("user_id = ?", id).
+		Exec(ctx)
+	if err != nil {
+		return errors.Wrapf(err, errors.TypeInternal, errors.CodeInternal, "failed to delete user roles")
+	}
+
 	// soft delete user
 	now := time.Now()
 	_, err = tx.NewUpdate().

pkg/querybuilder/clickhouse_quote.go

@@ -0,0 +1,17 @@
+package querybuilder
+
+import "strings"
+
+// ClickHouseStringLiteral quotes a value for a ClickHouse string literal.
+func ClickHouseStringLiteral(value string) string {
+	escaped := strings.ReplaceAll(value, `\`, `\\`)
+	escaped = strings.ReplaceAll(escaped, `'`, `\'`)
+	return "'" + escaped + "'"
+}
+
+// ClickHouseIdentifier quotes a value for a ClickHouse identifier.
+func ClickHouseIdentifier(value string) string {
+	escaped := strings.ReplaceAll(value, `\`, `\\`)
+	escaped = strings.ReplaceAll(escaped, "`", "\\`")
+	return "`" + escaped + "`"
+}

pkg/querybuilder/clickhouse_quote_test.go

@@ -0,0 +1,17 @@
+package querybuilder
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestClickHouseQuoting(t *testing.T) {
+	t.Run("string literal", func(t *testing.T) {
+		assert.Equal(t, `'name\'\\); SELECT 1 --'`, ClickHouseStringLiteral(`name'\); SELECT 1 --`))
+	})
+
+	t.Run("identifier", func(t *testing.T) {
+		assert.Equal(t, "`name\\`\\\\); SELECT 1 --`", ClickHouseIdentifier("name`\\); SELECT 1 --"))
+	})
+}

pkg/querybuilder/exists_expr.go

@@ -43,7 +43,7 @@ func ExistsExpression(columns []*schema.Column, key *telemetrytypes.TelemetryFie
 		if len(evolutionsEntries) > 0 && evolutionsEntries[0] != nil {
 			columnName = evolutionsEntries[0].ColumnName
 		}
-		rawPath := fmt.Sprintf("%s.`%s`", columnName, key.Name)
+		rawPath := fmt.Sprintf("%s.%s", columnName, ClickHouseIdentifier(key.Name))
 		if exists {
 			return rawPath + " IS NOT NULL", nil
 		}
@@ -88,7 +88,7 @@ func ExistsExpression(columns []*schema.Column, key *telemetrytypes.TelemetryFie
 
 		switch valueType := column.Type.(schema.MapColumnType).ValueType; valueType.GetType() {
 		case schema.ColumnTypeEnumString, schema.ColumnTypeEnumBool, schema.ColumnTypeEnumFloat64:
-			leftOperand := fmt.Sprintf("mapContains(%s, '%s')", column.Name, key.Name)
+			leftOperand := fmt.Sprintf("mapContains(%s, %s)", column.Name, ClickHouseStringLiteral(key.Name))
 			if key.Materialized {
 				leftOperand = telemetrytypes.FieldKeyToMaterializedColumnNameForExists(key)
 			}

pkg/querybuilder/family_selectors.go

@@ -0,0 +1,64 @@
+package querybuilder
+
+import (
+	"context"
+
+	"github.com/SigNoz/signoz/pkg/flagger"
+	"github.com/SigNoz/signoz/pkg/semconv"
+	"github.com/SigNoz/signoz/pkg/types/featuretypes"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/valuer"
+)
+
+// semconvFamiliesEnabled evaluates the resolve_semconv_families flag for the
+// org. A nil flagger means off, so a caller without family support stays
+// literal by default.
+func semconvFamiliesEnabled(ctx context.Context, orgID valuer.UUID, fl flagger.Flagger) bool {
+	if fl == nil {
+		return false
+	}
+	return fl.BooleanOrEmpty(ctx, flagger.FeatureResolveSemconvFamilies, featuretypes.NewFlaggerEvaluationContext(orgID))
+}
+
+// ExpandKeySelectorsForFamilies adds selectors for the other members of each
+// semantic-convention family that a selector names. The metadata fetched for
+// a query then contains each spelling that MatchingLogicalFields can group.
+// This function is the prefetch of the resolution layer: statement builders
+// call it after they derive the selectors, and the metadata store stays
+// family-blind (autocomplete responses keep the literal spelling that the
+// user typed). It does nothing when the resolve_semconv_families flag is off
+// for the org. Only trace selectors expand today, because that matches the
+// family support. Fuzzy (search-style) selectors never expand.
+func ExpandKeySelectorsForFamilies(ctx context.Context, orgID valuer.UUID, fl flagger.Flagger, selectors []*telemetrytypes.FieldKeySelector) []*telemetrytypes.FieldKeySelector {
+	if !semconvFamiliesEnabled(ctx, orgID, fl) {
+		return selectors
+	}
+
+	out := selectors
+	seen := make(map[string]bool, len(selectors))
+	for _, selector := range selectors {
+		seen[selector.Name] = true
+	}
+
+	for _, selector := range selectors {
+		if selector.Signal != telemetrytypes.SignalTraces ||
+			selector.SelectorMatchType == telemetrytypes.FieldSelectorMatchTypeFuzzy {
+			continue
+		}
+		members := semconv.Members(semconv.KindAttribute, telemetrytypes.FieldKeySelector{
+			Name:         selector.Name,
+			Signal:       selector.Signal,
+			FieldContext: selector.FieldContext,
+		})
+		for _, member := range members {
+			if seen[member] {
+				continue
+			}
+			seen[member] = true
+			expanded := *selector
+			expanded.Name = member
+			out = append(out, &expanded)
+		}
+	}
+	return out
+}

pkg/querybuilder/key_resolution.go

@@ -21,24 +21,25 @@ const (
 	hasTokenFunctionDocURL       = "https://signoz.io/docs/userguide/functions-reference/#hastoken-function"
 )
 
-// ResolveKeys picks which matching field keys a filter term builds conditions for.
-// With 0 or 1 match it returns the input unchanged and no warning. When a name is
-// ambiguous it returns a warning; a resource+attribute mix defaults to the resource
-// keys (the common intent), noted in the warning.
-func ResolveKeys(field *telemetrytypes.TelemetryFieldKey, fieldKeysForName []*telemetrytypes.TelemetryFieldKey) ([]*telemetrytypes.TelemetryFieldKey, string) {
-	if len(fieldKeysForName) <= 1 {
-		return fieldKeysForName, ""
+// ResolveLogicalFields picks which logical fields a filter term builds conditions
+// for. With 0 or 1 field it returns the input unchanged and no warning. When a
+// name is ambiguous (several logical fields — a family is one field and never
+// ambiguous with itself) it returns a warning; a resource+attribute mix defaults
+// to the resource fields (the common intent), noted in the warning.
+func ResolveLogicalFields(field *telemetrytypes.TelemetryFieldKey, logicalFields []*telemetrytypes.LogicalField) ([]*telemetrytypes.LogicalField, string) {
+	if len(logicalFields) <= 1 {
+		return logicalFields, ""
 	}
 
 	warning := fmt.Sprintf(
 		"Key `%s` is ambiguous, found %d different combinations of field context / data type: %v.",
 		field.Name,
-		len(fieldKeysForName),
-		fieldKeysForName,
+		len(logicalFields),
+		logicalFields,
 	)
 
 	hasResource, hasAttribute := false, false
-	for _, item := range fieldKeysForName {
+	for _, item := range logicalFields {
 		switch item.FieldContext {
 		case telemetrytypes.FieldContextResource:
 			hasResource = true
@@ -49,18 +50,40 @@ func ResolveKeys(field *telemetrytypes.TelemetryFieldKey, fieldKeysForName []*te
 
 	// when there is both resource and attribute context, default to resource only
 	if hasResource && hasAttribute {
-		filteredKeys := make([]*telemetrytypes.TelemetryFieldKey, 0, len(fieldKeysForName))
-		for _, item := range fieldKeysForName {
+		filtered := make([]*telemetrytypes.LogicalField, 0, len(logicalFields))
+		for _, item := range logicalFields {
 			if item.FieldContext == telemetrytypes.FieldContextResource {
-				filteredKeys = append(filteredKeys, item)
+				filtered = append(filtered, item)
 			}
 		}
-		fieldKeysForName = filteredKeys
+		logicalFields = filtered
 		warning += " " + "Using `resource` context by default. To query attributes explicitly, " +
 			fmt.Sprintf("use the fully qualified name (e.g., 'attribute.%s')", field.Name)
 	}
 
-	return fieldKeysForName, warning
+	return logicalFields, warning
+}
+
+// WrapAsLogicalFields wraps physical keys (candidate or synthesized) as
+// single-member logical fields addressed by the requested spelling.
+func WrapAsLogicalFields(requestedName string, keys []*telemetrytypes.TelemetryFieldKey) []*telemetrytypes.LogicalField {
+	fields := make([]*telemetrytypes.LogicalField, 0, len(keys))
+	for _, key := range keys {
+		fields = append(fields, telemetrytypes.SingleLogicalField(requestedName, key))
+	}
+	return fields
+}
+
+// SingleKeys flattens logical fields to their single members. It is the
+// adapter for signals whose fields are single-member by construction (every
+// signal without family support); their condition builders keep compiling per
+// physical key.
+func SingleKeys(fields []*telemetrytypes.LogicalField) []*telemetrytypes.TelemetryFieldKey {
+	keys := make([]*telemetrytypes.TelemetryFieldKey, 0, len(fields))
+	for _, field := range fields {
+		keys = append(keys, field.Single())
+	}
+	return keys
 }
 
 // NewKeyNotFoundError builds the error a condition builder returns when a filter term

pkg/querybuilder/logical_expr.go

@@ -0,0 +1,96 @@
+package querybuilder
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/valuer"
+)
+
+// The two functions below are the only place family expressions are built.
+// They compose exclusively from the mapper's per-key primitives (FieldFor,
+// ExistsFor), so every member honors its own storage: materialized columns,
+// evolutions, and JSON plans ride the member keys, and a signal supports
+// families the moment its primitives are correct.
+
+// LogicalValueExpr returns the value expression for a resolved logical field:
+// the member's own expression for a single-member field, and a current-first
+// merge across the members' expressions for a family.
+func LogicalValueExpr(
+	ctx context.Context,
+	orgID valuer.UUID,
+	tsStart, tsEnd uint64,
+	fm qbtypes.FieldMapper,
+	logical *telemetrytypes.LogicalField,
+) (string, error) {
+	if !logical.IsFamily() {
+		return fm.FieldFor(ctx, orgID, tsStart, tsEnd, logical.Single())
+	}
+
+	memberExprs := make([]string, 0, len(logical.Members))
+	for _, member := range logical.Members {
+		expr, err := fm.FieldFor(ctx, orgID, tsStart, tsEnd, member)
+		if err != nil {
+			return "", err
+		}
+		memberExprs = append(memberExprs, expr)
+	}
+
+	if logical.FieldDataType == telemetrytypes.FieldDataTypeString {
+		// The trailing '' keeps single-key semantics for rows without any
+		// member: string maps read '' for an absent key, and negative
+		// operators must keep including such rows (see AddDefaultExistsFilter).
+		// A NULL tail would drop them: NULL != 'x' evaluates to NULL, and the
+		// row falls out of the result.
+		values := make([]string, 0, len(memberExprs))
+		for _, expr := range memberExprs {
+			values = append(values, fmt.Sprintf("NULLIF(%s, '')", expr))
+		}
+		return "COALESCE(" + strings.Join(values, ", ") + ", '')", nil
+	}
+
+	// Numeric and boolean maps return zero for an absent key. If a family of
+	// either type is enabled, this tail must become zero too.
+	branches := make([]string, 0, len(logical.Members)*2)
+	for i, member := range logical.Members {
+		guard, err := fm.ExistsFor(ctx, orgID, tsStart, tsEnd, member, true)
+		if err != nil {
+			return "", err
+		}
+		branches = append(branches, guard, memberExprs[i])
+	}
+	return "multiIf(" + strings.Join(branches, ", ") + ", NULL)", nil
+}
+
+// LogicalExistsExpr returns the existence predicate for a resolved logical
+// field: the member's own predicate for a single-member field, presence of
+// any member for a family.
+func LogicalExistsExpr(
+	ctx context.Context,
+	orgID valuer.UUID,
+	tsStart, tsEnd uint64,
+	fm qbtypes.FieldMapper,
+	logical *telemetrytypes.LogicalField,
+	exists bool,
+) (string, error) {
+	if !logical.IsFamily() {
+		return fm.ExistsFor(ctx, orgID, tsStart, tsEnd, logical.Single(), exists)
+	}
+
+	guards := make([]string, 0, len(logical.Members))
+	for _, member := range logical.Members {
+		guard, err := fm.ExistsFor(ctx, orgID, tsStart, tsEnd, member, true)
+		if err != nil {
+			return "", err
+		}
+		guards = append(guards, guard)
+	}
+	combined := "(" + strings.Join(guards, " OR ") + ")"
+	if exists {
+		return combined, nil
+	}
+	return "NOT " + combined, nil
+}

pkg/querybuilder/logical_expr_test.go

@@ -0,0 +1,95 @@
+package querybuilder
+
+import (
+	"context"
+	"testing"
+
+	schema "github.com/SigNoz/signoz-otel-collector/cmd/signozschemamigrator/schema_migrator"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/valuer"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// stubFieldMapper provides just the two per-key primitives the shared
+// composition builds on; the remaining FieldMapper methods are unused here.
+type stubFieldMapper struct{}
+
+func (stubFieldMapper) FieldFor(_ context.Context, _ valuer.UUID, _, _ uint64, key *telemetrytypes.TelemetryFieldKey) (string, error) {
+	return "value(" + key.Name + ")", nil
+}
+
+func (stubFieldMapper) ExistsFor(_ context.Context, _ valuer.UUID, _, _ uint64, key *telemetrytypes.TelemetryFieldKey, exists bool) (string, error) {
+	if exists {
+		return "has(" + key.Name + ")", nil
+	}
+	return "NOT has(" + key.Name + ")", nil
+}
+
+func (stubFieldMapper) ColumnFor(context.Context, valuer.UUID, uint64, uint64, *telemetrytypes.TelemetryFieldKey) ([]*schema.Column, error) {
+	return nil, qbtypes.ErrColumnNotFound
+}
+
+func (stubFieldMapper) ColumnExpressionFor(context.Context, valuer.UUID, uint64, uint64, *telemetrytypes.TelemetryFieldKey, telemetrytypes.FieldDataType, map[string][]*telemetrytypes.TelemetryFieldKey) (string, error) {
+	return "", qbtypes.ErrColumnNotFound
+}
+
+func (stubFieldMapper) CandidateKeys(context.Context, valuer.UUID, *telemetrytypes.TelemetryFieldKey, any, map[string][]*telemetrytypes.TelemetryFieldKey) []*telemetrytypes.TelemetryFieldKey {
+	return nil
+}
+
+func stringFamily(names ...string) *telemetrytypes.LogicalField {
+	members := make([]*telemetrytypes.TelemetryFieldKey, 0, len(names))
+	for _, name := range names {
+		members = append(members, &telemetrytypes.TelemetryFieldKey{Name: name, FieldDataType: telemetrytypes.FieldDataTypeString})
+	}
+	return &telemetrytypes.LogicalField{Name: names[0], FieldDataType: telemetrytypes.FieldDataTypeString, Members: members}
+}
+
+func TestLogicalValueExprSingleMemberDelegatesToFieldFor(t *testing.T) {
+	logical := telemetrytypes.SingleLogicalField("a", &telemetrytypes.TelemetryFieldKey{Name: "a"})
+	expr, err := LogicalValueExpr(context.Background(), valuer.UUID{}, 0, 0, stubFieldMapper{}, logical)
+	require.NoError(t, err)
+	assert.Equal(t, "value(a)", expr)
+}
+
+func TestLogicalValueExprStringFamilyMergesCurrentFirst(t *testing.T) {
+	expr, err := LogicalValueExpr(context.Background(), valuer.UUID{}, 0, 0, stubFieldMapper{}, stringFamily("current", "old"))
+	require.NoError(t, err)
+	// The trailing '' preserves keyless-row semantics for negative operators.
+	assert.Equal(t, "COALESCE(NULLIF(value(current), ''), NULLIF(value(old), ''), '')", expr)
+}
+
+func TestLogicalValueExprNumericFamilyGuardsEveryMember(t *testing.T) {
+	logical := &telemetrytypes.LogicalField{
+		Name:          "current",
+		FieldDataType: telemetrytypes.FieldDataTypeNumber,
+		Members: []*telemetrytypes.TelemetryFieldKey{
+			{Name: "current", FieldDataType: telemetrytypes.FieldDataTypeNumber},
+			{Name: "old", FieldDataType: telemetrytypes.FieldDataTypeNumber},
+		},
+	}
+	expr, err := LogicalValueExpr(context.Background(), valuer.UUID{}, 0, 0, stubFieldMapper{}, logical)
+	require.NoError(t, err)
+	assert.Equal(t, "multiIf(has(current), value(current), has(old), value(old), NULL)", expr)
+}
+
+func TestLogicalExistsExprSingleMemberDelegatesToExistsFor(t *testing.T) {
+	logical := telemetrytypes.SingleLogicalField("a", &telemetrytypes.TelemetryFieldKey{Name: "a"})
+	expr, err := LogicalExistsExpr(context.Background(), valuer.UUID{}, 0, 0, stubFieldMapper{}, logical, false)
+	require.NoError(t, err)
+	assert.Equal(t, "NOT has(a)", expr)
+}
+
+func TestLogicalExistsExprFamilyIsAnyMemberPresence(t *testing.T) {
+	family := stringFamily("current", "old")
+
+	expr, err := LogicalExistsExpr(context.Background(), valuer.UUID{}, 0, 0, stubFieldMapper{}, family, true)
+	require.NoError(t, err)
+	assert.Equal(t, "(has(current) OR has(old))", expr)
+
+	expr, err = LogicalExistsExpr(context.Background(), valuer.UUID{}, 0, 0, stubFieldMapper{}, family, false)
+	require.NoError(t, err)
+	assert.Equal(t, "NOT (has(current) OR has(old))", expr)
+}

pkg/querybuilder/logical_fields_test.go

@@ -0,0 +1,239 @@
+package querybuilder
+
+import (
+	"context"
+	"testing"
+
+	"github.com/SigNoz/signoz/pkg/flagger"
+	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/valuer"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// familiesOn returns a flagger with resolve_semconv_families on.
+func familiesOn(t *testing.T) flagger.Flagger {
+	return flaggertest.WithBooleanFlags(t, map[string]bool{
+		flagger.FeatureResolveSemconvFamilies.String(): true,
+	})
+}
+
+func memberNames(logical *telemetrytypes.LogicalField) []string {
+	names := make([]string, 0, len(logical.Members))
+	for _, member := range logical.Members {
+		names = append(names, member.Name)
+	}
+	return names
+}
+
+// The deployment.environment(.name) family (enabled in pkg/semconv) drives the
+// grouping tests below.
+
+// With the resolve_semconv_families flag off, matches stay single-member and
+// selectors stay literal, even when the metadata map has both spellings.
+func TestFamiliesOffByDefault(t *testing.T) {
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+	}
+
+	fields := MatchingLogicalFields(context.Background(), valuer.UUID{}, flaggertest.New(t), &telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"}, fieldKeys)
+	require.Len(t, fields, 1)
+	assert.False(t, fields[0].IsFamily())
+	assert.Equal(t, []string{"deployment.environment.name"}, memberNames(fields[0]))
+
+	selectors := []*telemetrytypes.FieldKeySelector{
+		{Name: "deployment.environment.name", Signal: telemetrytypes.SignalTraces, SelectorMatchType: telemetrytypes.FieldSelectorMatchTypeExact},
+	}
+	assert.Len(t, ExpandKeySelectorsForFamilies(context.Background(), valuer.UUID{}, flaggertest.New(t), selectors), 1)
+}
+
+func TestMatchingLogicalFieldsGroupsFamilyMembers(t *testing.T) {
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+	}
+
+	for _, requested := range []string{"deployment.environment.name", "deployment.environment"} {
+		fields := MatchingLogicalFields(context.Background(), valuer.UUID{}, familiesOn(t), &telemetrytypes.TelemetryFieldKey{Name: requested}, fieldKeys)
+		require.Len(t, fields, 1, "a family is one logical field, requested via %s", requested)
+		logical := fields[0]
+		assert.Equal(t, requested, logical.Name, "response identity is the requested spelling")
+		assert.Equal(t, telemetrytypes.FieldContextResource, logical.FieldContext)
+		assert.True(t, logical.IsFamily())
+		assert.Equal(t, []string{"deployment.environment.name", "deployment.environment"}, memberNames(logical),
+			"members are current-first regardless of the requested spelling")
+	}
+}
+
+// Member precedence is the family's current-first order, not lookup arrival
+// order: a current-name key found only under its context-prefixed spelling
+// arrives in the second lookup pass yet must still sort first.
+func TestMatchingLogicalFieldsOrdersMembersByFamilyRank(t *testing.T) {
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+		"resource.deployment.environment.name": {{
+			Name:          "resource.deployment.environment.name",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+	}
+
+	fields := MatchingLogicalFields(context.Background(), valuer.UUID{}, familiesOn(t), &telemetrytypes.TelemetryFieldKey{
+		Name:         "deployment.environment.name",
+		FieldContext: telemetrytypes.FieldContextResource,
+	}, fieldKeys)
+
+	require.Len(t, fields, 1)
+	assert.Equal(t, []string{"resource.deployment.environment.name", "deployment.environment"}, memberNames(fields[0]))
+}
+
+// Non-trace signals have no family support: the requested spelling stays
+// literal, and a family member name never pulls in its siblings.
+func TestMatchingLogicalFieldsKeepsLogsLiteral(t *testing.T) {
+	logsKey := func(name string) *telemetrytypes.TelemetryFieldKey {
+		return &telemetrytypes.TelemetryFieldKey{
+			Name:          name,
+			Signal:        telemetrytypes.SignalLogs,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}
+	}
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {logsKey("deployment.environment.name")},
+		"deployment.environment":      {logsKey("deployment.environment")},
+	}
+
+	fields := MatchingLogicalFields(context.Background(), valuer.UUID{}, familiesOn(t), &telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"}, fieldKeys)
+	require.Len(t, fields, 1)
+	assert.False(t, fields[0].IsFamily())
+	assert.Equal(t, []string{"deployment.environment.name"}, memberNames(fields[0]))
+}
+
+// A family and a genuine same-name collision stack cleanly: the family stays
+// one logical field, the collision adds another, and resource preference keeps
+// the family as a unit.
+func TestResolveLogicalFieldsKeepsFamilyThroughAmbiguity(t *testing.T) {
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {
+			{
+				Name:          "deployment.environment.name",
+				Signal:        telemetrytypes.SignalTraces,
+				FieldContext:  telemetrytypes.FieldContextResource,
+				FieldDataType: telemetrytypes.FieldDataTypeString,
+			},
+			{
+				Name:          "deployment.environment.name",
+				Signal:        telemetrytypes.SignalTraces,
+				FieldContext:  telemetrytypes.FieldContextAttribute,
+				FieldDataType: telemetrytypes.FieldDataTypeString,
+			},
+		},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+	}
+
+	requested := &telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"}
+	fields := MatchingLogicalFields(context.Background(), valuer.UUID{}, familiesOn(t), requested, fieldKeys)
+	require.Len(t, fields, 2, "resource family + attribute collision")
+
+	resolved, warning := ResolveLogicalFields(requested, fields)
+	assert.NotEmpty(t, warning)
+	require.Len(t, resolved, 1)
+	assert.Equal(t, telemetrytypes.FieldContextResource, resolved[0].FieldContext)
+	assert.Equal(t, []string{"deployment.environment.name", "deployment.environment"}, memberNames(resolved[0]))
+}
+
+// Members of a family with different data types never merge: the identity
+// (signal, context, data type) separates them into distinct logical fields.
+func TestMatchingLogicalFieldsNeverMergesAcrossDataTypes(t *testing.T) {
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeNumber,
+		}},
+	}
+
+	fields := MatchingLogicalFields(context.Background(), valuer.UUID{}, familiesOn(t), &telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"}, fieldKeys)
+	require.Len(t, fields, 2)
+	for _, logical := range fields {
+		assert.False(t, logical.IsFamily())
+	}
+}
+
+func TestExpandKeySelectorsForFamilies(t *testing.T) {
+	selectors := []*telemetrytypes.FieldKeySelector{
+		{Name: "deployment.environment.name", Signal: telemetrytypes.SignalTraces, SelectorMatchType: telemetrytypes.FieldSelectorMatchTypeExact},
+		{Name: "service.name", Signal: telemetrytypes.SignalTraces, SelectorMatchType: telemetrytypes.FieldSelectorMatchTypeExact},
+		{Name: "deployment.environment.name", Signal: telemetrytypes.SignalLogs, SelectorMatchType: telemetrytypes.FieldSelectorMatchTypeExact},
+	}
+
+	expanded := ExpandKeySelectorsForFamilies(context.Background(), valuer.UUID{}, familiesOn(t), selectors)
+
+	names := make([]string, 0, len(expanded))
+	for _, selector := range expanded {
+		names = append(names, selector.Name)
+	}
+	assert.Equal(t, []string{
+		"deployment.environment.name",
+		"service.name",
+		"deployment.environment.name",
+		"deployment.environment",
+	}, names, "one sibling selector for the trace family member; logs and non-family names untouched")
+
+	sibling := expanded[len(expanded)-1]
+	assert.Equal(t, telemetrytypes.SignalTraces, sibling.Signal)
+	assert.Equal(t, telemetrytypes.FieldSelectorMatchTypeExact, sibling.SelectorMatchType)
+}
+
+func TestExpandKeySelectorsForFamiliesDeduplicatesAndSkipsFuzzy(t *testing.T) {
+	both := []*telemetrytypes.FieldKeySelector{
+		{Name: "deployment.environment.name", Signal: telemetrytypes.SignalTraces, SelectorMatchType: telemetrytypes.FieldSelectorMatchTypeExact},
+		{Name: "deployment.environment", Signal: telemetrytypes.SignalTraces, SelectorMatchType: telemetrytypes.FieldSelectorMatchTypeExact},
+	}
+	assert.Len(t, ExpandKeySelectorsForFamilies(context.Background(), valuer.UUID{}, familiesOn(t), both), 2, "both spellings already referenced")
+
+	fuzzy := []*telemetrytypes.FieldKeySelector{
+		{Name: "deployment.environment.name", Signal: telemetrytypes.SignalTraces, SelectorMatchType: telemetrytypes.FieldSelectorMatchTypeFuzzy},
+	}
+	assert.Len(t, ExpandKeySelectorsForFamilies(context.Background(), valuer.UUID{}, familiesOn(t), fuzzy), 1, "fuzzy (search-style) selectors never expand")
+}

pkg/querybuilder/where_clause_visitor.go

@@ -9,7 +9,9 @@ import (
 	"strings"
 
 	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/flagger"
 	grammar "github.com/SigNoz/signoz/pkg/parser/filterquery/grammar"
+	"github.com/SigNoz/signoz/pkg/semconv"
 	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"github.com/SigNoz/signoz/pkg/valuer"
@@ -27,6 +29,7 @@ const stringMatchingOperatorDocURL = "https://signoz.io/docs/userguide/operators
 type filterExpressionVisitor struct {
 	context            context.Context
 	orgID              valuer.UUID
+	fl                 flagger.Flagger
 	fieldMapper        qbtypes.FieldMapper
 	conditionBuilder   qbtypes.ConditionBuilder
 	warnings           []string
@@ -48,8 +51,11 @@ type filterExpressionVisitor struct {
 }
 
 type FilterExprVisitorOpts struct {
-	Context            context.Context
-	OrgID              valuer.UUID
+	Context context.Context
+	OrgID   valuer.UUID
+	// Flagger evaluates the resolve_semconv_families flag during resolution.
+	// A nil Flagger keeps resolution literal.
+	Flagger            flagger.Flagger
 	Logger             *slog.Logger
 	FieldMapper        qbtypes.FieldMapper
 	ConditionBuilder   qbtypes.ConditionBuilder
@@ -68,6 +74,7 @@ func newFilterExpressionVisitor(opts FilterExprVisitorOpts) *filterExpressionVis
 	return &filterExpressionVisitor{
 		context:            opts.Context,
 		orgID:              opts.OrgID,
+		fl:                 opts.Flagger,
 		fieldMapper:        opts.FieldMapper,
 		conditionBuilder:   opts.ConditionBuilder,
 		fieldKeys:          opts.FieldKeys,
@@ -360,7 +367,7 @@ func (v *filterExpressionVisitor) VisitPrimary(ctx *grammar.PrimaryContext) any
 				return ErrorConditionLiteral
 			}
 		}
-		conds, ok := v.buildConditions(v.fullTextColumn, []*telemetrytypes.TelemetryFieldKey{v.fullTextColumn}, qbtypes.FilterOperatorRegexp, FormatFullTextSearch(searchText))
+		conds, ok := v.buildConditions(v.fullTextColumn, []*telemetrytypes.LogicalField{telemetrytypes.SingleLogicalField(v.fullTextColumn.Name, v.fullTextColumn)}, qbtypes.FilterOperatorRegexp, FormatFullTextSearch(searchText))
 		if !ok {
 			return ErrorConditionLiteral
 		}
@@ -379,7 +386,7 @@ func (v *filterExpressionVisitor) VisitPrimary(ctx *grammar.PrimaryContext) any
 // VisitComparison handles all comparison operators.
 func (v *filterExpressionVisitor) VisitComparison(ctx *grammar.ComparisonContext) any {
 	key := v.Visit(ctx.Key()).(*telemetrytypes.TelemetryFieldKey)
-	matching := MatchingFieldKeys(key, v.fieldKeys)
+	matching := MatchingLogicalFields(v.context, v.orgID, v.fl, key, v.fieldKeys)
 
 	// Handle EXISTS specially
 	if ctx.EXISTS() != nil {
@@ -675,7 +682,7 @@ func (v *filterExpressionVisitor) VisitFullText(ctx *grammar.FullTextContext) an
 		v.errors = append(v.errors, "full text search is not supported")
 		return ErrorConditionLiteral
 	}
-	conds, ok := v.buildConditions(v.fullTextColumn, []*telemetrytypes.TelemetryFieldKey{v.fullTextColumn}, qbtypes.FilterOperatorRegexp, FormatFullTextSearch(text))
+	conds, ok := v.buildConditions(v.fullTextColumn, []*telemetrytypes.LogicalField{telemetrytypes.SingleLogicalField(v.fullTextColumn.Name, v.fullTextColumn)}, qbtypes.FilterOperatorRegexp, FormatFullTextSearch(text))
 	if !ok {
 		return ErrorConditionLiteral
 	}
@@ -730,7 +737,7 @@ func (v *filterExpressionVisitor) VisitFunctionCall(ctx *grammar.FunctionCallCon
 		return ErrorConditionLiteral
 	}
 
-	conds, ok := v.buildConditions(key, MatchingFieldKeys(key, v.fieldKeys), operator, value)
+	conds, ok := v.buildConditions(key, MatchingLogicalFields(v.context, v.orgID, v.fl, key, v.fieldKeys), operator, value)
 	if !ok {
 		return ErrorConditionLiteral
 	}
@@ -922,7 +929,7 @@ func (v *filterExpressionVisitor) VisitKey(ctx *grammar.KeyContext) any {
 
 // buildConditions invokes the condition builder for a filter term, folding its
 // warnings/errors into visitor state; returns false if an error was recorded.
-func (v *filterExpressionVisitor) buildConditions(key *telemetrytypes.TelemetryFieldKey, matching []*telemetrytypes.TelemetryFieldKey, op qbtypes.FilterOperator, value any) ([]string, bool) {
+func (v *filterExpressionVisitor) buildConditions(key *telemetrytypes.TelemetryFieldKey, matching []*telemetrytypes.LogicalField, op qbtypes.FilterOperator, value any) ([]string, bool) {
 	conds, warns, err := v.conditionBuilder.ConditionFor(v.context, v.orgID, v.startNs, v.endNs, key, v.fieldKeys, qbtypes.ConditionBuilderOptions{SkipResourceFilter: v.skipResourceFilter}, op, value, v.builder)
 	if err != nil {
 		_, _, _, _, errURL, _ := errors.Unwrapb(err)
@@ -979,30 +986,161 @@ func assignIfEmpty(s *string, value string) {
 	}
 }
 
-// MatchingFieldKeys returns the field keys from the map that match the given key,
-// honoring any context/data type the user specified.
-func MatchingFieldKeys(field *telemetrytypes.TelemetryFieldKey, fieldKeys map[string][]*telemetrytypes.TelemetryFieldKey) []*telemetrytypes.TelemetryFieldKey {
-	fieldKeysForName := []*telemetrytypes.TelemetryFieldKey{}
-
-	// match by name; keep items whose context and data type match (unspecified matches any)
-	for _, item := range fieldKeys[field.Name] {
-		if (field.FieldContext == telemetrytypes.FieldContextUnspecified || field.FieldContext == item.FieldContext) &&
-			(field.FieldDataType == telemetrytypes.FieldDataTypeUnspecified || field.FieldDataType == item.FieldDataType) {
-			fieldKeysForName = append(fieldKeysForName, item)
-		}
+// familyMemberNames returns the physical spellings to look up for the
+// referenced key: the semantic-convention family members (current-first) when
+// the resolve_semconv_families flag is on for the org and the key can resolve
+// to traces, else just the requested name. Only trace field mappers understand
+// families today; logs and metrics keep the requested spelling until theirs
+// land.
+func familyMemberNames(ctx context.Context, orgID valuer.UUID, fl flagger.Flagger, field *telemetrytypes.TelemetryFieldKey) []string {
+	if !semconvFamiliesEnabled(ctx, orgID, fl) {
+		return []string{field.Name}
 	}
-
-	// A context may have been split off a name that legitimately contained it (e.g.
-	// `attribute.key`); also look up the context-prefixed name so both readings resolve.
-	if field.FieldContext != telemetrytypes.FieldContextUnspecified {
-		contextPrefixedFieldName := fmt.Sprintf("%s.%s", field.FieldContext.StringValue(), field.Name)
-		for _, item := range fieldKeys[contextPrefixedFieldName] {
-			// Context already matched via the lookup key; only data type needs checking.
-			if field.FieldDataType == telemetrytypes.FieldDataTypeUnspecified || item.FieldDataType == field.FieldDataType {
-				fieldKeysForName = append(fieldKeysForName, item)
-			}
-		}
+	if field.Signal != telemetrytypes.SignalUnspecified && field.Signal != telemetrytypes.SignalTraces {
+		return []string{field.Name}
 	}
-
-	return fieldKeysForName
+	return semconv.Members(semconv.KindAttribute, telemetrytypes.FieldKeySelector{
+		Name:         field.Name,
+		Signal:       telemetrytypes.SignalTraces,
+		FieldContext: field.FieldContext,
+	})
+}
+
+// MatchingLogicalFields resolves the referenced key against the metadata map
+// into logical fields, honoring any context/data type the user specified.
+//
+// Physical keys that are members of one semantic-convention family (traces
+// only today) group into one logical field per (signal, context, data type)
+// identity, members ordered current-first. Every other matching key becomes
+// its own single-member logical field. Ambiguity is the length of the
+// returned slice: one family is one element and is never ambiguous with
+// itself, but the slice can hold several logical fields — including several
+// family fields, one per identity, when the family exists under more than
+// one context or data type. Members alias the metadata map entries; nothing
+// is copied or mutated.
+//
+// Family grouping only happens when the resolve_semconv_families flag is on
+// for the org. A nil flagger means off: every match then stays a
+// single-member logical field.
+func MatchingLogicalFields(ctx context.Context, orgID valuer.UUID, fl flagger.Flagger, field *telemetrytypes.TelemetryFieldKey, fieldKeys map[string][]*telemetrytypes.TelemetryFieldKey) []*telemetrytypes.LogicalField {
+	members := familyMemberNames(ctx, orgID, fl, field)
+	matches := collectMemberMatches(field, members, fieldKeys)
+	return groupIntoLogicalFields(field.Name, len(members) > 1, matches)
+}
+
+// memberMatch pairs a metadata entry with the family rank of the member name
+// it matched under. The stored name of a context-prefixed match differs from
+// the member name, so the rank must travel with the match.
+type memberMatch struct {
+	key  *telemetrytypes.TelemetryFieldKey
+	rank int
+}
+
+// matchesRequestedIdentity reports whether the entry fits the context and data
+// type that the request specified; unspecified matches any. A context-prefixed
+// lookup already matched the context through the lookup key itself.
+func matchesRequestedIdentity(field, item *telemetrytypes.TelemetryFieldKey, contextMatched bool) bool {
+	if !contextMatched && field.FieldContext != telemetrytypes.FieldContextUnspecified && field.FieldContext != item.FieldContext {
+		return false
+	}
+	if field.FieldDataType != telemetrytypes.FieldDataTypeUnspecified && field.FieldDataType != item.FieldDataType {
+		return false
+	}
+	return true
+}
+
+// inFamilyScope reports whether a match found under a sibling member name is
+// legitimate: the entry must be trace metadata, and the member must be in the
+// family of the requested name for the entry's context. A member lookup can
+// otherwise find a same-named field in a scope where the family does not
+// apply.
+func inFamilyScope(field, item *telemetrytypes.TelemetryFieldKey, memberName string) bool {
+	if item.Signal != telemetrytypes.SignalTraces {
+		return false
+	}
+	return slices.Contains(semconv.Members(semconv.KindAttribute, telemetrytypes.FieldKeySelector{
+		Name:         field.Name,
+		Signal:       telemetrytypes.SignalTraces,
+		FieldContext: item.FieldContext,
+	}), memberName)
+}
+
+// collectMemberMatches finds the metadata entries for every member spelling:
+// first under the member names, then under their context-prefixed spellings
+// (a context can be a legitimate part of a stored name, e.g. `attribute.key`).
+func collectMemberMatches(field *telemetrytypes.TelemetryFieldKey, members []string, fieldKeys map[string][]*telemetrytypes.TelemetryFieldKey) []memberMatch {
+	matches := make([]memberMatch, 0)
+	collect := func(lookupName string, rank int, memberName string, contextMatched bool) {
+		for _, item := range fieldKeys[lookupName] {
+			if !matchesRequestedIdentity(field, item, contextMatched) {
+				continue
+			}
+			if memberName != field.Name && !inFamilyScope(field, item, memberName) {
+				continue
+			}
+			matches = append(matches, memberMatch{key: item, rank: rank})
+		}
+	}
+
+	for rank, member := range members {
+		collect(member, rank, member, false)
+	}
+	if field.FieldContext != telemetrytypes.FieldContextUnspecified {
+		for rank, member := range members {
+			collect(fmt.Sprintf("%s.%s", field.FieldContext.StringValue(), member), rank, member, true)
+		}
+	}
+	return matches
+}
+
+// groupIntoLogicalFields turns matches into logical fields. Trace entries in
+// family mode group by their (signal, context, data type) identity; every
+// other entry becomes its own single-member field. Members sort by family
+// rank at the end: precedence is a property of the family, not of the order
+// in which the lookups found the members.
+func groupIntoLogicalFields(requestedName string, familyMode bool, matches []memberMatch) []*telemetrytypes.LogicalField {
+	fields := make([]*telemetrytypes.LogicalField, 0, len(matches))
+	groups := make(map[string]*telemetrytypes.LogicalField)
+	ranks := make(map[*telemetrytypes.TelemetryFieldKey]int)
+
+	for _, match := range matches {
+		if !familyMode || match.key.Signal != telemetrytypes.SignalTraces {
+			fields = append(fields, telemetrytypes.SingleLogicalField(requestedName, match.key))
+			continue
+		}
+
+		identity := match.key.Signal.StringValue() + ";" + match.key.FieldContext.StringValue() + ";" + match.key.FieldDataType.StringValue()
+		group, ok := groups[identity]
+		if !ok {
+			group = &telemetrytypes.LogicalField{
+				Name:          requestedName,
+				Signal:        match.key.Signal,
+				FieldContext:  match.key.FieldContext,
+				FieldDataType: match.key.FieldDataType,
+			}
+			groups[identity] = group
+			fields = append(fields, group)
+		}
+		if groupHasMemberNamed(group, match.key.Name) {
+			continue
+		}
+		ranks[match.key] = match.rank
+		group.Members = append(group.Members, match.key)
+	}
+
+	for _, logical := range fields {
+		slices.SortStableFunc(logical.Members, func(a, b *telemetrytypes.TelemetryFieldKey) int {
+			return ranks[a] - ranks[b]
+		})
+	}
+	return fields
+}
+
+func groupHasMemberNamed(group *telemetrytypes.LogicalField, name string) bool {
+	for _, member := range group.Members {
+		if member.Name == name {
+			return true
+		}
+	}
+	return false
 }

pkg/querybuilder/where_clause_visitor_test.go

@@ -588,9 +588,11 @@ func TestVisitKey(t *testing.T) {
 
 			// VisitKey only parses; the condition builder matches, resolves ambiguity
 			// and decides not-found handling. Replay that here against the generic
-			// builder behavior (error unless the key is ignored).
-			matching := MatchingFieldKeys(key, tt.fieldKeys)
-			keys, warning := ResolveKeys(key, matching)
+			// builder behavior (error unless the key is ignored). The test maps carry
+			// no signal, so every logical field is single-member and flattens losslessly.
+			matching := MatchingLogicalFields(context.Background(), valuer.UUID{}, nil, key, tt.fieldKeys)
+			resolved, warning := ResolveLogicalFields(key, matching)
+			keys := SingleKeys(resolved)
 
 			var gotErrors []string
 			var gotMainErrURL, gotMainWrnURL string
@@ -766,7 +768,8 @@ func (b *resourceConditionBuilder) ConditionFor(
 		return nil, nil, nil
 	}
 
-	keys, warning := ResolveKeys(key, MatchingFieldKeys(key, fieldKeys))
+	resolved, warning := ResolveLogicalFields(key, MatchingLogicalFields(context.Background(), valuer.UUID{}, nil, key, fieldKeys))
+	keys := SingleKeys(resolved)
 	var warnings []string
 	if warning != "" {
 		warnings = append(warnings, warning)
@@ -808,7 +811,8 @@ func (b *conditionBuilder) ConditionFor(
 		return []string{fmt.Sprintf("%s_cond", key.Name)}, nil, nil
 	}
 
-	keys, warning := ResolveKeys(key, MatchingFieldKeys(key, fieldKeys))
+	resolved, warning := ResolveLogicalFields(key, MatchingLogicalFields(context.Background(), valuer.UUID{}, nil, key, fieldKeys))
+	keys := SingleKeys(resolved)
 	var warnings []string
 	if warning != "" {
 		warnings = append(warnings, warning)

pkg/signoz/provider.go

@@ -241,6 +241,7 @@ func NewSQLMigrationProviderFactories(
 		sqlmigration.NewBackfillSavedViewRequestTypeFactory(sqlstore),
 		sqlmigration.NewRestructureAuthDomainConfigFactory(sqlstore),
 		sqlmigration.NewFixSavedViewSelectFieldsFactory(sqlstore),
+		sqlmigration.NewDeleteOrphanUserRolesFactory(),
 	)
 }
 

pkg/sqlmigration/115_delete_orphan_user_roles.go

@@ -0,0 +1,65 @@
+package sqlmigration
+
+import (
+	"context"
+	"database/sql"
+
+	"github.com/SigNoz/signoz/pkg/factory"
+	"github.com/SigNoz/signoz/pkg/types"
+	"github.com/SigNoz/signoz/pkg/types/authtypes"
+	"github.com/uptrace/bun"
+	"github.com/uptrace/bun/migrate"
+)
+
+type deleteOrphanUserRoles struct{}
+
+func NewDeleteOrphanUserRolesFactory() factory.ProviderFactory[SQLMigration, Config] {
+	return factory.NewProviderFactory(
+		factory.MustNewName("delete_orphan_user_roles"),
+		func(ctx context.Context, ps factory.ProviderSettings, c Config) (SQLMigration, error) {
+			return &deleteOrphanUserRoles{}, nil
+		},
+	)
+}
+
+func (migration *deleteOrphanUserRoles) Register(migrations *migrate.Migrations) error {
+	return migrations.Register(migration.Up, migration.Down)
+}
+
+func (migration *deleteOrphanUserRoles) Up(ctx context.Context, db *bun.DB) error {
+	tx, err := db.BeginTx(ctx, nil)
+	if err != nil {
+		return err
+	}
+	defer func() {
+		_ = tx.Rollback()
+	}()
+
+	var deletedUserIDs []string
+	err = tx.NewSelect().
+		Model(new(types.User)).
+		Column("id").
+		Where("status = ?", types.UserStatusDeleted).
+		Scan(ctx, &deletedUserIDs)
+	if err != nil && err != sql.ErrNoRows {
+		return err
+	}
+
+	if len(deletedUserIDs) == 0 {
+		return tx.Commit()
+	}
+
+	_, err = tx.NewDelete().
+		Model(new(authtypes.UserRole)).
+		Where("user_id IN (?)", bun.In(deletedUserIDs)).
+		Exec(ctx)
+	if err != nil {
+		return err
+	}
+
+	return tx.Commit()
+}
+
+func (migration *deleteOrphanUserRoles) Down(context.Context, *bun.DB) error {
+	return nil
+}

pkg/statementbuilder/resourcefilter/condition_builder.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 
 	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/flagger"
 	"github.com/SigNoz/signoz/pkg/querybuilder"
 	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
@@ -14,12 +15,15 @@ import (
 
 type defaultConditionBuilder struct {
 	fm qbtypes.FieldMapper
+	// fl evaluates the resolve_semconv_families flag during resolution.
+	// A nil flagger keeps resolution literal.
+	fl flagger.Flagger
 }
 
 var _ qbtypes.ConditionBuilder = (*defaultConditionBuilder)(nil)
 
-func NewConditionBuilder(fm qbtypes.FieldMapper) *defaultConditionBuilder {
-	return &defaultConditionBuilder{fm: fm}
+func NewConditionBuilder(fm qbtypes.FieldMapper, fl flagger.Flagger) *defaultConditionBuilder {
+	return &defaultConditionBuilder{fm: fm, fl: fl}
 }
 
 func valueForIndexFilter(op qbtypes.FilterOperator, key *telemetrytypes.TelemetryFieldKey, value any) any {
@@ -44,10 +48,74 @@ func keyIndexFilter(key *telemetrytypes.TelemetryFieldKey) any {
 	return fmt.Sprintf(`%%%s%%`, key.Name)
 }
 
+// The three helpers below take the members of one logical field. With a single
+// member they render exactly the pre-family shapes; a family widens key/value
+// index hints to any-member and presence to any-member (all-absent when negated).
+
+func keyIndexCondition(sb *sqlbuilder.SelectBuilder, column string, members []*telemetrytypes.TelemetryFieldKey) string {
+	conditions := make([]string, 0, len(members))
+	for _, member := range members {
+		conditions = append(conditions, sb.Like(column, keyIndexFilter(member)))
+	}
+	if len(conditions) == 1 {
+		return conditions[0]
+	}
+	return sb.Or(conditions...)
+}
+
+func valueIndexCondition(
+	sb *sqlbuilder.SelectBuilder,
+	column string,
+	members []*telemetrytypes.TelemetryFieldKey,
+	op qbtypes.FilterOperator,
+	value any,
+	caseInsensitive bool,
+) string {
+	conditions := make([]string, 0, len(members))
+	for _, member := range members {
+		patterns := valueForIndexFilter(op, member, value)
+		switch values := patterns.(type) {
+		case []string:
+			for _, pattern := range values {
+				conditions = append(conditions, sb.Like(column, pattern))
+			}
+		default:
+			if caseInsensitive {
+				conditions = append(conditions, sb.ILike(column, values))
+			} else {
+				conditions = append(conditions, sb.Like(column, values))
+			}
+		}
+	}
+	if len(conditions) == 1 {
+		return conditions[0]
+	}
+	return sb.Or(conditions...)
+}
+
+func memberPresenceCondition(sb *sqlbuilder.SelectBuilder, column string, members []*telemetrytypes.TelemetryFieldKey, exists bool) string {
+	conditions := make([]string, 0, len(members))
+	for _, member := range members {
+		field := fmt.Sprintf("simpleJSONHas(%s, %s)", column, querybuilder.ClickHouseStringLiteral(member.Name))
+		if exists {
+			conditions = append(conditions, sb.E(field, true))
+		} else {
+			conditions = append(conditions, sb.NE(field, true))
+		}
+	}
+	if exists {
+		if len(conditions) == 1 {
+			return conditions[0]
+		}
+		return sb.Or(conditions...)
+	}
+	return sb.And(conditions...)
+}
+
 // SkipResourceFilter is not applicable here: the fingerprint table only stores resource attributes.
 func (b *defaultConditionBuilder) ConditionFor(
 	ctx context.Context,
-	_ valuer.UUID,
+	orgID valuer.UUID,
 	startNs uint64,
 	endNs uint64,
 	key *telemetrytypes.TelemetryFieldKey,
@@ -57,7 +125,7 @@ func (b *defaultConditionBuilder) ConditionFor(
 	value any,
 	sb *sqlbuilder.SelectBuilder,
 ) ([]string, []string, error) {
-	matches := querybuilder.MatchingFieldKeys(key, fieldKeys)
+	matches := querybuilder.MatchingLogicalFields(ctx, orgID, b.fl, key, fieldKeys)
 
 	// has/hasAny/hasAll/hasToken are logs-body-only functions; they never apply to the
 	// resource fingerprint table, so skip them (the main query still evaluates them).
@@ -65,21 +133,21 @@ func (b *defaultConditionBuilder) ConditionFor(
 		return nil, nil, nil
 	}
 
-	keys, warning := querybuilder.ResolveKeys(key, matches)
+	logicalFields, warning := querybuilder.ResolveLogicalFields(key, matches)
 	var warnings []string
 	if warning != "" {
 		warnings = append(warnings, warning)
 	}
 
-	conds := make([]string, 0, len(keys))
-	for _, k := range keys {
-		// the resource fingerprint table only stores resource attributes; keys from
+	conds := make([]string, 0, len(logicalFields))
+	for _, logical := range logicalFields {
+		// the resource fingerprint table only stores resource attributes; fields from
 		// any other context contribute no condition and are omitted. An empty result
 		// (including an unknown key) lets the caller skip this filter entirely.
-		if k.FieldContext != telemetrytypes.FieldContextResource {
+		if logical.FieldContext != telemetrytypes.FieldContextResource {
 			continue
 		}
-		cond, err := b.conditionForKey(ctx, startNs, endNs, k, op, value, sb)
+		cond, err := b.conditionForLogicalField(ctx, orgID, startNs, endNs, logical, op, value, sb)
 		if err != nil {
 			return nil, nil, err
 		}
@@ -88,11 +156,12 @@ func (b *defaultConditionBuilder) ConditionFor(
 	return conds, warnings, nil
 }
 
-func (b *defaultConditionBuilder) conditionForKey(
+func (b *defaultConditionBuilder) conditionForLogicalField(
 	ctx context.Context,
+	orgID valuer.UUID,
 	startNs uint64,
 	endNs uint64,
-	key *telemetrytypes.TelemetryFieldKey,
+	logical *telemetrytypes.LogicalField,
 	op qbtypes.FilterOperator,
 	value any,
 	sb *sqlbuilder.SelectBuilder,
@@ -102,7 +171,9 @@ func (b *defaultConditionBuilder) conditionForKey(
 	// as we store resource values as string
 	formattedValue := querybuilder.FormatValueForContains(value)
 
-	columns, err := b.fm.ColumnFor(ctx, valuer.UUID{}, startNs, endNs, key)
+	// Every resource-context key maps to the labels column, so any member
+	// resolves the column for the whole field.
+	columns, err := b.fm.ColumnFor(ctx, orgID, startNs, endNs, logical.Single())
 	if err != nil {
 		return "", err
 	}
@@ -115,10 +186,12 @@ func (b *defaultConditionBuilder) conditionForKey(
 	// as we have not changed the resource column in the resource fingerprint table.
 	column := columns[0]
 
-	keyIdxFilter := sb.Like(column.Name, keyIndexFilter(key))
-	valueForIndexFilter := valueForIndexFilter(op, key, value)
+	members := logical.Members
+	isFamily := logical.IsFamily()
+	keyIdxFilter := keyIndexCondition(sb, column.Name, members)
+	singleValueIndexFilter := valueForIndexFilter(op, members[0], value)
 
-	fieldName, err := b.fm.FieldFor(ctx, valuer.UUID{}, startNs, endNs, key)
+	fieldName, err := querybuilder.LogicalValueExpr(ctx, orgID, startNs, endNs, b.fm, logical)
 	if err != nil {
 		return "", err
 	}
@@ -128,12 +201,17 @@ func (b *defaultConditionBuilder) conditionForKey(
 		return sb.And(
 			sb.E(fieldName, formattedValue),
 			keyIdxFilter,
-			sb.Like(column.Name, valueForIndexFilter),
+			valueIndexCondition(sb, column.Name, members, op, value, false),
 		), nil
 	case qbtypes.FilterOperatorNotEqual:
+		if isFamily {
+			// A negated value-index hint would drop rows where another member
+			// holds the value; the fingerprint scan is small enough without it.
+			return sb.NE(fieldName, formattedValue), nil
+		}
 		return sb.And(
 			sb.NE(fieldName, formattedValue),
-			sb.NotLike(column.Name, valueForIndexFilter),
+			sb.NotLike(column.Name, singleValueIndexFilter),
 		), nil
 	case qbtypes.FilterOperatorGreaterThan:
 		return sb.And(sb.GT(fieldName, formattedValue), keyIdxFilter), nil
@@ -148,7 +226,7 @@ func (b *defaultConditionBuilder) conditionForKey(
 		return sb.And(
 			sb.ILike(fieldName, formattedValue),
 			keyIdxFilter,
-			sb.ILike(column.Name, valueForIndexFilter),
+			valueIndexCondition(sb, column.Name, members, op, value, true),
 		), nil
 	case qbtypes.FilterOperatorNotLike, qbtypes.FilterOperatorNotILike:
 		// no index filter: as cannot apply `not contains x%y` as y can be somewhere else
@@ -185,13 +263,11 @@ func (b *defaultConditionBuilder) conditionForKey(
 			inConditions = append(inConditions, sb.E(fieldName, querybuilder.FormatValueForContains(v)))
 		}
 		mainCondition := sb.Or(inConditions...)
-		valConditions := make([]string, 0, len(values))
-		if valuesForIndexFilter, ok := valueForIndexFilter.([]string); ok {
-			for _, v := range valuesForIndexFilter {
-				valConditions = append(valConditions, sb.Like(column.Name, v))
-			}
-		}
-		mainCondition = sb.And(mainCondition, keyIdxFilter, sb.Or(valConditions...))
+		mainCondition = sb.And(
+			mainCondition,
+			keyIdxFilter,
+			valueIndexCondition(sb, column.Name, members, op, value, false),
+		)
 
 		return mainCondition, nil
 	case qbtypes.FilterOperatorNotIn:
@@ -204,8 +280,13 @@ func (b *defaultConditionBuilder) conditionForKey(
 			notInConditions = append(notInConditions, sb.NE(fieldName, querybuilder.FormatValueForContains(v)))
 		}
 		mainCondition := sb.And(notInConditions...)
+		if isFamily {
+			// A negated value-index hint would drop rows where another member
+			// holds the value; the fingerprint scan is small enough without it.
+			return mainCondition, nil
+		}
 		valConditions := make([]string, 0, len(values))
-		if valuesForIndexFilter, ok := valueForIndexFilter.([]string); ok {
+		if valuesForIndexFilter, ok := singleValueIndexFilter.([]string); ok {
 			for _, v := range valuesForIndexFilter {
 				valConditions = append(valConditions, sb.NotLike(column.Name, v))
 			}
@@ -215,13 +296,11 @@ func (b *defaultConditionBuilder) conditionForKey(
 
 	case qbtypes.FilterOperatorExists:
 		return sb.And(
-			sb.E(fmt.Sprintf("simpleJSONHas(%s, '%s')", column.Name, key.Name), true),
+			memberPresenceCondition(sb, column.Name, members, true),
 			keyIdxFilter,
 		), nil
 	case qbtypes.FilterOperatorNotExists:
-		return sb.And(
-			sb.NE(fmt.Sprintf("simpleJSONHas(%s, '%s')", column.Name, key.Name), true),
-		), nil
+		return memberPresenceCondition(sb, column.Name, members, false), nil
 
 	case qbtypes.FilterOperatorRegexp:
 		return sb.And(
@@ -237,7 +316,7 @@ func (b *defaultConditionBuilder) conditionForKey(
 		return sb.And(
 			sb.ILike(fieldName, fmt.Sprintf(`%%%s%%`, formattedValue)),
 			keyIdxFilter,
-			sb.ILike(column.Name, valueForIndexFilter),
+			valueIndexCondition(sb, column.Name, members, op, value, true),
 		), nil
 	case qbtypes.FilterOperatorNotContains:
 		// no index filter: as cannot apply `not contains x%y` as y can be somewhere else

pkg/statementbuilder/resourcefilter/condition_builder_test.go

@@ -2,6 +2,7 @@ package resourcefilter
 
 import (
 	"context"
+	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
 	"testing"
 
 	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
@@ -201,7 +202,7 @@ func TestConditionBuilder(t *testing.T) {
 	}
 
 	fm := NewFieldMapper()
-	conditionBuilder := NewConditionBuilder(fm)
+	conditionBuilder := NewConditionBuilder(fm, flaggertest.New(t))
 
 	for _, tc := range testCases {
 		sb := sqlbuilder.NewSelectBuilder()

pkg/statementbuilder/resourcefilter/family_test.go

@@ -0,0 +1,141 @@
+package resourcefilter
+
+import (
+	"context"
+	"testing"
+
+	"github.com/SigNoz/signoz/pkg/flagger"
+	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/valuer"
+	"github.com/huandu/go-sqlbuilder"
+	"github.com/stretchr/testify/require"
+)
+
+// The tests below run against the deployment.environment(.name) family with
+// the resolve_semconv_families flag on, and with both spellings present in
+// the metadata map as trace resource attributes.
+
+func TestFamilyEqualWidensIndexHintsToAnyMember(t *testing.T) {
+	cb := NewConditionBuilder(NewFieldMapper(), flaggertest.WithBooleanFlags(t, map[string]bool{flagger.FeatureResolveSemconvFamilies.String(): true}))
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+	}
+
+	sb := sqlbuilder.NewSelectBuilder()
+	conds, _, err := cb.ConditionFor(context.Background(), valuer.UUID{}, 0, 0,
+		&telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"},
+		fieldKeys, qbtypes.ConditionBuilderOptions{}, qbtypes.FilterOperatorEqual, "production", sb)
+	require.NoError(t, err)
+	require.Len(t, conds, 1)
+	sb.Where(conds...)
+	sql, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	require.Equal(t, "WHERE (COALESCE(NULLIF(simpleJSONExtractString(labels, 'deployment.environment.name'), ''), NULLIF(simpleJSONExtractString(labels, 'deployment.environment'), ''), '') = ? AND (labels LIKE ? OR labels LIKE ?) AND (labels LIKE ? OR labels LIKE ?))", sql)
+	require.Equal(t, []any{"production", "%deployment.environment.name%", "%deployment.environment%", "%deployment.environment.name\":\"production%", "%deployment.environment\":\"production%"}, args)
+}
+
+func TestFamilyNotEqualDropsNegatedValueHint(t *testing.T) {
+	cb := NewConditionBuilder(NewFieldMapper(), flaggertest.WithBooleanFlags(t, map[string]bool{flagger.FeatureResolveSemconvFamilies.String(): true}))
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+	}
+
+	sb := sqlbuilder.NewSelectBuilder()
+	conds, _, err := cb.ConditionFor(context.Background(), valuer.UUID{}, 0, 0,
+		&telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"},
+		fieldKeys, qbtypes.ConditionBuilderOptions{}, qbtypes.FilterOperatorNotEqual, "production", sb)
+	require.NoError(t, err)
+	require.Len(t, conds, 1)
+	sb.Where(conds...)
+	sql, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	require.Equal(t, "WHERE COALESCE(NULLIF(simpleJSONExtractString(labels, 'deployment.environment.name'), ''), NULLIF(simpleJSONExtractString(labels, 'deployment.environment'), ''), '') <> ?", sql)
+	require.Equal(t, []any{"production"}, args)
+}
+
+func TestFamilyExistsIsAnyMemberPresence(t *testing.T) {
+	cb := NewConditionBuilder(NewFieldMapper(), flaggertest.WithBooleanFlags(t, map[string]bool{flagger.FeatureResolveSemconvFamilies.String(): true}))
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+	}
+
+	sb := sqlbuilder.NewSelectBuilder()
+	conds, _, err := cb.ConditionFor(context.Background(), valuer.UUID{}, 0, 0,
+		&telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"},
+		fieldKeys, qbtypes.ConditionBuilderOptions{}, qbtypes.FilterOperatorExists, nil, sb)
+	require.NoError(t, err)
+	require.Len(t, conds, 1)
+	sb.Where(conds...)
+	sql, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	require.Equal(t, "WHERE ((simpleJSONHas(labels, 'deployment.environment.name') = ? OR simpleJSONHas(labels, 'deployment.environment') = ?) AND (labels LIKE ? OR labels LIKE ?))", sql)
+	require.Equal(t, []any{true, true, "%deployment.environment.name%", "%deployment.environment%"}, args)
+
+	sb = sqlbuilder.NewSelectBuilder()
+	conds, _, err = cb.ConditionFor(context.Background(), valuer.UUID{}, 0, 0,
+		&telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"},
+		fieldKeys, qbtypes.ConditionBuilderOptions{}, qbtypes.FilterOperatorNotExists, nil, sb)
+	require.NoError(t, err)
+	require.Len(t, conds, 1)
+	sb.Where(conds...)
+	sql, args = sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	require.Equal(t, "WHERE (simpleJSONHas(labels, 'deployment.environment.name') <> ? AND simpleJSONHas(labels, 'deployment.environment') <> ?)", sql)
+	require.Equal(t, []any{true, true}, args)
+}
+
+// With only one member in metadata the SQL keeps the exact pre-family shape,
+// including the negated value hint on !=.
+func TestSingleMemberShapesUnchanged(t *testing.T) {
+	cb := NewConditionBuilder(NewFieldMapper(), flaggertest.WithBooleanFlags(t, map[string]bool{flagger.FeatureResolveSemconvFamilies.String(): true}))
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+	}
+
+	sb := sqlbuilder.NewSelectBuilder()
+	conds, _, err := cb.ConditionFor(context.Background(), valuer.UUID{}, 0, 0,
+		&telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"},
+		fieldKeys, qbtypes.ConditionBuilderOptions{}, qbtypes.FilterOperatorNotEqual, "production", sb)
+	require.NoError(t, err)
+	require.Len(t, conds, 1)
+	sb.Where(conds...)
+	sql, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	require.Equal(t, "WHERE (simpleJSONExtractString(labels, 'deployment.environment.name') <> ? AND labels NOT LIKE ?)", sql)
+	require.Equal(t, []any{"production", "%deployment.environment.name\":\"production%"}, args)
+}

pkg/statementbuilder/resourcefilter/field_mapper.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 
 	schema "github.com/SigNoz/signoz-otel-collector/cmd/signozschemamigrator/schema_migrator"
+	"github.com/SigNoz/signoz/pkg/querybuilder"
 	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"github.com/SigNoz/signoz/pkg/valuer"
@@ -66,11 +67,38 @@ func (m *defaultFieldMapper) FieldFor(
 		return "", err
 	}
 	if key.FieldContext == telemetrytypes.FieldContextResource {
-		return fmt.Sprintf("simpleJSONExtractString(%s, '%s')", columns[0].Name, key.Name), nil
+		return fmt.Sprintf("simpleJSONExtractString(%s, %s)", columns[0].Name, querybuilder.ClickHouseStringLiteral(key.Name)), nil
 	}
 	return columns[0].Name, nil
 }
 
+// ExistsFor reports key presence in the fingerprint labels JSON. Only resource
+// context keys have a presence notion here; anything else is a real column and
+// always present.
+func (m *defaultFieldMapper) ExistsFor(
+	ctx context.Context,
+	_ valuer.UUID,
+	tsStart, tsEnd uint64,
+	key *telemetrytypes.TelemetryFieldKey,
+	exists bool,
+) (string, error) {
+	columns, err := m.getColumn(ctx, tsStart, tsEnd, key)
+	if err != nil {
+		return "", err
+	}
+	if key.FieldContext != telemetrytypes.FieldContextResource {
+		if exists {
+			return "true", nil
+		}
+		return "false", nil
+	}
+	pred := fmt.Sprintf("simpleJSONHas(%s, %s)", columns[0].Name, querybuilder.ClickHouseStringLiteral(key.Name))
+	if exists {
+		return pred, nil
+	}
+	return "NOT " + pred, nil
+}
+
 func (m *defaultFieldMapper) ColumnExpressionFor(
 	ctx context.Context,
 	orgID valuer.UUID,
@@ -83,5 +111,5 @@ func (m *defaultFieldMapper) ColumnExpressionFor(
 	if err != nil {
 		return "", err
 	}
-	return fmt.Sprintf("%s AS `%s`", fieldExpression, key.Name), nil
+	return fmt.Sprintf("%s AS %s", fieldExpression, querybuilder.ClickHouseIdentifier(key.Name)), nil
 }

pkg/statementbuilder/resourcefilter/statement_builder.go

@@ -47,7 +47,7 @@ func New[T any](
 ) *resourceFilterStatementBuilder[T] {
 	set := factory.NewScopedProviderSettings(settings, "github.com/SigNoz/signoz/pkg/statementbuilder/resourcefilter")
 	fm := NewFieldMapper()
-	cb := NewConditionBuilder(fm)
+	cb := NewConditionBuilder(fm, fl)
 	return &resourceFilterStatementBuilder[T]{
 		logger:           set.Logger(),
 		dbName:           dbName,
@@ -99,7 +99,7 @@ func (b *resourceFilterStatementBuilder[T]) Build(
 	q.Select("fingerprint")
 	q.From(fmt.Sprintf("%s.%s", b.dbName, b.tableName))
 
-	keySelectors := b.getKeySelectors(query)
+	keySelectors := querybuilder.ExpandKeySelectorsForFamilies(ctx, orgID, b.flagger, b.getKeySelectors(query))
 	keys, _, err := b.metadataStore.GetKeysMulti(ctx, orgID, keySelectors)
 	if err != nil {
 		return nil, err
@@ -164,6 +164,7 @@ func (b *resourceFilterStatementBuilder[T]) addConditions(
 		filterWhereClause, err := querybuilder.PrepareWhereClause(query.Filter.Expression, querybuilder.FilterExprVisitorOpts{
 			Context:            ctx,
 			OrgID:              orgID,
+			Flagger:            b.flagger,
 			Logger:             b.logger,
 			FieldMapper:        b.fieldMapper,
 			ConditionBuilder:   b.conditionBuilder,

pkg/statementbuilder/scopedtracesstatementbuilder/statement_builder.go

@@ -38,6 +38,7 @@ type scopedTraceStatementBuilder struct {
 	scope                     TraceScope
 	traceStmtBuilder          qbtypes.StatementBuilder[qbtypes.TraceAggregation]
 	resourceFilterStmtBuilder qbtypes.StatementBuilder[qbtypes.TraceAggregation]
+	fl                        flagger.Flagger
 }
 
 var _ qbtypes.StatementBuilder[qbtypes.TraceAggregation] = (*scopedTraceStatementBuilder)(nil)
@@ -59,8 +60,8 @@ func NewFactory(
 			if err != nil {
 				return nil, err
 			}
-			fm := tracestelemetryschema.NewFieldMapper()
-			cb := tracestelemetryschema.NewConditionBuilder(fm)
+			fm := tracestelemetryschema.NewFieldMapper(fl)
+			cb := tracestelemetryschema.NewConditionBuilder(fm, fl)
 			return NewScopedTraceStatementBuilder(settings, metadataStore, fm, cb, scope, traceStmtBuilder, fl), nil
 		},
 	)
@@ -98,6 +99,7 @@ func NewScopedTraceStatementBuilder(
 		scope:                     scope,
 		traceStmtBuilder:          traceStmtBuilder,
 		resourceFilterStmtBuilder: resourceFilterStmtBuilder,
+		fl:                        fl,
 	}
 }
 
@@ -267,7 +269,7 @@ func (b *scopedTraceStatementBuilder) fetchKeys(ctx context.Context, orgID value
 			SelectorMatchType: telemetrytypes.FieldSelectorMatchTypeExact,
 		})
 	}
-	keys, _, err := b.metadataStore.GetKeysMulti(ctx, orgID, selectors)
+	keys, _, err := b.metadataStore.GetKeysMulti(ctx, orgID, querybuilder.ExpandKeySelectorsForFamilies(ctx, orgID, b.fl, selectors))
 	return keys, err
 }
 
@@ -444,13 +446,14 @@ func (b *scopedTraceStatementBuilder) resolveSpanPredicate(ctx context.Context,
 	for i := range selectors {
 		selectors[i].Signal = telemetrytypes.SignalTraces
 	}
-	keys, _, err := b.metadataStore.GetKeysMulti(ctx, orgID, selectors)
+	keys, _, err := b.metadataStore.GetKeysMulti(ctx, orgID, querybuilder.ExpandKeySelectorsForFamilies(ctx, orgID, b.fl, selectors))
 	if err != nil {
 		return "", nil, "", err
 	}
 	prepared, err := querybuilder.PrepareWhereClause(expr, querybuilder.FilterExprVisitorOpts{
 		Context:          ctx,
 		OrgID:            orgID,
+		Flagger:          b.fl,
 		Logger:           b.logger,
 		FieldMapper:      b.fm,
 		ConditionBuilder: b.cb,

pkg/statementbuilder/tracesstatementbuilder/statement_builder.go

@@ -31,6 +31,7 @@ type traceQueryStatementBuilder struct {
 	cb                             qbtypes.ConditionBuilder
 	resourceFilterResolver         *resourcefilter.ResourceFingerprintResolver[qbtypes.TraceAggregation]
 	aggExprRewriter                qbtypes.AggExprRewriter
+	fl                             flagger.Flagger
 	skipResourceFingerprintEnabled bool
 }
 
@@ -47,8 +48,8 @@ func NewFactory(
 	return factory.NewProviderFactory(
 		factory.MustNewName("traces"),
 		func(_ context.Context, settings factory.ProviderSettings, cfg statementbuilder.Config) (qbtypes.StatementBuilder[qbtypes.TraceAggregation], error) {
-			fm := tracestelemetryschema.NewFieldMapper()
-			cb := tracestelemetryschema.NewConditionBuilder(fm)
+			fm := tracestelemetryschema.NewFieldMapper(fl)
+			cb := tracestelemetryschema.NewConditionBuilder(fm, fl)
 			aggExprRewriter := querybuilder.NewAggExprRewriter(settings, nil, fm, cb, fl)
 			return NewTraceQueryStatementBuilder(
 				settings, metadataStore, fm, cb, aggExprRewriter, telemetryStore, fl,
@@ -91,6 +92,7 @@ func NewTraceQueryStatementBuilder(
 		cb:                             conditionBuilder,
 		resourceFilterResolver:         resourceFilterResolver,
 		aggExprRewriter:                aggExprRewriter,
+		fl:                             flagger,
 		skipResourceFingerprintEnabled: skipResourceFingerprintEnable,
 	}
 }
@@ -119,7 +121,7 @@ func (b *traceQueryStatementBuilder) Build(
 
 	// We modify SelectFields above (injecting default fields), and those default
 	// fields can carry keys that need evolutions, so fetch keys after that.
-	keySelectors := getKeySelectors(query)
+	keySelectors := querybuilder.ExpandKeySelectorsForFamilies(ctx, orgID, b.fl, getKeySelectors(query))
 
 	keys, _, err := b.metadataStore.GetKeysMulti(ctx, orgID, keySelectors)
 	if err != nil {
@@ -795,6 +797,7 @@ func (b *traceQueryStatementBuilder) addFilterCondition(
 		preparedWhereClause, err = querybuilder.PrepareWhereClause(query.Filter.Expression, querybuilder.FilterExprVisitorOpts{
 			Context:            ctx,
 			OrgID:              orgID,
+			Flagger:            b.fl,
 			Logger:             b.logger,
 			FieldMapper:        b.fm,
 			ConditionBuilder:   b.cb,

pkg/statementbuilder/tracesstatementbuilder/stmt_builder_test.go

@@ -8,6 +8,7 @@ import (
 
 	cmock "github.com/SigNoz/clickhouse-go-mock"
 	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/flagger"
 	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
 	"github.com/SigNoz/signoz/pkg/instrumentation/instrumentationtest"
 	"github.com/SigNoz/signoz/pkg/querybuilder"
@@ -376,8 +377,8 @@ func TestStatementBuilder(t *testing.T) {
 	}
 
 	fl := flaggertest.New(t)
-	fm := tracestelemetryschema.NewFieldMapper()
-	cb := tracestelemetryschema.NewConditionBuilder(fm)
+	fm := tracestelemetryschema.NewFieldMapper(fl)
+	cb := tracestelemetryschema.NewConditionBuilder(fm, fl)
 	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
 	mockMetadataStore.KeysMap = tracestelemetryschema.BuildCompleteFieldKeyMap(releaseTime)
 	aggExprRewriter := querybuilder.NewAggExprRewriter(instrumentationtest.New().ToProviderSettings(), nil, fm, cb, fl)
@@ -677,8 +678,8 @@ func TestStatementBuilderListQuery(t *testing.T) {
 	}
 
 	fl := flaggertest.New(t)
-	fm := tracestelemetryschema.NewFieldMapper()
-	cb := tracestelemetryschema.NewConditionBuilder(fm)
+	fm := tracestelemetryschema.NewFieldMapper(fl)
+	cb := tracestelemetryschema.NewConditionBuilder(fm, fl)
 	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
 	mockMetadataStore.KeysMap = tracestelemetryschema.BuildCompleteFieldKeyMap(releaseTime)
 	aggExprRewriter := querybuilder.NewAggExprRewriter(instrumentationtest.New().ToProviderSettings(), nil, fm, cb, fl)
@@ -804,8 +805,8 @@ func TestStatementBuilderListQueryWithCorruptData(t *testing.T) {
 	for _, c := range cases {
 		t.Run(c.name, func(t *testing.T) {
 			fl := flaggertest.New(t)
-			fm := tracestelemetryschema.NewFieldMapper()
-			cb := tracestelemetryschema.NewConditionBuilder(fm)
+			fm := tracestelemetryschema.NewFieldMapper(fl)
+			cb := tracestelemetryschema.NewConditionBuilder(fm, fl)
 			mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
 			mockMetadataStore.KeysMap = c.keysMap
 			if mockMetadataStore.KeysMap == nil {
@@ -879,8 +880,8 @@ func TestStatementBuilderGroupByResourceEvolution(t *testing.T) {
 	}
 
 	fl := flaggertest.New(t)
-	fm := tracestelemetryschema.NewFieldMapper()
-	cb := tracestelemetryschema.NewConditionBuilder(fm)
+	fm := tracestelemetryschema.NewFieldMapper(fl)
+	cb := tracestelemetryschema.NewConditionBuilder(fm, fl)
 	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
 	mockMetadataStore.KeysMap = tracestelemetryschema.BuildCompleteFieldKeyMap(releaseTime)
 	aggExprRewriter := querybuilder.NewAggExprRewriter(instrumentationtest.New().ToProviderSettings(), nil, fm, cb, fl)
@@ -1046,8 +1047,8 @@ func TestStatementBuilderTraceQuery(t *testing.T) {
 	}
 
 	fl := flaggertest.New(t)
-	fm := tracestelemetryschema.NewFieldMapper()
-	cb := tracestelemetryschema.NewConditionBuilder(fm)
+	fm := tracestelemetryschema.NewFieldMapper(fl)
+	cb := tracestelemetryschema.NewConditionBuilder(fm, fl)
 	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
 	mockMetadataStore.KeysMap = tracestelemetryschema.BuildCompleteFieldKeyMap(releaseTime)
 	aggExprRewriter := querybuilder.NewAggExprRewriter(instrumentationtest.New().ToProviderSettings(), nil, fm, cb, fl)
@@ -1684,8 +1685,8 @@ func newSkipResourceFingerprintBuilder(
 	t.Helper()
 
 	fl := flaggertest.New(t)
-	fm := tracestelemetryschema.NewFieldMapper()
-	cb := tracestelemetryschema.NewConditionBuilder(fm)
+	fm := tracestelemetryschema.NewFieldMapper(fl)
+	cb := tracestelemetryschema.NewConditionBuilder(fm, fl)
 	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
 	releaseTime := time.Date(2025, 5, 22, 22, 0, 0, 0, time.UTC)
 	mockMetadataStore.KeysMap = tracestelemetryschema.BuildCompleteFieldKeyMap(releaseTime)
@@ -1714,8 +1715,8 @@ func TestStatementBuilderGroupByUnseenKey(t *testing.T) {
 	releaseTime := time.Date(2025, 5, 22, 22, 0, 0, 0, time.UTC)
 
 	fl := flaggertest.New(t)
-	fm := tracestelemetryschema.NewFieldMapper()
-	cb := tracestelemetryschema.NewConditionBuilder(fm)
+	fm := tracestelemetryschema.NewFieldMapper(fl)
+	cb := tracestelemetryschema.NewConditionBuilder(fm, fl)
 	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
 	mockMetadataStore.KeysMap = tracestelemetryschema.BuildCompleteFieldKeyMap(releaseTime)
 	aggExprRewriter := querybuilder.NewAggExprRewriter(instrumentationtest.New().ToProviderSettings(), nil, fm, cb, fl)
@@ -1756,8 +1757,8 @@ func TestStatementBuilderAggregationUnseenKey(t *testing.T) {
 	releaseTime := time.Date(2025, 5, 22, 22, 0, 0, 0, time.UTC)
 
 	fl := flaggertest.New(t)
-	fm := tracestelemetryschema.NewFieldMapper()
-	cb := tracestelemetryschema.NewConditionBuilder(fm)
+	fm := tracestelemetryschema.NewFieldMapper(fl)
+	cb := tracestelemetryschema.NewConditionBuilder(fm, fl)
 	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
 	mockMetadataStore.KeysMap = tracestelemetryschema.BuildCompleteFieldKeyMap(releaseTime)
 	aggExprRewriter := querybuilder.NewAggExprRewriter(instrumentationtest.New().ToProviderSettings(), nil, fm, cb, fl)
@@ -1787,3 +1788,72 @@ func TestStatementBuilderAggregationUnseenKey(t *testing.T) {
 	assert.Contains(t, q.Query, "attributes_number['error.type']")
 	assert.Contains(t, q.Query, "attributes_bool['error.type']")
 }
+
+// TestStatementBuilderSemconvFamilies builds the same family-member filter
+// with the resolve_semconv_families flag on and off. On: the resource filter
+// merges both spellings and widens the index hints to any member. Off: the
+// query uses only the requested spelling, so users see no change.
+func TestStatementBuilderSemconvFamilies(t *testing.T) {
+	releaseTime := time.Date(2025, 5, 22, 22, 0, 0, 0, time.UTC)
+	query := qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+		Signal:       telemetrytypes.SignalTraces,
+		StepInterval: qbtypes.Step{Duration: 30 * time.Second},
+		Aggregations: []qbtypes.TraceAggregation{{Expression: "count()"}},
+		Filter: &qbtypes.Filter{
+			Expression: "deployment.environment.name = 'production'",
+		},
+	}
+
+	cases := []struct {
+		name     string
+		flag     bool
+		expected qbtypes.Statement
+	}{
+		{
+			name: "flag on merges both spellings",
+			flag: true,
+			expected: qbtypes.Statement{
+				Query: "WITH __resource_filter AS (SELECT fingerprint FROM signoz_traces.distributed_traces_v3_resource WHERE (COALESCE(NULLIF(simpleJSONExtractString(labels, 'deployment.environment.name'), ''), NULLIF(simpleJSONExtractString(labels, 'deployment.environment'), ''), '') = ? AND (labels LIKE ? OR labels LIKE ?) AND (labels LIKE ? OR labels LIKE ?)) AND seen_at_ts_bucket_start >= ? AND seen_at_ts_bucket_start <= ? GROUP BY fingerprint) SELECT count() 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 <= ? ORDER BY __result_0 DESC",
+				Args:  []any{"production", "%deployment.environment.name%", "%deployment.environment%", "%deployment.environment.name\":\"production%", "%deployment.environment\":\"production%", uint64(1747945619), uint64(1747983448), "1747947419000000000", "1747983448000000000", uint64(1747945619), uint64(1747983448)},
+			},
+		},
+		{
+			name: "flag off keeps the literal spelling",
+			flag: false,
+			expected: qbtypes.Statement{
+				Query: "WITH __resource_filter AS (SELECT fingerprint FROM signoz_traces.distributed_traces_v3_resource WHERE (simpleJSONExtractString(labels, 'deployment.environment.name') = ? AND labels LIKE ? AND labels LIKE ?) AND seen_at_ts_bucket_start >= ? AND seen_at_ts_bucket_start <= ? GROUP BY fingerprint) SELECT count() 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 <= ? ORDER BY __result_0 DESC",
+				Args:  []any{"production", "%deployment.environment.name%", "%deployment.environment.name\":\"production%", uint64(1747945619), uint64(1747983448), "1747947419000000000", "1747983448000000000", uint64(1747945619), uint64(1747983448)},
+			},
+		},
+	}
+
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			fl := flaggertest.WithBooleanFlags(t, map[string]bool{
+				flagger.FeatureResolveSemconvFamilies.String(): c.flag,
+			})
+			fm := tracestelemetryschema.NewFieldMapper(fl)
+			cb := tracestelemetryschema.NewConditionBuilder(fm, fl)
+			mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
+			mockMetadataStore.KeysMap = tracestelemetryschema.BuildCompleteFieldKeyMap(releaseTime)
+			aggExprRewriter := querybuilder.NewAggExprRewriter(instrumentationtest.New().ToProviderSettings(), nil, fm, cb, fl)
+
+			statementBuilder := NewTraceQueryStatementBuilder(
+				instrumentationtest.New().ToProviderSettings(),
+				mockMetadataStore,
+				fm,
+				cb,
+				aggExprRewriter,
+				nil,
+				fl,
+				false,
+				100000,
+			)
+
+			q, err := statementBuilder.Build(context.Background(), valuer.UUID{}, 1747947419000, 1747983448000, qbtypes.RequestTypeScalar, query, nil)
+			require.NoError(t, err)
+			require.Equal(t, c.expected.Query, q.Query)
+			require.Equal(t, c.expected.Args, q.Args)
+		})
+	}
+}

pkg/statementbuilder/tracesstatementbuilder/trace_operator_cte_builder.go

@@ -212,7 +212,7 @@ func (b *traceOperatorCTEBuilder) buildQueryCTE(ctx context.Context, queryName s
 		return cteName, nil
 	}
 
-	keySelectors := getKeySelectors(*query)
+	keySelectors := querybuilder.ExpandKeySelectorsForFamilies(ctx, b.orgID, b.stmtBuilder.fl, getKeySelectors(*query))
 	b.stmtBuilder.logger.DebugContext(ctx, "Key selectors for query", slog.String("query_name", queryName), slog.Any("key_selectors", keySelectors))
 	keys, _, err := b.stmtBuilder.metadataStore.GetKeysMulti(ctx, b.orgID, keySelectors)
 	if err != nil {
@@ -265,6 +265,7 @@ func (b *traceOperatorCTEBuilder) buildQueryCTE(ctx context.Context, queryName s
 			querybuilder.FilterExprVisitorOpts{
 				Context:            ctx,
 				OrgID:              b.orgID,
+				Flagger:            b.stmtBuilder.fl,
 				Logger:             b.stmtBuilder.logger,
 				FieldMapper:        b.stmtBuilder.fm,
 				ConditionBuilder:   b.stmtBuilder.cb,
@@ -442,7 +443,7 @@ func (b *traceOperatorCTEBuilder) buildFinalQuery(ctx context.Context, selectFro
 		}
 	}
 
-	keySelectors := b.getKeySelectors()
+	keySelectors := querybuilder.ExpandKeySelectorsForFamilies(ctx, b.orgID, b.stmtBuilder.fl, b.getKeySelectors())
 	keys, _, err := b.stmtBuilder.metadataStore.GetKeysMulti(ctx, b.orgID, keySelectors)
 	if err != nil {
 		return nil, err

pkg/statementbuilder/tracesstatementbuilder/trace_operator_cte_builder_test.go

@@ -20,8 +20,8 @@ func newTestTraceOperatorStatementBuilder(t *testing.T) *traceOperatorStatementB
 	t.Helper()
 	releaseTime := time.Date(2025, 5, 22, 22, 0, 0, 0, time.UTC)
 	fl := flaggertest.New(t)
-	fm := tracestelemetryschema.NewFieldMapper()
-	cb := tracestelemetryschema.NewConditionBuilder(fm)
+	fm := tracestelemetryschema.NewFieldMapper(fl)
+	cb := tracestelemetryschema.NewConditionBuilder(fm, fl)
 	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
 	mockMetadataStore.KeysMap = tracestelemetryschema.BuildCompleteFieldKeyMap(releaseTime)
 	aggExprRewriter := querybuilder.NewAggExprRewriter(instrumentationtest.New().ToProviderSettings(), nil, fm, cb, fl)

pkg/statementbuilder/tracesstatementbuilder/trace_operator_statement_builder.go

@@ -25,6 +25,7 @@ type traceOperatorStatementBuilder struct {
 	traceStmtBuilder          qbtypes.StatementBuilder[qbtypes.TraceAggregation]
 	resourceFilterStmtBuilder qbtypes.StatementBuilder[qbtypes.TraceAggregation]
 	aggExprRewriter           qbtypes.AggExprRewriter
+	fl                        flagger.Flagger
 }
 
 var _ qbtypes.TraceOperatorStatementBuilder = (*traceOperatorStatementBuilder)(nil)
@@ -41,8 +42,8 @@ func NewOperatorFactory(
 	return factory.NewProviderFactory(
 		factory.MustNewName("traceoperator"),
 		func(_ context.Context, settings factory.ProviderSettings, cfg statementbuilder.Config) (qbtypes.TraceOperatorStatementBuilder, error) {
-			fm := tracestelemetryschema.NewFieldMapper()
-			cb := tracestelemetryschema.NewConditionBuilder(fm)
+			fm := tracestelemetryschema.NewFieldMapper(fl)
+			cb := tracestelemetryschema.NewConditionBuilder(fm, fl)
 			aggExprRewriter := querybuilder.NewAggExprRewriter(settings, nil, fm, cb, fl)
 			traceStmtBuilder := NewTraceQueryStatementBuilder(
 				settings, metadataStore, fm, cb, aggExprRewriter, telemetryStore, fl,
@@ -85,6 +86,7 @@ func NewTraceOperatorStatementBuilder(
 		traceStmtBuilder:          traceStmtBuilder,
 		resourceFilterStmtBuilder: resourceFilterStmtBuilder,
 		aggExprRewriter:           aggExprRewriter,
+		fl:                        flagger,
 	}
 }
 

pkg/statementbuilder/tracesstatementbuilder/trace_time_range_test.go

@@ -21,8 +21,9 @@ import (
 func TestTraceTimeRangeOptimization(t *testing.T) {
 	releaseTime := time.Date(2025, 5, 22, 22, 0, 0, 0, time.UTC)
 
-	fm := tracestelemetryschema.NewFieldMapper()
-	cb := tracestelemetryschema.NewConditionBuilder(fm)
+	fl := flaggertest.New(t)
+	fm := tracestelemetryschema.NewFieldMapper(fl)
+	cb := tracestelemetryschema.NewConditionBuilder(fm, fl)
 	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
 
 	mockMetadataStore.KeysMap = tracestelemetryschema.BuildCompleteFieldKeyMap(releaseTime)
@@ -39,7 +40,6 @@ func TestTraceTimeRangeOptimization(t *testing.T) {
 		Signal:        telemetrytypes.SignalTraces,
 	}}
 
-	fl := flaggertest.New(t)
 	aggExprRewriter := querybuilder.NewAggExprRewriter(instrumentationtest.New().ToProviderSettings(), nil, fm, cb, fl)
 
 	statementBuilder := NewTraceQueryStatementBuilder(

pkg/telemetrymetadata/condition_builder.go

@@ -38,8 +38,11 @@ func (c *conditionBuilder) ConditionFor(
 		return nil, nil, err
 	}
 
-	// an unknown key simply yields no condition rather than an error.
-	keys, warning := querybuilder.ResolveKeys(key, querybuilder.MatchingFieldKeys(key, fieldKeys))
+	// an unknown key simply yields no condition rather than an error. Metadata
+	// fields have no family support, so every logical field is single-member
+	// and flattens losslessly to its physical key.
+	resolved, warning := querybuilder.ResolveLogicalFields(key, querybuilder.MatchingLogicalFields(ctx, orgID, nil, key, fieldKeys))
+	keys := querybuilder.SingleKeys(resolved)
 	var warnings []string
 	if warning != "" {
 		warnings = append(warnings, warning)
@@ -165,7 +168,7 @@ func (c *conditionBuilder) conditionForKey(
 			KeyType:   schema.LowCardinalityColumnType{ElementType: schema.ColumnTypeString},
 			ValueType: schema.ColumnTypeString,
 		}:
-			leftOperand := fmt.Sprintf("mapContains(%s, '%s')", columns[0].Name, key.Name)
+			leftOperand := fmt.Sprintf("mapContains(%s, %s)", columns[0].Name, querybuilder.ClickHouseStringLiteral(key.Name))
 			if operator == qbtypes.FilterOperatorExists {
 				cond = sb.E(leftOperand, true)
 			} else {

pkg/telemetrymetadata/field_mapper.go

@@ -7,6 +7,7 @@ import (
 
 	schema "github.com/SigNoz/signoz-otel-collector/cmd/signozschemamigrator/schema_migrator"
 	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/querybuilder"
 	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"github.com/SigNoz/signoz/pkg/valuer"
@@ -58,6 +59,19 @@ func (m *fieldMapper) ColumnFor(ctx context.Context, _ valuer.UUID, tsStart, tsE
 	return columns, nil
 }
 
+// ExistsFor implements the per-key existence primitive of qbtypes.FieldMapper.
+func (m *fieldMapper) ExistsFor(ctx context.Context, _ valuer.UUID, tsStart, tsEnd uint64, key *telemetrytypes.TelemetryFieldKey, exists bool) (string, error) {
+	columns, err := m.getColumn(ctx, tsStart, tsEnd, key)
+	if err != nil {
+		return "", err
+	}
+	pred := fmt.Sprintf("mapContains(%s, %s)", columns[0].Name, querybuilder.ClickHouseStringLiteral(key.Name))
+	if exists {
+		return pred, nil
+	}
+	return "NOT " + pred, nil
+}
+
 func (m *fieldMapper) FieldFor(ctx context.Context, _ valuer.UUID, startNs, endNs uint64, key *telemetrytypes.TelemetryFieldKey) (string, error) {
 	columns, err := m.getColumn(ctx, startNs, endNs, key)
 	if err != nil {
@@ -69,7 +83,7 @@ func (m *fieldMapper) FieldFor(ctx context.Context, _ valuer.UUID, startNs, endN
 		KeyType:   schema.LowCardinalityColumnType{ElementType: schema.ColumnTypeString},
 		ValueType: schema.ColumnTypeString,
 	}:
-		return fmt.Sprintf("%s['%s']", columns[0].Name, key.Name), nil
+		return fmt.Sprintf("%s[%s]", columns[0].Name, querybuilder.ClickHouseStringLiteral(key.Name)), nil
 	}
 	return columns[0].Name, nil
 }
@@ -117,5 +131,5 @@ func (m *fieldMapper) ColumnExpressionFor(
 		}
 	}
 
-	return fmt.Sprintf("%s AS `%s`", sqlbuilder.Escape(fieldExpression), field.Name), nil
+	return fmt.Sprintf("%s AS %s", sqlbuilder.Escape(fieldExpression), querybuilder.ClickHouseIdentifier(field.Name)), nil
 }

pkg/telemetryschema/audittelemetryschema/condition_builder.go

@@ -147,7 +147,10 @@ func (c *conditionBuilder) ConditionFor(
 		return nil, nil, err
 	}
 
-	keys, warning := querybuilder.ResolveKeys(key, querybuilder.MatchingFieldKeys(key, fieldKeys))
+	// Audit fields have no family support, so every logical field is
+	// single-member and flattens losslessly to its physical key.
+	resolved, warning := querybuilder.ResolveLogicalFields(key, querybuilder.MatchingLogicalFields(ctx, orgID, nil, key, fieldKeys))
+	keys := querybuilder.SingleKeys(resolved)
 	var warnings []string
 	if warning != "" {
 		warnings = append(warnings, warning)

pkg/telemetryschema/audittelemetryschema/field_mapper.go

@@ -68,7 +68,7 @@ func (m *fieldMapper) FieldFor(ctx context.Context, _ valuer.UUID, _, _ uint64,
 		if key.FieldContext != telemetrytypes.FieldContextResource {
 			return "", errors.NewInvalidInputf(errors.CodeInvalidInput, "only resource context fields are supported for json columns in audit, got %s", key.FieldContext.String)
 		}
-		return fmt.Sprintf("%s.`%s`::String", column.Name, key.Name), nil
+		return fmt.Sprintf("%s.%s::String", column.Name, querybuilder.ClickHouseIdentifier(key.Name)), nil
 	case schema.ColumnTypeEnumLowCardinality:
 		return column.Name, nil
 	case schema.ColumnTypeEnumString, schema.ColumnTypeEnumUInt64, schema.ColumnTypeEnumUInt32, schema.ColumnTypeEnumUInt8:
@@ -84,7 +84,7 @@ func (m *fieldMapper) FieldFor(ctx context.Context, _ valuer.UUID, _, _ uint64,
 			if key.Materialized {
 				return telemetrytypes.FieldKeyToMaterializedColumnName(key), nil
 			}
-			return fmt.Sprintf("%s['%s']", column.Name, key.Name), nil
+			return fmt.Sprintf("%s[%s]", column.Name, querybuilder.ClickHouseStringLiteral(key.Name)), nil
 		default:
 			return "", errors.NewInvalidInputf(errors.CodeInvalidInput, "unsupported map value type %s", valueType)
 		}
@@ -97,6 +97,19 @@ func (m *fieldMapper) ColumnFor(ctx context.Context, _ valuer.UUID, _, _ uint64,
 	return m.getColumn(ctx, key)
 }
 
+// ExistsFor implements the per-key existence primitive of qbtypes.FieldMapper.
+func (m *fieldMapper) ExistsFor(ctx context.Context, orgID valuer.UUID, tsStart, tsEnd uint64, key *telemetrytypes.TelemetryFieldKey, exists bool) (string, error) {
+	fieldExpression, err := m.FieldFor(ctx, orgID, tsStart, tsEnd, key)
+	if err != nil {
+		return "", err
+	}
+	columns, err := m.getColumn(ctx, key)
+	if err != nil {
+		return "", err
+	}
+	return querybuilder.ExistsExpression(columns, key, tsStart, tsEnd, fieldExpression, exists)
+}
+
 func (m *fieldMapper) ColumnExpressionFor(
 	ctx context.Context,
 	orgID valuer.UUID,
@@ -143,7 +156,7 @@ func (m *fieldMapper) ColumnExpressionFor(
 		return fmt.Sprintf("multiIf(%s, %s, NULL)", guard, coerced), nil
 	}
 
-	return fmt.Sprintf("%s AS `%s`", sqlbuilder.Escape(fieldExpression), field.Name), nil
+	return fmt.Sprintf("%s AS %s", sqlbuilder.Escape(fieldExpression), querybuilder.ClickHouseIdentifier(field.Name)), nil
 }
 
 // CandidateKeys returns nil: audit has no synthesize-on-unknown-key fallback, so an

pkg/telemetryschema/logstelemetryschema/condition_builder.go

@@ -460,7 +460,7 @@ func (c *conditionBuilder) ConditionFor(
 	value any,
 	sb *sqlbuilder.SelectBuilder,
 ) ([]string, []string, error) {
-	matches := querybuilder.MatchingFieldKeys(key, fieldKeys)
+	matches := querybuilder.MatchingLogicalFields(ctx, orgID, nil, key, fieldKeys)
 	skipResourceFilter := options.SkipResourceFilter
 
 	// search() resolves its own (optional) scope; handle it before key resolution.
@@ -468,7 +468,10 @@ func (c *conditionBuilder) ConditionFor(
 		return c.conditionForSearch(ctx, orgID, key, value, sb)
 	}
 
-	keys, warning := querybuilder.ResolveKeys(key, matches)
+	// Logs fields have no family support yet, so every logical field is
+	// single-member and flattens losslessly to its physical key.
+	resolved, warning := querybuilder.ResolveLogicalFields(key, matches)
+	keys := querybuilder.SingleKeys(resolved)
 	var warnings []string
 	if warning != "" {
 		warnings = append(warnings, warning)

pkg/telemetryschema/logstelemetryschema/field_mapper.go

@@ -141,8 +141,8 @@ func (m *fieldMapper) FieldFor(ctx context.Context, orgID valuer.UUID, tsStart,
 		case schema.ColumnTypeEnumJSON:
 			switch key.FieldContext {
 			case telemetrytypes.FieldContextResource:
-				exprs = append(exprs, fmt.Sprintf("%s.`%s`::String", columnName, key.Name))
-				existExpr = append(existExpr, fmt.Sprintf("%s.`%s` IS NOT NULL", columnName, key.Name))
+				exprs = append(exprs, fmt.Sprintf("%s.%s::String", columnName, querybuilder.ClickHouseIdentifier(key.Name)))
+				existExpr = append(existExpr, fmt.Sprintf("%s.%s IS NOT NULL", columnName, querybuilder.ClickHouseIdentifier(key.Name)))
 			case telemetrytypes.FieldContextBody:
 				if key.Name == messageSubField {
 					exprs = append(exprs, messageSubColumn)
@@ -186,8 +186,8 @@ func (m *fieldMapper) FieldFor(ctx context.Context, orgID valuer.UUID, tsStart,
 					exprs = append(exprs, telemetrytypes.FieldKeyToMaterializedColumnName(key))
 					existExpr = append(existExpr, telemetrytypes.FieldKeyToMaterializedColumnNameForExists(key))
 				} else {
-					exprs = append(exprs, fmt.Sprintf("%s['%s']", columnName, key.Name))
-					existExpr = append(existExpr, fmt.Sprintf("mapContains(%s, '%s')", columnName, key.Name))
+					exprs = append(exprs, fmt.Sprintf("%s[%s]", columnName, querybuilder.ClickHouseStringLiteral(key.Name)))
+					existExpr = append(existExpr, fmt.Sprintf("mapContains(%s, %s)", columnName, querybuilder.ClickHouseStringLiteral(key.Name)))
 				}
 			default:
 				return "", errors.NewInvalidInputf(errors.CodeInvalidInput, "exists operator is not supported for map column type %s", valueType)
@@ -279,7 +279,7 @@ func (m *fieldMapper) ColumnExpressionFor(
 		}
 		var stmts []string
 		for _, key := range candidates {
-			guard, err := m.existsExpressionFor(ctx, orgID, tsStart, tsEnd, key, true)
+			guard, err := m.ExistsFor(ctx, orgID, tsStart, tsEnd, key, true)
 			if err != nil {
 				return "", err
 			}
@@ -308,7 +308,7 @@ func (m *fieldMapper) ColumnExpressionFor(
 		if !m.membershipGuarded(ctx, orgID, tsStart, tsEnd, candidates[0]) {
 			return m.FieldFor(ctx, orgID, tsStart, tsEnd, candidates[0])
 		}
-		guard, err := m.existsExpressionFor(ctx, orgID, tsStart, tsEnd, candidates[0], true)
+		guard, err := m.ExistsFor(ctx, orgID, tsStart, tsEnd, candidates[0], true)
 		if err != nil {
 			return "", err
 		}
@@ -326,7 +326,7 @@ func (m *fieldMapper) ColumnExpressionFor(
 
 	var stmts []string
 	for _, key := range candidates {
-		guard, err := m.existsExpressionFor(ctx, orgID, tsStart, tsEnd, key, true)
+		guard, err := m.ExistsFor(ctx, orgID, tsStart, tsEnd, key, true)
 		if err != nil {
 			return "", err
 		}
@@ -415,7 +415,7 @@ func (m *fieldMapper) buildFieldForJSON(key *telemetrytypes.TelemetryFieldKey) (
 			elemType = telemetrytypes.String
 		}
 
-		fieldPath := fmt.Sprintf("%s.`%s`", LogsV2BodyV2Column, key.Name)
+		fieldPath := fmt.Sprintf("%s.%s", LogsV2BodyV2Column, querybuilder.ClickHouseIdentifier(key.Name))
 		return fmt.Sprintf("dynamicElement(%s, '%s')", fieldPath, elemType.StringValue()), nil
 	}
 
@@ -569,7 +569,8 @@ func (m *fieldMapper) membershipGuarded(ctx context.Context, orgID valuer.UUID,
 	return columnType == schema.ColumnTypeEnumMap || columnType == schema.ColumnTypeEnumJSON
 }
 
-func (m *fieldMapper) existsExpressionFor(
+// ExistsFor implements the per-key existence primitive of qbtypes.FieldMapper.
+func (m *fieldMapper) ExistsFor(
 	ctx context.Context,
 	orgID valuer.UUID,
 	tsStart, tsEnd uint64,

pkg/telemetryschema/logstelemetryschema/json_condition_builder.go

@@ -41,7 +41,7 @@ func (c *jsonConditionBuilder) buildJSONCondition(operator qbtypes.FilterOperato
 
 	// path index
 	if operator.AddDefaultExistsFilter() {
-		pathIndex := fmt.Sprintf(`has(%s, '%s')`, schemamigrator.JSONPathsIndexExpr(LogsV2BodyV2Column), c.key.ArrayParentPaths()[0])
+		pathIndex := fmt.Sprintf(`has(%s, %s)`, schemamigrator.JSONPathsIndexExpr(LogsV2BodyV2Column), querybuilder.ClickHouseStringLiteral(c.key.ArrayParentPaths()[0]))
 		return sb.And(baseCond, pathIndex), nil
 	}
 

pkg/telemetryschema/metricstelemetryschema/condition_builder.go

@@ -136,9 +136,9 @@ func (c *conditionBuilder) conditionFor(
 		}
 
 		if operator == qbtypes.FilterOperatorExists {
-			return fmt.Sprintf("has(JSONExtractKeys(labels), '%s')", key.Name), nil
+			return fmt.Sprintf("has(JSONExtractKeys(labels), %s)", querybuilder.ClickHouseStringLiteral(key.Name)), nil
 		}
-		return fmt.Sprintf("not has(JSONExtractKeys(labels), '%s')", key.Name), nil
+		return fmt.Sprintf("not has(JSONExtractKeys(labels), %s)", querybuilder.ClickHouseStringLiteral(key.Name)), nil
 	}
 	return "", errors.NewInvalidInputf(errors.CodeInvalidInput, "unsupported operator: %v", operator)
 }
@@ -162,7 +162,9 @@ func (c *conditionBuilder) ConditionFor(
 		return nil, nil, err
 	}
 
-	keys := querybuilder.MatchingFieldKeys(key, fieldKeys)
+	// Metric labels have no family support, so every logical field is
+	// single-member and flattens losslessly to its physical key.
+	keys := querybuilder.SingleKeys(querybuilder.MatchingLogicalFields(ctx, orgID, nil, key, fieldKeys))
 	var warnings []string
 	if len(keys) == 0 {
 		if _, isColumn := timeSeriesV4Columns[key.Name]; isColumn {

pkg/telemetryschema/metricstelemetryschema/field_mapper.go

@@ -6,6 +6,7 @@ import (
 	"slices"
 
 	schema "github.com/SigNoz/signoz-otel-collector/cmd/signozschemamigrator/schema_migrator"
+	"github.com/SigNoz/signoz/pkg/querybuilder"
 	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"github.com/SigNoz/signoz/pkg/valuer"
@@ -79,14 +80,14 @@ func (m *fieldMapper) FieldFor(ctx context.Context, _ valuer.UUID, startNs, endN
 
 	switch key.FieldContext {
 	case telemetrytypes.FieldContextResource, telemetrytypes.FieldContextScope, telemetrytypes.FieldContextAttribute:
-		return fmt.Sprintf("JSONExtractString(%s, '%s')", columns[0].Name, key.Name), nil
+		return fmt.Sprintf("JSONExtractString(%s, %s)", columns[0].Name, querybuilder.ClickHouseStringLiteral(key.Name)), nil
 	case telemetrytypes.FieldContextMetric:
 		return columns[0].Name, nil
 	case telemetrytypes.FieldContextUnspecified:
 		if slices.Contains(IntrinsicFields, key.Name) {
 			return columns[0].Name, nil
 		}
-		return fmt.Sprintf("JSONExtractString(%s, '%s')", columns[0].Name, key.Name), nil
+		return fmt.Sprintf("JSONExtractString(%s, %s)", columns[0].Name, querybuilder.ClickHouseStringLiteral(key.Name)), nil
 	}
 
 	return columns[0].Name, nil
@@ -96,6 +97,18 @@ func (m *fieldMapper) ColumnFor(ctx context.Context, _ valuer.UUID, tsStart, tsE
 	return m.getColumn(ctx, tsStart, tsEnd, key)
 }
 
+// ExistsFor implements the per-key existence primitive of qbtypes.FieldMapper.
+// Intrinsic fields always exist; labels are checked for key membership.
+func (m *fieldMapper) ExistsFor(_ context.Context, _ valuer.UUID, _, _ uint64, key *telemetrytypes.TelemetryFieldKey, exists bool) (string, error) {
+	if slices.Contains(IntrinsicFields, key.Name) {
+		return "true", nil
+	}
+	if exists {
+		return fmt.Sprintf("has(JSONExtractKeys(labels), %s)", querybuilder.ClickHouseStringLiteral(key.Name)), nil
+	}
+	return fmt.Sprintf("not has(JSONExtractKeys(labels), %s)", querybuilder.ClickHouseStringLiteral(key.Name)), nil
+}
+
 func (m *fieldMapper) ColumnExpressionFor(
 	ctx context.Context,
 	orgID valuer.UUID,

pkg/telemetryschema/tracestelemetryschema/condition_builder.go

@@ -9,6 +9,7 @@ import (
 	"time"
 
 	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/flagger"
 	"github.com/SigNoz/signoz/pkg/querybuilder"
 	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
@@ -19,12 +20,15 @@ import (
 
 type conditionBuilder struct {
 	fm qbtypes.FieldMapper
+	// fl evaluates the resolve_semconv_families flag during resolution.
+	// A nil flagger keeps resolution literal.
+	fl flagger.Flagger
 }
 
 var _ qbtypes.ConditionBuilder = (*conditionBuilder)(nil)
 
-func NewConditionBuilder(fm qbtypes.FieldMapper) *conditionBuilder {
-	return &conditionBuilder{fm: fm}
+func NewConditionBuilder(fm qbtypes.FieldMapper, fl flagger.Flagger) *conditionBuilder {
+	return &conditionBuilder{fm: fm, fl: fl}
 }
 
 func (c *conditionBuilder) conditionFor(
@@ -32,7 +36,7 @@ func (c *conditionBuilder) conditionFor(
 	orgID valuer.UUID,
 	startNs uint64,
 	endNs uint64,
-	key *telemetrytypes.TelemetryFieldKey,
+	logical *telemetrytypes.LogicalField,
 	operator qbtypes.FilterOperator,
 	value any,
 	sb *sqlbuilder.SelectBuilder,
@@ -42,13 +46,13 @@ func (c *conditionBuilder) conditionFor(
 		value = querybuilder.FormatValueForContains(value)
 	}
 
-	fieldExpression, err := c.fm.FieldFor(ctx, orgID, startNs, endNs, key)
+	fieldExpression, err := querybuilder.LogicalValueExpr(ctx, orgID, startNs, endNs, c.fm, logical)
 	if err != nil {
 		return "", err
 	}
 
 	// TODO(srikanthccv): maybe extend this to every possible attribute
-	if key.Name == "duration_nano" || key.Name == "durationNano" { // QoL improvement
+	if logical.Name == "duration_nano" || logical.Name == "durationNano" { // QoL improvement
 		switch v := value.(type) {
 		case string:
 			if duration, err := time.ParseDuration(v); err == nil {
@@ -65,7 +69,9 @@ func (c *conditionBuilder) conditionFor(
 		}
 	}
 
-	fieldExpression, value = querybuilder.DataTypeCollisionHandledFieldName(key, value, fieldExpression, operator)
+	// Coercion switches only on the data type, which every member shares, so
+	// the first member stands in for the field.
+	fieldExpression, value = querybuilder.DataTypeCollisionHandledFieldName(logical.Single(), value, fieldExpression, operator)
 
 	// regular operators
 	switch operator {
@@ -135,7 +141,7 @@ func (c *conditionBuilder) conditionFor(
 		// instead of using IN, we use `=` + `OR` to make use of index
 		conditions := []string{}
 		for _, value := range values {
-			cond, err := c.conditionFor(ctx, orgID, startNs, endNs, key, qbtypes.FilterOperatorEqual, value, sb)
+			cond, err := c.conditionFor(ctx, orgID, startNs, endNs, logical, qbtypes.FilterOperatorEqual, value, sb)
 			if err != nil {
 				return "", err
 			}
@@ -150,7 +156,7 @@ func (c *conditionBuilder) conditionFor(
 		// instead of using NOT IN, we use `!=` + `AND` to make use of index
 		conditions := []string{}
 		for _, value := range values {
-			cond, err := c.conditionFor(ctx, orgID, startNs, endNs, key, qbtypes.FilterOperatorNotEqual, value, sb)
+			cond, err := c.conditionFor(ctx, orgID, startNs, endNs, logical, qbtypes.FilterOperatorNotEqual, value, sb)
 			if err != nil {
 				return "", err
 			}
@@ -162,11 +168,7 @@ func (c *conditionBuilder) conditionFor(
 	// in the query builder, `exists` and `not exists` are used for
 	// key membership checks, so depending on the column type, the condition changes
 	case qbtypes.FilterOperatorExists, qbtypes.FilterOperatorNotExists:
-		columns, err := c.fm.ColumnFor(ctx, orgID, startNs, endNs, key)
-		if err != nil {
-			return "", err
-		}
-		pred, err := querybuilder.ExistsExpression(columns, key, startNs, endNs, fieldExpression, operator == qbtypes.FilterOperatorExists)
+		pred, err := querybuilder.LogicalExistsExpr(ctx, orgID, startNs, endNs, c.fm, logical, operator == qbtypes.FilterOperatorExists)
 		if err != nil {
 			return "", err
 		}
@@ -218,10 +220,10 @@ func (c *conditionBuilder) ConditionFor(
 		return nil, nil, err
 	}
 
-	matches := querybuilder.MatchingFieldKeys(key, fieldKeys)
+	matches := querybuilder.MatchingLogicalFields(ctx, orgID, c.fl, key, fieldKeys)
 	skipResourceFilter := options.SkipResourceFilter
 
-	keys, warning := querybuilder.ResolveKeys(key, matches)
+	logicalFields, warning := querybuilder.ResolveLogicalFields(key, matches)
 	var warnings []string
 	if warning != "" {
 		warnings = append(warnings, warning)
@@ -229,10 +231,10 @@ func (c *conditionBuilder) ConditionFor(
 	// 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(keys) > 0 {
+	if key.FieldContext == telemetrytypes.FieldContextUnspecified && len(logicalFields) > 0 {
 		hasColumn := false
-		for _, k := range keys {
-			if k.FieldContext == telemetrytypes.FieldContextSpan {
+		for _, logical := range logicalFields {
+			if logical.FieldContext == telemetrytypes.FieldContextSpan {
 				hasColumn = true
 				break
 			}
@@ -240,49 +242,49 @@ func (c *conditionBuilder) ConditionFor(
 		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.TelemetryFieldKey, 0, len(keys)+1)
-				combined = append(combined, probe)
-				for _, k := range keys {
-					if columnMatchesDataType(cols[0], k.FieldDataType) {
-						combined = append(combined, k)
+				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)
 					}
 				}
-				keys = combined
+				logicalFields = combined
 			}
 		}
 	}
 
 	synthesized := false
-	if len(keys) == 0 {
+	if len(logicalFields) == 0 {
 		// 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.
-		keys = c.fm.CandidateKeys(ctx, orgID, key, value, candidateLookupKeys(key, fieldKeys))
-		if len(keys) == 0 {
+		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 keys from the main
+	// When a resource sub-query already covers the term, drop resource fields from the main
 	// query. Synthesized keys are exempt: the sub-query skips keys absent from metadata.
 	if skipResourceFilter && !synthesized {
-		filtered := make([]*telemetrytypes.TelemetryFieldKey, 0, len(keys))
-		for _, k := range keys {
-			if k.FieldContext != telemetrytypes.FieldContextResource {
-				filtered = append(filtered, k)
+		filtered := make([]*telemetrytypes.LogicalField, 0, len(logicalFields))
+		for _, logical := range logicalFields {
+			if logical.FieldContext != telemetrytypes.FieldContextResource {
+				filtered = append(filtered, logical)
 			}
 		}
 		if len(filtered) == 0 {
 			return nil, warnings, nil
 		}
-		keys = filtered
+		logicalFields = filtered
 	}
 
-	conds := make([]string, 0, len(keys))
-	for _, k := range keys {
-		cond, err := c.conditionForKey(ctx, orgID, startNs, endNs, k, operator, value, sb)
+	conds := make([]string, 0, len(logicalFields))
+	for _, logical := range logicalFields {
+		cond, err := c.conditionForLogicalField(ctx, orgID, startNs, endNs, logical, operator, value, sb)
 		if err != nil {
 			return nil, nil, err
 		}
@@ -291,28 +293,28 @@ func (c *conditionBuilder) ConditionFor(
 	return conds, warnings, nil
 }
 
-func (c *conditionBuilder) conditionForKey(
+func (c *conditionBuilder) conditionForLogicalField(
 	ctx context.Context,
 	orgID valuer.UUID,
 	startNs uint64,
 	endNs uint64,
-	key *telemetrytypes.TelemetryFieldKey,
+	logical *telemetrytypes.LogicalField,
 	operator qbtypes.FilterOperator,
 	value any,
 	sb *sqlbuilder.SelectBuilder,
 ) (string, error) {
-	if c.isSpanScopeField(key.Name) {
-		return c.buildSpanScopeCondition(key, operator, value, startNs)
+	if c.isSpanScopeField(logical.Name) {
+		return c.buildSpanScopeCondition(logical.Single(), operator, value, startNs)
 	}
 
-	condition, err := c.conditionFor(ctx, orgID, startNs, endNs, key, operator, value, sb)
+	condition, err := c.conditionFor(ctx, orgID, startNs, endNs, logical, operator, value, sb)
 	if err != nil {
 		return "", err
 	}
 
 	if operator.AddDefaultExistsFilter() {
 		// skip adding exists filter for intrinsic fields
-		field, _ := c.fm.FieldFor(ctx, orgID, startNs, endNs, key)
+		field, _ := c.fm.FieldFor(ctx, orgID, startNs, endNs, logical.Single())
 		if slices.Contains(maps.Keys(IntrinsicFields), field) ||
 			slices.Contains(maps.Keys(IntrinsicFieldsDeprecated), field) ||
 			slices.Contains(maps.Keys(CalculatedFields), field) ||
@@ -320,7 +322,7 @@ func (c *conditionBuilder) conditionForKey(
 			return condition, nil
 		}
 
-		existsCondition, err := c.conditionFor(ctx, orgID, startNs, endNs, key, qbtypes.FilterOperatorExists, nil, sb)
+		existsCondition, err := c.conditionFor(ctx, orgID, startNs, endNs, logical, qbtypes.FilterOperatorExists, nil, sb)
 		if err != nil {
 			return "", err
 		}

pkg/telemetryschema/tracestelemetryschema/condition_builder_test.go

@@ -2,6 +2,7 @@ package tracestelemetryschema
 
 import (
 	"context"
+	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
 	"testing"
 	"time"
 
@@ -288,8 +289,8 @@ func TestConditionFor(t *testing.T) {
 		},
 	}
 
-	fm := NewFieldMapper()
-	conditionBuilder := NewConditionBuilder(fm)
+	fm := NewFieldMapper(flaggertest.New(t))
+	conditionBuilder := NewConditionBuilder(fm, flaggertest.New(t))
 
 	for _, tc := range testCases {
 		sb := sqlbuilder.NewSelectBuilder()
@@ -375,8 +376,8 @@ func TestConditionForResourceWithEvolution(t *testing.T) {
 		},
 	}
 
-	fm := NewFieldMapper()
-	conditionBuilder := NewConditionBuilder(fm)
+	fm := NewFieldMapper(flaggertest.New(t))
+	conditionBuilder := NewConditionBuilder(fm, flaggertest.New(t))
 
 	for _, tc := range testCases {
 		sb := sqlbuilder.NewSelectBuilder()
@@ -395,8 +396,8 @@ func TestConditionForResourceWithEvolution(t *testing.T) {
 // user input and queries anyway, emitting a warning instead of failing.
 func TestConditionForSynthesizedKeys(t *testing.T) {
 	ctx := context.Background()
-	fm := NewFieldMapper()
-	cb := NewConditionBuilder(fm)
+	fm := NewFieldMapper(flaggertest.New(t))
+	cb := NewConditionBuilder(fm, flaggertest.New(t))
 
 	// no metadata matches -> the builder must synthesize from user input
 	var noMatches map[string][]*telemetrytypes.TelemetryFieldKey

pkg/telemetryschema/tracestelemetryschema/family_test.go

@@ -0,0 +1,243 @@
+package tracestelemetryschema
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/SigNoz/signoz/pkg/flagger"
+	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/valuer"
+	"github.com/huandu/go-sqlbuilder"
+	"github.com/stretchr/testify/require"
+)
+
+// familyFlagOn returns a flagger with resolve_semconv_families on.
+func familyFlagOn(t *testing.T) flagger.Flagger {
+	return flaggertest.WithBooleanFlags(t, map[string]bool{
+		flagger.FeatureResolveSemconvFamilies.String(): true,
+	})
+}
+
+// The tests below run against the deployment.environment(.name) family as
+// trace resource attributes with the canonical evolution timeline, inside the
+// JSON-column window. The single-member value expression at this range is
+//
+//	multiIf(resource.`<name>` IS NOT NULL, resource.`<name>`::String,
+//	        mapContains(resources_string, '<name>'), resources_string['<name>'], NULL)
+//
+// and the family expressions below compose it per member.
+
+func TestConditionForFamilyMergesMembersCurrentFirst(t *testing.T) {
+	releaseTime := time.Date(2025, 5, 22, 22, 0, 0, 0, time.UTC)
+	startNs, endNs := uint64(1747947419000000000), uint64(1747983448000000000)
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+			Evolutions:    MockEvolutionData(releaseTime),
+		}},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+			Evolutions:    MockEvolutionData(releaseTime),
+		}},
+	}
+	fl := familyFlagOn(t)
+	cb := NewConditionBuilder(NewFieldMapper(fl), fl)
+
+	// The requested spelling is the old name; precedence must still be
+	// current-first.
+	sb := sqlbuilder.NewSelectBuilder()
+	conds, warnings, err := cb.ConditionFor(context.Background(), valuer.UUID{}, startNs, endNs,
+		&telemetrytypes.TelemetryFieldKey{Name: "deployment.environment"},
+		fieldKeys, qbtypes.ConditionBuilderOptions{}, qbtypes.FilterOperatorEqual, "production", sb)
+	require.NoError(t, err)
+	require.Empty(t, warnings, "a family is one logical field, never ambiguous with itself")
+	require.Len(t, conds, 1)
+
+	sb.Where(conds...)
+	sql, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	require.Equal(t, "WHERE (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), ''), '') = ? AND (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))", sql)
+	require.Equal(t, []any{"production"}, args)
+}
+
+func TestConditionForFamilyNegativeKeepsKeylessRows(t *testing.T) {
+	releaseTime := time.Date(2025, 5, 22, 22, 0, 0, 0, time.UTC)
+	startNs, endNs := uint64(1747947419000000000), uint64(1747983448000000000)
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+			Evolutions:    MockEvolutionData(releaseTime),
+		}},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+			Evolutions:    MockEvolutionData(releaseTime),
+		}},
+	}
+	fl := familyFlagOn(t)
+	cb := NewConditionBuilder(NewFieldMapper(fl), fl)
+
+	sb := sqlbuilder.NewSelectBuilder()
+	conds, _, err := cb.ConditionFor(context.Background(), valuer.UUID{}, startNs, endNs,
+		&telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"},
+		fieldKeys, qbtypes.ConditionBuilderOptions{}, qbtypes.FilterOperatorNotEqual, "production", sb)
+	require.NoError(t, err)
+	require.Len(t, conds, 1)
+
+	// The trailing '' makes rows without any member read '' (single-key map
+	// semantics), so `!=` keeps including them; no exists filter is added.
+	sb.Where(conds...)
+	sql, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	require.Equal(t, "WHERE 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), ''), '') <> ?", sql)
+	require.Equal(t, []any{"production"}, args)
+}
+
+func TestConditionForFamilyExists(t *testing.T) {
+	releaseTime := time.Date(2025, 5, 22, 22, 0, 0, 0, time.UTC)
+	startNs, endNs := uint64(1747947419000000000), uint64(1747983448000000000)
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+			Evolutions:    MockEvolutionData(releaseTime),
+		}},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+			Evolutions:    MockEvolutionData(releaseTime),
+		}},
+	}
+	fl := familyFlagOn(t)
+	cb := NewConditionBuilder(NewFieldMapper(fl), fl)
+
+	sb := sqlbuilder.NewSelectBuilder()
+	conds, _, err := cb.ConditionFor(context.Background(), valuer.UUID{}, startNs, endNs,
+		&telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"},
+		fieldKeys, qbtypes.ConditionBuilderOptions{}, qbtypes.FilterOperatorNotExists, nil, sb)
+	require.NoError(t, err)
+	require.Len(t, conds, 1)
+
+	sb.Where(conds...)
+	sql, _ := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	require.Equal(t, "WHERE NOT (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)", sql)
+}
+
+// With the flag off, both spellings can be in the metadata map and the
+// condition still uses only the requested key. Users see no change until the
+// flag is on.
+func TestConditionForFamilyOffByDefault(t *testing.T) {
+	releaseTime := time.Date(2025, 5, 22, 22, 0, 0, 0, time.UTC)
+	startNs, endNs := uint64(1747947419000000000), uint64(1747983448000000000)
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+			Evolutions:    MockEvolutionData(releaseTime),
+		}},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+			Evolutions:    MockEvolutionData(releaseTime),
+		}},
+	}
+	fl := flaggertest.New(t)
+	cb := NewConditionBuilder(NewFieldMapper(fl), fl)
+
+	sb := sqlbuilder.NewSelectBuilder()
+	conds, _, err := cb.ConditionFor(context.Background(), valuer.UUID{}, startNs, endNs,
+		&telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"},
+		fieldKeys, qbtypes.ConditionBuilderOptions{}, qbtypes.FilterOperatorEqual, "production", sb)
+	require.NoError(t, err)
+	require.Len(t, conds, 1)
+
+	sb.Where(conds...)
+	sql, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	require.Equal(t, "WHERE (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) = ? AND 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)", sql)
+	require.Equal(t, []any{"production"}, args)
+}
+
+// With only one member in metadata the condition is the exact single-key
+// shape: composition only appears when metadata proves a second member.
+func TestConditionForSingleMemberIsUnchanged(t *testing.T) {
+	releaseTime := time.Date(2025, 5, 22, 22, 0, 0, 0, time.UTC)
+	startNs, endNs := uint64(1747947419000000000), uint64(1747983448000000000)
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+			Evolutions:    MockEvolutionData(releaseTime),
+		}},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+			Evolutions:    MockEvolutionData(releaseTime),
+		}},
+	}
+	delete(fieldKeys, "deployment.environment")
+	fl := familyFlagOn(t)
+	cb := NewConditionBuilder(NewFieldMapper(fl), fl)
+
+	sb := sqlbuilder.NewSelectBuilder()
+	conds, _, err := cb.ConditionFor(context.Background(), valuer.UUID{}, startNs, endNs,
+		&telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"},
+		fieldKeys, qbtypes.ConditionBuilderOptions{}, qbtypes.FilterOperatorEqual, "production", sb)
+	require.NoError(t, err)
+	require.Len(t, conds, 1)
+
+	sb.Where(conds...)
+	sql, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	require.Equal(t, "WHERE (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) = ? AND 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)", sql)
+	require.Equal(t, []any{"production"}, args)
+}
+
+func TestColumnExpressionForFamilyGroupBy(t *testing.T) {
+	releaseTime := time.Date(2025, 5, 22, 22, 0, 0, 0, time.UTC)
+	startNs, endNs := uint64(1747947419000000000), uint64(1747983448000000000)
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+			Evolutions:    MockEvolutionData(releaseTime),
+		}},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+			Evolutions:    MockEvolutionData(releaseTime),
+		}},
+	}
+	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)
+}

pkg/telemetryschema/tracestelemetryschema/field_mapper.go

@@ -7,6 +7,7 @@ import (
 
 	schema "github.com/SigNoz/signoz-otel-collector/cmd/signozschemamigrator/schema_migrator"
 	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/flagger"
 	"github.com/SigNoz/signoz/pkg/querybuilder"
 	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
@@ -159,12 +160,16 @@ var (
 	}
 )
 
-type fieldMapper struct{}
+type fieldMapper struct {
+	// fl evaluates the resolve_semconv_families flag during resolution.
+	// A nil flagger keeps resolution literal.
+	fl flagger.Flagger
+}
 
 var _ qbtypes.FieldMapper = (*fieldMapper)(nil)
 
-func NewFieldMapper() *fieldMapper {
-	return &fieldMapper{}
+func NewFieldMapper(fl flagger.Flagger) *fieldMapper {
+	return &fieldMapper{fl: fl}
 }
 
 func (m *fieldMapper) getColumn(
@@ -293,8 +298,8 @@ func (m *fieldMapper) resolveColumnExprs(
 			}
 			// have to add ::string as clickHouse throws an error :- data types Variant/Dynamic are not allowed in GROUP BY
 			// once clickHouse dependency is updated, we need to check if we can remove it.
-			exprs = append(exprs, fmt.Sprintf("%s.`%s`::String", columnName, key.Name))
-			existExprs = append(existExprs, fmt.Sprintf("%s.`%s` IS NOT NULL", columnName, key.Name))
+			exprs = append(exprs, fmt.Sprintf("%s.%s::String", columnName, querybuilder.ClickHouseIdentifier(key.Name)))
+			existExprs = append(existExprs, fmt.Sprintf("%s.%s IS NOT NULL", columnName, querybuilder.ClickHouseIdentifier(key.Name)))
 		case schema.ColumnTypeEnumString,
 			schema.ColumnTypeEnumUInt64,
 			schema.ColumnTypeEnumUInt32,
@@ -324,8 +329,8 @@ func (m *fieldMapper) resolveColumnExprs(
 					exprs = append(exprs, telemetrytypes.FieldKeyToMaterializedColumnName(key))
 					existExprs = append(existExprs, telemetrytypes.FieldKeyToMaterializedColumnNameForExists(key))
 				} else {
-					exprs = append(exprs, fmt.Sprintf("%s['%s']", columnName, key.Name))
-					existExprs = append(existExprs, fmt.Sprintf("mapContains(%s, '%s')", columnName, key.Name))
+					exprs = append(exprs, fmt.Sprintf("%s[%s]", columnName, querybuilder.ClickHouseStringLiteral(key.Name)))
+					existExprs = append(existExprs, fmt.Sprintf("mapContains(%s, %s)", columnName, querybuilder.ClickHouseStringLiteral(key.Name)))
 				}
 			default:
 				return nil, nil, nil, errors.NewInvalidInputf(errors.CodeInvalidInput, "value type %s is not supported for map column type %s", valueType, column.Type)
@@ -336,6 +341,68 @@ func (m *fieldMapper) resolveColumnExprs(
 	return exprs, existExprs, columns, nil
 }
 
+// logicalForResolvedColumn upgrades a directly-resolvable key (the FieldFor
+// probe succeeded) to its family when the metadata map proves membership;
+// otherwise the key stays a single-member logical field.
+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
+// 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.
@@ -348,18 +415,23 @@ func (m *fieldMapper) ColumnExpressionFor(
 	keys map[string][]*telemetrytypes.TelemetryFieldKey,
 ) (string, error) {
 
-	// Resolve the candidate column(s).
-	var candidates []*telemetrytypes.TelemetryFieldKey
+	// Resolve the candidate logical field(s).
+	var candidates []*telemetrytypes.LogicalField
 	switch _, err := m.FieldFor(ctx, orgID, startNs, endNs, field); {
 	case err == nil:
-		candidates = []*telemetrytypes.TelemetryFieldKey{field}
+		// A directly-resolvable key upgrades to its family when the metadata
+		// map proves membership; otherwise it stays single-member.
+		candidates = []*telemetrytypes.LogicalField{m.logicalForResolvedColumn(ctx, orgID, field, keys)}
 	case errors.Is(err, qbtypes.ErrColumnNotFound):
-		// column (when the bare name is one) plus metadata matches, else synthesized
-		// type-variant keys.
-		candidates = m.CandidateKeys(ctx, orgID, field, nil, keys)
-		if len(candidates) == 0 {
+		// The legacy candidate flow, unchanged: column (when the bare name is
+		// one) plus metadata matches, else synthesized type-variant keys. The
+		// family step below only swaps candidates for their family; it never
+		// changes candidate order or non-family behavior.
+		raw := m.CandidateKeys(ctx, orgID, field, nil, keys)
+		if len(raw) == 0 {
 			return "", errors.Wrapf(err, errors.TypeInvalidInput, errors.CodeInvalidInput, "field `%s` not found", field.Name).WithSuggestions(errors.NewSuggestionsOnLevenshteinDistance(field.Name, errors.NounKeys, maps.Keys(keys))...)
 		}
+		candidates = m.upgradeToFamilies(ctx, orgID, field, querybuilder.WrapAsLogicalFields(field.Name, raw), keys)
 	default:
 		return "", err
 	}
@@ -373,21 +445,21 @@ func (m *fieldMapper) ColumnExpressionFor(
 			dummyValue = 0.0
 		}
 		stmts := make([]string, 0, len(candidates)*2)
-		for _, key := range candidates {
-			value, err := m.FieldFor(ctx, orgID, startNs, endNs, key)
+		for _, logical := range candidates {
+			value, err := querybuilder.LogicalValueExpr(ctx, orgID, startNs, endNs, m, logical)
 			if err != nil {
 				return "", err
 			}
-			guard, err := m.existsExpressionFor(ctx, orgID, startNs, endNs, key, true)
+			guard, err := querybuilder.LogicalExistsExpr(ctx, orgID, startNs, endNs, m, logical, true)
 			if err != nil {
 				return "", err
 			}
 			coerced := value
 			// a time column keeps its native type; coercing it would yield seconds
-			if temporal, err := m.columnIsTemporal(ctx, startNs, endNs, key); err != nil {
+			if temporal, err := m.logicalIsTemporal(ctx, startNs, endNs, logical); err != nil {
 				return "", err
 			} else if !temporal {
-				coerced, _ = querybuilder.DataTypeCollisionHandledFieldName(key, dummyValue, value, qbtypes.FilterOperatorUnknown)
+				coerced, _ = querybuilder.DataTypeCollisionHandledFieldName(logical.Single(), dummyValue, value, qbtypes.FilterOperatorUnknown)
 			}
 			stmts = append(stmts, guard, coerced)
 		}
@@ -395,13 +467,14 @@ func (m *fieldMapper) ColumnExpressionFor(
 	}
 
 	if len(candidates) == 1 {
-		value, err := m.FieldFor(ctx, orgID, startNs, endNs, candidates[0])
+		logical := candidates[0]
+		value, err := querybuilder.LogicalValueExpr(ctx, orgID, startNs, endNs, m, logical)
 		if err != nil {
 			return "", err
 		}
-		exprs, existExprs, _, _ := m.resolveColumnExprs(ctx, startNs, endNs, candidates[0])
-		if len(exprs) == 1 && len(existExprs) == 1 {
-			guard, err := m.existsExpressionFor(ctx, orgID, startNs, endNs, candidates[0], true)
+		exprs, existExprs, _, _ := m.resolveColumnExprs(ctx, startNs, endNs, logical.Single())
+		if !logical.IsFamily() && len(exprs) == 1 && len(existExprs) == 1 {
+			guard, err := querybuilder.LogicalExistsExpr(ctx, orgID, startNs, endNs, m, logical, true)
 			if err != nil {
 				return "", err
 			}
@@ -413,12 +486,12 @@ func (m *fieldMapper) ColumnExpressionFor(
 	// Multiple candidates (collision / synth): multiIf picks the first that exists,
 	// stringified so branches share a type.
 	args := make([]string, 0, len(candidates))
-	for _, key := range candidates {
-		value, err := m.FieldFor(ctx, orgID, startNs, endNs, key)
+	for _, logical := range candidates {
+		value, err := querybuilder.LogicalValueExpr(ctx, orgID, startNs, endNs, m, logical)
 		if err != nil {
 			return "", err
 		}
-		guard, err := m.existsExpressionFor(ctx, orgID, startNs, endNs, key, true)
+		guard, err := querybuilder.LogicalExistsExpr(ctx, orgID, startNs, endNs, m, logical, true)
 		if err != nil {
 			return "", err
 		}
@@ -427,6 +500,15 @@ func (m *fieldMapper) ColumnExpressionFor(
 	return fmt.Sprintf("multiIf(%s, NULL)", strings.Join(args, ", ")), nil
 }
 
+// logicalIsTemporal reports whether the logical field resolves to a single time
+// column. A family is attribute-backed and never temporal.
+func (m *fieldMapper) logicalIsTemporal(ctx context.Context, startNs, endNs uint64, logical *telemetrytypes.LogicalField) (bool, error) {
+	if logical.IsFamily() {
+		return false, nil
+	}
+	return m.columnIsTemporal(ctx, startNs, endNs, logical.Single())
+}
+
 // columnIsTemporal reports whether key resolves to a single time column, after evolution
 // selection. Multiple columns mean an attribute-map union, which is never temporal.
 func (m *fieldMapper) columnIsTemporal(ctx context.Context, startNs, endNs uint64, key *telemetrytypes.TelemetryFieldKey) (bool, error) {
@@ -522,7 +604,8 @@ func (m *fieldMapper) CandidateKeys(ctx context.Context, _ valuer.UUID, field *t
 	return nil
 }
 
-func (m *fieldMapper) existsExpressionFor(
+// ExistsFor implements the per-key existence primitive of qbtypes.FieldMapper.
+func (m *fieldMapper) ExistsFor(
 	ctx context.Context,
 	orgID valuer.UUID,
 	tsStart, tsEnd uint64,

pkg/telemetryschema/tracestelemetryschema/field_mapper_test.go

@@ -2,6 +2,7 @@ package tracestelemetryschema
 
 import (
 	"context"
+	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
 	"testing"
 	"time"
 
@@ -107,7 +108,7 @@ func TestGetFieldKeyName(t *testing.T) {
 
 	for _, tc := range testCases {
 		t.Run(tc.name, func(t *testing.T) {
-			fm := NewFieldMapper()
+			fm := NewFieldMapper(flaggertest.New(t))
 			result, err := fm.FieldFor(ctx, valuer.UUID{}, uint64(time.Date(2024, 6, 1, 0, 0, 0, 0, time.UTC).UnixNano()), uint64(time.Date(2024, 6, 5, 0, 0, 0, 0, time.UTC).UnixNano()), &tc.key)
 
 			if tc.expectedError != nil {
@@ -195,7 +196,7 @@ func TestFieldForResourceWithEvolution(t *testing.T) {
 
 	for _, tc := range testCases {
 		t.Run(tc.name, func(t *testing.T) {
-			fm := NewFieldMapper()
+			fm := NewFieldMapper(flaggertest.New(t))
 			result, err := fm.FieldFor(ctx, valuer.UUID{}, tc.tsStart, tc.tsEnd, &tc.key)
 			require.NoError(t, err)
 			assert.Equal(t, tc.expectedResult, result)
@@ -255,7 +256,7 @@ func TestColumnExpressionForTemporalColumn(t *testing.T) {
 
 	for _, tc := range testCases {
 		t.Run(tc.name, func(t *testing.T) {
-			fm := NewFieldMapper()
+			fm := NewFieldMapper(flaggertest.New(t))
 			result, err := fm.ColumnExpressionFor(ctx, valuer.UUID{}, tsStart, tsEnd, &tc.key, tc.requiredDataType, nil)
 			require.NoError(t, err)
 			assert.Equal(t, tc.expectedResult, result)
@@ -283,7 +284,7 @@ func TestColumnExpressionForTimestampAttributeCollision(t *testing.T) {
 		},
 	}
 
-	fm := NewFieldMapper()
+	fm := NewFieldMapper(flaggertest.New(t))
 
 	t.Run("bare timestamp resolves to the intrinsic column alone", func(t *testing.T) {
 		bare := telemetrytypes.TelemetryFieldKey{Name: "timestamp"}

pkg/telemetryschema/tracestelemetryschema/span_scope_simple_test.go

@@ -2,6 +2,7 @@ package tracestelemetryschema
 
 import (
 	"context"
+	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
 	"testing"
 
 	"github.com/SigNoz/signoz/pkg/instrumentation/instrumentationtest"
@@ -14,8 +15,8 @@ import (
 
 func TestSpanScopeFilterExpression(t *testing.T) {
 	// Test that span scope fields work in filter expressions
-	fm := NewFieldMapper()
-	cb := NewConditionBuilder(fm)
+	fm := NewFieldMapper(flaggertest.New(t))
+	cb := NewConditionBuilder(fm, flaggertest.New(t))
 
 	tests := []struct {
 		name              string
@@ -128,8 +129,8 @@ func TestSpanScopeWithResourceFilter(t *testing.T) {
 			// For now, just verify the expression parses correctly
 			// In a real implementation, we'd need to check that the resource filter
 			// is properly skipped when span scope fields are present
-			fm := NewFieldMapper()
-			cb := NewConditionBuilder(fm)
+			fm := NewFieldMapper(flaggertest.New(t))
+			cb := NewConditionBuilder(fm, flaggertest.New(t))
 
 			// Prepare field keys for the test
 			fieldKeys := make(map[string][]*telemetrytypes.TelemetryFieldKey)

pkg/telemetryschema/tracestelemetryschema/test_data.go

@@ -113,6 +113,21 @@ func BuildCompleteFieldKeyMap(releaseTime time.Time) map[string][]*telemetrytype
 				FieldDataType: telemetrytypes.FieldDataTypeBool,
 			},
 		},
+		// both spellings of an enabled semantic-convention family
+		"deployment.environment.name": {
+			{
+				Name:          "deployment.environment.name",
+				FieldContext:  telemetrytypes.FieldContextResource,
+				FieldDataType: telemetrytypes.FieldDataTypeString,
+			},
+		},
+		"deployment.environment": {
+			{
+				Name:          "deployment.environment",
+				FieldContext:  telemetrytypes.FieldContextResource,
+				FieldDataType: telemetrytypes.FieldDataTypeString,
+			},
+		},
 	}
 	for _, keys := range keysMap {
 		for _, key := range keys {

pkg/types/querybuildertypes/querybuildertypesv5/qb.go

@@ -18,7 +18,14 @@ var (
 	ErrUnsupportedOperator = errors.NewInvalidInputf(errors.CodeInvalidInput, "unsupported operator")
 )
 
-// FieldMapper maps the telemetry field key to the table field name.
+// FieldMapper is a signal's storage dialect: given a resolved physical key, it
+// renders how this signal's tables express that key — its value (FieldFor),
+// its presence (ExistsFor), and its backing columns (ColumnFor) — honoring
+// materialization and column-generation choices carried on the key.
+//
+// ColumnExpressionFor and CandidateKeys additionally carry per-signal
+// resolution behavior (unknown-name fallback, candidate ordering); they
+// predate the resolution layer and are slated to move behind it.
 type FieldMapper interface {
 	// FieldFor returns the field name for the given key.
 	FieldFor(ctx context.Context, orgID valuer.UUID, tsStart, tsEnd uint64, key *telemetrytypes.TelemetryFieldKey) (string, error)
@@ -34,6 +41,11 @@ type FieldMapper interface {
 	// the name (or `{context}.{name}`) first, else synthesized type-variant keys for sources
 	// that support it, else nil (caller errors). value is the filter operand, nil otherwise.
 	CandidateKeys(ctx context.Context, orgID valuer.UUID, field *telemetrytypes.TelemetryFieldKey, value any, keys map[string][]*telemetrytypes.TelemetryFieldKey) []*telemetrytypes.TelemetryFieldKey
+	// ExistsFor returns the existence predicate for a single physical key (negated when
+	// exists is false), self-contained and arg-free so it can guard column expressions.
+	// It is the per-member primitive querybuilder.LogicalExistsExpr and the numeric branch
+	// of querybuilder.LogicalValueExpr compose family expressions from.
+	ExistsFor(ctx context.Context, orgID valuer.UUID, tsStart, tsEnd uint64, key *telemetrytypes.TelemetryFieldKey, exists bool) (string, error)
 }
 
 // ConditionBuilder builds the conditions for a filter term. The builder owns key resolution:

tests/fixtures/serviceaccount.py

@@ -24,12 +24,12 @@ def create_service_account(signoz: types.SigNoz, token: str, name: str, role: st
 
     role_id = find_role_by_name(signoz, token, role)
     role_resp = requests.post(
-        signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{service_account_id}/roles"),
-        json={"id": role_id},
+        signoz.self.host_configs["8080"].get("/api/v1/service_account_roles"),
+        json={"serviceAccountId": service_account_id, "roleId": role_id},
         headers={"Authorization": f"Bearer {token}"},
         timeout=5,
     )
-    assert role_resp.status_code == HTTPStatus.NO_CONTENT, role_resp.text
+    assert role_resp.status_code == HTTPStatus.CREATED, role_resp.text
 
     return service_account_id
 
@@ -85,12 +85,12 @@ def create_service_account_with_roles(signoz: types.SigNoz, token: str, name: st
     for role in roles:
         role_id = find_role_by_name(signoz, token, role)
         role_resp = requests.post(
-            signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{service_account_id}/roles"),
-            json={"id": role_id},
+            signoz.self.host_configs["8080"].get("/api/v1/service_account_roles"),
+            json={"serviceAccountId": service_account_id, "roleId": role_id},
             headers={"Authorization": f"Bearer {token}"},
             timeout=5,
         )
-        assert role_resp.status_code == HTTPStatus.NO_CONTENT, role_resp.text
+        assert role_resp.status_code == HTTPStatus.CREATED, role_resp.text
 
     return service_account_id
 

tests/integration/tests/passwordauthn/06_invite_status.py

@@ -129,4 +129,4 @@ def test_delete_user(
     assert response.status_code == HTTPStatus.OK
     data = response.json()["data"]
     assert data["status"] == "deleted"
-    assert len(data["userRoles"]) == 1
+    assert len(data["userRoles"]) == 0

tests/integration/tests/role/02_crud.py

@@ -267,6 +267,40 @@ def test_delete_role_with_assignee_guarded(
     assert resp.status_code == HTTPStatus.NO_CONTENT, resp.text
 
 
+def test_delete_role_after_deleting_assigned_user(
+    signoz: types.SigNoz,
+    create_user_admin: types.Operation,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    create_role: Callable[..., str],
+):
+    admin_token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+
+    role_id = create_role(admin_token, "crud-deleted-assignee-role", [transaction_group("read", "metaresource", "dashboard", ["*"])])
+
+    user_id = create_active_user(
+        signoz,
+        admin_token,
+        email="crud+deleted-assignee@integration.test",
+        role="signoz-viewer",
+        password=CRUD_ASSIGNEE_USER_PASSWORD,
+        name="crud-deleted-assignee-user",
+    )
+
+    resp = requests.post(
+        signoz.self.host_configs["8080"].get("/api/v2/user_roles"),
+        json={"userId": user_id, "roleId": role_id},
+        headers={"Authorization": f"Bearer {admin_token}"},
+        timeout=5,
+    )
+    assert resp.status_code == HTTPStatus.CREATED, resp.text
+
+    resp = requests.delete(signoz.self.host_configs["8080"].get(f"/api/v2/users/{user_id}"), headers={"Authorization": f"Bearer {admin_token}"}, timeout=5)
+    assert resp.status_code == HTTPStatus.NO_CONTENT, resp.text
+
+    resp = requests.delete(signoz.self.host_configs["8080"].get(f"/api/v1/roles/{role_id}"), headers={"Authorization": f"Bearer {admin_token}"}, timeout=5)
+    assert resp.status_code == HTTPStatus.NO_CONTENT, f"delete role after deleting its only assignee: {resp.text}"
+
+
 def test_delete_removes_role(
     signoz: types.SigNoz,
     create_user_admin: types.Operation,  # pylint: disable=unused-argument

tests/integration/tests/serviceaccount/04_roles.py

@@ -44,7 +44,7 @@ def test_assign_role_to_service_account(
     create_user_admin: types.Operation,  # pylint: disable=unused-argument
     get_token: Callable[[str, str], str],
 ):
-    """POST /{id}/roles adds a role alongside existing ones."""
+    """POST /service_account_roles adds a role alongside existing ones."""
     token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
 
     # create service account with viewer role
@@ -53,12 +53,13 @@ def test_assign_role_to_service_account(
     # assign editor role (additive — viewer stays)
     editor_role_id = find_role_by_name(signoz, token, "signoz-editor")
     assign_resp = requests.post(
-        signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{service_account_id}/roles"),
-        json={"id": editor_role_id},
+        signoz.self.host_configs["8080"].get("/api/v1/service_account_roles"),
+        json={"serviceAccountId": service_account_id, "roleId": editor_role_id},
         headers={"Authorization": f"Bearer {token}"},
         timeout=5,
     )
-    assert assign_resp.status_code == HTTPStatus.NO_CONTENT, assign_resp.text
+    assert assign_resp.status_code == HTTPStatus.CREATED, assign_resp.text
+    assert assign_resp.json()["data"]["id"]
 
     # verify both viewer and editor roles are present
     roles_resp = requests.get(
@@ -75,12 +76,12 @@ def test_assign_role_to_service_account(
     # assign admin role — all three should be present
     admin_role_id = find_role_by_name(signoz, token, "signoz-admin")
     assign_resp = requests.post(
-        signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{service_account_id}/roles"),
-        json={"id": admin_role_id},
+        signoz.self.host_configs["8080"].get("/api/v1/service_account_roles"),
+        json={"serviceAccountId": service_account_id, "roleId": admin_role_id},
         headers={"Authorization": f"Bearer {token}"},
         timeout=5,
     )
-    assert assign_resp.status_code == HTTPStatus.NO_CONTENT, assign_resp.text
+    assert assign_resp.status_code == HTTPStatus.CREATED, assign_resp.text
 
     roles_resp = requests.get(
         signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{service_account_id}/roles"),
@@ -100,7 +101,7 @@ def test_assign_role_idempotent(
     create_user_admin: types.Operation,  # pylint: disable=unused-argument
     get_token: Callable[[str, str], str],
 ):
-    """POST same role twice succeeds (replace with same role is idempotent)."""
+    """POST same role twice returns the same assignment (idempotent)."""
     token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
     service_account_id = create_service_account(signoz, token, "sa-role-idempotent", role="signoz-viewer")
 
@@ -108,12 +109,12 @@ def test_assign_role_idempotent(
 
     # assign the same role again
     resp = requests.post(
-        signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{service_account_id}/roles"),
-        json={"id": viewer_role_id},
+        signoz.self.host_configs["8080"].get("/api/v1/service_account_roles"),
+        json={"serviceAccountId": service_account_id, "roleId": viewer_role_id},
         headers={"Authorization": f"Bearer {token}"},
         timeout=5,
     )
-    assert resp.status_code == HTTPStatus.NO_CONTENT, resp.text
+    assert resp.status_code == HTTPStatus.CREATED, resp.text
 
     # verify only one instance of the role
     roles_resp = requests.get(
@@ -147,12 +148,12 @@ def test_assign_role_expands_access(
     # assign admin role (additive — viewer stays)
     admin_role_id = find_role_by_name(signoz, token, "signoz-admin")
     assign_resp = requests.post(
-        signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{service_account_id}/roles"),
-        json={"id": admin_role_id},
+        signoz.self.host_configs["8080"].get("/api/v1/service_account_roles"),
+        json={"serviceAccountId": service_account_id, "roleId": admin_role_id},
         headers={"Authorization": f"Bearer {token}"},
         timeout=5,
     )
-    assert assign_resp.status_code == HTTPStatus.NO_CONTENT, assign_resp.text
+    assert assign_resp.status_code == HTTPStatus.CREATED, assign_resp.text
 
     # SA should now have admin access
     resp = requests.get(
@@ -180,24 +181,32 @@ def test_remove_role_from_service_account(
     create_user_admin: types.Operation,  # pylint: disable=unused-argument
     get_token: Callable[[str, str], str],
 ):
-    """DELETE /{id}/roles/{rid} revokes one role while keeping others."""
+    """DELETE /service_account_roles/{id} revokes one role while keeping others."""
     token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
     service_account_id = create_service_account(signoz, token, "sa-remove-role", role="signoz-editor")
 
     # add admin role (now has editor + admin)
     admin_role_id = find_role_by_name(signoz, token, "signoz-admin")
     assign_resp = requests.post(
-        signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{service_account_id}/roles"),
-        json={"id": admin_role_id},
+        signoz.self.host_configs["8080"].get("/api/v1/service_account_roles"),
+        json={"serviceAccountId": service_account_id, "roleId": admin_role_id},
         headers={"Authorization": f"Bearer {token}"},
         timeout=5,
     )
-    assert assign_resp.status_code == HTTPStatus.NO_CONTENT, assign_resp.text
+    assert assign_resp.status_code == HTTPStatus.CREATED, assign_resp.text
+
+    # find the editor assignment entry id from the service account detail
+    detail_resp = requests.get(
+        signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{service_account_id}"),
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=5,
+    )
+    assert detail_resp.status_code == HTTPStatus.OK, detail_resp.text
+    editor_entry_id = next(entry["id"] for entry in detail_resp.json()["data"]["serviceAccountRoles"] if entry["role"]["name"] == "signoz-editor")
 
     # remove editor role
-    editor_role_id = find_role_by_name(signoz, token, "signoz-editor")
     resp = requests.delete(
-        signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{service_account_id}/roles/{editor_role_id}"),
+        signoz.self.host_configs["8080"].get(f"/api/v1/service_account_roles/{editor_entry_id}"),
         headers={"Authorization": f"Bearer {token}"},
         timeout=5,
     )
@@ -232,10 +241,18 @@ def test_remove_role_verify_access_lost(
     )
     assert resp.status_code == HTTPStatus.OK, resp.text
 
+    # find the admin assignment entry id from the service account detail
+    detail_resp = requests.get(
+        signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{service_account_id}"),
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=5,
+    )
+    assert detail_resp.status_code == HTTPStatus.OK, detail_resp.text
+    admin_entry_id = next(entry["id"] for entry in detail_resp.json()["data"]["serviceAccountRoles"] if entry["role"]["name"] == "signoz-admin")
+
     # remove admin role
-    admin_role_id = find_role_by_name(signoz, token, "signoz-admin")
     del_resp = requests.delete(
-        signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{service_account_id}/roles/{admin_role_id}"),
+        signoz.self.host_configs["8080"].get(f"/api/v1/service_account_roles/{admin_entry_id}"),
         headers={"Authorization": f"Bearer {token}"},
         timeout=5,
     )

tests/integration/tests/serviceaccount/06_fga.py

@@ -131,8 +131,8 @@ def test_write_forbidden_without_grant(
     assert resp.status_code == HTTPStatus.FORBIDDEN, f"update SA: expected 403, got {resp.status_code}: {resp.text}"
 
     resp = requests.post(
-        signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{target_id}/roles"),
-        json={"id": viewer_role_id},
+        signoz.self.host_configs["8080"].get("/api/v1/service_account_roles"),
+        json={"serviceAccountId": target_id, "roleId": viewer_role_id},
         headers={"Authorization": f"Bearer {token}"},
         timeout=5,
     )
@@ -220,17 +220,18 @@ def test_attach_detach_dual_scoped(
 
     # Both SA-attach (target id) and role-attach (editor) present -> allowed.
     resp = requests.post(
-        signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{target_id}/roles"),
-        json={"id": editor_role_id},
+        signoz.self.host_configs["8080"].get("/api/v1/service_account_roles"),
+        json={"serviceAccountId": target_id, "roleId": editor_role_id},
         headers={"Authorization": f"Bearer {token}"},
         timeout=5,
     )
-    assert resp.status_code == HTTPStatus.NO_CONTENT, f"assign editor to target: {resp.text}"
+    assert resp.status_code == HTTPStatus.CREATED, f"assign editor to target: {resp.text}"
+    editor_entry_id = resp.json()["data"]["id"]
 
     # SA-attach not held for the other SA id -> forbidden.
     resp = requests.post(
-        signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{other_id}/roles"),
-        json={"id": editor_role_id},
+        signoz.self.host_configs["8080"].get("/api/v1/service_account_roles"),
+        json={"serviceAccountId": other_id, "roleId": editor_role_id},
         headers={"Authorization": f"Bearer {token}"},
         timeout=5,
     )
@@ -238,8 +239,8 @@ def test_attach_detach_dual_scoped(
 
     # role-attach not held for viewer -> forbidden even on the target SA.
     resp = requests.post(
-        signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{target_id}/roles"),
-        json={"id": viewer_role_id},
+        signoz.self.host_configs["8080"].get("/api/v1/service_account_roles"),
+        json={"serviceAccountId": target_id, "roleId": viewer_role_id},
         headers={"Authorization": f"Bearer {token}"},
         timeout=5,
     )
@@ -247,7 +248,7 @@ def test_attach_detach_dual_scoped(
 
     # Both SA-detach (target id) and role-detach (editor) present -> remove allowed.
     resp = requests.delete(
-        signoz.self.host_configs["8080"].get(f"{SERVICE_ACCOUNT_BASE}/{target_id}/roles/{editor_role_id}"),
+        signoz.self.host_configs["8080"].get(f"/api/v1/service_account_roles/{editor_entry_id}"),
         headers={"Authorization": f"Bearer {token}"},
         timeout=5,
     )