Semantic Search
GoodData.UI provides a React component for embedding a semantic search interface that allows users to search for analytical objects using natural language.
Features
- Embed UI for semantic search functionality.
- Search for analytical objects using natural language.
- Filter search results by object types.
- Enable deep search to find dashboards by their contents.
- Theming is supported out of the box through Theme Provider.
Basic integration example
SemanticSearch
component renders a search input field with a dropdown for displaying search results.
import * as React from "react";
import { SemanticSearch, ISemanticSearchResultItem } from "@gooddata/sdk-ui-semantic-search";
// Import required styles
import "@gooddata/sdk-ui-semantic-search/styles/css/main.css";
const App = () => {
return (
<div style={{ width: 300 }}>
{/* Wrap the search UI in a container of desired size */}
<SemanticSearch
// Handle item selection
onSelect={(item: ISemanticSearchResultItem) => {
console.log(`Selected item: ${item.title}`);
// Handle the selected item, e.g., navigate to the dashboard
}}
// Optional: Handle search errors
onError={(errorMessage: string) => {
console.error(`Search error: ${errorMessage}`);
}}
// Optional: Filter by object types
objectTypes={["dashboard", "metric"]}
// Optional: Enable deep search
deepSearch={true}
// Optional: Set results limit
limit={10}
// Optional: Custom placeholder
placeholder="Search for dashboards, metrics..."
/>
</div>
);
};
Props
Name | Type | Default | Description |
---|---|---|---|
locale | string | - | Specifies the locale for internationalization. Falls back to context if not specified |
backend | IAnalyticalBackend | - | Backend instance. Falls back to BackendProvider context if not specified |
workspace | string | - | Workspace ID. Falls back to WorkspaceProvider context if not specified |
onSelect | (item: ISemanticSearchResultItem) => void | - | Required callback function called when the user selects an item from the search results |
onError | (errorMessage: string) => void | - | Optional callback function called when an error occurs during the search |
className | string | - | Additional CSS class for the component |
objectTypes | GenAIObjectType[] | - | A list of object types to search for (e.g., “dashboard”, “metric”, “insight”) |
deepSearch | boolean | false | Enable deep search to find dashboards by their contents |
limit | number | 10 | Target number of search results to return. See note below about actual result count |
placeholder | string | - | Placeholder text for the search input |
Note about result limits: The
limit
parameter specifies a target number of results, but the actual number of returned items may vary:
- Fewer items may be returned if there aren’t enough semantically relevant matches for the search term
- More items may be returned when using
deepSearch=true
, as both matching items (like visualizations) and their containers (like dashboards) will be included in the results- The relationships between items are provided separately in the
relationships
array
Using the semantic search hook
If you need more control over the search functionality, you can use the useSemanticSearch
hook directly:
import * as React from "react";
import { useSemanticSearch } from "@gooddata/sdk-ui-semantic-search";
const MyCustomSearchComponent = () => {
const [searchTerm, setSearchTerm] = React.useState("");
const { searchStatus, searchResults, searchError, relationships } = useSemanticSearch({
searchTerm,
objectTypes: ["dashboard", "metric"],
deepSearch: true,
limit: 10,
// backend and workspace are optional if provided via context
});
return (
<div>
<input
type="text"
value={searchTerm}
onChange={(e) => setSearchTerm(e.target.value)}
placeholder="Search..."
/>
{searchStatus === "loading" && <div>Loading...</div>}
{searchStatus === "error" && <div>Error: {searchError}</div>}
{searchStatus === "success" && (
<ul>
{searchResults.map((item) => (
<li key={item.id} onClick={() => handleItemClick(item)}>
{item.title}
</li>
))}
</ul>
)}
</div>
);
};
Hook Parameters
Name | Type | Default | Description |
---|---|---|---|
searchTerm | string | - | The search term to use for semantic search |
objectTypes | GenAIObjectType[] | - | A list of object types to search for |
deepSearch | boolean | false | Enable deep search to find dashboards by their contents |
limit | number | - | Target number of search results to return. See note in Props section |
backend | IAnalyticalBackend | - | Backend instance. Falls back to BackendProvider context if not specified |
workspace | string | - | Workspace ID. Falls back to WorkspaceProvider context if not specified |
Hook Return Value
The hook returns an object with the following properties:
Name | Type | Description |
---|---|---|
searchStatus | “idle” | “loading” | “error” | “success” | Current status of the search operation |
searchError | string | Error message if the search failed |
searchResults | ISemanticSearchResultItem[] | Array of search results |
relationships | ISemanticSearchRelationship[] | Array of relationships between search results (e.g., dashboard containing a matching insight) |
Search Result Item Interface
The ISemanticSearchResultItem
interface represents an item in the search results:
interface ISemanticSearchResultItem {
/**
* The ID of the item.
*/
id: string;
/**
* The title of the item.
*/
title: string;
/**
* The description of the item.
*/
description?: string;
/**
* The type of the item (e.g., "dashboard", "metric", "insight").
*/
type: string;
/**
* The URL to the item in the GoodData platform.
*/
link?: string;
/**
* Additional metadata about the item.
*/
meta?: Record<string, any>;
}
Search Relationship Interface
The ISemanticSearchRelationship
interface represents relationships between items in the search results, such as a dashboard containing a matching visualization:
interface ISemanticSearchRelationship {
/**
* The ID of the source item.
*/
sourceId: string;
/**
* The type of the source item.
*/
sourceType: string;
/**
* The ID of the target item.
*/
targetId: string;
/**
* The type of the target item.
*/
targetType: string;
/**
* The type of relationship between the source and target.
* For example, "contains" for a dashboard containing a visualization.
*/
type: string;
}