@databricks/appkit 0.23.0 → 0.25.0

package/docs/plugins/vector-search.md

@@ -0,0 +1,247 @@
+# Vector Search plugin
+
+Query Databricks Vector Search indexes with hybrid search, reranking, and cursor pagination from your AppKit application.
+
+**Key features:**
+
+* Named index aliases for multiple Vector Search indexes
+* Hybrid, ANN, and full-text query modes
+* Optional reranking with column-level control
+* Cursor-based pagination for large result sets
+* Service principal (default) and on-behalf-of-user auth
+* Self-managed embedding indexes via custom `embeddingFn`
+
+## Basic usage[​](#basic-usage "Direct link to Basic usage")
+
+```ts
+import { createApp, vectorSearch, server } from "@databricks/appkit";
+
+await createApp({
+  plugins: [
+    server(),
+    vectorSearch({
+      indexes: {
+        products: {
+          indexName: "catalog.schema.products_idx",
+          columns: ["id", "name", "description"],
+          queryType: "hybrid",
+          numResults: 20,
+        },
+      },
+    }),
+  ],
+});
+
+```
+
+## Configuration options[​](#configuration-options "Direct link to Configuration options")
+
+| Option    | Type                          | Default | Description                                              |
+| --------- | ----------------------------- | ------- | -------------------------------------------------------- |
+| `indexes` | `Record<string, IndexConfig>` | —       | **Required.** Map of alias names to index configurations |
+| `timeout` | `number`                      | `30000` | Query timeout in ms                                      |
+
+### Index aliases[​](#index-aliases "Direct link to Index aliases")
+
+Index aliases let you reference multiple Vector Search indexes by name. The alias is used in API routes and programmatic calls:
+
+```ts
+vectorSearch({
+  indexes: {
+    products: {
+      indexName: "catalog.schema.products_idx",
+      columns: ["id", "name", "description"],
+    },
+    docs: {
+      indexName: "catalog.schema.docs_idx",
+      columns: ["id", "title", "content", "url"],
+      queryType: "full_text",
+    },
+  },
+});
+
+```
+
+## 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                    |
+
+### Query types[​](#query-types "Direct link to Query types")
+
+* **`hybrid`** — Combines vector similarity and keyword search. Best for general-purpose retrieval.
+* **`ann`** — Approximate nearest neighbor search using embeddings only. Best for semantic similarity.
+* **`full_text`** — Keyword-based search with no embedding required.
+
+### Reranking[​](#reranking "Direct link to Reranking")
+
+Reranking improves result relevance by running a second-stage model over the initial candidates:
+
+```ts
+vectorSearch({
+  indexes: {
+    products: {
+      indexName: "catalog.schema.products_idx",
+      columns: ["id", "name", "description", "category"],
+      reranker: { columnsToRerank: ["name", "description"] },
+    },
+  },
+});
+
+```
+
+Pass `reranker: true` to rerank across all returned columns.
+
+### On-behalf-of-user auth[​](#on-behalf-of-user-auth "Direct link to On-behalf-of-user auth")
+
+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({
+  indexes: {
+    documents: {
+      indexName: "catalog.schema.documents_idx",
+      columns: ["id", "title", "body"],
+      auth: "on-behalf-of-user",
+    },
+  },
+});
+
+```
+
+### Pagination[​](#pagination "Direct link to Pagination")
+
+Enable cursor pagination to page through large result sets:
+
+```ts
+vectorSearch({
+  indexes: {
+    products: {
+      indexName: "catalog.schema.products_idx",
+      columns: ["id", "name", "description"],
+      pagination: true,
+      endpointName: "my-vector-search-endpoint",
+    },
+  },
+});
+
+```
+
+`endpointName` is required when `pagination` is `true`. Use the `/:alias/next-page` route to fetch subsequent pages.
+
+### Self-managed embedding indexes[​](#self-managed-embedding-indexes "Direct link to Self-managed embedding indexes")
+
+For indexes that manage their own embeddings, provide an `embeddingFn` that takes a query string and returns a vector:
+
+```ts
+import { embed } from "./my-embedding-client";
+
+vectorSearch({
+  indexes: {
+    products: {
+      indexName: "catalog.schema.products_idx",
+      columns: ["id", "name", "description"],
+      queryType: "ann",
+      embeddingFn: (text) => embed(text),
+    },
+  },
+});
+
+```
+
+## HTTP routes[​](#http-routes "Direct link to HTTP routes")
+
+Routes are mounted at `/api/vector-search`.
+
+| Method | Path                | Description                                                  |
+| ------ | ------------------- | ------------------------------------------------------------ |
+| `POST` | `/:alias/query`     | Query an index by alias                                      |
+| `POST` | `/:alias/next-page` | Fetch the next page of results (requires `pagination: true`) |
+| `GET`  | `/:alias/config`    | Return the resolved config for an index alias                |
+
+### Query an index[​](#query-an-index "Direct link to Query an index")
+
+```text
+POST /api/vector-search/:alias/query
+Content-Type: application/json
+
+{
+  "queryText": "machine learning guide",
+  "numResults": 10
+}
+
+```
+
+Response:
+
+```json
+{
+  "results": [
+    { "id": "42", "name": "Intro to ML", "description": "..." }
+  ],
+  "nextPageToken": "eyJvZmZzZXQiOjEwfQ=="
+}
+
+```
+
+`nextPageToken` is only present when `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
+Content-Type: application/json
+
+{
+  "queryText": "machine learning guide",
+  "pageToken": "eyJvZmZzZXQiOjEwfQ=="
+}
+
+```
+
+### Get index config[​](#get-index-config "Direct link to Get index config")
+
+```text
+GET /api/vector-search/:alias/config
+
+```
+
+Returns the resolved `IndexConfig` for the alias (excluding `embeddingFn`).
+
+## Programmatic access[​](#programmatic-access "Direct link to Programmatic access")
+
+The plugin exposes a `query` method for server-side use:
+
+```ts
+const AppKit = await createApp({
+  plugins: [
+    server(),
+    vectorSearch({
+      indexes: {
+        products: {
+          indexName: "catalog.schema.products_idx",
+          columns: ["id", "name", "description"],
+        },
+      },
+    }),
+  ],
+});
+
+const result = await AppKit.vectorSearch.query("products", {
+  queryText: "machine learning guide",
+});
+
+console.log(result.results);
+
+```
+
+Pass optional overrides as a second argument to `query` to adjust `numResults` or other per-call settings.

package/llms.txt

@@ -49,9 +49,10 @@ npx @databricks/appkit docs <query>
 - [Files plugin](./docs/plugins/files.md): File operations against Databricks Unity Catalog Volumes. Supports listing, reading, downloading, uploading, deleting, and previewing files with built-in caching, retry, and timeout handling via the execution interceptor pipeline.
 - [Genie plugin](./docs/plugins/genie.md): Integrates Databricks AI/BI Genie spaces into your AppKit application, enabling natural language data queries via a conversational interface.
 - [Lakebase plugin](./docs/plugins/lakebase.md): Provides a PostgreSQL connection pool for Databricks Lakebase Autoscaling with automatic OAuth token refresh.
+- [Model Serving plugin](./docs/plugins/model-serving.md): Provides an authenticated proxy to Databricks Model Serving endpoints, with invoke and streaming support.
 - [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.
-- [Serving plugin](./docs/plugins/serving.md): Provides an authenticated proxy to Databricks Model Serving endpoints, with invoke and streaming support.
+- [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]
 
@@ -63,6 +64,7 @@ npx @databricks/appkit docs <query>
 - [Class: ExecutionError](./docs/api/appkit/Class.ExecutionError.md): Error thrown when an operation execution fails.
 - [Class: InitializationError](./docs/api/appkit/Class.InitializationError.md): Error thrown when a service or component is not properly initialized.
 - [Abstract Class: Plugin<TConfig>](./docs/api/appkit/Class.Plugin.md): Base abstract class for creating AppKit plugins.
+- [Class: PolicyDeniedError](./docs/api/appkit/Class.PolicyDeniedError.md): Thrown when a policy denies an action.
 - [Class: ResourceRegistry](./docs/api/appkit/Class.ResourceRegistry.md): Central registry for tracking plugin resource requirements.
 - [Class: ServerError](./docs/api/appkit/Class.ServerError.md): Error thrown when server lifecycle operations fail.
 - [Class: TunnelError](./docs/api/appkit/Class.TunnelError.md): Error thrown when remote tunnel operations fail.
@@ -88,6 +90,8 @@ npx @databricks/appkit docs <query>
 - [Interface: CacheConfig](./docs/api/appkit/Interface.CacheConfig.md): Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup.
 - [Interface: DatabaseCredential](./docs/api/appkit/Interface.DatabaseCredential.md): Database credentials with OAuth token for Postgres connection
 - [Interface: EndpointConfig](./docs/api/appkit/Interface.EndpointConfig.md): Properties
+- [Interface: FilePolicyUser](./docs/api/appkit/Interface.FilePolicyUser.md): Minimal user identity passed to the policy function.
+- [Interface: FileResource](./docs/api/appkit/Interface.FileResource.md): Describes the file or directory being acted upon.
 - [Interface: GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md): Request parameters for generating database OAuth credentials
 - [Interface: ITelemetry](./docs/api/appkit/Interface.ITelemetry.md): Plugin-facing interface for OpenTelemetry instrumentation.
 - [Interface: LakebasePoolConfig](./docs/api/appkit/Interface.LakebasePoolConfig.md): Configuration for creating a Lakebase connection pool
@@ -104,12 +108,16 @@ npx @databricks/appkit docs <query>
 - [Interface: ValidationResult](./docs/api/appkit/Interface.ValidationResult.md): Result of validating all registered resources against the environment.
 - [Type Alias: ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md): Configuration schema definition for plugin config.
 - [Type Alias: ExecutionResult<T>](./docs/api/appkit/TypeAlias.ExecutionResult.md): Discriminated union for plugin execution results.
+- [Type Alias: FileAction](./docs/api/appkit/TypeAlias.FileAction.md): Every action the files plugin can perform.
+- [Type Alias: FilePolicy()](./docs/api/appkit/TypeAlias.FilePolicy.md): A policy function that decides whether user may perform action on
 - [Type Alias: IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md): Express router type for plugin route registration
 - [Type Alias: PluginData<T, U, N>](./docs/api/appkit/TypeAlias.PluginData.md): Tuple of plugin class, config, and name. Created by toPlugin() and passed to createApp().
 - [Type Alias: ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md): Union of all possible permission levels across all resource types.
 - [Type Alias: ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md): Factory function returned by AppKit.serving.
 - [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: 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: WRITE_ACTIONS](./docs/api/appkit/Variable.WRITE_ACTIONS.md): Actions that mutate data.
 
 ## appkit-ui API reference [collapsed]
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit",
   "type": "module",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "packageManager": "pnpm@10.21.0",