agents-inc/api-search-meilisearch

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 -- 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>

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 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. The documents are NOT searchable immediately -- they enter a task queue.

// 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 to be configured first. Filter syntax uses SQL-like operators with 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 -- this is the most common Meilisearch gotcha

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() only in scripts and tests.

// 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() used in seed script (not request handler), error status checked, task details inspected

// 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() polls Meilisearch repeatedly, blocking the request handler -- tasks may take seconds or minutes depending on queue depth

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.

</patterns>

---

<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 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)

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

</critical_reminders>