--- title: "Search" description: "Index and query searchable Beignet read models through SearchPort, memory tests, and Meilisearch providers." url: "https://www.beignetjs.com/search" markdown_url: "https://www.beignetjs.com/markdown/search.md" framework_version: "0.0.65" documentation_scope: "current-checkout" source_revision: "ba3f49c103f3c4515e8ca14e07651fe5b83e2cec" source_modified: true --- # Search Use `SearchPort` when application code needs to index and query searchable read models without depending on a specific search service. Search indexes are application read models. Keep writes, authorization, and business invariants in your database and use search for discovery, filtering, sorting, facets, and ranking. ## Define an index Define index metadata near the feature that owns the searchable document: ```typescript // features/issues/search.ts import { defineSearchIndex } from "@beignet/core/search"; export type IssueSearchDocument = { id: string; tenantId: string; key: string; title: string; status: "open" | "resolved"; createdAt: string; }; export const issueSearchIndex = defineSearchIndex( "issues", { searchableAttributes: ["key", "title"], filterableAttributes: ["tenantId", "status"], sortableAttributes: ["createdAt"], displayedAttributes: ["id", "key", "title", "status"], }, ); ``` ## Index documents Use cases, listeners, jobs, and tasks can index documents through the same port: ```typescript import { waitForSearchOperation } from "@beignet/core/search"; await waitForSearchOperation( ctx.ports.search, await ctx.ports.search.configureIndex(issueSearchIndex), ); const operation = await ctx.ports.search.indexDocuments(issueSearchIndex, { id: issue.id, tenantId: issue.tenantId, key: issue.key, title: issue.title, status: issue.status, createdAt: issue.createdAt, }); ``` All writes, deletions, clears, and index configuration return a `SearchOperationResult`. Memory search returns `{ status: "completed", affected }` (`affected` is omitted for configuration). Meilisearch returns `{ status: "accepted", taskIds }`: acceptance does not prove indexing succeeded. For durable indexing, use outbox-backed jobs or listeners after the database commit. In workers and backfills, explicitly wait before reporting success: ```typescript import { waitForSearchOperation } from "@beignet/core/search"; const search = ctx.ports.search; await waitForSearchOperation(search, await search.configureIndex(issueSearchIndex)); const operation = await search.indexDocuments( issueSearchIndex, issues.map(issueToSearchDocument), ); const completed = await waitForSearchOperation(search, operation, { timeoutMs: 10_000, pollIntervalMs: 100, }); // completed.affected is the actual count when the provider reports one. ``` `waitForSearchOperation` defaults to a 5-second overall timeout and 50 ms polling. The deadline includes status requests. Both timing options must be integers between 1 and 2,147,483,647 ms. Pass `signal` to stop waiting when a worker stops. Failed or canceled tasks throw `SearchOperationError` with the task and provider error. Timeout throws `SearchOperationTimeoutError` with the original operation; it stops waiting but does not cancel remote work. Persist receipts for later checks, or let a retryable job reindex current database state. Status-request errors also propagate to the caller. For nonblocking flows, inspect each `operation.taskIds` entry after narrowing `operation.status === "accepted"` with `search.getTask(id, { signal })`. Tasks expose `pending`, `succeeded`, `failed`, or `canceled` status and optional `affected`/`error` details. These are provider task IDs, separate from Beignet's application [tasks](https://www.beignetjs.com/markdown/tasks.md). Synchronous memory search has no task IDs. Meilisearch configuration retains both creation and settings tasks; an `index_already_exists` creation result is treated as success for repeat setup. Configuration replaces the four attribute lists: omitted searchable/displayed lists reset to all fields, and omitted filterable/sortable lists reset to empty. ## Query documents ```typescript const results = await ctx.ports.search.search(issueSearchIndex, { query: "billing", filters: { tenantId, status: "open", }, sort: ["createdAt:desc"], facets: ["status"], limit: 20, offset: 0, }); ``` `filters` are provider-neutral exact-match filters. Providers translate them to their native query language. Keep user authorization in use cases and policies; include tenant or visibility filters when the index contains multi-tenant data. Both memory and Meilisearch accept filters and facets only for fields declared in `filterableAttributes`, and sort entries only for fields declared in `sortableAttributes`. Map request input to app-owned allow-listed field names before calling `ctx.ports.search.search(...)`. Non-2xx Meilisearch responses throw `MeilisearchHttpError` with the request path, status, and response body. The adapter preserves plain-text or HTML responses from proxies and gateways, so an upstream outage does not turn into an unrelated JSON parse error. ## Handle projected hits Indexing still requires the full document type. Search results contain `SearchHit` values: fields, including nested fields, are optional. `displayedAttributes` can hide fields, and previously indexed documents may predate the current shape. Both adapters apply the projection; `[]` returns empty objects and an omitted list returns all stored fields. Filtering, sorting, and facets still operate on indexed fields, including fields hidden from hits. Dotted selections omit scalar ancestors and array entries that cannot reach the selected field. Undefined properties are omitted. Selecting a field directly still preserves its scalar value, null, or empty container. Displayed attributes are not an authorization boundary: facets can expose hidden values, and all tenant/visibility restrictions remain app-owned. Validate hits against a result DTO before exposing required properties: ```typescript import { z } from "zod"; const hitSchema = z.object({ id: z.string(), key: z.string(), title: z.string(), status: z.enum(["open", "resolved"]), }); const hits = results.hits.flatMap((hit) => { const parsed = hitSchema.safeParse(hit); return parsed.success ? [parsed.data] : []; }); ``` This example drops stale hits. Apps can instead fail explicitly and trigger a backfill. Search pagination totals count matching indexed documents before any app-level validation drops hits. ## Setup with Meilisearch Install the Meilisearch search provider: ```bash bun add @beignet/provider-search-meilisearch ``` Register it in `server/providers.ts`: ```typescript import { createMeilisearchSearchProvider } from "@beignet/provider-search-meilisearch"; export const providers = [ createMeilisearchSearchProvider({ indexPrefix: "my-app", }), ]; ``` Set `MEILISEARCH_HOST` in production. Optional env vars include `MEILISEARCH_API_KEY`, `MEILISEARCH_INDEX_PREFIX`, and `MEILISEARCH_TIMEOUT_MS`. The timeout must be an integer from 1 through 2,147,483,647 milliseconds, the JavaScript timer range. Search instrumentation records the index, result count, and query length; it does not record query text or document bodies. The provider contributes `ctx.ports.search` and `ctx.ports.meilisearch` as an escape hatch with the raw client and configured index prefix. ## Testing `createTestPorts(...)` includes an in-memory search port by default: ```typescript const { ports, search } = createTestPorts(); await ports.search.indexDocuments(issueSearchIndex, issueDocument); await expect( search.search(issueSearchIndex, { query: "billing", filters: { tenantId: "tenant_example" }, }), ).resolves.toMatchObject({ hits: [{ id: issueDocument.id, key: issueDocument.key, title: issueDocument.title, status: issueDocument.status }], }); ``` Memory search enforces the same attribute allow-lists and displayed-field projection, and completes writes synchronously. It remains a substring-search test adapter, not a simulation of Meilisearch ranking, tokenization, or timing. Test asynchronous failures with a port that returns an accepted receipt and a failed task. Cover both indexing jobs and backfills. You can also import the memory adapter directly: ```typescript import { createMemorySearch } from "@beignet/core/search"; const search = createMemorySearch(); ``` > **Memory search is per-process.** Documents indexed by a seed script are > invisible to a dev server running `createMemorySearchProvider()` — they are > different processes. Rebuild the index inside the serving process with a > backfill [task](https://www.beignetjs.com/markdown/tasks.md) or outbox-driven sync listeners, or use > `@beignet/provider-search-meilisearch` so both processes share one store. > See > [Process boundaries of memory providers](https://www.beignetjs.com/markdown/providers.md#process-boundaries-of-memory-providers). ## API reference - [`createMeilisearchSearchProvider`](https://www.beignetjs.com/typedoc/functions/_beignet_provider-search-meilisearch.createMeilisearchSearchProvider.html) ## Related pages - [Ports and adapters](https://www.beignetjs.com/markdown/ports.md) for app-facing dependency boundaries. - [Tasks](https://www.beignetjs.com/markdown/tasks.md) for search backfills. - [Outbox](https://www.beignetjs.com/markdown/outbox.md) for durable post-commit indexing. - [Providers](https://www.beignetjs.com/markdown/providers.md) for provider setup and escape hatches.