[RFC] Global Search Enhancements for New Home

[wanglam]

Summary

This RFC proposes three key enhancements to the global search functionality in OpenSearch Dashboards when the new home is enabled:

1. Expanded Header with Centralized Global Search: Repurpose the expanded header to display only a centered global search bar, removing all other header elements when both new home and useExpandedHeader are enabled
2. Global Assets Search with @ Prefix: Introduce @ prefix to search for saved objects (dashboards, visualizations) directly from the global search bar
3. Global Search Submit Commands: Add extensible command system triggered by Enter key to enable actions like opening a chatbot with the search query

Note: These enhancements are specifically designed for and only work when the new home is enabled.

Motivation

Current State and Problems

Problem 1: Underutilized Expanded Header with New Home

• The expanded header space could be better utilized for global features when new home is active
• There is a need to provide a prominent location for global search functionality in the new home experience

Problem 2: Limited Action Options from Search

• Users can only click on search results to navigate
• No way to take alternative actions with the search query (e.g., start a chatbot conversation)
• Limits the extensibility of the search experience

Problem 3: Missing Assets Search

• Users cannot search for their saved dashboards and visualizations from the global search
• Must navigate to management pages to find assets
• Reduces discoverability and efficiency

Proposed Solution

This RFC proposes three technical enhancements:

1. UI Change: When new home and useExpandedHeader are both enabled, repurpose the expanded header to display only a centered global search bar, removing all other header elements (branding logo, navigation controls, etc.)

2. New Search Capability: Introduce @ prefix to enable asset-only search, allowing users to search for saved objects (dashboards, visualizations) directly from the global search bar with workspace-aware filtering

3. Extensibility Feature: Add a submit command system that executes when users press Enter, enabling plugins to register custom actions (primary use case: opening AI chatbot with search query)

User Experience

Current User Flow (New Home Enabled)

Finding a Dashboard:

User wants to find a dashboard
    ↓
Navigate to Assets
    ↓
Use table search/filters
    ↓
Click on dashboard
    ↓
Navigate to dashboard

New User Flow (New Home Enabled)

Finding a Dashboard:

User wants to find a dashboard
    ↓
Click on global search (top center or left nav)
    ↓
Type dashboard name
    ↓
See results instantly (grouped by Pages/Assets)
    ↓
Click on result → Navigate to dashboard

Starting a Chatbot Conversation:

User wants to ask AI about sales data
    ↓
Click on global search
    ↓
Type "sales trends last quarter"
    ↓
Press Enter
    ↓
Chatbot opens with the query pre-filled
    ↓
Start conversation with AI

Visual Changes (New Home Enabled)

Before:

• Expanded header hidden when new home is enabled
• Search only available in left navigation

After (with useExpandedHeader enabled):

• Expanded header visible with centered search bar
• Clean, focused design with only the search bar
• Search available in two locations: top center (expanded header) and left navigation

Search Behavior

Default Search (no prefix):

• Searches both pages and assets
• Results grouped by type (Pages, Assets)
• Up to 10 results per type
• User can click any result to navigate

Assets-Only Search (@ prefix):

• Example: @sales searches only for assets containing "sales"
• Useful when you know you're looking for a saved object
• Only shows Assets section in results

Submit Command (Enter key):

• When user presses Enter, registered submit commands execute
• Primary use case: Open chatbot with the search query
• Hint displayed: "Press Enter to [action name]"
• Example: "Press Enter to chat with AI"

Detailed Design

1. Expanded Header with Centralized Search (New Home Only)

Overview

When new home is enabled, repurpose the expanded header to display only a centered global search bar. This feature is controlled by the opensearchDashboards.branding.useExpandedHeader configuration flag and only activates when new home is enabled.

Key Changes

• Prerequisite: New home must be enabled

• When useExpandedHeader is enabled with new home:

  • Expanded header displays only the centralized search bar
  • All other expanded header elements are removed: branding logo, navigation controls, breadcrumbs, etc.
  • Clean, minimal design with a single focus on search functionality
  • Header height remains the same, but content is simplified

• Search bar is available in two locations:

  • Top center: In the expanded header (new, new home only)
  • Left navigation: Existing location (unchanged)

Implementation Notes

• When both useExpandedHeader and new home are enabled, the header component conditionally renders only the search bar
• All other header elements (branding logo, navigation controls, breadcrumbs) are removed
• Search bar is centered horizontally with appropriate width constraints
• Responsive design maintains usability across different screen sizes

Configuration

The expanded header behavior is controlled by the existing configuration:

