Class AiSearchNamespaceBinding<E>

Accessor for a namespace-scoped AI Search binding.

Remarks

The other half of AI Search, and a genuinely different binding rather than a convenience over AiSearchBinding: ai_search names one instance at deploy time, while ai_search_namespaces opens a namespace and lets a request name the instance. That is what a per-tenant corpus needs, since the set of instances is not known when the Worker is deployed.

Which one to bind follows from that. One corpus, fixed at deploy — the single-instance binding, and a Worker that cannot ask for the wrong one. A corpus per customer, created as customers arrive — this one.

Nothing stops a Worker binding both, and the default names here differ (AI_SEARCH and AI_SEARCH_NAMESPACE) so that it can. Two bindings cannot share a name on one env regardless of what this package defaults to.

Example

const corpora = new AiSearchNamespaceBinding()

const tenant = corpora.instance(env, `tenant-${id}`)
const { chunks } = await tenant.search({ query })

Author

Bayu Dwiyan Satria

Version

1.0.0

Since

1.3.0

Type Parameters

E extends CloudflareEnv = CloudflareEnv

Hierarchy (View Summary)

Binding<AiSearchNamespace, E>
- AiSearchNamespaceBinding

Index

Constructors

constructor

new AiSearchNamespaceBinding<E extends CloudflareEnv = CloudflareEnv>(
settings?: AiSearchNamespaceSettings,
): AiSearchNamespaceBinding<E>
Constructs an AiSearchNamespaceBinding instance.
Type Parameters
- E extends CloudflareEnv = CloudflareEnv
Parameters
- Optionalsettings: AiSearchNamespaceSettings
  Resolved settings. Defaults to resolve('aiSearchNamespace'), so callers normally construct this with no arguments at all.
Returns AiSearchNamespaceBinding<E>
Overrides Binding.constructor
- Defined in src/core/bindings/AiSearchNamespaceBinding.ts:53

Accessors

name

get name(): string
The binding name this instance resolves.

Returns string
The binding name as declared in wrangler.json.
Inherited from Binding.name
- Defined in src/core/bindings/Binding.ts:58

Methods

create

create(env: E, config: AiSearchConfig): Promise<AiSearchInstance>
Creates an instance in the namespace.
Parameters
- env: E
  The Worker environment.
- config: AiSearchConfig
  The instance configuration. Only id is required.
Returns Promise<AiSearchInstance>
A handle to the new instance.

Remarks
Provisioning from the request path is unusual, and it is here because the namespace binding's reason to exist is the case where it is not: a corpus created when a customer signs up cannot be declared in wrangler.json. Passing only id creates one with built-in storage, to upload items into.

Throws
MissingBindingError When the namespace binding is absent.
- Defined in src/core/bindings/AiSearchNamespaceBinding.ts:104

instance

instance(env: E, name: string): AiSearchInstance
Opens one instance within the namespace.
Parameters
- env: E
  The Worker environment.
- name: string
  The instance name within the bound namespace.
Returns AiSearchInstance
The instance handle.

Remarks
Synchronous and local — this names an instance rather than fetching it, so an instance that does not exist fails on the first operation rather than here. The returned handle is the platform's own AiSearchInstance, so search, chatCompletions, items and jobs are all reachable on it without this package standing in the way.

Throws
MissingBindingError When the namespace binding is absent.
- Defined in src/core/bindings/AiSearchNamespaceBinding.ts:74

isBound

isBound(env: E): boolean
Checks whether the binding is available on the given environment.

Use this to degrade gracefully when a binding is optional.
Parameters
- env: E
  The Worker environment.
Returns boolean
true when the binding is present.
Inherited from Binding.isBound
- Defined in src/core/bindings/Binding.ts:74

list

list(
env: E,
params?: AiSearchListInstancesParams,
): Promise<AiSearchListResponse>
Lists the instances in the namespace.
Parameters
- env: E
  The Worker environment.
- Optionalparams: AiSearchListInstancesParams
  Optional pagination, search, and ordering.
Returns Promise<AiSearchListResponse>
The instances and their pagination cursor.

Throws
MissingBindingError When the namespace binding is absent.
- Defined in src/core/bindings/AiSearchNamespaceBinding.ts:86

remove

remove(env: E, name: string): Promise<void>
Deletes an instance from the namespace.
Parameters
- env: E
  The Worker environment.
- name: string
  The instance name to delete.
Returns Promise<void>

Throws
MissingBindingError When the namespace binding is absent.
- Defined in src/core/bindings/AiSearchNamespaceBinding.ts:115

resolve

resolve(env: E): AiSearchNamespace
Resolves the binding, failing fast when it is not configured.
Parameters
- env: E
  The Worker environment.
Returns AiSearchNamespace
The resolved binding.

Throws
MissingBindingError When the binding is absent from the environment.
Inherited from Binding.resolve
- Defined in src/core/bindings/Binding.ts:85

search

search(
env: E,
params: AiSearchMultiSearchRequest,
): Promise<AiSearchMultiSearchResponse>
Searches across several instances at once.
Parameters
- env: E
  The Worker environment.
- params: AiSearchMultiSearchRequest
  The multi-instance search request.
Returns Promise<AiSearchMultiSearchResponse>
Merged chunks, tagged by instance, plus any partial failures.

Remarks
A fan-out, and it reports partial failure rather than hiding it: chunks come back tagged with the instance they came from, and an errors array names the instances that did not answer. A caller that ignores errors is reading a result set that silently lost a corpus.

ai_search_options.instance_ids is required, which is why nothing is defaulted into this request — which instances to search is the question being asked.

Throws
MissingBindingError When the namespace binding is absent.
- Defined in src/core/bindings/AiSearchNamespaceBinding.ts:137

tryResolve

tryResolve(env: E): AiSearchNamespace
Resolves the binding without throwing.
Parameters
- env: E
  The Worker environment.
Returns AiSearchNamespace
The resolved binding, or null when it is not configured.
Inherited from Binding.tryResolve
- Defined in src/core/bindings/Binding.ts:101

Class AiSearchNamespaceBinding<E>

Remarks

Example

Author

Version

Since

Type Parameters

Hierarchy (View Summary)

Index

Constructors

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns AiSearchNamespaceBinding<E>

Accessors

name

Returns string

Methods

create

Parameters

Returns Promise<AiSearchInstance>

Remarks

Throws

instance

Parameters

Returns AiSearchInstance

Remarks

Throws

isBound

Parameters

Returns boolean

list

Parameters

Returns Promise<AiSearchListResponse>

Throws

remove

Parameters

Returns Promise<void>

Throws

resolve

Parameters

Returns AiSearchNamespace

Throws

search

Parameters

Returns Promise<AiSearchMultiSearchResponse>

Remarks

Throws

tryResolve

Parameters

Returns AiSearchNamespace

Settings

On This Page