Meilisearch

Why Meilisearch

Meilisearch is a Rust-based search engine optimized for developer experience:

• Typo tolerance out of the box (1 typo for 5+ char words by default)
• Sub-100ms search even on millions of documents
• Facets with counts, filter, and sort — all configured per index
• Simple JSON API — no query DSL to learn
• Single binary, easy to self-host

Compared to Elasticsearch: Meilisearch is simpler, faster to set up, but less configurable. Elasticsearch handles petabyte-scale and complex aggregations; Meilisearch handles “search my product catalog” without a PhD in Lucene.

Running Meilisearch

# Docker
docker run -d \
  --name meilisearch \
  -p 7700:7700 \
  -e MEILI_MASTER_KEY="your-master-key" \
  -v $(pwd)/meili_data:/meili_data \
  getmeili/meilisearch:latest

# Docker Compose
services:
  meilisearch:
    image: getmeili/meilisearch:latest
    ports: ["7700:7700"]
    environment:
      MEILI_MASTER_KEY: "your-master-key"
      MEILI_ENV: production
      MEILI_DB_PATH: /meili_data
    volumes:
      - meili_data:/meili_data
    restart: unless-stopped

# Verify
curl http://localhost:7700/health
# {"status":"available"}

Creating an Index and Configuring Settings

import MeiliSearch from 'meilisearch';

const client = new MeiliSearch({
  host: 'http://localhost:7700',
  apiKey: 'your-master-key',
});

// Create index
const index = client.index('products');

// Configure settings (do this before indexing)
await index.updateSettings({
  // Which fields are searchable and their relative importance
  searchableAttributes: [
    'name',          // highest priority
    'brand',
    'description',
    'tags',
  ],

  // Which fields can be used to filter/facet
  filterableAttributes: ['category', 'brand', 'price_cents', 'in_stock', 'tags'],

  // Which fields can be sorted
  sortableAttributes: ['price_cents', 'created_at', 'popularity'],

  // Relevance ranking (order matters)
  rankingRules: [
    'words',        // documents with more query words rank higher
    'typo',         // fewer typos = higher rank
    'proximity',    // closer query words = higher rank
    'attribute',    // match in searchableAttributes[0] > [1] > [2]
    'sort',         // custom sort fields
    'exactness',    // exact match > prefix match
    'popularity:desc',  // custom ranking field (inject popularity score)
  ],

  // Typo tolerance configuration
  typoTolerance: {
    enabled: true,
    minWordSizeForTypos: {
      oneTypo: 5,    // allow 1 typo for words >= 5 chars
      twoTypos: 9,   // allow 2 typos for words >= 9 chars
    },
  },

  // Stop words (don't index/search these)
  stopWords: ['the', 'a', 'an', 'and', 'or', 'but'],

  // Synonyms
  synonyms: {
    'tv': ['television', 'screen'],
    'laptop': ['notebook', 'portable computer'],
  },
});

Indexing Documents

// Index documents (upsert — safe to re-run)
await index.addDocuments([
  {
    id: 'prod-123',           // required — Meilisearch's primary key
    name: 'MacBook Pro 14"',
    brand: 'Apple',
    category: 'laptops',
    description: 'M3 chip, 18GB RAM, 512GB SSD',
    price_cents: 199900,
    in_stock: true,
    tags: ['laptop', 'apple', 'pro'],
    popularity: 9500,
    created_at: '2024-01-01T00:00:00Z',
  },
  // ...
], { primaryKey: 'id' });

// Check indexing status
const task = await index.addDocuments(documents);
const status = await client.waitForTask(task.taskUid);
console.log(status.status);  // 'succeeded'

// Update single document
await index.updateDocuments([{ id: 'prod-123', price_cents: 189900 }]);

// Delete
await index.deleteDocument('prod-123');

Searching

// Basic search
const results = await index.search('macbook pro');
console.log(results.hits);
// [{ id: 'prod-123', name: 'MacBook Pro 14"', ... }]
console.log(results.processingTimeMs);  // e.g., 3ms

// With filters and facets
const results = await index.search('laptop', {
  filter: ['category = "laptops"', 'price_cents < 200000', 'in_stock = true'],
  sort: ['price_cents:asc'],
  limit: 20,
  offset: 0,
  facets: ['brand', 'category', 'tags'],
  attributesToHighlight: ['name', 'description'],
  highlightPreTag: '<mark>',
  highlightPostTag: '</mark>',
  attributesToCrop: ['description'],
  cropLength: 100,
});

console.log(results.facetDistribution);
// {
//   brand: { Apple: 45, Dell: 23, HP: 18 },
//   category: { laptops: 86 },
//   tags: { laptop: 86, apple: 45, pro: 32 }
// }

