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