@gooddata/sdk-ui-semantic-search 11.26.0-alpha.2 → 11.26.0-alpha.3

package/README.md

@@ -9,6 +9,12 @@ To learn more, check [the source monorepo](https://github.com/gooddata/gooddata-
 
 This package provides a set of React-based UI components and hooks for semantic search within your metadata.
 
+## Components
+
+### SemanticSearch
+
+The `SemanticSearch` component provides a search input with semantic search capabilities.
+
 Example usage:
 
 ```tsx
@@ -28,6 +34,106 @@ const App = () => {
 
 You can also use providers for backend and workspace.
 
+## Hooks
+
+### useHybridSearch
+
+The `useHybridSearch` hook is a powerful tool that combines traditional keyword-based search with AI-powered semantic search. It handles debouncing of the search query and manages the state of both search types.
+
+#### Basic Usage
+
+```tsx
+import { useHybridSearch, SearchItem, SearchItemGroup } from "@gooddata/sdk-ui-semantic-search";
+
+const MySearchComponent = ({ items }: { items: SearchItem[] }) => {
+    const { searchState, semanticSearchState, search, onSearchQueryChange } = useHybridSearch({
+        itemBuilder: (item, { ref, type }) => {
+            // Transform semantic search result to your SearchItem format
+            return items.find((i) => areObjRefsEqual(i.ref, ref));
+        },
+        debounceMs: 200,
+    });
+
+    // Perform the combined search
+    const results = search({ items });
+
+    return (
+        <div>
+            <input
+                type="text"
+                value={searchState.query}
+                onChange={(e) => onSearchQueryChange(e.target.value)}
+                placeholder="Search..."
+            />
+
+            {searchState.state === "searching" && <div>Searching...</div>}
+
+            <h3>Results</h3>
+            <ul>
+                {results.searchItems.map((item) => (
+                    <li key={objRefToString(item.ref)}>{item.title}</li>
+                ))}
+            </ul>
+
+            {semanticSearchState.state === "loading" && <div>Loading semantic results...</div>}
+
+            {results.searchRelatedItems.length > 0 && (
+                <>
+                    <h3>Related (Semantic) Results</h3>
+                    <ul>
+                        {results.searchRelatedItems.map((item) => (
+                            <li key={objRefToString(item.ref)}>{item.title}</li>
+                        ))}
+                    </ul>
+                </>
+            )}
+        </div>
+    );
+};
+```
+
+#### Configuration Options
+
+The `useHybridSearch` hook accepts an options object (`IUseHybridSearchOptions`):
+
+| Property             | Type                      | Description                                                                                     |
+| :------------------- | :------------------------ | :---------------------------------------------------------------------------------------------- |
+| `itemBuilder`        | `HybridSearchItemBuilder` | **Required.** A function to transform semantic search results into your local item format.      |
+| `backend`            | `IAnalyticalBackend`      | Optional. Backend to use. If not provided, it's retrieved from `BackendContext`.                |
+| `workspace`          | `string`                  | Optional. Workspace ID to use. If not provided, it's retrieved from `WorkspaceContext`.         |
+| `debounceMs`         | `number`                  | Optional. Debounce time for the search query in milliseconds (default: 150ms).                  |
+| `allowSematicSearch` | `boolean`                 | Optional. Enable or disable AI-powered semantic search (default: true).                         |
+| `limit`              | `number`                  | Optional. Maximum number of semantic search results to return.                                  |
+| `deepSearch`         | `boolean`                 | Optional. Whether to perform a deep semantic search.                                            |
+| `objectTypes`        | `ObjectType[]`            | Optional. Restrict semantic search to specific object types (e.g., `'insight'`, `'dashboard'`). |
+| `includeTags`        | `string[]`                | Optional. Tags that must be present on the searched objects.                                    |
+| `excludeTags`        | `string[]`                | Optional. Tags that must not be present on the searched objects.                                |
+| `matcher`            | `HybridSearchMatcher`     | Optional. A custom matching function for local keyword search.                                  |
+
+#### Hook Return Value
+
+The hook returns an object (`IHybridSearchResult`) with the following properties:
+
+| Property              | Type                   | Description                                                                 |
+| :-------------------- | :--------------------- | :-------------------------------------------------------------------------- |
+| `searchState`         | `ISearchState`         | Current state of the keyword search (`query`, `debouncedQuery`, `state`).   |
+| `semanticSearchState` | `ISemanticSearchState` | Current state of the semantic search (`state`, `message`, `error`).         |
+| `search`              | `Function`             | A function that takes your local items and returns combined search results. |
+| `onSearchQueryChange` | `Function`             | Callback to update the search query.                                        |
+
+The `search` function returns `ICombinedSearchResults`, which extends the standard `SearchResults` with `searchRelatedItems` (items found via semantic search but transformed by your `itemBuilder`).
+
+#### Search Function Parameters
+
+The `search` function accepts the following properties:
+
+| Property     | Type               | Description                                                                                                                                               |
+| :----------- | :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `items`      | `ReadonlyArray<I>` | **Required.** The current list of items to search through (e.g., currently filtered or paged items).                                                      |
+| `allItems`   | `ReadonlyArray<I>` | Optional. The full list of all available items. If provided, it's used to calculate `searchAllItems` in the results. Defaults to `items` if not provided. |
+| `itemGroups` | `ReadonlyArray<G>` | Optional. Groups of items to search through. Used to calculate `searchItemGroups` in the results.                                                         |
+| `keywords`   | `string[]`         | Optional. A list of keywords to match against the search query. Used to calculate `searchKeywords` in the results.                                        |
+
 ## License
 
 (C) 2017-2022 GoodData Corporation

package/esm/hooks/search/matchers.d.ts

@@ -0,0 +1,12 @@
+import type { HybridSearchMatcher, SearchItem, SearchItemGroup } from "./types.js";
+/**
+ * @alpha
+ * Default matcher for the search. Supports title, name, description, summary.
+ */
+export declare function defaultMatcher<I extends SearchItem, G extends SearchItemGroup<I>>(item: I | G | string, searchQueryUpper: string): boolean;
+/**
+ * @alpha
+ * Custom matcher for the search. Can be used to match any property of the search item.
+ */
+export declare function customMatcher<I extends SearchItem, G extends SearchItemGroup<I>>(props: (keyof I & keyof G)[]): HybridSearchMatcher;
+//# sourceMappingURL=matchers.d.ts.map

package/esm/hooks/search/matchers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchers.d.ts","sourceRoot":"","sources":["../../../src/hooks/search/matchers.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEnF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,eAAe,CAAC,CAAC,CAAC,EAC7E,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,MAAM,EACpB,gBAAgB,EAAE,MAAM,GACzB,OAAO,CAQT;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,eAAe,CAAC,CAAC,CAAC,EAC5E,KAAK,EAAE,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,GAC7B,mBAAmB,CAcrB"}

package/esm/hooks/search/matchers.js

@@ -0,0 +1,30 @@
+// (C) 2024-2026 GoodData Corporation
+/**
+ * @alpha
+ * Default matcher for the search. Supports title, name, description, summary.
+ */
+export function defaultMatcher(item, searchQueryUpper) {
+    if (typeof item === "string") {
+        return isUpperCaseMatch(item, searchQueryUpper);
+    }
+    const searchIn = [item.title, item.name, item.description, item.summary].filter(Boolean);
+    return searchIn.some((name) => isUpperCaseMatch(name, searchQueryUpper));
+}
+/**
+ * @alpha
+ * Custom matcher for the search. Can be used to match any property of the search item.
+ */
+export function customMatcher(props) {
+    return (item, searchQueryUpper) => {
+        if (typeof item === "string") {
+            return isUpperCaseMatch(item, searchQueryUpper);
+        }
+        const values = props.map((prop) => item[prop]);
+        const searchIn = values.filter(Boolean);
+        return searchIn.some((name) => isUpperCaseMatch(name, searchQueryUpper));
+    };
+}
+function isUpperCaseMatch(keyword, searchQueryUpper) {
+    return keyword.toUpperCase().includes(searchQueryUpper);
+}
+//# sourceMappingURL=matchers.js.map

package/esm/hooks/search/matchers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchers.js","sourceRoot":"","sources":["../../../src/hooks/search/matchers.ts"],"names":[],"mappings":"AAAA,qCAAqC;AAIrC;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC1B,IAAoB,EACpB,gBAAwB,EACjB;IACP,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC3B,OAAO,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,CAAa,CAAC;IAErG,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAAA,CAC5E;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CACzB,KAA4B,EACT;IACnB,OAAO,CACH,IAAoB,EACpB,gBAAwB,EACjB,EAAE,CAAC;QACV,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC3B,OAAO,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;QACpD,CAAC;QAED,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAE,IAAgC,CAAC,IAAc,CAAC,CAAa,CAAC;QAClG,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAExC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAAA,CAC5E,CAAC;AAAA,CACL;AAED,SAAS,gBAAgB,CAAC,OAAe,EAAE,gBAAwB,EAAE;IACjE,OAAO,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;AAAA,CAC3D"}

package/esm/hooks/search/related.d.ts

@@ -0,0 +1,4 @@
+import { type ISemanticSearchResultItem } from "@gooddata/sdk-model";
+import { type HybridSearchItemBuilder, type SearchItem } from "./types.js";
+export declare function doFilterRelatedItems<I extends SearchItem>(items: ReadonlyArray<I>, searchResults: ISemanticSearchResultItem[], itemBuilder: HybridSearchItemBuilder<I>): ReadonlyArray<I>;
+//# sourceMappingURL=related.d.ts.map

package/esm/hooks/search/related.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"related.d.ts","sourceRoot":"","sources":["../../../src/hooks/search/related.ts"],"names":[],"mappings":"AAEA,OAAO,EAEH,KAAK,yBAAyB,EAKjC,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,KAAK,uBAAuB,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAE3E,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,UAAU,EACrD,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,aAAa,EAAE,yBAAyB,EAAE,EAC1C,WAAW,EAAE,uBAAuB,CAAC,CAAC,CAAC,GACxC,aAAa,CAAC,CAAC,CAAC,CAelB"}

package/esm/hooks/search/related.js

@@ -0,0 +1,47 @@
+// (C) 2024-2026 GoodData Corporation
+import { areObjRefsEqual, assertNever, } from "@gooddata/sdk-model";
+export function doFilterRelatedItems(items, searchResults, itemBuilder) {
+    const rest = searchResults.filter((item) => {
+        const objRef = createIdentifierRef(item);
+        return !items.some((searchItem) => areObjRefsEqual(searchItem.ref, objRef));
+    });
+    return rest
+        .map((item) => {
+        const objRef = createIdentifierRef(item);
+        return itemBuilder(item, {
+            ref: objRef,
+            type: convertGenAiTypeToObjectType(item.type),
+        });
+    })
+        .filter(Boolean);
+}
+function createIdentifierRef(item) {
+    return {
+        type: convertGenAiTypeToObjectType(item.type),
+        identifier: item.id,
+    };
+}
+function convertGenAiTypeToObjectType(type) {
+    switch (type) {
+        case "attribute":
+            return "attribute";
+        case "fact":
+            return "fact";
+        case "dashboard":
+            return "analyticalDashboard";
+        case "dataset":
+            return "dataSet";
+        case "date":
+            return "dataSet";
+        case "label":
+            return "displayForm";
+        case "metric":
+            return "measure";
+        case "visualization":
+            return "insight";
+        default:
+            assertNever(type);
+            throw new Error(`Unknown type: ${type}`);
+    }
+}
+//# sourceMappingURL=related.js.map

package/esm/hooks/search/related.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"related.js","sourceRoot":"","sources":["../../../src/hooks/search/related.ts"],"names":[],"mappings":"AAAA,qCAAqC;AAErC,OAAO,EAKH,eAAe,EACf,WAAW,GACd,MAAM,qBAAqB,CAAC;AAI7B,MAAM,UAAU,oBAAoB,CAChC,KAAuB,EACvB,aAA0C,EAC1C,WAAuC,EACvB;IAChB,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;QACzC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,eAAe,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;IAAA,CAC/E,CAAC,CAAC;IAEH,OAAO,IAAI;SACN,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACX,MAAM,MAAM,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;QACzC,OAAO,WAAW,CAAC,IAAI,EAAE;YACrB,GAAG,EAAE,MAAM;YACX,IAAI,EAAE,4BAA4B,CAAC,IAAI,CAAC,IAAI,CAAC;SAChD,CAAC,CAAC;IAAA,CACN,CAAC;SACD,MAAM,CAAC,OAAO,CAAQ,CAAC;AAAA,CAC/B;AAED,SAAS,mBAAmB,CAAC,IAA+B,EAAiB;IACzE,OAAO;QACH,IAAI,EAAE,4BAA4B,CAAC,IAAI,CAAC,IAAI,CAAC;QAC7C,UAAU,EAAE,IAAI,CAAC,EAAE;KACtB,CAAC;AAAA,CACL;AAED,SAAS,4BAA4B,CAAC,IAAqB,EAAc;IACrE,QAAQ,IAAI,EAAE,CAAC;QACX,KAAK,WAAW;YACZ,OAAO,WAAW,CAAC;QACvB,KAAK,MAAM;YACP,OAAO,MAAM,CAAC;QAClB,KAAK,WAAW;YACZ,OAAO,qBAAqB,CAAC;QACjC,KAAK,SAAS;YACV,OAAO,SAAS,CAAC;QACrB,KAAK,MAAM;YACP,OAAO,SAAS,CAAC;QACrB,KAAK,OAAO;YACR,OAAO,aAAa,CAAC;QACzB,KAAK,QAAQ;YACT,OAAO,SAAS,CAAC;QACrB,KAAK,eAAe;YAChB,OAAO,SAAS,CAAC;QACrB;YACI,WAAW,CAAC,IAAI,CAAC,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;IACjD,CAAC;AAAA,CACJ"}

package/esm/hooks/search/search.d.ts

@@ -0,0 +1,4 @@
+import { defaultMatcher } from "./matchers.js";
+import { type SearchItem, type SearchItemGroup, type SearchResults } from "./types.js";
+export declare function doSearch<I extends SearchItem, G extends SearchItemGroup<I>>(items: ReadonlyArray<I>, allItems: ReadonlyArray<I>, itemGroups: ReadonlyArray<G>, keywords: string[], searchQuery: string, matcher?: typeof defaultMatcher): SearchResults<I, G>;
+//# sourceMappingURL=search.d.ts.map

package/esm/hooks/search/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/hooks/search/search.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAEH,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,aAAa,EACrB,MAAM,YAAY,CAAC;AAEpB,wBAAgB,QAAQ,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,eAAe,CAAC,CAAC,CAAC,EACvE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,EAC5B,QAAQ,EAAE,MAAM,EAAE,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,wBAAiB,GACzB,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAYrB"}

package/esm/hooks/search/search.js

@@ -0,0 +1,36 @@
+// (C) 2024-2026 GoodData Corporation
+import { defaultMatcher } from "./matchers.js";
+export function doSearch(items, allItems, itemGroups, keywords, searchQuery, matcher = defaultMatcher) {
+    const searchItems = isMatchingItems(items, itemGroups, searchQuery, matcher);
+    const searchAllItems = isMatchingItems(allItems, itemGroups, searchQuery, matcher);
+    const searchItemGroups = isMatchingItemGroups(itemGroups, searchQuery, matcher);
+    const searchKeywords = isMatchingKeywords(keywords, searchQuery, matcher);
+    return {
+        searchItems,
+        searchAllItems,
+        searchItemGroups,
+        searchKeywords,
+    };
+}
+function isMatchingItems(items, itemGroups, searchQuery, matcher) {
+    const searchQueryUpper = upper(searchQuery);
+    if (searchQuery === "") {
+        if (itemGroups.length === 0) {
+            return items;
+        }
+        return [];
+    }
+    return items.filter((item) => matcher(item, searchQueryUpper));
+}
+function isMatchingItemGroups(itemGroups, searchQuery, matcher) {
+    const searchQueryUpper = upper(searchQuery);
+    return itemGroups.filter((itemGroup) => matcher(itemGroup, searchQueryUpper));
+}
+function isMatchingKeywords(keywords, searchQuery, matcher) {
+    const searchQueryUpper = upper(searchQuery);
+    return keywords.filter((keyword) => matcher(keyword, searchQueryUpper));
+}
+function upper(searchQuery) {
+    return searchQuery.toUpperCase();
+}
+//# sourceMappingURL=search.js.map

package/esm/hooks/search/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../../src/hooks/search/search.ts"],"names":[],"mappings":"AAAA,qCAAqC;AAErC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAQ/C,MAAM,UAAU,QAAQ,CACpB,KAAuB,EACvB,QAA0B,EAC1B,UAA4B,EAC5B,QAAkB,EAClB,WAAmB,EACnB,OAAO,GAAG,cAAc,EACL;IACnB,MAAM,WAAW,GAAG,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IAC7E,MAAM,cAAc,GAAG,eAAe,CAAC,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IACnF,MAAM,gBAAgB,GAAG,oBAAoB,CAAC,UAAU,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IAChF,MAAM,cAAc,GAAG,kBAAkB,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IAE1E,OAAO;QACH,WAAW;QACX,cAAc;QACd,gBAAgB;QAChB,cAAc;KACjB,CAAC;AAAA,CACL;AAED,SAAS,eAAe,CACpB,KAAuB,EACvB,UAA4B,EAC5B,WAAmB,EACnB,OAA4B,EAC9B;IACE,MAAM,gBAAgB,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;IAE5C,IAAI,WAAW,KAAK,EAAE,EAAE,CAAC;QACrB,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,OAAO,EAAE,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAAA,CAClE;AAED,SAAS,oBAAoB,CACzB,UAA4B,EAC5B,WAAmB,EACnB,OAA4B,EAC9B;IACE,MAAM,gBAAgB,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;IAC5C,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAAA,CACjF;AAED,SAAS,kBAAkB,CAAC,QAAkB,EAAE,WAAmB,EAAE,OAA4B,EAAE;IAC/F,MAAM,gBAAgB,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;IAC5C,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAAA,CAC3E;AAED,SAAS,KAAK,CAAC,WAAmB,EAAE;IAChC,OAAO,WAAW,CAAC,WAAW,EAAE,CAAC;AAAA,CACpC"}

package/esm/hooks/search/types.d.ts

@@ -0,0 +1,47 @@
+import { type ISemanticSearchResultItem, type ObjRef, type ObjectType } from "@gooddata/sdk-model";
+/**
+ * @alpha
+ * Defines the shape of the search item.
+ */
+export type SearchItem = {
+    ref: ObjRef;
+    title?: string;
+    name?: string;
+    description?: string;
+    summary?: string;
+};
+/**
+ * @alpha
+ * Defines the shape of the search item group.
+ */
+export type SearchItemGroup<I> = {
+    title?: string;
+    name?: string;
+    description?: string;
+    summary?: string;
+    items?: I[];
+};
+/**
+ * @alpha
+ * Defines the shape of the search results.
+ */
+export type SearchResults<I extends SearchItem, G extends SearchItemGroup<I>> = {
+    searchItems: ReadonlyArray<I>;
+    searchAllItems: ReadonlyArray<I>;
+    searchItemGroups: ReadonlyArray<G>;
+    searchKeywords: ReadonlyArray<string>;
+};
+/**
+ * @alpha
+ * Defines the shape of the search matcher.
+ */
+export type HybridSearchMatcher = <I extends SearchItem, G extends SearchItemGroup<I>>(item: I | G | string, searchQueryUpper: string) => boolean;
+/**
+ * @alpha
+ * Defines the shape of the item builder.
+ */
+export type HybridSearchItemBuilder<I extends SearchItem> = (item: ISemanticSearchResultItem, props: {
+    ref: ObjRef;
+    type: ObjectType;
+}) => I | null | undefined;
+//# sourceMappingURL=types.d.ts.map

package/esm/hooks/search/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/hooks/search/types.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,yBAAyB,EAAE,KAAK,MAAM,EAAE,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEnG;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;CACf,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,eAAe,CAAC,CAAC,CAAC,IAAI;IAC5E,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC9B,cAAc,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACjC,gBAAgB,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACnC,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACzC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,eAAe,CAAC,CAAC,CAAC,EACjF,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,MAAM,EACpB,gBAAgB,EAAE,MAAM,KACvB,OAAO,CAAC;AAEb;;;GAGG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,UAAU,IAAI,CACxD,IAAI,EAAE,yBAAyB,EAC/B,KAAK,EAAE;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,UAAU,CAAC;CACpB,KACA,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC"}

package/esm/hooks/search/types.js

@@ -0,0 +1,3 @@
+// (C) 2024-2026 GoodData Corporation
+export {};
+//# sourceMappingURL=types.js.map

package/esm/hooks/search/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/hooks/search/types.ts"],"names":[],"mappings":"AAAA,qCAAqC"}

package/esm/hooks/useHybridSearch.d.ts

@@ -0,0 +1,125 @@
+import { type IAnalyticalBackend } from "@gooddata/sdk-backend-spi";
+import { type HybridSearchItemBuilder, type HybridSearchMatcher, type SearchItem, type SearchItemGroup, type SearchResults } from "./search/types.js";
+import { type SemanticSearchHookInput } from "./useSemanticSearch.js";
+/**
+ * @alpha
+ * On search query change callback.
+ */
+export type OnSearchQueryChanged = (searchQuery: string) => void;
+/**
+ * @alpha
+ * Options for the useHybridSearch hook.
+ */
+export interface IUseHybridSearchOptions<I extends SearchItem> extends Pick<SemanticSearchHookInput, "deepSearch" | "limit" | "includeTags" | "excludeTags" | "objectTypes"> {
+    /**
+     * The backend to use for the search.
+     * If omitted, will be retrieved from the context.
+     */
+    backend?: IAnalyticalBackend;
+    /**
+     * The workspace to use for the search.
+     * If omitted, will be retrieved from the context.
+     */
+    workspace?: string;
+    /**
+     * Allow semantic search.
+     * default: true
+     */
+    allowSematicSearch?: boolean;
+    /**
+     * Debounce time in milliseconds for search query.
+     * default: 150
+     */
+    debounceMs?: number;
+    /**
+     * Custom matcher for the search results.
+     * If provided, the matcher will be used to filter the search results.
+     * The matcher should return true if the item should be included in the search results,
+     * and false otherwise.
+     */
+    matcher?: HybridSearchMatcher;
+    /**
+     * Item builder for the search results.
+     * If provided, the item builder will be used to transform the search results into a different format.
+     * The item builder should return the transformed item.
+     */
+    itemBuilder: HybridSearchItemBuilder<I>;
+}
+/**
+ * @alpha
+ * State of the search.
+ */
+export interface ISearchState {
+    /**
+     * The current search query.
+     * This is the query that is currently being typed by the user.
+     * It may be different from the debouncedQuery if the user is still typing.
+     */
+    query: string;
+    /**
+     * The debounced search query.
+     * This is the query that is currently being used for the search.
+     * It may be different from the query if the user is still typing.
+     */
+    debouncedQuery: string;
+    /**
+     * The current state of the search.
+     * - idle - means the user has not typed anything yet
+     * - searching - means the user is currently typing
+     * - completed - means the user has stopped typing and the search is complete
+     */
+    state: "idle" | "searching" | "completed";
+}
+/**
+ * @alpha
+ * State of semantic search.
+ */
+export interface ISemanticSearchState {
+    /**
+     * The current state of semantic search.
+     * - idle - means the semantic search is not running
+     * - loading - means the semantic search is running
+     * - error - means the semantic search failed
+     * - success - means the semantic search succeeded
+     */
+    state: "idle" | "loading" | "error" | "success";
+    /**
+     * The message to show to the user that came from the backend.
+     */
+    message: string;
+    /**
+     * The error message if the semantic search failed.
+     */
+    error?: string;
+}
+/**
+ * @alpha
+ * Result of the useHybridSearch hook.
+ */
+export interface IHybridSearchResult<I extends SearchItem, G extends SearchItemGroup<I>> {
+    searchState: ISearchState;
+    semanticSearchState: ISemanticSearchState;
+    search: (props: {
+        items: ReadonlyArray<I>;
+        allItems?: ReadonlyArray<I>;
+        itemGroups?: ReadonlyArray<G>;
+        keywords?: string[];
+    }) => ICombinedSearchResults<I, G>;
+    onSearchQueryChange: OnSearchQueryChanged;
+}
+/**
+ * @alpha
+ * Search results that are combined from semantic search and normal search.
+ */
+export interface ICombinedSearchResults<I extends SearchItem, G extends SearchItemGroup<I>> extends SearchResults<I, G> {
+    searchRelatedItems: ReadonlyArray<I>;
+    searchState: ISearchState;
+    semanticSearchState: ISemanticSearchState;
+}
+/**
+ * @alpha
+ * Use a hybrid search implementation that debounce the search query and provide semantic search
+ * related results
+ */
+export declare function useHybridSearch<I extends SearchItem, G extends SearchItemGroup<I>>({ limit, workspace, backend, debounceMs, allowSematicSearch, deepSearch, objectTypes, includeTags, excludeTags, matcher, itemBuilder }: IUseHybridSearchOptions<I>): IHybridSearchResult<I, G>;
+//# sourceMappingURL=useHybridSearch.d.ts.map

package/esm/hooks/useHybridSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHybridSearch.d.ts","sourceRoot":"","sources":["../../src/hooks/useHybridSearch.ts"],"names":[],"mappings":"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"}

package/esm/hooks/useHybridSearch.js

@@ -0,0 +1,106 @@
+// (C) 2024-2026 GoodData Corporation
+import { startTransition, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useBackendStrict, useWorkspaceStrict } from "@gooddata/sdk-ui";
+import { doFilterRelatedItems } from "./search/related.js";
+import { doSearch } from "./search/search.js";
+import { useSemanticSearch } from "./useSemanticSearch.js";
+const SEARCH_DEBOUNCE_MS = 150;
+/**
+ * @alpha
+ * Use a hybrid search implementation that debounce the search query and provide semantic search
+ * related results
+ */
+export function useHybridSearch({ limit, workspace, backend, debounceMs = SEARCH_DEBOUNCE_MS, allowSematicSearch = true, deepSearch, objectTypes, includeTags, excludeTags, matcher, itemBuilder, }) {
+    const [searchQuery, setSearchQuery] = useState("");
+    const debouncedSearchQuery = useDebouncedValue(searchQuery, debounceMs);
+    const onSearchQueryChange = useOnSearchQueryChangeCallback(setSearchQuery);
+    const semanticSearchProps = useMemo(() => {
+        return {
+            objectTypes,
+            excludeTags,
+            includeTags,
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [objectTypes?.join(), includeTags?.join(), excludeTags?.join()]);
+    const effectiveBackend = useBackendStrict(backend);
+    const effectiveWorkspace = useWorkspaceStrict(workspace);
+    const { searchStatus, searchError, searchResults, searchMessage } = useSemanticSearch({
+        searchTerm: allowSematicSearch ? debouncedSearchQuery : "",
+        backend: effectiveBackend,
+        workspace: effectiveWorkspace,
+        deepSearch,
+        limit,
+        ...semanticSearchProps,
+    });
+    const searchState = useMemo(() => ({
+        query: searchQuery,
+        debouncedQuery: debouncedSearchQuery,
+        state: getSearchState(searchQuery, debouncedSearchQuery),
+    }), [debouncedSearchQuery, searchQuery]);
+    const semanticSearchState = useMemo(() => ({
+        state: searchStatus,
+        error: searchError,
+        message: searchMessage,
+    }), [searchStatus, searchError, searchMessage]);
+    const search = useCallback((({ items, allItems = items, itemGroups = [], keywords = [] }) => {
+        const results = doSearch(items, allItems, itemGroups, keywords, searchQuery, matcher);
+        const searchRelatedItems = doFilterRelatedItems(results.searchAllItems, searchResults, itemBuilder);
+        return {
+            ...results,
+            searchRelatedItems,
+            //states
+            searchState,
+            semanticSearchState,
+        };
+    }), [searchQuery, searchState, semanticSearchState, searchResults, matcher, itemBuilder]);
+    return {
+        searchState,
+        semanticSearchState,
+        search,
+        onSearchQueryChange,
+    };
+}
+/**
+ * Debounce a string value by the given delay.
+ * Empty values are applied immediately (clearing search should feel instant).
+ */
+function useDebouncedValue(value, delay) {
+    const [debouncedValue, setDebouncedValue] = useState(value);
+    const timerRef = useRef(undefined);
+    useEffect(() => {
+        // Clear search immediately — no debounce, no transition
+        if (value === "") {
+            setDebouncedValue("");
+            return undefined;
+        }
+        timerRef.current = setTimeout(() => {
+            // Mark as low-priority so React can interrupt for input events
+            startTransition(() => setDebouncedValue(value));
+        }, delay);
+        return () => {
+            if (timerRef.current) {
+                clearTimeout(timerRef.current);
+            }
+        };
+    }, [value, delay]);
+    return debouncedValue;
+}
+/**
+ * Create a callback that updates the search query.
+ */
+function useOnSearchQueryChangeCallback(setSearchQuery) {
+    return useCallback((query) => {
+        setSearchQuery(query);
+    }, [setSearchQuery]);
+}
+//utils
+function getSearchState(searchQuery, debouncedSearchQuery) {
+    if (searchQuery === "") {
+        return "idle";
+    }
+    if (debouncedSearchQuery !== searchQuery) {
+        return "searching";
+    }
+    return "completed";
+}
+//# sourceMappingURL=useHybridSearch.js.map

package/esm/hooks/useHybridSearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHybridSearch.js","sourceRoot":"","sources":["../../src/hooks/useHybridSearch.ts"],"names":[],"mappings":"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"}

package/esm/index.d.ts

@@ -6,4 +6,7 @@
 export { type SemanticSearchInputResult, type SemanticSearchHookInput, useSemanticSearch, } from "./hooks/useSemanticSearch.js";
 export { type FooterButtonAiAssistantProps, FooterButtonAiAssistant } from "./FooterButtonAiAssistant.js";
 export { type SemanticSearchProps, SemanticSearch } from "./SemanticSearch.js";
+export { type ICombinedSearchResults, type IHybridSearchResult, type ISearchState, type ISemanticSearchState, type IUseHybridSearchOptions, useHybridSearch, type OnSearchQueryChanged, } from "./hooks/useHybridSearch.js";
+export type { HybridSearchMatcher, SearchItem, SearchItemGroup, SearchResults, HybridSearchItemBuilder, } from "./hooks/search/types.js";
+export { defaultMatcher, customMatcher } from "./hooks/search/matchers.js";
 //# sourceMappingURL=index.d.ts.map

package/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AAEH,OAAO,EACH,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAC5B,iBAAiB,GACpB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,KAAK,4BAA4B,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC1G,OAAO,EAAE,KAAK,mBAAmB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AAEH,OAAO,EACH,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAC5B,iBAAiB,GACpB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,KAAK,4BAA4B,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC1G,OAAO,EAAE,KAAK,mBAAmB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE/E,OAAO,EACH,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,eAAe,EACf,KAAK,oBAAoB,GAC5B,MAAM,4BAA4B,CAAC;AAEpC,YAAY,EACR,mBAAmB,EACnB,UAAU,EACV,eAAe,EACf,aAAa,EACb,uBAAuB,GAC1B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC"}

package/esm/index.js

@@ -8,4 +8,6 @@
 export { useSemanticSearch, } from "./hooks/useSemanticSearch.js";
 export { FooterButtonAiAssistant } from "./FooterButtonAiAssistant.js";
 export { SemanticSearch } from "./SemanticSearch.js";
+export { useHybridSearch, } from "./hooks/useHybridSearch.js";
+export { defaultMatcher, customMatcher } from "./hooks/search/matchers.js";
 //# sourceMappingURL=index.js.map

package/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qCAAqC;AAErC,oDAAoD;AAEpD;;;;GAIG;AAEH,OAAO,EAGH,iBAAiB,GACpB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAqC,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC1G,OAAO,EAA4B,cAAc,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qCAAqC;AAErC,oDAAoD;AAEpD;;;;GAIG;AAEH,OAAO,EAGH,iBAAiB,GACpB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAqC,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC1G,OAAO,EAA4B,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE/E,OAAO,EAMH,eAAe,GAElB,MAAM,4BAA4B,CAAC;AAUpC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC"}

package/esm/sdk-ui-semantic-search.d.ts

@@ -11,8 +11,22 @@ import { ISemanticSearchRelationship } from '@gooddata/sdk-model';
 import { ISemanticSearchResultItem } from '@gooddata/sdk-model';
 import { JSX } from 'react/jsx-runtime';
 import { MouseEvent as MouseEvent_2 } from 'react';
+import { ObjectType } from '@gooddata/sdk-model';
+import { ObjRef } from '@gooddata/sdk-model';
 import { ReactNode } from 'react';
 
+/**
+ * @alpha
+ * Custom matcher for the search. Can be used to match any property of the search item.
+ */
+export declare function customMatcher<I extends SearchItem, G extends SearchItemGroup<I>>(props: (keyof I & keyof G)[]): HybridSearchMatcher;
+
+/**
+ * @alpha
+ * Default matcher for the search. Supports title, name, description, summary.
+ */
+export declare function defaultMatcher<I extends SearchItem, G extends SearchItemGroup<I>>(item: I | G | string, searchQueryUpper: string): boolean;
+
 /**
  * @public
  */
@@ -25,6 +39,177 @@ export declare type FooterButtonAiAssistantProps = {
     onClick?: (e: MouseEvent_2) => void;
 };
 
+/**
+ * @alpha
+ * Defines the shape of the item builder.
+ */
+export declare type HybridSearchItemBuilder<I extends SearchItem> = (item: ISemanticSearchResultItem, props: {
+    ref: ObjRef;
+    type: ObjectType;
+}) => I | null | undefined;
+
+/**
+ * @alpha
+ * Defines the shape of the search matcher.
+ */
+export declare type HybridSearchMatcher = <I extends SearchItem, G extends SearchItemGroup<I>>(item: I | G | string, searchQueryUpper: string) => boolean;
+
+/**
+ * @alpha
+ * Search results that are combined from semantic search and normal search.
+ */
+export declare interface ICombinedSearchResults<I extends SearchItem, G extends SearchItemGroup<I>> extends SearchResults<I, G> {
+    searchRelatedItems: ReadonlyArray<I>;
+    searchState: ISearchState;
+    semanticSearchState: ISemanticSearchState;
+}
+
+/**
+ * @alpha
+ * Result of the useHybridSearch hook.
+ */
+export declare interface IHybridSearchResult<I extends SearchItem, G extends SearchItemGroup<I>> {
+    searchState: ISearchState;
+    semanticSearchState: ISemanticSearchState;
+    search: (props: {
+        items: ReadonlyArray<I>;
+        allItems?: ReadonlyArray<I>;
+        itemGroups?: ReadonlyArray<G>;
+        keywords?: string[];
+    }) => ICombinedSearchResults<I, G>;
+    onSearchQueryChange: OnSearchQueryChanged;
+}
+
+/**
+ * @alpha
+ * State of the search.
+ */
+export declare interface ISearchState {
+    /**
+     * The current search query.
+     * This is the query that is currently being typed by the user.
+     * It may be different from the debouncedQuery if the user is still typing.
+     */
+    query: string;
+    /**
+     * The debounced search query.
+     * This is the query that is currently being used for the search.
+     * It may be different from the query if the user is still typing.
+     */
+    debouncedQuery: string;
+    /**
+     * The current state of the search.
+     * - idle - means the user has not typed anything yet
+     * - searching - means the user is currently typing
+     * - completed - means the user has stopped typing and the search is complete
+     */
+    state: "idle" | "searching" | "completed";
+}
+
+/**
+ * @alpha
+ * State of semantic search.
+ */
+export declare interface ISemanticSearchState {
+    /**
+     * The current state of semantic search.
+     * - idle - means the semantic search is not running
+     * - loading - means the semantic search is running
+     * - error - means the semantic search failed
+     * - success - means the semantic search succeeded
+     */
+    state: "idle" | "loading" | "error" | "success";
+    /**
+     * The message to show to the user that came from the backend.
+     */
+    message: string;
+    /**
+     * The error message if the semantic search failed.
+     */
+    error?: string;
+}
+
+/**
+ * @alpha
+ * Options for the useHybridSearch hook.
+ */
+export declare interface IUseHybridSearchOptions<I extends SearchItem> extends Pick<SemanticSearchHookInput, "deepSearch" | "limit" | "includeTags" | "excludeTags" | "objectTypes"> {
+    /**
+     * The backend to use for the search.
+     * If omitted, will be retrieved from the context.
+     */
+    backend?: IAnalyticalBackend;
+    /**
+     * The workspace to use for the search.
+     * If omitted, will be retrieved from the context.
+     */
+    workspace?: string;
+    /**
+     * Allow semantic search.
+     * default: true
+     */
+    allowSematicSearch?: boolean;
+    /**
+     * Debounce time in milliseconds for search query.
+     * default: 150
+     */
+    debounceMs?: number;
+    /**
+     * Custom matcher for the search results.
+     * If provided, the matcher will be used to filter the search results.
+     * The matcher should return true if the item should be included in the search results,
+     * and false otherwise.
+     */
+    matcher?: HybridSearchMatcher;
+    /**
+     * Item builder for the search results.
+     * If provided, the item builder will be used to transform the search results into a different format.
+     * The item builder should return the transformed item.
+     */
+    itemBuilder: HybridSearchItemBuilder<I>;
+}
+
+/**
+ * @alpha
+ * On search query change callback.
+ */
+export declare type OnSearchQueryChanged = (searchQuery: string) => void;
+
+/**
+ * @alpha
+ * Defines the shape of the search item.
+ */
+export declare type SearchItem = {
+    ref: ObjRef;
+    title?: string;
+    name?: string;
+    description?: string;
+    summary?: string;
+};
+
+/**
+ * @alpha
+ * Defines the shape of the search item group.
+ */
+export declare type SearchItemGroup<I> = {
+    title?: string;
+    name?: string;
+    description?: string;
+    summary?: string;
+    items?: I[];
+};
+
+/**
+ * @alpha
+ * Defines the shape of the search results.
+ */
+export declare type SearchResults<I extends SearchItem, G extends SearchItemGroup<I>> = {
+    searchItems: ReadonlyArray<I>;
+    searchAllItems: ReadonlyArray<I>;
+    searchItemGroups: ReadonlyArray<G>;
+    searchKeywords: ReadonlyArray<string>;
+};
+
 /**
  * Semantic search filed with dropdown for selecting items.
  * @beta
@@ -175,6 +360,13 @@ export declare type SemanticSearchProps = {
     }) => ReactNode;
 };
 
+/**
+ * @alpha
+ * Use a hybrid search implementation that debounce the search query and provide semantic search
+ * related results
+ */
+export declare function useHybridSearch<I extends SearchItem, G extends SearchItemGroup<I>>({ limit, workspace, backend, debounceMs, allowSematicSearch, deepSearch, objectTypes, includeTags, excludeTags, matcher, itemBuilder }: IUseHybridSearchOptions<I>): IHybridSearchResult<I, G>;
+
 /**
  * Hook to perform semantic search.
  * Makes the request to server and returns the search results.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gooddata/sdk-ui-semantic-search",
-  "version": "11.26.0-alpha.2",
+  "version": "11.26.0-alpha.3",
   "description": "GoodData SDK TypeScript & React skeleton",
   "license": "MIT",
   "author": "GoodData Corporation",
@@ -35,12 +35,12 @@
     "lodash-es": "^4.17.23",
     "react-intl": "7.1.11",
     "tslib": "2.8.1",
-    "@gooddata/sdk-model": "11.26.0-alpha.2",
-    "@gooddata/sdk-backend-spi": "11.26.0-alpha.2",
-    "@gooddata/sdk-ui": "11.26.0-alpha.2",
-    "@gooddata/sdk-ui-kit": "11.26.0-alpha.2",
-    "@gooddata/sdk-ui-theme-provider": "11.26.0-alpha.2",
-    "@gooddata/util": "11.26.0-alpha.2"
+    "@gooddata/sdk-backend-spi": "11.26.0-alpha.3",
+    "@gooddata/sdk-model": "11.26.0-alpha.3",
+    "@gooddata/sdk-ui-theme-provider": "11.26.0-alpha.3",
+    "@gooddata/sdk-ui": "11.26.0-alpha.3",
+    "@gooddata/sdk-ui-kit": "11.26.0-alpha.3",
+    "@gooddata/util": "11.26.0-alpha.3"
   },
   "devDependencies": {
     "@microsoft/api-documenter": "^7.17.0",
@@ -80,11 +80,11 @@
     "typescript": "5.9.3",
     "vitest": "4.0.8",
     "vitest-dom": "0.1.1",
-    "@gooddata/eslint-config": "11.26.0-alpha.2",
-    "@gooddata/i18n-toolkit": "11.26.0-alpha.2",
-    "@gooddata/oxlint-config": "11.26.0-alpha.2",
-    "@gooddata/sdk-backend-mockingbird": "11.26.0-alpha.2",
-    "@gooddata/stylelint-config": "11.26.0-alpha.2"
+    "@gooddata/eslint-config": "11.26.0-alpha.3",
+    "@gooddata/i18n-toolkit": "11.26.0-alpha.3",
+    "@gooddata/oxlint-config": "11.26.0-alpha.3",
+    "@gooddata/stylelint-config": "11.26.0-alpha.3",
+    "@gooddata/sdk-backend-mockingbird": "11.26.0-alpha.3"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",