Class: SearchPlugin

AppKit extension plugin for agent tools, federated search, and optional Vector Search lifecycle operations. Register aiSearch() or lakebaseAiSearch() before this plugin.

Example

import { createApp, server } from "@databricks/appkit";
import { aiSearch } from "@databricks/appkit/beta";
import { search } from "@dbx-tools/search";

await createApp({
  plugins: [
    server(),
    aiSearch({
      indexes: {
        docs: {
          indexName: "main.support.docs",
          columns: ["id", "title", "body"],
        },
      },
    }),
    search({
      index: "main.support.docs",
      indexes: [{ name: "main.support.docs", alias: "docs" }],
    }),
  ],
});

Extends

ToolRegistryPlugin<SearchPluginConfig>

Constructors

Constructor

new SearchPlugin(config): SearchPlugin

Parameters

config

SearchPluginConfig

Returns

SearchPlugin

Inherited from

ToolRegistryPlugin<SearchPluginConfig>.constructor

Properties

app

protected app: AppManager

Inherited from

ToolRegistryPlugin.app

cache

protected cache: CacheManager

Inherited from

ToolRegistryPlugin.cache

config

protected config: SearchPluginConfig

Inherited from

ToolRegistryPlugin.config

context?

protected optional context?: PluginContext

Inherited from

ToolRegistryPlugin.context

devFileReader

protected devFileReader: DevFileReader

Inherited from

ToolRegistryPlugin.devFileReader

isReady

protected isReady: boolean

Inherited from

ToolRegistryPlugin.isReady

name

name: string

Plugin name identifier.

Inherited from

ToolRegistryPlugin.name

streamManager

protected streamManager: StreamManager

Inherited from

ToolRegistryPlugin.streamManager

telemetry

protected telemetry: ITelemetry

Inherited from

ToolRegistryPlugin.telemetry

manifest

static manifest: object

config

config: object

config.schema

schema: JSONSchema7 = SEARCH_CONFIG_SCHEMA

description

description: string

displayName

displayName: string = "AI Search"

name

name: "search" = "search"

resources

resources: object

resources.optional

optional: never[] = []

resources.required

required: never[] = []

stability

stability: "beta" = "beta"

phase

static phase: PluginPhase

Plugin initialization phase.

‘core’: Initialized first (e.g., config plugins)
‘normal’: Initialized second (most plugins)
‘deferred’: Initialized last (e.g., server plugin)

Inherited from

ToolRegistryPlugin.phase

Accessors

toolRegistry

Get Signature

get protected toolRegistry(): ToolRegistry

The tools this plugin offers to an AppKit agent. search / universal_search are reads; add_documents / create_index / sync_index are only offered when the write surface is enabled. None is autoInheritable: every tool runs under the caller’s identity, so it must be granted explicitly.

Returns

ToolRegistry

Overrides

ToolRegistryPlugin.toolRegistry

Methods

abortActiveOperations()

abortActiveOperations(): void

Returns

void

Overrides

ToolRegistryPlugin.abortActiveOperations

asUser()

asUser(req): this

Execute operations using the user’s identity from the request. Returns a proxy of this plugin where all method calls execute with the user’s Databricks credentials instead of the service principal.

Parameters

req

Request

The Express request containing the user token in headers

Returns

this

A proxied plugin instance that executes as the user

Throws

AuthenticationError if user token is not available in request headers (production only). In development mode (NODE_ENV=development), skips user impersonation instead of throwing.

Inherited from

ToolRegistryPlugin.asUser

attachContext()

attachContext(deps?): void

Binds runtime dependencies (telemetry provider, cache, plugin context) to this plugin. Called by AppKit._createApp after construction and before setup(). Idempotent: safe to call if the constructor already bound them eagerly. Kept separate so factories can eagerly construct plugin instances without running this before TelemetryManager.initialize() / CacheManager.getInstance() have run.

Parameters

deps?

context?

unknown

telemetryConfig?

TelemetryOptions

Returns

void

Inherited from

ToolRegistryPlugin.attachContext

clientConfig()

clientConfig(): Record<string, unknown>

Surface the index catalogue + defaults so a search box needs no round-trip.

Returns

Record<string, unknown>

Overrides

ToolRegistryPlugin.clientConfig

execute()

protected execute<T>(fn, options, userKey?): Promise<ExecutionResult<T>>

Execute a function with the plugin’s interceptor chain.

Returns an ExecutionResult discriminated union:

{ ok: true, data: T } on success
{ ok: false, status: number, message: string } on failure

Errors are never thrown — the method is production-safe.

Type Parameters

T

T

Parameters

fn

(signal?) => Promise<T>

options

PluginExecutionSettings

userKey?

string

Returns

Promise<ExecutionResult<T>>

Inherited from

ToolRegistryPlugin.execute

executeAgentTool()

executeAgentTool(name, args, signal?, _context?): Promise<unknown>

Validate and dispatch one AppKit agent tool call.

Parameters

name

string

args

unknown

signal?

AbortSignal

_context?

AgentToolExecutionContext

Returns

Promise<unknown>

Inherited from

ToolRegistryPlugin.executeAgentTool

executeStream()

