AiSearchNamespace

Source: src/Cloudflare/AiSearch/AiSearchNamespace.ts

A Cloudflare AI Search namespace — a logical grouping for AI Search instances within an account.

Namespaces partition AI Search (formerly AutoRAG) instances: each namespace owns its own set of namespace-scoped instances and can be searched or queried as a unit. The namespace name is its identity — changing it triggers a replacement; only the description is mutable in place.

The account-provided default namespace is reserved: it always exists and Cloudflare disallows modifying or deleting it. Alchemy adopts it so it can be referenced and bound, but never updates or tears it down.

Creating a Namespace

Generated name

const ns = yield* Cloudflare.AiSearchNamespace("docs", {});

Explicit name and description

const ns = yield* Cloudflare.AiSearchNamespace("docs", {
  name: "docs-search",
  description: "Search over the product documentation",
});

Updating a Namespace

Only the description is mutable; changing name replaces the namespace.

const ns = yield* Cloudflare.AiSearchNamespace("docs", {
  name: "docs-search",
  description: "Search over docs and changelogs",
});

Grouping pipelines

Group {@link AiSearch} pipelines under the namespace by passing the namespace resource itself to each pipeline’s namespace prop. The engine orders each pipeline after the namespace on deploy and tears them down before it on destroy.

const ns = yield* Cloudflare.AiSearchNamespace("docs", {});
const guides = yield* Cloudflare.AiSearch("guides", {
  source: guidesBucket,
  namespace: ns,
});
const api = yield* Cloudflare.AiSearch("api", {
  source: apiBucket,
  namespace: ns,
});

Binding to an Effect Worker

Bind the namespace with Cloudflare.AiSearchNamespace.bind(namespace), which attaches the ai_search_namespace binding and returns a client whose .get(name) selects an instance within the namespace at runtime. Provide {@link AiSearchNamespaceBindingLive} in the Worker’s runtime layer.

import * as Cloudflare from "alchemy/Cloudflare";
import * as Effect from "effect/Effect";
import { HttpServerRequest } from "effect/unstable/http/HttpServerRequest";
import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";

export default class Api extends Cloudflare.Worker<Api>()(
  "api",
  { main: import.meta.filename },
  Effect.gen(function* () {
    const ns = yield* Cloudflare.AiSearchNamespace.bind(Docs);

    return {
      fetch: Effect.gen(function* () {
        const url = new URL((yield* HttpServerRequest).url);
        const instance = url.searchParams.get("instance") ?? "guides";
        const query = url.searchParams.get("q") ?? "";
        const answer = yield* ns.get(instance).chatCompletions({
          messages: [{ role: "user", content: query }],
        });
        return yield* HttpServerResponse.json(answer);
      }),
    };
  }).pipe(Effect.provide(Cloudflare.AiSearchNamespaceBindingLive)),
) {}

Binding to an Async Worker

For a vanilla async fetch Worker, pass the namespace under Worker.env. InferEnv types env.SEARCH as the runtime AiSearchNamespace handle.

export const Api = Cloudflare.Worker("api", {
  main: "./worker.ts",
  env: { SEARCH: namespace },
});
export type ApiEnv = Cloudflare.InferEnv<typeof Api>;

// worker.ts
export default {
  async fetch(request: Request, env: ApiEnv): Promise<Response> {
    const query = new URL(request.url).searchParams.get("q") ?? "";
    return Response.json(
      await env.SEARCH.get("guides").chatCompletions({
        messages: [{ role: "user", content: query }],
      }),
    );
  },
};