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

filter

filterableAttributes

(You MUST configure

sortableAttributes

sort

(You MUST NOT call

.waitTask()

(You MUST set the primary key explicitly when documents lack an

id

</critical_requirements>

Examples

• Core Patterns -- Client setup, document operations, search basics, task management, TypeScript integration
• Filtering & Facets -- Filter syntax, faceted search, geo search, sortable attributes
• Index Settings -- Ranking rules, typo tolerance, synonyms, stop words, searchable attributes, pagination
• Security & Multi-Tenancy -- API keys, tenant tokens, search rules, multi-tenant patterns

Additional resources:

• 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

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.

Core Patterns

Pattern 1: Client Setup

Initialize the client with host and API key. Use

client.index()

client.getIndex()

// 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 environment variable is required");
  }

  return new Meilisearch({ host, apiKey });
}

export { createSearchClient };

Why good: Environment variable validation, named export, apiKey is optional (Meilisearch allows unauthenticated access in development)

// Bad Example -- Hardcoded credentials
import { Meilisearch } from "meilisearch";
const client = new Meilisearch({
  host: "http://localhost:7700",
  apiKey: "masterKey123",
});

Why bad: Hardcoded host and API key leak in version control, master key exposed (use scoped API keys in production)

See examples/core.md for health checks, AbortController usage, and custom request configuration.

Pattern 2: Document Indexing (Async)

All document operations return

EnqueuedTaskPromise

// Good Example -- Add documents with explicit primary key
interface Product {
  productId: string;
  name: string;
  description: string;
  price: number;
  categories: string[];
}

const index = client.index<Product>("products");

// First add: set primary key explicitly
const task = await index.addDocuments(products, { primaryKey: "productId" });
// task.taskUid: number -- use this to track progress

Why good: Explicit primary key prevents auto-inference issues, TypeScript generic provides type safety on document shape

// Bad Example -- Relying on auto-inference
const index = client.index("products");
await index.addDocuments(products); // No primary key specified
// If first document has both 'id' and 'productId', Meilisearch guesses wrong

Why bad: Meilisearch infers primary key from the first document -- if it guesses wrong, all subsequent adds may fail with primary key conflicts

See examples/core.md for update, delete, batching, and task management patterns.

Pattern 3: Search with Filters

Filters require

filterableAttributes

AND

OR

NOT

// Good Example -- Search with filter and sort
const MIN_PRICE = 10;
const MAX_PRICE = 100;

const results = await index.search("wireless headphones", {
  filter: `price >= ${MIN_PRICE} AND price <= ${MAX_PRICE} AND categories = "electronics"`,
  sort: ["price:asc"],
  limit: 20,
});
// results.hits: Product[], results.estimatedTotalHits: number

Why good: Named constants for filter values, combined text search with structured filtering, explicit limit

// Bad Example -- Filtering without configuring filterableAttributes
const index = client.index("products");
// MISSING: await index.updateFilterableAttributes(["price", "categories"])
const results = await index.search("headphones", {
  filter: "price < 50", // Returns 0 results -- silently fails!
});

Why bad: Filters return empty results without error when the attribute is not in

filterableAttributes

See examples/filtering.md for faceted search, geo filters, and advanced filter syntax.

Pattern 4: Multi-Search

Search across multiple indexes in a single request. Federated search merges results into a unified list.

// Good Example -- Multi-search across indexes
const results = await client.multiSearch({
  queries: [
    { indexUid: "products", q: "laptop", limit: 5 },
    { indexUid: "articles", q: "laptop review", limit: 5 },
  ],
});
// results.results[0].hits -- products
// results.results[1].hits -- articles

// Federated search -- merged results
const federated = await client.multiSearch({
  federation: {},
  queries: [
    { indexUid: "products", q: "laptop" },
    { indexUid: "articles", q: "laptop" },
  ],
});
// federated.hits -- single merged list sorted by relevance

Why good: Single network request for multiple index searches, federated search provides unified ranking across indexes

See examples/core.md for federated search with query weighting.

Pattern 5: Task Management

Write operations are async. Use task UIDs to track progress. Use

.waitTask()

// Good Example -- Task tracking in a seed script
const task = await index.addDocuments(products, {
  primaryKey: "productId",
});

// In scripts/seeds: wait for completion
const completed = await task.waitTask();
if (completed.status === "failed") {
  throw new Error(`Indexing failed: ${completed.error?.message}`);
}
console.log(`Indexed ${completed.details?.indexedDocuments} documents`);

Why good:

.waitTask()

// Bad Example -- Waiting in a request handler
app.post("/products", async (req, res) => {
  const task = await index.addDocuments([req.body]);
  await task.waitTask(); // BLOCKS the request until Meilisearch processes the task!
  res.json({ success: true });
});

Why bad:

.waitTask()

See examples/core.md for batch task management and task status polling.

Pattern 6: Index Settings Configuration

Settings changes trigger a full re-index. Configure settings BEFORE adding documents to avoid re-indexing.

// Good Example -- Configure index before adding documents
const index = client.index("products");

// Step 1: Configure settings (triggers re-index)
await index
  .updateSettings({
    filterableAttributes: ["price", "categories", "brand", "inStock"],
    sortableAttributes: ["price", "createdAt"],
    searchableAttributes: ["name", "description", "brand"],
    rankingRules: [
      "words",
      "typo",
      "proximity",
      "attribute",
      "sort",
      "exactness",
      "price:asc",
    ],
    typoTolerance: {
      disableOnAttributes: ["sku", "barcode"],
    },
    synonyms: {
      phone: ["smartphone", "mobile"],
      laptop: ["notebook"],
    },
  })
  .waitTask(); // OK in setup script

// Step 2: Add documents (indexes with correct settings)
await index.addDocuments(products, { primaryKey: "productId" });

Why good: Settings configured before documents avoids double re-index, typo tolerance disabled on exact-match fields, synonyms defined for common aliases

See examples/settings.md for all settings options, stop words, and pagination configuration.

<decision_framework>

Decision Framework

Which Search Approach?

What kind of search do I need?
-- Single index, text query? -> index.search(query, options)
-- Multiple indexes, separate results? -> client.multiSearch({ queries })
-- Multiple indexes, merged results? -> client.multiSearch({ federation: {}, queries })
-- Browse/filter without text? -> index.search("", { filter, sort })  (placeholder search)

Filter vs Search?

How should users find data?
-- Natural language, typo-tolerant? -> Use the `q` parameter (search)
-- Exact attribute matching? -> Use `filter` parameter
-- Both? -> Combine: search("query", { filter: "category = 'X'" })
-- Browsing without a query? -> Placeholder search: search("", { filter, sort })

Pagination Strategy?

How should I paginate results?
-- Infinite scroll / load more? -> Use offset + limit (default)
-- Page numbers (page 1, 2, 3)? -> Use page + hitsPerPage
-- NOTE: Default maxTotalHits is 1000 -- increase in pagination settings if needed

Task Management Strategy?

How should I handle async operations?
-- Seed script / migration? -> .waitTask() is fine
-- Test setup? -> .waitTask() to ensure data is ready
-- API request handler? -> Fire-and-forget, return task UID to client
-- Need confirmation? -> Return taskUid, let client poll GET /tasks/:uid

</decision_framework>

<red_flags>

RED FLAGS

High Priority Issues:

• Filtering or sorting without first configuring

  filterableAttributes

  /

  sortableAttributes

  -- filters silently return empty results, sorts are silently ignored
• Using

  .waitTask()

  in production request handlers -- blocks the event loop, causes request timeouts under load
• Using the master key in client-side code -- exposes full admin access; use search-only API keys or tenant tokens
• Not setting the primary key explicitly -- Meilisearch auto-infers from the first document and may pick the wrong field, causing all subsequent indexing to fail

Medium Priority Issues:

• Configuring settings AFTER adding documents -- triggers a full re-index of all documents, which can take minutes on large datasets
• Exceeding the default

  maxTotalHits: 1000

  pagination limit -- search silently caps results at 1000; increase via

  pagination.maxTotalHits

  in settings if you need deeper pagination
• Using

  AND

  /

  OR

  in filters without parentheses --

  AND

  has higher precedence than

  OR

  , leading to unexpected filter results
• Not handling task failures -- failed tasks leave the index unchanged but the error is only visible by checking the task status

Gotchas & Edge Cases:

• filterableAttributes

  must include

  _geo

  for geo search -- adding documents with

  _geo

  fields is not enough, the attribute must be explicitly listed

• client.index("name")

  does NOT create the index or verify it exists -- it returns a local reference; use

  client.createIndex("name")

  to actually create it
• Empty string search (

  search("")

  ) is a valid "placeholder search" -- returns all documents matching filters, useful for browsing/faceted navigation
• Meilisearch task queue has a ~10 GiB limit -- if the queue fills up, new write operations fail with

  no_space_left_on_device

  ; delete finished tasks periodically
• Synonyms do NOT apply to filters -- filtering by "phone" will not match documents with "smartphone" even if they are configured as synonyms

• _geo

  field format is strict: must be

  { lat: number, lng: number }

  --

  longitude

  instead of

  lng

  causes

  invalid_document_geo_field

  errors
• Setting changes (filterableAttributes, etc.) queue as tasks too -- they are not instant; wait for the task to complete before relying on the new settings

• hitsPerPage

  and

  page

  parameters override

  offset

  /

  limit

  -- do not mix both pagination styles in the same query
• Default

  maxTotalHits

  is 1000 -- even with offset-based pagination, you cannot access documents beyond position 1000 without increasing this setting

</red_flags>

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,

import type

, named constants)

(You MUST configure

filterableAttributes

filter

filterableAttributes

(You MUST configure

sortableAttributes

sort

(You MUST NOT call

.waitTask()

(You MUST set the primary key explicitly when documents lack an

id

Failure to follow these rules will cause silent search failures, request timeouts, and indexing errors.

</critical_reminders>