Create a simple search engine

Last updated Aug 25, 2026 This guide builds a search engine that returns the file names matching a query, using the search() method on the Workers binding. You can adapt it to use the REST API instead.

For the best results with this pattern:

  • Disable query rewriting so the original user query is matched directly.
  • Configure your AI Search instance with small chunk sizes (256 tokens is usually enough).

Prerequisites

  1. Sign up for a Cloudflare account ↗︎.
  2. Install Node.js ↗︎.

<details>

<summary>

Node.js version manager

</summary>

Use <a href="https://viteplus.dev/guide/env">Vite+ (<code>vp env</code>) ↗︎</a> to install and manage Node.js versions.

For supported Node.js versions, refer to the <a href="https://developers.cloudflare.com/workers/wrangler/install-and-update/#install-wrangler">Wrangler system requirements</a>.

</details>

You also need an AI Search instance that already contains indexed content. To create one and add content, refer to Get started.

1. Create a Worker project

Create a new Worker project using the create-cloudflare CLI (C3). C3 ↗︎ is a command-line tool designed to help you set up and deploy new applications to Cloudflare.

Create a new project named search-engine by running:

npmyarnpnpm

npm create cloudflare@latest -- search-engine

yarn create cloudflare search-engine

pnpm create cloudflare@latest search-engine

For setup, select the following options:

  • For What would you like to start with?, choose Hello World example.
  • For Which template would you like to use?, choose Worker only.
  • For Which language do you want to use?, choose TypeScript.
  • For Do you want to use git for version control?, choose Yes.
  • For Do you want to add an AGENTS.md file to help AI coding tools understand Cloudflare APIs?, choose Yes.
  • For Do you want to deploy your application?, choose No (we will be making some changes before deploying).

Go to your application directory:

cd search-engine

Add the following to your Wrangler configuration file:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "ai_search_namespaces": [
    {
      "binding": "AI_SEARCH",
      "namespace": "default",
      "remote": true
    }
  ]
}

[[ai_search_namespaces]]
binding = "AI_SEARCH"
namespace = "default"
remote = true

This binds the default namespace to env.AI_SEARCH. The remote option lets wrangler dev proxy requests to your deployed instance, since AI Search does not run locally.

3. Add the search code

Update src/index.ts. This Worker reads a query from the URL, searches your instance, and returns the file name of each matching chunk. Replace my-instance with the name of your instance.

src/index.jsjs

export default {
    async fetch(request, env) {
        const url = new URL(request.url);
        const userQuery = url.searchParams.get("query") ?? "What is Cloudflare?";

        const searchResult = await env.AI_SEARCH.get("my-instance").search({
            messages: [{ role: "user", content: userQuery }],
        });

        return Response.json({
            files: searchResult.chunks.map((chunk) => chunk.item.key),
        });
    },
};

src/index.tsts

export interface Env {
    AI_SEARCH: AiSearchNamespace;
}

export default {
    async fetch(request, env): Promise<Response> {
        const url = new URL(request.url);
        const userQuery = url.searchParams.get("query") ?? "What is Cloudflare?";

        const searchResult = await env.AI_SEARCH.get("my-instance").search({
            messages: [{ role: "user", content: userQuery }],
        });

        return Response.json({
            files: searchResult.chunks.map((chunk) => chunk.item.key),
        });
    },
} satisfies ExportedHandler<Env>;

4. Run and deploy

Start a local development server, then query it at /?query=your+search+terms:

npx wrangler dev

Log in with your Cloudflare account, then deploy your Worker to make it accessible on the Internet:

npx wrangler login
npx wrangler deploy

Next steps

Search Workers binding

Full reference for searching and chatting from a Worker.

Query rewriting

Control whether AI Search rewrites the query before searching.

Was this helpful?

YesNo

On this page

Create a simple search engine - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/ai-search/how-to/simple-search-engine/#page","headline":"Create a simple search engine","description":"Build a simple search engine using the AI Search Workers binding and the search method.","url":"https://developers.cloudflare.com/ai-search/how-to/simple-search-engine/","inLanguage":"en","image":"https://developers.cloudflare.com/ai-search/how-to/simple-search-engine/og.png?v=86a208213155f237","dateModified":"2026-08-25","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Build a voice agent that lets users speak to an AI Search knowledge base and hear spoken answers, using the Cloudflare Agents voice pipeline. title: Talk to your knowledge base image: https://developers.cloudflare.com/ai-search/how-to/talk-to-your-knowledge-base/og.png?v=14abd7712498fb20

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/ai-search/llms.txt
Use this file to discover all available pages before exploring further.