protected executeStream<T>(res, fn, options, userKey?): Promise<void>

Type Parameters

T

T

Parameters

res

IAppResponse

fn

StreamExecuteHandler<T>

options

StreamExecutionSettings

userKey?

string

Returns

Promise<void>

Inherited from

ToolRegistryPlugin.executeStream

exports()

exports(): object

Returns the public exports for this plugin. Override this to define a custom public API. By default, returns an empty object.

The returned object becomes the plugin’s public API on the AppKit instance (e.g. appkit.myPlugin.method()). AppKit automatically binds method context and adds asUser(req) for user-scoped execution.

Returns

addDocuments

addDocuments: (request, signal?) => Promise<{ count: number; index: string; }>

Add or update documents in a direct-access index (throws when writes are disabled).

Parameters

request

documents

unknown

index?

string

signal?

AbortSignal

Returns

Promise<{ count: number; index: string; }>

createIndex

createIndex: (request, signal?) => Promise<{ columns: string[]; directAccess?: boolean; endpoint?: string; name: string; primaryKey?: string; ready: boolean; rowCount?: number; }>

Create a Vector Search index (throws when writes are disabled).

Parameters

request

columnsToSync?

string[] = ...

embeddingDimension?

number = ...

embeddingModel?

string = ...

embeddingSourceColumn?

string = ...

endpoint?

string = ...

name

string = ...

pipelineType?

"TRIGGERED" | "CONTINUOUS" = ...

primaryKey?

string = ...

sourceTable?

string = ...

signal?

AbortSignal

Returns

Promise<{ columns: string[]; directAccess?: boolean; endpoint?: string; name: string; primaryKey?: string; ready: boolean; rowCount?: number; }>

search

search: (request, signal?) => Promise<{ count: number; hits: object[]; index?: string; query: string; }>

Search one index (default when omitted). Runs as the current context user.

Parameters

request

columns?

string[] = ...

filter?

Record<string, string | number | boolean | (string | number)[]> = ...

index?

string = ...

limit?

number = ...

mode?

"hybrid" | "vector" | "keyword" = ...

query

string = ...

scoreThreshold?

number = ...

signal?

AbortSignal

Returns

Promise<{ count: number; hits: object[]; index?: string; query: string; }>

syncIndex

syncIndex: (request, signal?) => Promise<{ index: string; synced: boolean; }>

Sync a Delta Sync index from its source table (throws when writes are disabled).

Parameters

request

index?

string = ...

signal?

AbortSignal

Returns

Promise<{ index: string; synced: boolean; }>

universalSearch

universalSearch: (request, signal?) => Promise<{ count: number; hits: object[]; index?: string; query: string; }>

Search across every configured index and merge the hits.

Parameters

request

indexes?

string[] = ...

limit?

number = ...

mode?

"hybrid" | "vector" | "keyword" = ...

query

string = ...

signal?

AbortSignal

Returns

Promise<{ count: number; hits: object[]; index?: string; query: string; }>

Example

class MyPlugin extends Plugin {
  private getData() { return []; }

  exports() {
    return { getData: this.getData };
  }
}

// After registration:
const appkit = await createApp({ plugins: [myPlugin()] });
appkit.myPlugin.getData();

Overrides

ToolRegistryPlugin.exports

getAgentTools()

getAgentTools(): AgentToolDefinition[]

Tool definitions offered to an AppKit agent.

Returns

AgentToolDefinition[]

Inherited from

ToolRegistryPlugin.getAgentTools

getEndpoints()

getEndpoints(): PluginEndpointMap

Returns

PluginEndpointMap

Inherited from

ToolRegistryPlugin.getEndpoints

getSkipBodyParsingPaths()

getSkipBodyParsingPaths(): ReadonlySet<string>

Returns

ReadonlySet<string>

Inherited from

ToolRegistryPlugin.getSkipBodyParsingPaths

injectRoutes()

injectRoutes(router): void

Mount extension routes under /api/search. Single-index queries stay on the provider’s native /api/ai-search/:alias/query surface.

Parameters

router

Router

Returns

void

Overrides

ToolRegistryPlugin.injectRoutes

registerEndpoint()

protected registerEndpoint(name, path): void

Parameters

name

string

path

string

Returns

void

Inherited from

ToolRegistryPlugin.registerEndpoint

resolveUserId()

protected resolveUserId(req): string

Resolve the effective user ID from a request.

Returns the x-forwarded-user header when present. In development mode (NODE_ENV=development) falls back to the current context user ID so that callers outside an active runInUserContext scope still get a consistent value.

Parameters

req

Request

Returns

string

Throws

AuthenticationError in production when no user header is present.

Inherited from

ToolRegistryPlugin.resolveUserId

route()

protected route<_TResponse>(router, config): void

Type Parameters

_TResponse

_TResponse

Parameters

router

Router

config

RouteConfig

Returns

void

Inherited from

ToolRegistryPlugin.route

setup()

setup(): Promise<void>

Attach the registered provider and log the effective policy at boot.

Returns

Promise<void>

Overrides

ToolRegistryPlugin.setup

shutdown()

shutdown(): void

Release this plugin’s instance-owned runtime.

Returns

void