@databricks/appkit 0.53.1 → 0.55.0

package/docs/api/appkit/Interface.IndexConfig.md

@@ -0,0 +1,110 @@
+# Interface: IndexConfig
+
+## Properties[​](#properties "Direct link to Properties")
+
+### auth?[​](#auth "Direct link to auth?")
+
+```ts
+optional auth: "service-principal" | "on-behalf-of-user";
+
+```
+
+Auth mode for the built-in HTTP routes — "service-principal" (default) uses the app's SP, "on-behalf-of-user" proxies the logged-in user's token. Programmatic callers select per call via `appkit.aiSearch.asUser(req)`.
+
+***
+
+### columns?[​](#columns "Direct link to columns?")
+
+```ts
+optional columns: string[];
+
+```
+
+Columns to return in results. Optional: in development the plugin auto-discovers them from the index's source table when omitted (and warns that they should be set explicitly for production).
+
+***
+
+### embeddingFn()?[​](#embeddingfn "Direct link to embeddingFn()?")
+
+```ts
+optional embeddingFn: (text: string) => Promise<number[]>;
+
+```
+
+For self-managed embedding indexes: converts query text to an embedding vector. When provided, the plugin calls this function and sends query\_vector to VS. When omitted, query\_text is sent and VS computes embeddings server-side (managed mode).
+
+#### Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type     |
+| --------- | -------- |
+| `text`    | `string` |
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`Promise`<`number`\[]>
+
+***
+
+### endpointName?[​](#endpointname "Direct link to endpointName?")
+
+```ts
+optional endpointName: string;
+
+```
+
+VS endpoint name (required when pagination is true)
+
+***
+
+### indexName?[​](#indexname "Direct link to indexName?")
+
+```ts
+optional indexName: string;
+
+```
+
+Three-level UC name: catalog.schema.index\_name. Defaults to the `DATABRICKS_VS_INDEX_NAME` env var when omitted — so multiple aliases that omit it all resolve to that same physical index. Set it explicitly per alias when they should point at distinct indexes.
+
+***
+
+### numResults?[​](#numresults "Direct link to numResults?")
+
+```ts
+optional numResults: number;
+
+```
+
+Max results per query
+
+***
+
+### pagination?[​](#pagination "Direct link to pagination?")
+
+```ts
+optional pagination: boolean;
+
+```
+
+Enable cursor pagination
+
+***
+
+### queryType?[​](#querytype "Direct link to queryType?")
+
+```ts
+optional queryType: SearchQueryType;
+
+```
+
+Default search mode
+
+***
+
+### reranker?[​](#reranker "Direct link to reranker?")
+
+```ts
+optional reranker: boolean | RerankerConfig;
+
+```
+
+Enable built-in reranker. Pass true to rerank all non-id columns, or an object for fine control.

package/docs/api/appkit/Interface.RerankerConfig.md

@@ -0,0 +1,10 @@
+# Interface: RerankerConfig
+
+## Properties[​](#properties "Direct link to Properties")
+
+### columnsToRerank[​](#columnstorerank "Direct link to columnsToRerank")
+
+```ts
+columnsToRerank: string[];
+
+```

package/docs/api/appkit/Interface.SearchRequest.md

@@ -0,0 +1,64 @@
+# Interface: SearchRequest
+
+## Properties[​](#properties "Direct link to Properties")
+
+### columns?[​](#columns "Direct link to columns?")
+
+```ts
+optional columns: string[];
+
+```
+
+***
+
+### filters?[​](#filters "Direct link to filters?")
+
+```ts
+optional filters: SearchFilters;
+
+```
+
+***
+
+### numResults?[​](#numresults "Direct link to numResults?")
+
+```ts
+optional numResults: number;
+
+```
+
+***
+
+### queryText?[​](#querytext "Direct link to queryText?")
+
+```ts
+optional queryText: string;
+
+```
+
+***
+
+### queryType?[​](#querytype "Direct link to queryType?")
+
+```ts
+optional queryType: SearchQueryType;
+
+```
+
+***
+
+### queryVector?[​](#queryvector "Direct link to queryVector?")
+
+```ts
+optional queryVector: number[];
+
+```
+
+***
+
+### reranker?[​](#reranker "Direct link to reranker?")
+
+```ts
+optional reranker: boolean;
+
+```

