Search adapter

The search adapter is the backend behind app.search, the client search API, and a collection's .searchable() indexing. Wire one adapter into questpie.config.ts and every searchable collection becomes queryable by relevance, full-text and fuzzy matching with the default Postgres adapter, or semantic vector search when you add pgvector and an embedding provider. Swap the adapter; your app.search.search(...) calls and .searchable() config never change.

What it does

• One config line, search everywhere. Set search in questpie.config.ts (or omit it for the default) and you get app.search.search(...) on the server, a search method on the typed client, and per-collection indexing, no extra wiring.
• Lexical by default. The default Postgres adapter does Postgres full-text search (FTS) plus trigram fuzzy matching, with no extra services, just one extension.
• Semantic when you need it. Swap in the pgvector adapter with an embedding provider (OpenAI or your own) to rank by meaning, not just keyword overlap.
• Faceted + filtered. Return facet aggregations (counts, ranges, hierarchies) and filter by collection, locale, or indexed metadata.
• Indexing handled for you. Searchable collections are re-indexed automatically after writes (debounced via the index-records job); you rarely call index() by hand.
• Pluggable. Both built-in adapters implement the SearchAdapter contract, so you can point search at Meilisearch, Elasticsearch, or anything else without touching call sites.

Quick start

The Postgres adapter is the default, if you never set search in your config, you already have lexical search. To configure it explicitly (e.g. to tune scoring), pass it to runtimeConfig:

import { runtimeConfig } from "questpie/app";
import { createPostgresSearchAdapter } from "questpie/adapters/postgres-search";

export default runtimeConfig({
  app: { url: process.env.APP_URL! },
  db: { url: process.env.DATABASE_URL! },
  // Optional, this is what the default already gives you:
  search: createPostgresSearchAdapter(),
});

Then mark which collections are searchable. Collections are indexed by default (title + auto-derived content); pass an object to customize what gets indexed, or false to opt out:

import { collection } from "#questpie/factories";

export const posts = collection("posts")
  .fields(({ f }) => ({
    title: f.text().required(),
    excerpt: f.text(),
    body: f.richText(),
  }))
  .searchable({
    content: (record) => `${record.title}\n${record.excerpt}`,
  });

Run codegen and create the search tables:

questpie generate   # registers the searchable config
questpie push       # creates questpie_search + questpie_search_facets

Now query it, from the server or the client:

// Server (inside a route, job, or service):
const { results, total, facets } = await app.search.search({
  query: "release notes",
  collections: ["posts"],
});

// Client (typed):
const { docs, total } = await client.search.search({ query: "release notes" });

Example → real output

app.search.search(...) returns a SearchResponse: scored results, a total, and optional facets. Scores are normalized to 0-1 (higher is better), and highlights wrap matches in <mark>:

const res = await app.search.search({
  query: "post",
  collections: ["posts"],
  highlights: true,
});
//   ^? SearchResponse
// {
//   results: [
//     {
//       id: "…",                  // search-index row id
//       collection: "posts",
//       recordId: "01H…",         // the source row id
//       score: 0.87,              // normalized relevance 0-1
//       title: "First post",
//       content: "First post\nthe excerpt",
//       highlights: { title: "First <mark>post</mark>" },
//       metadata: {},
//       locale: "en",
//       updatedAt: Date,
//     },
//   ],
//   total: 1,
//   facets: undefined,
// }

The client search returns the same data hydrated into full records (so you get the live row, not just the index snapshot): { docs, total, facets? }, where each doc is your collection row plus a _collection name and a _search block (score, highlights, indexedTitle, indexedContent).

Search options

Both app.search.search(...) and client.search.search(...) take the same SearchOptions:

filters matches the metadata you index per collection. For example, with .searchable({ metadata: (r) => ({ status: r.status }) }):

await app.search.search({
  query: "guide",
  filters: { status: ["published", "featured"] }, // status IN (...)
});

Configuring the index: .searchable()

.searchable() on a collection is the single source of truth for what gets indexed, the title, content, metadata, and facets you pass are taught in full on Collections → Searchable. This page only covers the two keys that are search-adapter-specific: embeddings (override the vector the pgvector adapter generates) and manual.

