---
title: "Typesense"
description: "Use Typesense for MainSDK search - self-hosted or cloud, API key, main.yaml, results scoped to the searcher, testing and swapping."
section: "integrations"
canonical: "https://mainsdk.dev/docs/integrations/typesense"
updated: "2026-10-28"
---

# Typesense

> Use Typesense for MainSDK search - self-hosted or cloud, API key, main.yaml, results scoped to the searcher, testing and swapping.

Canonical: https://mainsdk.dev/docs/integrations/typesense · Updated: 2026-10-28

Typesense is an open-source search engine, self-hosted or on Typesense Cloud, and the driver in the [`search`](https://mainsdk.dev/docs/interfaces/search) examples. MainSDK limits every result to what the person searching may see. Pick it for fast, typo-tolerant search you can run in your own region.

> **Note:** `search` has no spec yet. The calls and options on this page are provisional and may change when the spec lands.

## Interfaces it serves

### Search (`search`)

- Status: Building for 0.4 · ships as a beta API
- Driver: `typesense` (Typesense)
- Docs: https://mainsdk.dev/docs/interfaces/search.md

```yaml
search:
  driver: typesense
```

Swap to another provider: `db`, `meilisearch`, `local`, `algolia`, `pgvector`.

## Before you start

1. Run Typesense yourself or create a Typesense Cloud cluster, in the region your records belong to.
2. Create an API key for the app scoped to the collections and actions it needs, and store it in your secrets manager.

## Configure

```yaml title="main.yaml"
search:
  driver: typesense
  # key: secret:TYPESENSE_API_KEY   # suggested name; host and collection keys are [TBD]
```

## Use it

```ts title="app/api/search/route.ts"
import { auth, search } from "mainsdk";

export async function GET(req: Request) {
  const session = await auth.require(req);
  const q = new URL(req.url).searchParams.get("q") ?? "";
  return Response.json(await search.query({ q, for: session.user, limit: 10 }));
}
```

## Local development and testing

Run Typesense in a container for development. A `search` fake for `createTestApp()` from `@mainsdk/testing`, and `chaos.on("search", { outage: true })`, arrive with the spec.

## What MainSDK adds on top

- Results scoped to the person searching (`for: user`).
- The same calls on every engine. See [Search and vector search](https://mainsdk.dev/docs/interfaces/search).

## Limits and notes

- `typesense` is a planned `search` driver for phase 2; `search` has no spec yet.
- An index is a copy of your data; keep `personal` and `sensitive` fields out unless needed, and keep the cluster in US, EU or India as your data requires.

## Swap to or from it

```yaml title="main.yaml"
search:
  driver: pgvector   # was typesense
```

> **Warning:** Moving engines means re-indexing your records in the new one.

## FAQ

**Typesense or pgvector?** Both serve `search`. Typesense is a separate engine; pgvector runs inside your Postgres, so there is no second system to operate.

## Next

- [Search and vector search](https://mainsdk.dev/docs/interfaces/search)
- [Meilisearch](https://mainsdk.dev/docs/integrations/meilisearch), [Algolia](https://mainsdk.dev/docs/integrations/algolia) and [Postgres](https://mainsdk.dev/docs/integrations/postgres)