feat(explore): Validate trace item search keys asynchronously (#111189)

The goal of this PR is to validate the filter keys on any trace item
based search query builder. To do this we've introduced a new API
endpoint that accepts in a list of attributes and checks to see if they
exist and are valid.

We trigger this with a useQuery that runs on mount, and whenever the
user modifies the query. We also have guards in place to ignore running
the validation if the user is just modifying the filter values as those
don't need to be validated, reducing the amount of calls we make.

Validation is currently gated behind this flag:
#111752

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: nsdeschenes

static/app/components/searchQueryBuilder/context.tsx

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

static/app/components/searchQueryBuilder/index.tsx

@@ -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

static/app/components/searchQueryBuilder/tokens/filter/filter.tsx

@@ -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}>

static/app/components/searchQueryBuilder/tokens/invalidTokenTooltip.tsx

@@ -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;
 };
 

static/app/views/dashboards/widgetBuilder/buildSteps/filterResultsStep/spansSearchBar.spec.tsx

@@ -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 () => {

static/app/views/detectors/components/forms/metric/metric.spec.tsx

@@ -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: [],

static/app/views/detectors/edit.spec.tsx

@@ -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/`,

static/app/views/detectors/new-setting.spec.tsx

@@ -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/`,

static/app/views/explore/components/traceItemSearchQueryBuilder.spec.tsx

@@ -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);
+    });
+  });
 });

static/app/views/explore/components/traceItemSearchQueryBuilder.tsx

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