SearchableConfig is { disabled?, title?, content?, embeddings?, metadata?, facets?, manual? }. manual: true means the collection is searchable but you index it yourself, no automatic re-index on write (see Indexing).

Facets

A facet returns counts (or ranges) for an indexed metadata field. Declare facet fields on the collection, then request them per query.

collection("products").searchable({
  metadata: (r) => ({ category: r.category, price: r.price, tags: r.tags }),
  facets: {
    category: true,                                       // distinct values + counts
    tags: { type: "array" },                              // facet over array values
    price: { type: "range", buckets: [                    // bucketed numeric ranges
      { label: "Under $10", max: 10 },
      { label: "$10-50", min: 10, max: 50 },
    ] },
    path: { type: "hierarchy", separator: "/" },          // hierarchical paths
  },
});

const { facets } = await app.search.search({
  query: "shoes",
  facets: [{ field: "category", limit: 10, sortBy: "count" }],
});
// facets: [{ field: "category", values: [{ value: "sneakers", count: 12 }, …] }]

A FacetFieldConfig is true | { type: "array" } | { type: "range"; buckets } | { type: "hierarchy"; separator? }. A per-query FacetDefinition is { field, limit? (10), sortBy? ("count" | "alpha") }. Facet keys should match your metadata field names.

Search modes

mode picks the ranking strategy. What each mode does depends on the adapter's capabilities:

The Postgres adapter's hybrid score combines the FTS rank (ts_rank_cd) with a trigram similarity(title, query) so typos and partial words still match; the trigram term lives in hybrid, not lexical. The pgvector adapter forwards every non-semantic mode to the base adapter unchanged, so its lexical and hybrid behave exactly like the Postgres adapter's.

The Postgres adapter (default)

createPostgresSearchAdapter(options?) is the default adapter. It uses Postgres' built-in FTS plus the pg_trgm extension for fuzzy matching, no external service.

import { createPostgresSearchAdapter } from "questpie/adapters/postgres-search";

createPostgresSearchAdapter({
  trigramThreshold: 0.3, // similarity cutoff for trigram matching (0-1)
  ftsWeight: 0.7,        // weight of FTS in hybrid score; trigram weight = 1 − this
});

