@databricks/appkit-ui 0.53.1 → 0.55.0

package/docs/plugins/{vector-search.md → ai-search.md}

@@ -1,4 +1,8 @@
-# Vector Search plugin
+# AI Search plugin
+
+Beta plugin
+
+This plugin is currently **beta**. APIs may change between minor releases. Import from `@databricks/appkit/beta`. See [Plugin Stability Tiers](./docs/plugins/stability.md).
 
 Query Databricks Vector Search indexes with hybrid search, reranking, and cursor pagination from your AppKit application.
 
@@ -14,12 +18,13 @@ Query Databricks Vector Search indexes with hybrid search, reranking, and cursor
 ## Basic usage[​](#basic-usage "Direct link to Basic usage")
 
 ```ts
-import { createApp, vectorSearch, server } from "@databricks/appkit";
+import { createApp, server } from "@databricks/appkit";
+import { aiSearch } from "@databricks/appkit/beta";
 
 await createApp({
   plugins: [
     server(),
-    vectorSearch({
+    aiSearch({
       indexes: {
         products: {
           indexName: "catalog.schema.products_idx",
@@ -46,7 +51,7 @@ await createApp({
 Index aliases let you reference multiple Vector Search indexes by name. The alias is used in API routes and programmatic calls:
 
 ```ts