opensearchDashboards.branding.useExpandedHeader: true

Important: The global search bar in the expanded header only appears when:

1. New home is enabled
2. useExpandedHeader is set to true

2. Global Assets Search with @ Prefix

Overview

Adds the ability to search for saved objects (dashboards, visualizations) directly from the global search bar using the @ prefix. This introduces a new search command type (SAVED_OBJECTS) with automatic prefix-based filtering.

Public Interface

Search Command Type:

export const SAVED_OBJECTS_SYMBOL = '@';

export const SearchCommandTypes = {
  PAGES: {
    description: 'Pages',
    alias: null,
  },
  SAVED_OBJECTS: {
    description: 'Assets',
    alias: SAVED_OBJECTS_SYMBOL,  // '@' prefix
  },
} as const;

export interface GlobalSearchCommand {
  id: string;
  type: 'PAGES' | 'SAVED_OBJECTS';
  run(value: string, callback?: () => void, abortSignal?: AbortSignal): Promise<ReactNode[]>;
}

Registration Example:

// Register assets search command
chrome.globalSearch.registerSearchCommand({
  id: 'searchAssets',
  type: 'SAVED_OBJECTS',
  run: async (query, callback, abortSignal) => {
    // Search for dashboards and visualizations
    const response = await http.get('/api/opensearch-dashboards/management/saved_objects/_find', {
      query: {
        type: ['dashboard', 'visualization'],
        search: `*${query}*`,
        perPage: 10,
        workspaces: currentWorkspaceId ? [currentWorkspaceId] : [],
      },
      signal: abortSignal,
    });
    
    // Return React elements for display
    return response.saved_objects.map(asset => (
      <EuiSimplifiedBreadcrumbs
        breadcrumbs={[
          { text: asset.type },
          { text: asset.meta.title, href: assetUrl, onClick: callback }
        ]}
      />
    ));
  }
});

Search Behavior

Default Search (no prefix):

• Searches only pages
• Up to 10 results per type
• Example: Typing "discovery" shows pages that contain "discovery"

Assets-Only Search (@ prefix):

• Searches only assets
• Example: @sales searches for assets containing "sales"
• Pages search command is not triggered
• Only Assets section displayed in results

Workspace Integration

• Inside a workspace: Query includes workspaces: [currentWorkspaceId] to filter results
• Outside a workspace: Query uses workspaces: [] to search across all accessible workspaces
• Workspace permissions enforced by the saved objects API
• URLs generated with proper workspace context using formatUrlWithWorkspaceId

Search Results Display

Results displayed as breadcrumb-style links:

dashboard > Sales Overview
visualization > Sales Chart
dashboard > Sales Metrics

Clicking navigates to: /app/dashboards#/view/{id}?workspace={workspaceId}

3. Global Search Submit Commands

Overview

Introduces a new command system that executes when users press Enter in the search bar. This enables extensible actions beyond navigation, with the primary use case being AI chatbot integration.

Public Interface

export interface GlobalSearchSubmitCommand {
  id: string;
  name: string;
  run: (payload: { content: string }) => void;
}

// Registration example
chrome.globalSearch.registerSearchSubmitCommand({
  id: 'openChatbot',
  name: 'chat with AI',
  run: (payload) => {
    // Open chatbot with search query
    chatbot.open({ initialMessage: payload.content });
  }
});

Setup Contract:

export interface GlobalSearchServiceSetupContract {
  registerSearchCommand(searchCommand: GlobalSearchCommand): void;
  registerSearchSubmitCommand(searchSubmitCommand: GlobalSearchSubmitCommand): void;
}

Start Contract:

export interface GlobalSearchServiceStartContract {
  getAllSearchCommands(): GlobalSearchCommand[];
  unregisterSearchCommand(id: string): void;
  unregisterSearchSubmitCommand(id: string): void;
  getSearchSubmitCommands$: () => Observable<GlobalSearchSubmitCommand[]>;
}

User Interaction Flow

1. User types a query in the search bar (e.g., "sales trends")
2. Search results appear in dropdown
3. User sees hint: "Press Enter to chat with AI"
4. User presses Enter
5. Chatbot opens with "sales trends" pre-filled
6. User can start conversation immediately

UI Interaction

Hint Display:

• When submit commands are registered and the search value is not empty, a hint is displayed
• Format: "Press Enter to {command names}."
• Example: "Press Enter to chat with AI."

Execution:

• All registered submit commands execute when Enter is pressed
• Commands receive the search query in payload.content
• Search dropdown closes after execution

Use Cases

