/api-search-meilisearch

name: api-search-meilisearch
description: Meilisearch search engine patterns -- client setup, indexing, search, filtering, facets, geo search, multi-tenancy, task management

Meilisearch Patterns

> **Quick Guide:** Use `meilisearch` (v0.56+) as the TypeScript client for Meilisearch v1.x. All write operations (document adds, setting changes, index creation) are **asynchronous** -- they return an `EnqueuedTaskPromise` and are processed in a background queue. You MUST configure `filterableAttributes` and `sortableAttributes` on the index **before** using filter/sort in search queries -- this triggers a full re-index. Use `client.index("name")` for a lazy reference (no network call) vs `client.getIndex("name")` which fetches from server. Use `.waitTask()` on `EnqueuedTaskPromise` only in scripts/seeds/tests -- never in request handlers.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST configure `filterableAttributes` on the index BEFORE using `filter` in search queries -- filters silently return no results if the attribute is not in `filterableAttributes`)**

**(You MUST configure `sortableAttributes` on the index BEFORE using `sort` in search queries -- sort on unconfigured attributes is silently ignored)**

**(You MUST NOT call `.waitTask()` in production request handlers -- it blocks the event loop polling Meilisearch until the task completes; use it only in scripts, seeds, and tests)**

**(You MUST set the primary key explicitly when documents lack an `id` field -- Meilisearch auto-infers primary key only on first document add, and wrong inference causes indexing failures on subsequent batches)**

</critical_requirements>

---

Examples

• [Core Patterns](examples/core.md) -- Client setup, document operations, search basics, task management, TypeScript integration
• [Filtering & Facets](examples/filtering.md) -- Filter syntax, faceted search, geo search, sortable attributes
• [Index Settings](examples/settings.md) -- Ranking rules, typo tolerance, synonyms, stop words, searchable attributes, pagination
• [Security & Multi-Tenancy](examples/security.md) -- API keys, tenant tokens, search rules, multi-tenant patterns

**Additional resources:**

• [reference.md](reference.md) -- Search parameter cheat sheet, settings defaults, decision frameworks, anti-patterns

---

**Auto-detection:** Meilisearch, meilisearch, MeiliSearch, meilisearch-js, client.index, addDocuments, updateDocuments, multiSearch, filterableAttributes, sortableAttributes, searchableAttributes, rankingRules, typoTolerance, tenant token, generateTenantToken, EnqueuedTaskPromise, waitTask, facets, \_geoRadius, \_geoBoundingBox, \_geoPoint, instantsearch

**When to use:**

• Adding full-text search to an application (product search, content search, autocomplete)
• Implementing faceted navigation (category filters, price ranges, attribute counts)
• Building geo-aware search (find nearby, sort by distance)
• Multi-tenant search where tenants share an index but see only their documents
• Search across multiple indexes simultaneously (multi-search, federated search)
• Real-time document indexing with typo-tolerant instant search

**Key patterns covered:**

• Client initialization and connection management
• Document CRUD operations with async task handling
• Search with filtering, sorting, facets, and highlighting
• Geo search with `_geoRadius`, `_geoBoundingBox`, and distance sorting
• Multi-search and federated search across indexes
• Index settings configuration (ranking rules, typo tolerance, synonyms, stop words)
• Tenant tokens for multi-tenant access control
• TypeScript generics for typed search results

**When NOT to use:**

• Full-text search on a relational database (use your database's built-in full-text search for simple cases)
• Log aggregation or analytics queries (use a dedicated log/analytics search engine)
• Vector-only semantic search without keyword component (use a dedicated vector database)
• Searching fewer than ~1,000 documents (client-side filtering is simpler)

---

<philosophy>

Philosophy

Meilisearch is a **search engine**, not a database. It indexes documents for fast retrieval but is not the source of truth. The core principles:

1. **Async everything** -- All write operations (documents, settings, index management) are queued and processed asynchronously. The API returns a task ID immediately. Design your application to not depend on instant indexing. 2. **Configure before search** -- Filterable attributes, sortable attributes, and searchable attributes must be configured BEFORE they can be used in search queries. This triggers a re-index of all documents. 3. **Typo tolerance by default** -- Meilisearch handles typos out of the box. Tune `typoTolerance` settings to disable it for specific fields (product codes, serial numbers) rather than trying to implement exact matching manually. 4. **Primary key matters** -- Every document needs a unique primary key. Meilisearch auto-infers it from the first document, but explicit is better than implicit. Set it on index creation. 5. **Search, don't query** -- Meilisearch is optimized for human search queries (typo-tolerant, prefix matching, ranking). It is not a SQL replacement. Use filters for structured queries, search for natural language.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Client Setup

Initialize the client with host and API key. Use `client.index()` for a lazy local reference (no network call) -- prefer this over `client.getIndex()` which hits the server.

// Good Example -- Typed client setup
import { Meilisearch } from "meilisearch";

function createSearchClient(): Meilisearch {
  const host = process.env.MEILISEARCH_URL;
  const apiKey = process.env.MEILISEARCH_API_KEY;
  if (!host) {
    throw new Error("MEILISEARCH_URL envi