-vectorSearch({
+aiSearch({
   indexes: {
     products: {
       indexName: "catalog.schema.products_idx",
@@ -62,19 +67,23 @@ vectorSearch({
 
 ```
 
+note
+
+An alias without its own `indexName` falls back to the `DATABRICKS_VS_INDEX_NAME` env var. If several aliases omit `indexName`, they all resolve to that one physical index (with their own per-alias `columns`, `queryType`, etc.). Give each alias an explicit `indexName` when you mean distinct indexes.
+
 ## IndexConfig[​](#indexconfig "Direct link to IndexConfig")
 
-| Field          | Type                                         | Default               | Description                                                                     |
-| -------------- | -------------------------------------------- | --------------------- | ------------------------------------------------------------------------------- |
-| `indexName`    | `string`                                     | —                     | **Required.** Three-level Unity Catalog name (`catalog.schema.index`)           |
-| `columns`      | `string[]`                                   | —                     | **Required.** Columns to return in query results                                |
-| `queryType`    | `"ann" \| "hybrid" \| "full_text"`           | `"hybrid"`            | Search mode                                                                     |
-| `numResults`   | `number`                                     | `20`                  | Maximum results per query                                                       |
-| `reranker`     | `boolean \| { columnsToRerank: string[] }`   | —                     | Enable reranking. Pass `true` to rerank all result columns, or specify a subset |
-| `auth`         | `"service-principal" \| "on-behalf-of-user"` | `"service-principal"` | Authentication mode for query execution                                         |
-| `pagination`   | `boolean`                                    | —                     | Enable cursor-based pagination                                                  |
-| `endpointName` | `string`                                     | —                     | Vector Search endpoint name. Required when `pagination` is `true`               |
-| `embeddingFn`  | `(text: string) => Promise<number[]>`        | —                     | Custom embedding function for self-managed embedding indexes                    |
+| Field          | Type                                         | Default                    | Description                                                                                                                                                                                                             |
+| -------------- | -------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `indexName`    | `string`                                     | `DATABRICKS_VS_INDEX_NAME` | Three-level Unity Catalog name (`catalog.schema.index`). Defaults to the `DATABRICKS_VS_INDEX_NAME` env var when omitted.                                                                                               |
+| `columns`      | `string[]`                                   | auto-discovered in dev     | Columns to return in query results. Optional in development — when omitted, the plugin reads them from the index's source table and warns. **Set explicitly for production**, where a missing value is not auto-filled. |
+| `queryType`    | `"ann" \| "hybrid" \| "full_text"`           | `"hybrid"`                 | Search mode                                                                                                                                                                                                             |
+| `numResults`   | `number`                                     | `20`                       | Maximum results per query                                                                                                                                                                                               |
+| `reranker`     | `boolean \| { columnsToRerank: string[] }`   | —                          | Enable reranking. Pass `true` to rerank all result columns, or specify a subset                                                                                                                                         |
+| `auth`         | `"service-principal" \| "on-behalf-of-user"` | `"service-principal"`      | Authentication mode for query execution                                                                                                                                                                                 |
+| `pagination`   | `boolean`                                    | —                          | Enable cursor-based pagination                                                                                                                                                                                          |
+| `endpointName` | `string`                                     | —                          | Vector Search endpoint name. Required when `pagination` is `true`                                                                                                                                                       |
+| `embeddingFn`  | `(text: string) => Promise<number[]>`        | —                          | Custom embedding function for self-managed embedding indexes                                                                                                                                                            |
 
 ### Query types[​](#query-types "Direct link to Query types")
 
@@ -87,7 +96,7 @@ vectorSearch({
 Reranking improves result relevance by running a second-stage model over the initial candidates:
 
 ```ts
-vectorSearch({
+aiSearch({
   indexes: {
     products: {
       indexName: "catalog.schema.products_idx",
@@ -106,7 +115,7 @@ Pass `reranker: true` to rerank across all returned columns.
 By default, queries run as the app's service principal. Set `auth: "on-behalf-of-user"` to execute queries as the signed-in user instead:
 
 ```ts
-vectorSearch({
+aiSearch({
   indexes: {
     documents: {
       indexName: "catalog.schema.documents_idx",
@@ -123,7 +132,7 @@ vectorSearch({
 Enable cursor pagination to page through large result sets:
 
 ```ts
-vectorSearch({
+aiSearch({
   indexes: {
     products: {
       indexName: "catalog.schema.products_idx",
@@ -145,7 +154,7 @@ For indexes that manage their own embeddings, provide an `embeddingFn` that take
 ```ts
 import { embed } from "./my-embedding-client";
 
-vectorSearch({
+aiSearch({
   indexes: {
     products: {
       indexName: "catalog.schema.products_idx",
@@ -160,7 +169,7 @@ vectorSearch({
 
 ## HTTP routes[​](#http-routes "Direct link to HTTP routes")
 
-Routes are mounted at `/api/vector-search`.
+Routes are mounted at `/api/ai-search`.
 
 | Method | Path                | Description                                                  |
 | ------ | ------------------- | ------------------------------------------------------------ |
@@ -171,7 +180,7 @@ Routes are mounted at `/api/vector-search`.
 ### Query an index[​](#query-an-index "Direct link to Query an index")
 
 ```text
-POST /api/vector-search/:alias/query
+POST /api/ai-search/:alias/query
 Content-Type: application/json
 
 {
@@ -186,19 +195,25 @@ Response:
 ```json
 {
   "results": [
-    { "id": "42", "name": "Intro to ML", "description": "..." }
+    {
+      "score": 0.87,
+      "data": { "id": "42", "name": "Intro to ML", "description": "..." }
+    }
   ],
+  "totalCount": 1,
+  "queryTimeMs": 35,
+  "queryType": "hybrid",
   "nextPageToken": "eyJvZmZzZXQiOjEwfQ=="
 }
 
 ```
 
-`nextPageToken` is only present when `pagination` is enabled and more results are available.
+Each result carries its relevance `score` and the returned columns under `data`. `nextPageToken` is `null` unless `pagination` is enabled and more results are available.
 
 ### Fetch the next page[​](#fetch-the-next-page "Direct link to Fetch the next page")
 
 ```text
-POST /api/vector-search/:alias/next-page
+POST /api/ai-search/:alias/next-page
 Content-Type: application/json
 
 {
@@ -211,7 +226,7 @@ Content-Type: application/json
 ### Get index config[​](#get-index-config "Direct link to Get index config")
 
 ```text
-GET /api/vector-search/:alias/config
+GET /api/ai-search/:alias/config
 
 ```
 
@@ -222,10 +237,13 @@ Returns the resolved `IndexConfig` for the alias (excluding `embeddingFn`).
 The plugin exposes a `query` method for server-side use:
 
 ```ts
+import { createApp, server } from "@databricks/appkit";
+import { aiSearch } from "@databricks/appkit/beta";
+
 const AppKit = await createApp({
   plugins: [
     server(),
-    vectorSearch({
+    aiSearch({
       indexes: {
         products: {
           indexName: "catalog.schema.products_idx",
@@ -236,7 +254,7 @@ const AppKit = await createApp({
   ],
 });
 
-const result = await AppKit.vectorSearch.query("products", {
+const result = await AppKit.aiSearch.query("products", {
   queryText: "machine learning guide",
 });
 
@@ -245,3 +263,28 @@ console.log(result.results);
 ```
 
 Pass optional overrides as a second argument to `query` to adjust `numResults` or other per-call settings.
+
+## React hook[​](#react-hook "Direct link to React hook")
+
+`useAiSearchQuery` reads the configured indexes from the plugin's client config and posts to the right `/:alias/query` route, so the UI never hardcodes an alias. With one index configured it needs no arguments; pass `{ alias }` to target a specific one.
+
+```tsx
+import { useAiSearchQuery } from "@databricks/appkit-ui/react/beta";
+
+function Search() {
+  const { search, data, loading, error } = useAiSearchQuery();
+
+  return (
+    <>
+      <input onKeyDown={(e) => e.key === "Enter" && search(e.currentTarget.value)} />
+      {error && <p>{error}</p>}
+      {data?.results.map((r, i) => (
+        <div key={i}>{JSON.stringify(r.data)}</div>
+      ))}
+    </>
+  );
+}
+
+```
+
+`search` also accepts a full request object (`{ queryText, numResults, filters, ... }`) for per-call control. The hook's `indexes` field lists every configured index, which you can use to build an index picker.

package/llms.txt

@@ -44,6 +44,7 @@ npx @databricks/appkit docs <query>
 ## Plugins
 
 - [Agents](./docs/plugins/agents.md): This plugin is currently beta. APIs may change between minor releases. Import from @databricks/appkit/beta. See Plugin Stability Tiers.
+- [AI Search plugin](./docs/plugins/ai-search.md): This plugin is currently beta. APIs may change between minor releases. Import from @databricks/appkit/beta. See Plugin Stability Tiers.
 - [Analytics plugin](./docs/plugins/analytics.md): Enables SQL query execution against Databricks SQL Warehouses.
 - [Caching](./docs/plugins/caching.md): AppKit provides both global and plugin-level caching capabilities.
 - [Creating custom plugins](./docs/plugins/custom-plugins.md): If you need custom API routes or background logic, implement an AppKit plugin. The fastest way is to use the CLI:
@@ -57,7 +58,6 @@ npx @databricks/appkit docs <query>
 - [Plugin management](./docs/plugins/plugin-management.md): AppKit includes a CLI for managing plugins. All commands are available under npx @databricks/appkit plugin.
 - [Server plugin](./docs/plugins/server.md): Provides HTTP server capabilities with development and production modes.
 - [Plugin Stability Tiers](./docs/plugins/stability.md): AppKit plugins have a two-tier stability system that communicates API maturity and breaking-change expectations.
-- [Vector Search plugin](./docs/plugins/vector-search.md): Query Databricks Vector Search indexes with hybrid search, reranking, and cursor pagination from your AppKit application.
 
 ## appkit API reference [collapsed]
 
@@ -131,7 +131,9 @@ npx @databricks/appkit docs <query>
 - [Interface: GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md): Request parameters for generating database OAuth credentials
 - [Interface: GenerationParams](./docs/api/appkit/Interface.GenerationParams.md): Optional generation parameters forwarded to the OpenAI-compatible serving
 - [Interface: HostedSupervisorTool](./docs/api/appkit/Interface.HostedSupervisorTool.md): Tagged record returned by every supervisorTools factory. The
+- [Interface: IAiSearchConfig](./docs/api/appkit/Interface.IAiSearchConfig.md): Base configuration interface for AppKit plugins
 - [Interface: IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md): Configuration for the Jobs plugin.
+- [Interface: IndexConfig](./docs/api/appkit/Interface.IndexConfig.md): Properties
 - [Interface: ITelemetry](./docs/api/appkit/Interface.ITelemetry.md): Plugin-facing interface for OpenTelemetry instrumentation.
 - [Interface: JobAPI](./docs/api/appkit/Interface.JobAPI.md): User-facing API for a single configured job.
 - [Interface: JobConfig](./docs/api/appkit/Interface.JobConfig.md): Per-job configuration options.
@@ -147,10 +149,14 @@ npx @databricks/appkit docs <query>
 - [Interface: RegisteredAgent](./docs/api/appkit/Interface.RegisteredAgent.md): Properties
 - [Interface: RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md): Optional claims for fine-grained Unity Catalog table permissions
 - [Interface: RequestedResource](./docs/api/appkit/Interface.RequestedResource.md): Resource to request permissions for in Unity Catalog
+- [Interface: RerankerConfig](./docs/api/appkit/Interface.RerankerConfig.md): Properties
 - [Interface: ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md): Internal representation of a resource in the registry.
 - [Interface: ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md): Declares a resource requirement for a plugin.
 - [Interface: RunAgentInput](./docs/api/appkit/Interface.RunAgentInput.md): Properties
 - [Interface: RunAgentResult](./docs/api/appkit/Interface.RunAgentResult.md): Properties
+- [Interface: SearchRequest](./docs/api/appkit/Interface.SearchRequest.md): Properties
+- [Interface: SearchResponse<T>](./docs/api/appkit/Interface.SearchResponse.md): Type Parameters
+- [Interface: SearchResult<T>](./docs/api/appkit/Interface.SearchResult.md): Type Parameters
 - [Interface: ServingEndpointEntry](./docs/api/appkit/Interface.ServingEndpointEntry.md): Shape of a single registry entry.
 - [Interface: ServingEndpointRegistry](./docs/api/appkit/Interface.ServingEndpointRegistry.md): Registry interface for serving endpoint type generation.
 - [Interface: StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md): Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.
@@ -187,11 +193,13 @@ npx @databricks/appkit docs <query>
 - [Type Alias: ResolvedToolEntry](./docs/api/appkit/TypeAlias.ResolvedToolEntry.md): Internal tool-index entry after a tool record has been resolved to a dispatchable form.
 - [Type Alias: ResourceFieldEntry](./docs/api/appkit/TypeAlias.ResourceFieldEntry.md)
 - [Type Alias: ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md): Union of all possible permission levels across all resource types.
+- [Type Alias: SearchFilters](./docs/api/appkit/TypeAlias.SearchFilters.md)
 - [Type Alias: ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md): Factory function returned by AppKit.serving.
 - [Type Alias: SupervisorTool](./docs/api/appkit/TypeAlias.SupervisorTool.md): Tools supported by the Databricks AI Gateway Responses API. The shapes match
 - [Type Alias: ToolRegistry](./docs/api/appkit/TypeAlias.ToolRegistry.md)
 - [Type Alias: ToPlugin()<T, U, N>](./docs/api/appkit/TypeAlias.ToPlugin.md): Factory function type returned by toPlugin(). Accepts optional config and returns a PluginData tuple.
 - [Variable: agents](./docs/api/appkit/Variable.agents.md): Plugin factory for the agents plugin. Reads config/agents/*.md by default,
+- [Variable: aiSearch](./docs/api/appkit/Variable.aiSearch.md)
 - [Variable: READ_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md): Actions that only read data.
 - [Variable: sql](./docs/api/appkit/Variable.sql.md): SQL helper namespace
 - [Variable: SUPERVISOR_EXTENSION_KEY](./docs/api/appkit/Variable.SUPERVISOR_EXTENSION_KEY.md): Namespace key under which the adapter reads its hosted-tool payload

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit-ui",
   "type": "module",
-  "version": "0.53.1",
+  "version": "0.55.0",
   "license": "Apache-2.0",
   "sideEffects": [
     "**/*.css"