package/docs/api/appkit/Interface.SearchResponse.md

@@ -0,0 +1,52 @@
+# Interface: SearchResponse\<T>
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter                              | Default type                  |
+| ------------------------------------------- | ----------------------------- |
+| `T` *extends* `Record`<`string`, `unknown`> | `Record`<`string`, `unknown`> |
+
+## Properties[​](#properties "Direct link to Properties")
+
+### nextPageToken[​](#nextpagetoken "Direct link to nextPageToken")
+
+```ts
+nextPageToken: string | null;
+
+```
+
+***
+
+### queryTimeMs[​](#querytimems "Direct link to queryTimeMs")
+
+```ts
+queryTimeMs: number;
+
+```
+
+***
+
+### queryType[​](#querytype "Direct link to queryType")
+
+```ts
+queryType: SearchQueryType;
+
+```
+
+***
+
+### results[​](#results "Direct link to results")
+
+```ts
+results: SearchResult<T>[];
+
+```
+
+***
+
+### totalCount[​](#totalcount "Direct link to totalCount")
+
+```ts
+totalCount: number;
+
+```

package/docs/api/appkit/Interface.SearchResult.md

@@ -0,0 +1,25 @@
+# Interface: SearchResult\<T>
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter                              | Default type                  |
+| ------------------------------------------- | ----------------------------- |
+| `T` *extends* `Record`<`string`, `unknown`> | `Record`<`string`, `unknown`> |
+
+## Properties[​](#properties "Direct link to Properties")
+
+### data[​](#data "Direct link to data")
+
+```ts
+data: T;
+
+```
+
+***
+
+### score[​](#score "Direct link to score")
+
+```ts
+score: number;
+
+```

package/docs/api/appkit/TypeAlias.SearchFilters.md

@@ -0,0 +1,6 @@
+# Type Alias: SearchFilters
+
+```ts
+type SearchFilters = Record<string, string | number | boolean | (string | number)[]>;
+
+```

package/docs/api/appkit/Variable.aiSearch.md

@@ -0,0 +1,6 @@
+# Variable: aiSearch
+
+```ts
+const aiSearch: ToPlugin<typeof AiSearchPlugin, IAiSearchConfig, "aiSearch">;
+
+```

package/docs/api/appkit.md

@@ -50,7 +50,9 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials                                                                                                                                                                                                                                                                                                                                                                                                  |
 | [GenerationParams](./docs/api/appkit/Interface.GenerationParams.md)                                   | Optional generation parameters forwarded to the OpenAI-compatible serving request body. Names match the serving API wire keys. Only keys that are set are sent — undefined values are omitted so the endpoint applies its own defaults. Ranges are not validated here; the serving endpoint validates.                                                                                                                                                        |
 | [HostedSupervisorTool](./docs/api/appkit/Interface.HostedSupervisorTool.md)                           | Tagged record returned by every [supervisorTools](./docs/api/appkit/Variable.supervisorTools.md) factory. The `__kind` discriminator lets the agents plugin (and standalone `runAgent`) classify these tools without a structural match against the wire format — keeps the SA wire shape free to evolve and avoids namespace collisions with MCP hosted tools (which use `type: "genie-space"` hyphenated, vs SA's `type: "genie_space"` underscored). |
+| [IAiSearchConfig](./docs/api/appkit/Interface.IAiSearchConfig.md)                                     | Base configuration interface for AppKit plugins                                                                                                                                                                                                                                                                                                                                                                                                               |
 | [IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md)                                             | Configuration for the Jobs plugin.                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| [IndexConfig](./docs/api/appkit/Interface.IndexConfig.md)                                             | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [ITelemetry](./docs/api/appkit/Interface.ITelemetry.md)                                               | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins.                                                                                                                                                                                                                                                                                                                                   |
 | [JobAPI](./docs/api/appkit/Interface.JobAPI.md)                                                       | User-facing API for a single configured job.                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | [JobConfig](./docs/api/appkit/Interface.JobConfig.md)                                                 | Per-job configuration options.                                                                                                                                                                                                                                                                                                                                                                                                                                |
@@ -66,10 +68,14 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [RegisteredAgent](./docs/api/appkit/Interface.RegisteredAgent.md)                                     | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md)                                     | Optional claims for fine-grained Unity Catalog table permissions When specified, the returned token will be scoped to only the requested tables                                                                                                                                                                                                                                                                                                               |
 | [RequestedResource](./docs/api/appkit/Interface.RequestedResource.md)                                 | Resource to request permissions for in Unity Catalog                                                                                                                                                                                                                                                                                                                                                                                                          |