// Typo tolerance in action
const results2 = await index.search('macbok pro');  // "macbok" typo
// Still finds MacBook Pro — typo tolerance at work

// API route
app.get('/search', async (req, res) => {
  const { q = '', category, minPrice, maxPrice, sort = 'popularity:desc', page = 1 } = req.query;

  const filters: string[] = [];
  if (category) filters.push(`category = "${category}"`);
  if (minPrice) filters.push(`price_cents >= ${Number(minPrice) * 100}`);
  if (maxPrice) filters.push(`price_cents <= ${Number(maxPrice) * 100}`);
  filters.push('in_stock = true');

  const results = await index.search(q as string, {
    filter: filters.join(' AND '),
    sort: [sort as string],
    facets: ['brand', 'category'],
    limit: 20,
    offset: (Number(page) - 1) * 20,
  });

  res.json({
    hits: results.hits,
    total: results.estimatedTotalHits,
    facets: results.facetDistribution,
    processingTimeMs: results.processingTimeMs,
  });
});

Keeping Meilisearch in Sync

Meilisearch is a read-optimized secondary index. Postgres is authoritative. Sync strategies:

1. Write-through (sync on every write):

async function createProduct(product: Product): Promise<Product> {
  const saved = await db.create(product);
  
  // Index in Meilisearch (fire-and-forget — ok if it fails, background job retries)
  index.addDocuments([productToSearchDoc(saved)]).catch(err =>
    log.error({ err, productId: saved.id }, 'Meilisearch sync failed')
  );
  
  return saved;
}

Simple but fragile — if Meilisearch is down, the sync is lost.

2. Outbox pattern (reliable sync):

// On write: record intent to sync
await db.transaction(async (tx) => {
  const product = await tx.create(product);
  await tx.query(
    'INSERT INTO search_sync_queue (entity_type, entity_id, operation) VALUES ($1, $2, $3)',
    ['product', product.id, 'upsert']
  );
});

// Background worker: process sync queue
async function processSyncQueue() {
  const batch = await db.query(
    `SELECT * FROM search_sync_queue
     WHERE processed_at IS NULL
     ORDER BY created_at
     LIMIT 100
     FOR UPDATE SKIP LOCKED`
  );

  if (batch.rows.length === 0) return;

  const toUpsert = batch.rows.filter(r => r.operation === 'upsert');
  const toDelete = batch.rows.filter(r => r.operation === 'delete');

  if (toUpsert.length > 0) {
    const products = await db.query(
      'SELECT * FROM products WHERE id = ANY($1)',
      [toUpsert.map(r => r.entity_id)]
    );
    await index.addDocuments(products.rows.map(productToSearchDoc));
  }

  if (toDelete.length > 0) {
    await index.deleteDocuments(toDelete.map(r => r.entity_id));
  }

  await db.query(
    'UPDATE search_sync_queue SET processed_at = NOW() WHERE id = ANY($1)',
    [batch.rows.map(r => r.id)]
  );
}

setInterval(processSyncQueue, 5000);

3. Full reindex (scheduled):

async function fullReindex() {
  let offset = 0;
  const batchSize = 1000;

  while (true) {
    const products = await db.query(
      'SELECT * FROM products ORDER BY id LIMIT $1 OFFSET $2',
      [batchSize, offset]
    );
    if (products.rows.length === 0) break;

    await index.addDocuments(products.rows.map(productToSearchDoc));
    offset += batchSize;
  }

  log.info({ offset }, 'Full reindex complete');
}

// Run nightly as a safety net
new CronJob('0 2 * * *', fullReindex).start();

Multi-Tenant Search

Separate index per tenant (small tenants) or filter by tenant ID (large tenants):

// Small SaaS: one index per tenant
function getTenantIndex(tenantId: string) {
  return client.index(`products_${tenantId}`);
}

// Large SaaS: shared index with tenant filter
const results = await index.search(query, {
  filter: [`tenant_id = "${tenantId}"`],
  // tenant_id must be in filterableAttributes
});

Separate indexes provide perfect isolation but multiply operational overhead. Shared index with filter is simpler but requires careful access control (server-side filter injection, never trust client-provided filters).

Meilisearch API Keys for Frontend

Never expose the master key to clients. Create scoped API keys:

const searchKey = await client.createKey({
  description: 'Frontend search — read only',
  actions: ['search'],
  indexes: ['products'],
  expiresAt: null,  // no expiry for production search key
});

console.log(searchKey.key);  // give this to the frontend

Frontend can call Meilisearch directly — zero latency from bypassing your backend — while the master key stays server-side.