Its capabilities are { lexical: true, trigram: true, semantic: false, hybrid: true, facets: true }. FTS uses to_tsvector('simple', …), a language-agnostic config with no stemming (so "run" won't match "running"; trigram matching softens this for typos and prefixes). The index lives in two tables, questpie_search and questpie_search_facets, which QUESTPIE creates through Drizzle from the adapter's getTableSchemas().

The pgvector adapter (semantic search)

createPgVectorSearchAdapter(options) adds semantic, embedding-based search on top of the Postgres adapter. It composes the Postgres adapter for lexical matching and adds a vector column plus a cosine-distance search path. It requires an embedding provider.

import { createOpenAIEmbeddingProvider } from "questpie/search";
import { createPgVectorSearchAdapter } from "questpie/adapters/pgvector-search";

export default runtimeConfig({
  app: { url: process.env.APP_URL! },
  db: { url: process.env.DATABASE_URL! },
  search: createPgVectorSearchAdapter({
    embeddingProvider: createOpenAIEmbeddingProvider({
      apiKey: process.env.OPENAI_API_KEY!,
    }),
    lexicalWeight: 0.4,   // hybrid weights (reserved for the fused re-rank)
    semanticWeight: 0.6,
    indexType: "ivfflat", // or "hnsw"
  }),
});

Its capabilities are { lexical: true, trigram, semantic: true, hybrid: true, facets: true }. On index(), it generates an embedding from the title + content (or uses one returned by your .searchable({ embeddings }) override) and stores it in the embedding vector(N) column, where N is the provider's dimension count. Semantic search excludes rows whose embedding is still NULL.

Embedding providers

A provider implements EmbeddingProvider, { name, model, dimensions, generate(text), generateBatch?(texts) }. QUESTPIE ships two factories from questpie (also questpie/search):

OpenAI, createOpenAIEmbeddingProvider(options):

import { createOpenAIEmbeddingProvider } from "questpie/search";

createOpenAIEmbeddingProvider({
  apiKey: process.env.OPENAI_API_KEY!, // required
  model: "text-embedding-3-small",     // default
  dimensions: 1536,                    // default
  baseUrl: "https://api.openai.com/v1", // default, point at OpenAI-compatible proxies
});

Custom / local, createCustomEmbeddingProvider(options) wraps any embedding service (a local model, a different API). Provide generate; generateBatch is optional and falls back to Promise.all of generate:

import { createCustomEmbeddingProvider } from "questpie/search";

createCustomEmbeddingProvider({
  name: "local",
  model: "all-MiniLM-L6-v2",
  dimensions: 384,
  generate: async (text) => myLocalModel.embed(text),
});

Required Postgres extensions

QUESTPIE is drizzle-native and does not auto-create Postgres extensions, the search adapters declare the CREATE EXTENSION statements, but you must ensure the extension exists before db:push / migrations run the index DDL.

How to provide them:

• Local dev (starters): create-questpie projects mount an init script into the Postgres container, so docker compose up runs CREATE EXTENSION IF NOT EXISTS "pg_trgm"; on first cluster init, db:push works out of the box. For pgvector, add CREATE EXTENSION IF NOT EXISTS "vector"; to that script (docker/init-extensions.sql) and use a Postgres image that bundles pgvector.
• Managed Postgres: enable the extension through your provider (most expose pg_trgm and pgvector as one-click or CREATE EXTENSION in a console).

Indexing

You almost never index by hand. Searchable collections are re-indexed automatically after a write: the search service batches changed records over a 100 ms debounce window and dispatches the core index-records job (when a queue adapter is configured), falling back to synchronous indexing otherwise.

When you do need manual control, app.search exposes the service surface:

await app.search.index({ collection: "posts", recordId, locale: "en", title, content });
await app.search.indexBatch([...params]);          // upsert many
await app.search.remove({ collection: "posts", recordId }); // omit locale → all locales
await app.search.clear();                          // wipe the whole index

Extending: custom search adapters

The search slot accepts any SearchAdapter, so you can back search with Meilisearch, Elasticsearch, Typesense, or a hosted service without changing a single call site. The contract is:

interface SearchAdapter {
  readonly name: string;
  readonly capabilities: AdapterCapabilities; // { lexical, trigram, semantic, hybrid, facets }
  initialize(ctx: AdapterInitContext): Promise<void>;
  getMigrations(): AdapterMigration[];
  search(opts: SearchOptions): Promise<SearchResponse>;
  index(params: IndexParams): Promise<void>;
  indexBatch?(params: IndexParams[]): Promise<void>;
  remove(params: RemoveParams): Promise<void>;
  reindex(collection: string): Promise<void>;
  clear(): Promise<void>;
  getTableSchemas?(): Record<string, any>; // local adapters only, drives Drizzle migrations
}

initialize() must not create tables, return Drizzle table objects from getTableSchemas() (local backends) so migrations own the DDL, or return undefined (external backends). app.search.search(...) and .searchable() work unchanged regardless of which adapter is wired. This is the QUESTPIE principle: the framework, modules, and your own code all reach the same search slot through one contract, there is no privileged internal search API.

TypeScript

The search types are exported from questpie/search (and questpie):

import type {
  SearchAdapter,
  SearchOptions,
  SearchResponse,
  SearchResult,
  SearchableConfig,
  EmbeddingProvider,
  FacetDefinition,
} from "questpie/search";

Adapter and provider factories and their option types come from their own entry points: createPostgresSearchAdapter / PostgresSearchAdapterOptions from questpie/adapters/postgres-search, createPgVectorSearchAdapter / PgVectorSearchAdapterOptions from questpie/adapters/pgvector-search, and the embedding providers from questpie/search.

Related

• Collections → Searchable, the .searchable() config that controls what each collection indexes.
• Configuration, the runtimeConfig / questpie.config.ts pattern that wires the search adapter.
• Access control, how search results respect row-level access rules, and how reindexAccess gates the reindex route.
• Jobs, the index-records job behind automatic re-indexing.
• Typed client SDK, calling client.search.search(...) from the frontend.