+| [RerankerConfig](./docs/api/appkit/Interface.RerankerConfig.md)                                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md)                                         | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership.                                                                                                                                                                                                                                                                                                                                |
 | [ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md)                             | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements().                                                                                                                                                                                                                                                                                                                           |
 | [RunAgentInput](./docs/api/appkit/Interface.RunAgentInput.md)                                         | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [RunAgentResult](./docs/api/appkit/Interface.RunAgentResult.md)                                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| [SearchRequest](./docs/api/appkit/Interface.SearchRequest.md)                                         | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| [SearchResponse](./docs/api/appkit/Interface.SearchResponse.md)                                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| [SearchResult](./docs/api/appkit/Interface.SearchResult.md)                                           | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [ServingEndpointEntry](./docs/api/appkit/Interface.ServingEndpointEntry.md)                           | Shape of a single registry entry.                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [ServingEndpointRegistry](./docs/api/appkit/Interface.ServingEndpointRegistry.md)                     | Registry interface for serving endpoint type generation. Empty by default — augmented by the Vite type generator's `.d.ts` output via module augmentation. When populated, provides autocomplete for alias names and typed request/response/chunk per endpoint.                                                                                                                                                                                               |
 | [StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md)                     | Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.                                                                                                                                                                                                                                                                                                                                                    |
@@ -111,6 +117,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [ResolvedToolEntry](./docs/api/appkit/TypeAlias.ResolvedToolEntry.md)           | Internal tool-index entry after a tool record has been resolved to a dispatchable form.                                                                                                                                                                                                                                |
 | [ResourceFieldEntry](./docs/api/appkit/TypeAlias.ResourceFieldEntry.md)         | -                                                                                                                                                                                                                                                                                                                      |
 | [ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md)         | Union of all possible permission levels across all resource types.                                                                                                                                                                                                                                                     |
+| [SearchFilters](./docs/api/appkit/TypeAlias.SearchFilters.md)                   | -                                                                                                                                                                                                                                                                                                                      |
 | [ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md)                 | Factory function returned by `AppKit.serving`.                                                                                                                                                                                                                                                                         |
 | [SupervisorTool](./docs/api/appkit/TypeAlias.SupervisorTool.md)                 | Tools supported by the Databricks AI Gateway Responses API. The shapes match the wire format the endpoint expects, so the adapter passes the array straight into the request body.                                                                                                                                     |
 | [ToolRegistry](./docs/api/appkit/TypeAlias.ToolRegistry.md)                     | -                                                                                                                                                                                                                                                                                                                      |
@@ -121,6 +128,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | Variable                                                                                   | Description                                                                                                                                                                                                                                                                                                    |
 | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [agents](./docs/api/appkit/Variable.agents.md)                                       | Plugin factory for the agents plugin. Reads `config/agents/*.md` by default, resolves toolkits/tools from registered plugins, exposes `appkit.agents.*` runtime API and mounts `POST /invocations` and `POST /responses` (aliased non-streaming invoke endpoints) plus `POST /chat` (streaming, HITL-capable). |