Primary Use Case: AI Chatbot Integration

• User types a question in global search
• Presses Enter
• Chatbot opens with the query pre-filled
• User can immediately start conversation

Future Use Cases

• Navigate to a search results page
• Create a new dashboard with the query as title
• Share search query with team
• Save search as a bookmark

Note: The current implementation passes only the search query (content) to submit commands. Context carryover (page state, filters, etc.) can be added as a future enhancement by extending the GlobalSearchSubmitCommand interface.

Technical Architecture

High-Level Components (New Home Enabled)

Expanded Header (when useExpandedHeader enabled + new home enabled)
    └── Global Search Bar (centered)
        ├── Search Input Field
        ├── Results Dropdown
        │   ├── Pages Section
        │   └── Assets Section
        └── Submit Command Hint

Search Command System

Search Commands (triggered on typing):

• Execute as user types (with debouncing)
• Return search results to display
• Can be filtered by prefix (e.g., @ for assets only)

Submit Commands (triggered on Enter):

• Execute when user presses Enter key
• Receive the search query as input
• Perform actions like opening chatbot, navigating, etc.
• Independent of search results

Public APIs

For Plugin Developers

Register Search Command:

chrome.globalSearch.registerSearchCommand({
  id: 'mySearch',
  type: 'PAGES' | 'SAVED_OBJECTS',
  run: async (query, callback, abortSignal) => {
    // Fetch and return search results
    // Return array of React elements
  }
});

Register Submit Command:

chrome.globalSearch.registerSearchSubmitCommand({
  id: 'myAction',
  name: 'my action',
  run: (payload) => {
    // Execute action with search query
    // payload.content contains the search text
  }
});

Unregister Commands:

chrome.globalSearch.unregisterSearchCommand(id);
chrome.globalSearch.unregisterSearchSubmitCommand(id);

Data Flow

User Types in Search Bar
    ↓
Debounce (200ms)
    ↓
Determine Active Search Commands
    ├─ If starts with @: Only Assets Search
    └─ Otherwise: Pages Search + Assets Search
    ↓
Execute Search Commands
    ↓
Group Results by Type
    ↓
Display in Dropdown
    ↓
User Action
    ├─ Click Result → Navigate to that item
    └─ Press Enter → Execute Submit Commands

Implementation Considerations

Configuration Requirements

The expanded header with global search requires:

1. New home must be enabled (prerequisite)
2. opensearchDashboards.branding.useExpandedHeader: true

Without new home enabled, this feature will not activate.

Performance

• Debouncing: Search requests debounced by 200ms to reduce API calls
• Request Cancellation: Previous search requests cancelled when new ones start
• Result Limiting: Maximum 10 results per search type
• Lazy Loading: Search components loaded on demand

Workspace Awareness

• Assets search automatically filters by current workspace
• URLs generated with proper workspace context
• Respects workspace permissions
• Handles cross-workspace navigation correctly

Open Questions

1. Should we add more asset types beyond dashboards and visualizations?

   • Potential additions: Index patterns, saved searches, data sources
   • Trade-off: More comprehensive results vs. focused, relevant results
   • Performance impact of searching more types

2. Should we implement semantic search for page navigation?

   • Current: Keyword-based matching on page titles
   • Enhancement: Natural language understanding (e.g., "log analysis" → "Discover", "Logs")
   • Implementation options:
     • Browser-Side Small PLM(Pre-trained Language Model)
     • Neural Sparse Search
   • Trade-off: Better discoverability vs. implementation complexity and performance

3. Should we add page context to submit commands?

   • Current: Submit commands receive only the search query
   • Enhancement: Pass page context (index patterns, time range, filters, workspace)
   • Use case: AI chatbot with contextual awareness
   • Implementation: Extend GlobalSearchSubmitCommand interface with optional context parameter
   • Trade-off: More powerful integration vs. increased complexity

Conclusion

This RFC proposes three focused enhancements to the global search functionality for the new home experience:

1. UI Enhancement: Repurposes the expanded header to display only a centered global search bar when both new home and useExpandedHeader are enabled, removing all other header elements for a clean, focused design

2. Asset Search: Introduces @ prefix to enable direct search for saved objects (dashboards, visualizations) with workspace-aware filtering, providing quick access to assets without menu navigation

3. Extensibility: Adds a submit command system triggered by the Enter key, enabling plugins to register custom actions (primary use case: AI chatbot integration)

These changes improve navigation efficiency, asset discoverability, and enable new interaction patterns while maintaining backward compatibility and extensibility for future enhancements.