getsentry · nsdeschenes · Mar 30, 2026 · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026
@@ -61,6 +61,7 @@ interface SearchQueryBuilderContextData {
   getSuggestedFilterKey: (key: string) => string | null;
   getTagValues: GetTagValues;
   handleSearch: (query: string) => void;
+  invalidFilterKeys: string[];
   parseQuery: (query: string) => ParseResult | null;
   parsedQuery: ParseResult | null;
   query: string;
@@ -128,6 +129,7 @@ export function SearchQueryBuilderProvider({
   filterKeyAliases,
   caseInsensitive,
   onCaseInsensitiveClick,
+  invalidFilterKeys,
 }: SearchQueryBuilderProps & {children: React.ReactNode}) {
   const wrapperRef = useRef<HTMLDivElement>(null);
   const actionBarRef = useRef<HTMLDivElement>(null);
@@ -198,6 +200,11 @@ export function SearchQueryBuilderProvider({
 
   const parsedQuery = useMemo(() => parseQuery(state.query), [parseQuery, state.query]);
 
+  const stableInvalidFilterKeys = useMemo(
+    () => invalidFilterKeys ?? [],
+    [invalidFilterKeys]
+  );
+
   const previousQuery = usePrevious(state.query);
   const firstRender = useRef(true);
   useEffect(() => {
@@ -242,6 +249,7 @@ export function SearchQueryBuilderProvider({
     return {
       ...state,
       aiSearchBadgeType,
+      invalidFilterKeys: stableInvalidFilterKeys,
       disabled,
       disallowFreeText: Boolean(disallowFreeText),
       disallowLogicalOperators: Boolean(disallowLogicalOperators),
@@ -300,6 +308,7 @@ export function SearchQueryBuilderProvider({
     getTagKeys,
     getTagValues,
     handleSearch,
+    stableInvalidFilterKeys,
     matchKeySuggestions,
     onCaseInsensitiveClick,
     parseQuery,

@@ -126,6 +126,12 @@ export interface SearchQueryBuilderProps {
    * and display the returned keys alongside any static filterKeys.
    */
   getTagKeys?: GetTagKeys;
+  /**
+   * List of filter key strings that are invalid.
+   * When provided, tokens with matching keys will display a warning state.
+   * The parent component is responsible for fetching and determining invalid keys.
+   */
+  invalidFilterKeys?: string[];
 
   /**
    * Allows for customization of the invalid token messages.
@@ -174,11 +180,11 @@ export interface SearchQueryBuilderProps {
    */
   portalTarget?: HTMLElement | null;
   queryInterface?: QueryInterfaceType;
+
   /**
    * If provided, saves and displays recent searches of the given type.
    */
   recentSearches?: SavedSearchType;
-
   /**
    * When set, provided keys will override default raw search capabilities, while
    * replacing it with options that include the provided keys, and the user's input

@@ -203,7 +203,7 @@ export function SearchQueryBuilderFilter({item, state, token}: SearchQueryTokenP
 
   const isFocused = item.key === state.selectionManager.focusedKey;
 
-  const {dispatch} = useSearchQueryBuilder();
+  const {dispatch, invalidFilterKeys} = useSearchQueryBuilder();
   const {rowProps, gridCellProps} = useQueryBuilderGridItem(item, state, ref);
 
   const onKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
@@ -227,12 +227,19 @@ export function SearchQueryBuilderFilter({item, state, token}: SearchQueryTokenP
 
   const tokenHasError = 'invalid' in token && defined(token.invalid);
   const tokenHasWarning = 'warning' in token && defined(token.warning);
+  const isInvalidFilterKey = invalidFilterKeys.includes(getKeyName(token.key));
 
   return (
     <FilterWrapper
       aria-label={token.text}
       aria-invalid={tokenHasError}
-      state={tokenHasWarning ? 'warning' : tokenHasError ? 'invalid' : 'valid'}
+      state={
+        tokenHasWarning || isInvalidFilterKey
+          ? 'warning'
+          : tokenHasError
+            ? 'invalid'
+            : 'valid'
+      }
       ref={ref}
       {...modifiedRowProps}
     >
@@ -243,6 +250,11 @@ export function SearchQueryBuilderFilter({item, state, token}: SearchQueryTokenP
         columnCount={4}
         containerDisplayMode="grid"
         forceVisible={filterMenuOpen ? false : undefined}
+        warning={
+          isInvalidFilterKey
+            ? t('Invalid key. "%s" is not a supported search key.', getKeyName(token.key))
+            : undefined
+        }
       >
         {token.filter === FilterType.IS || token.filter === FilterType.HAS ? null : (
           <BaseGridCell {...gridCellProps}>

@@ -14,20 +14,23 @@ interface InvalidTokenTooltipProps extends Omit<TooltipProps, 'title'> {
   item: Node<ParseResultToken>;
   state: ListState<ParseResultToken>;
   token: ParseResultToken;
+  warning?: ReactNode;
 }
 
 function getForceVisible({
   isFocused,
   isInvalid,
+  hasTokenWarning,
   hasWarning,
   forceVisible,
 }: {
+  hasTokenWarning: boolean;
   hasWarning: boolean;
   isFocused: boolean;
   isInvalid: boolean;
   forceVisible?: boolean;
 }) {
-  if (!isInvalid && !hasWarning) {
+  if (!isInvalid && !hasTokenWarning && !hasWarning) {
     return false;
   }
 
@@ -44,11 +47,13 @@ export function InvalidTokenTooltip({
   state,
   item,
   forceVisible,
+  warning,
   ...tooltipProps
 }: InvalidTokenTooltipProps) {
   const invalid = 'invalid' in token ? token.invalid : null;
-  const warning = 'warning' in token ? token.warning : null;
+  const tokenWarning = 'warning' in token ? token.warning : null;
 
+  const hasTokenWarning = Boolean(tokenWarning);
   const hasWarning = Boolean(warning);
   const isInvalid = Boolean(invalid);
   const isFocused =
@@ -57,9 +62,15 @@ export function InvalidTokenTooltip({
   return (
     <Tooltip
       skipWrapper
-      forceVisible={getForceVisible({isFocused, isInvalid, hasWarning, forceVisible})}
+      forceVisible={getForceVisible({
+        isFocused,
+        isInvalid,
+        hasTokenWarning,
+        hasWarning,
+        forceVisible,
+      })}
       position="bottom"
-      title={warning ?? invalid?.reason ?? t('This token is invalid')}
+      title={warning ?? tokenWarning ?? invalid?.reason ?? t('This token is invalid')}
       {...tooltipProps}
     >
       {children}
@@ -68,7 +79,6 @@ export function InvalidTokenTooltip({
 }
 
 type GridInvalidTokenTooltipProps = InvalidTokenTooltipProps & {
-  children: React.ReactNode;
   columnCount: number;
 };
 

@@ -88,6 +88,12 @@ describe('SpansSearchBar', () => {
     mockSpanTagValues({type: 'number', tagKey: 'span.op', mockedValues: []});
 
     mockSpanTags({type: 'boolean', mockedTags: []});
+
+    MockApiClient.addMockResponse({
+      url: `/organizations/org-slug/trace-items/attributes/validate/`,
+      method: 'POST',
+      body: {attributes: {}},
+    });
   });
 
   it('renders the initial query conditions', async () => {

@@ -39,6 +39,11 @@ describe('NewMetricDetectorForm', () => {
       url: '/organizations/org-slug/trace-items/attributes/',
       body: [],
     });
+    MockApiClient.addMockResponse({
+      url: '/organizations/org-slug/trace-items/attributes/validate/',
+      method: 'POST',
+      body: {attributes: {}},
+    });
     MockApiClient.addMockResponse({
       url: '/organizations/org-slug/recent-searches/',
       body: [],

@@ -93,6 +93,11 @@ describe('DetectorEdit', () => {
       url: `/organizations/${organization.slug}/trace-items/attributes/`,
       body: [],
     });
+    MockApiClient.addMockResponse({
+      url: `/organizations/${organization.slug}/trace-items/attributes/validate/`,
+      method: 'POST',
+      body: {attributes: {}},
+    });
 
     MockApiClient.addMockResponse({
       url: `/organizations/${organization.slug}/workflows/`,

@@ -66,6 +66,11 @@ describe('DetectorEdit', () => {
       url: `/organizations/${organization.slug}/trace-items/attributes/`,
       body: [],
     });
+    MockApiClient.addMockResponse({
+      url: `/organizations/${organization.slug}/trace-items/attributes/validate/`,
+      method: 'POST',
+      body: {attributes: {}},
+    });
 
     MockApiClient.addMockResponse({
       url: `/organizations/${organization.slug}/workflows/`,

@@ -1,6 +1,6 @@
 import {OrganizationFixture} from 'sentry-fixture/organization';
 
-import {renderHookWithProviders} from 'sentry-test/reactTestingLibrary';
+import {renderHookWithProviders, waitFor} from 'sentry-test/reactTestingLibrary';
 
 import {PageFiltersStore} from 'sentry/components/pageFilters/store';
 import {FieldKind} from 'sentry/utils/fields';
@@ -22,7 +22,7 @@ const defaultInitialProps: TraceItemSearchQueryBuilderProps = {
   searchSource: 'test',
 };
 const organization = OrganizationFixture({
-  features: [],
+  features: ['search-query-attribute-validation'],
 });
 
 describe('useTraceItemSearchQueryBuilderProps', () => {
@@ -247,4 +247,88 @@ describe('useTraceItemSearchQueryBuilderProps', () => {
       'log.flag',
     ]);
   });
+
+  it('calls validateQuery when filter keys change', async () => {
+    const validateMock = MockApiClient.addMockResponse({
+      url: '/organizations/org-slug/trace-items/attributes/validate/',
+      method: 'POST',
+      body: {attributes: {'span.op': {valid: true}}},
+    });
+
+    renderHookWithProviders(useTraceItemSearchQueryBuilderProps, {
+      initialProps: {
+        ...defaultInitialProps,
+        initialQuery: 'span.op:db',
+      },
+      organization,
+    });
+
+    await waitFor(() => {
+      expect(validateMock).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it('does not call validateQuery when only filter values change', async () => {
+    const validateMock = MockApiClient.addMockResponse({
+      url: '/organizations/org-slug/trace-items/attributes/validate/',
+      method: 'POST',
+      body: {attributes: {'span.op': {valid: true}}},
+    });
+
+    const {rerender} = renderHookWithProviders(useTraceItemSearchQueryBuilderProps, {
+      initialProps: {
+        ...defaultInitialProps,
+        initialQuery: 'span.op:db',
+      },
+      organization,
+    });
+
+    await waitFor(() => {
+      expect(validateMock).toHaveBeenCalledTimes(1);
+    });
+
+    rerender({
+      ...defaultInitialProps,
+      initialQuery: 'span.op:web',
+    });
+
+    // Still only 1 call — value changed but keys didn't (React Query deduplicates)
+    await waitFor(() => {
+      expect(validateMock).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it('calls validateQuery when a new filter key is added', async () => {
+    const validateMock = MockApiClient.addMockResponse({
+      url: '/organizations/org-slug/trace-items/attributes/validate/',
+      method: 'POST',
+      body: {
+        attributes: {
+          'span.op': {valid: true},
+          'other.key': {valid: true},
+        },
+      },
+    });
+
+    const {rerender} = renderHookWithProviders(useTraceItemSearchQueryBuilderProps, {
+      initialProps: {
+        ...defaultInitialProps,
+        initialQuery: 'span.op:db',
+      },
+      organization,
+    });
+
+    await waitFor(() => {
+      expect(validateMock).toHaveBeenCalledTimes(1);
+    });
+
+    rerender({
+      ...defaultInitialProps,
+      initialQuery: 'span.op:db other.key:val',
+    });
+
+    await waitFor(() => {
+      expect(validateMock).toHaveBeenCalledTimes(2);
+    });
+  });
 });
@@ -1,5 +1,6 @@
 import {useMemo} from 'react';
 
+import {usePageFilters} from 'sentry/components/pageFilters/usePageFilters';
 import type {SpanSearchQueryBuilderProps} from 'sentry/components/performance/spanSearchQueryBuilder';
 import {
   SearchQueryBuilder,
@@ -11,6 +12,7 @@ import {SavedSearchType, type TagCollection} from 'sentry/types/group';
 import type {AggregationKey} from 'sentry/utils/fields';
 import {FieldKind, getFieldDefinition} from 'sentry/utils/fields';
 import {getHasTag} from 'sentry/utils/tag';
+import {useAttributeValidation} from 'sentry/views/explore/hooks/useAttributeValidation';
 import {useExploreSuggestedAttribute} from 'sentry/views/explore/hooks/useExploreSuggestedAttribute';
 import {useGetTraceItemAttributeTagKeys} from 'sentry/views/explore/hooks/useGetTraceItemAttributeTagKeys';
 import {useGetTraceItemAttributeValues} from 'sentry/views/explore/hooks/useGetTraceItemAttributeValues';
@@ -105,6 +107,19 @@ export function useTraceItemSearchQueryBuilderProps({
   disableRecentSearches,
 }: TraceItemSearchQueryBuilderProps) {
   const placeholderText = itemTypeToDefaultPlaceholder(itemType);
+
+  const {selection} = usePageFilters();
+  const effectiveProjects = projects ?? selection.projects;
+  const validationSelection = useMemo(
+    () => ({datetime: selection.datetime, projects: effectiveProjects}),
+    [selection.datetime, effectiveProjects]
+  );
+
+  const {invalidFilterKeys} = useAttributeValidation(
+    itemType,
+    initialQuery ?? '',
+    validationSelection
+  );
   const functionTags = useFunctionTags(itemType, supportedAggregates);
   const filterKeySections = useFilterKeySections(itemType, stringAttributes);
   const filterTags = useFilterTags({
@@ -166,6 +181,7 @@ export function useTraceItemSearchQueryBuilderProps({
       },
       caseInsensitive,
       onCaseInsensitiveClick,
+      invalidFilterKeys,
     }),
     [
       booleanSecondaryAliases,
@@ -180,6 +196,7 @@ export function useTraceItemSearchQueryBuilderProps({
       getTagKeys,
       getTraceItemAttributeValues,
       initialQuery,
+      invalidFilterKeys,
       itemType,
       matchKeySuggestions,
       namespace,