+| [aiSearch](./docs/api/appkit/Variable.aiSearch.md)                                   | -                                                                                                                                                                                                                                                                                                              |
 | [READ\_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md)                          | Actions that only read data.                                                                                                                                                                                                                                                                                   |
 | [sql](./docs/api/appkit/Variable.sql.md)                                             | SQL helper namespace                                                                                                                                                                                                                                                                                           |
 | [SUPERVISOR\_EXTENSION\_KEY](./docs/api/appkit/Variable.SUPERVISOR_EXTENSION_KEY.md) | Namespace key under which the adapter reads its hosted-tool payload from [AgentInput.extensions](./docs/api/appkit/Interface.AgentInput.md#extensions). Exported so the agents plugin and standalone `runAgent` (the producers) can write under the same key the adapter reads.                          |

package/docs/development/type-generation.md

@@ -6,7 +6,7 @@ AppKit can automatically generate TypeScript types for your SQL queries, providi
 
 Generate type-safe TypeScript declarations for query keys, parameters, and result rows.
 
-All generated files live in `shared/appkit-types/`, one per concern: `analytics.d.ts` (SQL query types), `serving.d.ts` (model-serving endpoint types), and `metric-views.d.ts`. A single command (and the Vite plugin) produces them all in one pass; see [Metric-view types](#metric-view-types). The `.d.ts` files use [`declare module`](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) to augment existing interfaces, so the types apply globally — you never need to import them. TypeScript auto-discovers them through `"include": ["shared/appkit-types"]` in your tsconfig.
+All generated files live in `shared/appkit-types/`, one per concern: `analytics.d.ts` (SQL query types), `serving.d.ts` (model-serving endpoint types), and `metric-views.ts` — a real source file rather than a `.d.ts` because it also carries a runtime `metricViewsMetadata` constant alongside the augmentation. A single command (and the Vite plugin) produces them all in one pass; see [Metric-view types](#metric-view-types). The files use [`declare module`](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) to augment existing interfaces, so the types apply globally — you never need to import them. TypeScript auto-discovers them through `"include": ["shared/appkit-types"]` in your tsconfig.
 
 ## Vite plugin: `appKitTypesPlugin`[​](#vite-plugin-appkittypesplugin "Direct link to vite-plugin-appkittypesplugin")
 
@@ -86,28 +86,28 @@ npx @databricks/appkit generate-types --wait
 
 #### CI resilience: committed types as fallback[​](#ci-resilience-committed-types-as-fallback "Direct link to CI resilience: committed types as fallback")
 
-In blocking mode (`--wait`), the generator attempts to fetch real types from your warehouse, but delegates to **committed `.d.ts` files** (`shared/appkit-types/analytics.d.ts`, `metric-views.d.ts`) as the fallback when the warehouse is unreachable. These committed files should be part of your repository. On a fresh CI checkout, every build attempts to DESCRIBE against the warehouse; the committed types are used only when that cannot complete.
+In blocking mode (`--wait`), the generator attempts to fetch real types from your warehouse, but delegates to **committed type files** (`shared/appkit-types/analytics.d.ts` and, when Metric Views are configured, `shared/appkit-types/metric-views.ts`) as the fallback when the warehouse is unreachable. These generated files should be part of your repository. On a fresh CI checkout, every build attempts to DESCRIBE against the warehouse; the committed types are used only when that cannot complete.
 
 The generator **never overwrites committed types with degraded (`result: unknown`) types** — it writes real types, or it does not write at all.
 
 A **two-bucket failure taxonomy** determines whether the build crashes or falls back to committed types:
 
 * **Deterministic failures (always crash):** SQL syntax errors in your queries (genuine DESCRIBE failure against a reachable warehouse), HTTP 404 (bad or unknown warehouse ID), HTTP 400 (malformed request). These are developer or configuration errors that committed types must not hide.
-* **Environmental failures (gate on committed types):** Authentication failures (401/403), network unreachability, warehouse unavailability (cold, deleting, or deleted), wait timeout on `RUNNING`, or any unrecognized failure. If committed types exist, the build **keeps them, emits a loud warning to stderr, and succeeds (exit 0)**. If no committed types exist, the build **crashes** with a message instructing you to run `npx @databricks/appkit generate-types --wait` locally (against a reachable warehouse) and commit the `.d.ts` files.
+* **Environmental failures (gate on committed types):** Authentication failures (401/403), network unreachability, warehouse unavailability (cold, deleting, or deleted), wait timeout on `RUNNING`, or any unrecognized failure. If every type file required by the app exists, the build **keeps them, emits a loud warning to stderr, and succeeds (exit 0)**. If a required file is missing, the build **crashes** with a message instructing you to run `npx @databricks/appkit generate-types --wait` locally (against a reachable warehouse) and commit the generated type files.
 
 The loud warning is a single greppable stderr line naming the coarse cause (auth blocked / warehouse unreachable / warehouse unavailable) and the warehouse ID, so CI logs surface that the build fell back to committed types.
 
-**Note:** If your app declares only metric views and no `config/queries/`, the first build still writes an empty `analytics.d.ts`, which counts as "committed types present" for the gate. An environmental failure will then fall back and warn rather than crash, even on a first build — an accepted v1 simplification.
+For a Metric Views app, `metric-views.ts` must already exist before an environmental failure can fall back successfully. Unlike a declaration-only artifact, this file also exports the runtime `metricViewsMetadata` value consumed by the server, so `analytics.d.ts` alone cannot satisfy the gate.
 
 The app template wires this up for you: `postinstall` and `predev` run the non-blocking default, while `prebuild` runs `--wait`.
 
 ## Metric-view types[​](#metric-view-types "Direct link to Metric-view types")
 
-`generate-types` (and the Vite plugin) emit metric-view types **additively** — there is no separate command. When a `config/metric-views/definitions.json` file is present, the same run that generates your query types also DESCRIBEs each declared [UC Metric View](./docs/plugins/analytics.md) and writes `metric-views.d.ts` into `shared/appkit-types/`:
+`generate-types` (and the Vite plugin) emit metric-view types **additively** — there is no separate command. When a `config/metric-views/definitions.json` file is present, the same run that generates your query types also DESCRIBEs each declared [UC Metric View](./docs/plugins/analytics.md) and writes `metric-views.ts` into `shared/appkit-types/`:
 
-* `metric-views.d.ts` — augments the `MetricRegistry` interface so `useMetricView('<key>', …)` is autocompleted and type-checked. Each view's measures, dimensions, and their semantic metadata (SQL type, display name, format, time grains) are encoded at the type level.
+* `metric-views.ts` — augments the `MetricRegistry` interface so `useMetricView('<key>', …)` is autocompleted and type-checked. Each view's measures, dimensions, and their semantic metadata (SQL type, display name, format, time grains) are encoded at the type level. The same file also exports a runtime `metricViewsMetadata` constant carrying that metadata as a value — inject it via `analytics({ metricViewsMetadata })` so the [metric route](./docs/plugins/analytics.md#metric-views) can attach per-column display metadata to its response payload.
 
-If `config/metric-views/definitions.json` is absent the metric path stays dormant (nothing is emitted). When present it follows the **same** warehouse-readiness contract as query types: in the default non-blocking run a view that can't be described yet — a cold warehouse, or a bad/unreachable source — is written with permissive types and a warning, while under `--wait` metric views obey the [two-bucket taxonomy](#ci-resilience-committed-types-as-fallback) (environmental failures gate to committed `metric-views.d.ts` + warn; deterministic failures like malformed definitions crash the build). A malformed `definitions.json` (invalid JSON, or a source that isn't a three-part UC FQN) fails fast in every mode.
+If `config/metric-views/definitions.json` is absent the metric path stays dormant (nothing is emitted). When present it follows the **same** warehouse-readiness contract as query types: in the default non-blocking run a view that can't be described yet — a cold warehouse, or a bad/unreachable source — is written with permissive types and a warning, while under `--wait` metric views obey the [two-bucket taxonomy](#ci-resilience-committed-types-as-fallback) (environmental failures gate to committed `metric-views.ts` + warn; deterministic failures like malformed definitions crash the build). A malformed `definitions.json` (invalid JSON, or a source that isn't a three-part UC FQN) fails fast in every mode.
 
 `definitions.json` is keyed by metric key; each entry names the three-part UC FQN of the view and, optionally, the executor it runs as (`app_service_principal`, the default, or `user`):
 

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.