Meilisearch

Deploy and tune Meilisearch with indexing, filtering, and production configuration.

Security Scan

This is an instruction-only reference for deploying and tuning Meilisearch (no code, no installs, no credentials requested) and its requirements and guidance align with the description.

Purpose & Capability

The SKILL.md is a Meilisearch-focused guide (indexing, filtering, production config). It does not ask for unrelated credentials, binaries, or config paths — consistent with the advertised purpose.

Instruction Scope

The instructions are prose best-practices and operational notes (settings, indexing behavior, API key guidance). They do not instruct the agent to read files, access environment variables, or transmit data to external endpoints.

Install Mechanism

No install spec and no code files — lowest-risk instruction-only skill that does not write or download artifacts.

Credentials

The skill declares no required environment variables or credentials. The SKILL.md references the concept of master/search API keys as operational guidance (appropriate) but does not request them.

Persistence & Privilege

always is false and the skill does not request persistent/system-wide privileges or modify other skill configurations.

Assessment

This skill is an offline guidance document (no code or installs) and appears coherent with its description — low inherent risk. Before using it in an automated agent workflow, consider: (1) the agent could use these instructions to recommend actions, so ensure the agent is not given credentials or deployment rights you don't intend; (2) never expose Meilisearch master keys to clients — use search-only keys as advised; (3) verify the Meilisearch version you run matches the recommendations in the guide (behavior and defaults can change across versions); and (4) if you want to prevent autonomous changes, consider restricting the agent's ability to perform deployments or set disable-model-invocation for agents you don't fully trust.

Index Configuration Traps

• filterableAttributes and sortableAttributes must be declared BEFORE adding documents — adding later triggers full reindex
• Changing any index setting triggers reindex — batch all setting changes together
• Order of searchableAttributes affects ranking — put most important fields first, not alphabetical
• displayedAttributes defaults to all — explicitly limit to reduce response size

Indexing Pitfalls

• Document updates are async — the API returns taskUid, must poll /tasks/{uid} for actual completion
• Primary key inference fails on nested or array fields — always set primaryKey explicitly
• Batch size affects indexing speed — 10-50MB batches optimal, not one document at a time
• Updating one field requires sending the whole document — no true partial updates

Typo Tolerance Issues

• First character is never typo-tolerant — "tset" won't match "test", by design
• Typo tolerance on IDs/codes causes false matches — disable per attribute with typoTolerance.disableOnAttributes
• Min word length defaults: 1 typo at 5 chars, 2 typos at 9 chars — adjust if matching too aggressively

Filtering Mistakes

• Filters on undeclared filterableAttributes silently return empty — no error, just no results
• Geo filtering requires _geo field with lat/lng — field name is hardcoded, can't customize
• Filter syntax is NOT SQL — use TO for ranges (year 2020 TO 2024), not BETWEEN
• Empty array in IN clause causes error — check array length before building filter

Search Behavior

• Default limit is 20, max is 1000 per request — no deep pagination, use filters to narrow
• Multi-word queries match ANY word by default — use quotes for phrase matching
• Highlighting only works on searchableAttributes — not on stored-only fields
• Facets distribution counts include all matching docs — not affected by limit parameter

Production Configuration

• Master key MUST be set in production — without it, all endpoints are public
• Create search-only API keys for frontend — never expose master key
• Snapshots are the only backup method — schedule them, no continuous replication
• No clustering — single node only, scale vertically with RAM

Performance Realities

• Index lives in memory-mapped files — RAM determines max index size
• Payload limit is 100MB per request — split large imports into batches
• Indexing blocks during settings update — queries still work but new docs queue
• Task queue has no priority — large reindex blocks small document adds

API Key Restrictions

• Keys can restrict to specific indexes — use for multi-tenant isolation
• Keys can have expiresAt — but no auto-rotation, must manage manually
• Actions are granular — search, documents.add, indexes.create, settings.update, etc.
• Invalid key returns 401, missing key on protected instance returns 401 — same error, check both