Building a semantic search API in Go with Meilisearch

Full-text search is one of those features that looks simple until you have to ship it. Typos fail silently. Category filters conflict with relevance ranking. The database LIKE query that worked at 10,000 rows grinds to a halt at 100,000. This tutorial walks through building a real search API in Go using Fiber and Meilisearch, complete with filter support, typo tolerance configuration, and a MySQL LIKE fallback for resilience.

This is roughly the architecture running search across 1,600+ cybersecurity articles at AYI NEDJIMI Consultants.

Setup

go mod init search-api
go get github.com/gofiber/fiber/v2
go get github.com/meilisearch/meilisearch-go
go get github.com/go-sql-driver/mysql

Run Meilisearch:

docker run -d -p 7700:7700 \
  -e MEILI_MASTER_KEY=your_master_key \
  getmeili/meilisearch:latest

Project structure

search-api/
├── main.go
├── config/
│   └── config.go
├── search/
│   ├── meili.go
│   └── fallback.go
└── handlers/
    └── search.go

Data model

// search/meili.go
package search

// Article is the document type stored in Meilisearch and MySQL.
type Article struct {
    ID         string   `json:"id"`
    Title      string   `json:"title"`
    Slug       string   `json:"slug"`
    Content    string   `json:"content"`    // plain text, stripped of HTML
    Category   string   `json:"category"`   // news, guide, analyse, blog, checklist
    Difficulty string   `json:"difficulty"` // beginner, intermediate, advanced
    DocType    string   `json:"doc_type"`   // article, checklist, glossary
    Tags       []string `json:"tags"`
    PublishedAt int64   `json:"published_at"` // Unix timestamp for sort
}

// SearchResult wraps hits with metadata.
type SearchResult struct {
    Hits             []Article `json:"hits"`
    TotalHits        int64     `json:"total_hits"`
    ProcessingTimeMs int64     `json:"processing_time_ms"`
    Query            string    `json:"query"`
    Source           string    `json:"source"` // "meilisearch" or "mysql_fallback"
}

Meilisearch client initialization

// search/meili.go (continued)
package search

import (
    "fmt"
    "log"

    "github.com/meilisearch/meilisearch-go"
)

const IndexName = "articles"

type MeiliSearcher struct {
    client meilisearch.ServiceManager
    index  meilisearch.IndexManager
}

func NewMeiliSearcher(host, apiKey string) (*MeiliSearcher, error) {
    client := meilisearch.New(host, meilisearch.WithAPIKey(apiKey))

    // Verify connectivity
    if _, err := client.Health(); err != nil {
        return nil, fmt.Errorf("meilisearch unreachable at %s: %w", host, err)
    }

    s := &MeiliSearcher{client: client}
    if err := s.ensureIndex(); err != nil {
        return nil, err
    }
    return s, nil
}

func (s *MeiliSearcher) ensureIndex() error {
    // Get or create index
    idx, err := s.client.GetIndex(IndexName)
    if err != nil {
        task, err := s.client.CreateIndex(&meilisearch.IndexConfig{
            Uid:        IndexName,
            PrimaryKey: "id",
        })
        if err != nil {
            return fmt.Errorf("create index: %w", err)
        }
        s.client.WaitForTask(task.TaskUID, nil)
        idx, err = s.client.GetIndex(IndexName)
        if err != nil {
            return fmt.Errorf("get index after create: %w", err)
        }
    }
    s.index = idx
    return s.configureIndex()
}

func (s *MeiliSearcher) configureIndex() error {
    task, err := s.index.UpdateSettings(&meilisearch.Settings{
        SearchableAttributes: []string{
            "title",      // highest weight
            "tags",
            "content",    // lowest weight
        },
        FilterableAttributes: []string{
            "category",
            "difficulty",
            "doc_type",
        },
        SortableAttributes: []string{
            "published_at",
        },
        RankingRules: []string{
            "words",
            "typo",
            "proximity",
            "attribute",   // respects SearchableAttributes order
            "sort",
            "exactness",
        },
        TypoTolerance: &meilisearch.TypoTolerance{
            Enabled: func() *bool { b := true; return &b }(),
            MinWordSizeForTypos: meilisearch.MinWordSizeForTypos{
                OneTypo:  4,
                TwoTypos: 8,
            },
        },
        Pagination: &meilisearch.Pagination{
            MaxTotalHits: 10000,
        },
    })
    if err != nil {
        return fmt.Errorf("update settings: %w", err)
    }
    s.client.WaitForTask(task.TaskUID, nil)
    log.Println("Meilisearch index configured.")
    return nil
}

Index sync function

Call this on startup and hook it to your CRUD operations.

// search/meili.go (continued)

func (s *MeiliSearcher) IndexDocuments(articles []Article) error {
    if len(articles) == 0 {
        return nil
    }
    task, err := s.index.AddDocuments(articles, "id")
    if err != nil {
        return fmt.Errorf("add documents: %w", err)
    }
    s.client.WaitForTask(task.TaskUID, nil)
    log.Printf("Indexed %d documents.", len(articles))
    return nil
}

func (s *MeiliSearcher) DeleteDocument(id string) error {
    task, err := s.index.DeleteDocument(id)
    if err != nil {
        return fmt.Errorf("delete document %s: %w", id, err)
    }
    s.client.WaitForTask(task.TaskUID, nil)
    return nil
}

Search with filters

// search/meili.go (continued)

type SearchParams struct {
    Query      string
    Category   string
    Difficulty string
    DocType    string
    Limit      int64
    Offset     int64
}

func (s *MeiliSearcher) Search(params SearchParams) (*SearchResult, error) {
    if params.Limit <= 0 {
        params.Limit = 10
    }
    if params.Limit > 100 {
        params.Limit = 100
    }

    // Build filter expression
    var filters []string
    if params.Category != "" {
        filters = append(filters, fmt.Sprintf("category = %q", params.Category))
    }
    if params.Difficulty != "" {
        filters = append(filters, fmt.Sprintf("difficulty = %q", params.Difficulty))
    }
    if params.DocType != "" {
        filters = append(filters, fmt.Sprintf("doc_type = %q", params.DocType))
    }

    filterStr := ""
    for i, f := range filters {
        if i == 0 {
            filterStr = f
        } else {
            filterStr += " AND " + f
        }
    }

    req := &meilisearch.SearchRequest{
        Limit:  params.Limit,
        Offset: params.Offset,
        AttributesToRetrieve: []string{
            "id", "title", "slug", "category",
            "difficulty", "doc_type", "tags", "published_at",
        },
        // Don't return full content in search results
    }
    if filterStr != "" {
        req.Filter = filterStr
    }

    resp, err := s.index.Search(params.Query, req)
    if err != nil {
        return nil, err
    }

    hits := make([]Article, 0, len(resp.Hits))
    for _, h := range resp.Hits {
        // Meilisearch returns hits as map[string]interface{}
        b, _ := json.Marshal(h)
        var a Article
        if err := json.Unmarshal(b, &a); err == nil {
            hits = append(hits, a)
        }
    }

    return &SearchResult{
        Hits:             hits,
        TotalHits:        resp.TotalHits,
        ProcessingTimeMs: resp.ProcessingTimeMs,
        Query:            params.Query,
        Source:           "meilisearch",
    }, nil
}

MySQL fallback

When Meilisearch is down (restart, OOM, maintenance), fall back to MySQL LIKE. It's slower and has no typo tolerance, but it keeps the API responding.

// search/fallback.go
package search

import (
    "database/sql"
    "fmt"
    "strings"
    "time"

    _ "github.com/go-sql-driver/mysql"
)

type MySQLFallback struct {
    db *sql.DB
}

func NewMySQLFallback(dsn string) (*MySQLFallback, error) {
    db, err := sql.Open("mysql", dsn)
    if err != nil {
        return nil, err
    }
    db.SetMaxOpenConns(10)
    db.SetConnMaxLifetime(5 * time.Minute)
    return &MySQLFallback{db: db}, nil
}

func (m *MySQLFallback) Search(params SearchParams) (*SearchResult, error) {
    query := "%" + strings.ReplaceAll(params.Query, "%", "\\%") + "%"

    args := []interface{}{query, query}
    where := "WHERE (title LIKE ? OR content LIKE ?)"

    if params.Category != "" {
        where += " AND category = ?"
        args = append(args, params.Category)
    }
    if params.Difficulty != "" {
        where += " AND difficulty = ?"
        args = append(args, params.Difficulty)
    }
    if params.DocType != "" {
        where += " AND doc_type = ?"
        args = append(args, params.DocType)
    }

    // Count total
    var total int64
    countSQL := fmt.Sprintf("SELECT COUNT(*) FROM articles %s", where)
    _ = m.db.QueryRow(countSQL, args...).Scan(&total)

    // Fetch page
    args = append(args, params.Limit, params.Offset)
    rows, err := m.db.Query(
        fmt.Sprintf(`SELECT id, title, slug, category, difficulty, doc_type, published_at
                     FROM articles %s ORDER BY published_at DESC LIMIT ? OFFSET ?`, where),
        args...,
    )
    if err != nil {
        return nil, err
    }
    defer rows.Close()

    var hits []Article
    for rows.Next() {
        var a Article
        if err := rows.Scan(&a.ID, &a.Title, &a.Slug,
            &a.Category, &a.Difficulty, &a.DocType, &a.PublishedAt); err != nil {
            continue
        }
        hits = append(hits, a)
    }

    return &SearchResult{
        Hits:      hits,
        TotalHits: total,
        Query:     params.Query,
        Source:    "mysql_fallback",
    }, nil
}

HTTP handler

// handlers/search.go
package handlers

import (
    "encoding/json"
    "log"

    "github.com/gofiber/fiber/v2"
    "search-api/search"
)

type SearchHandler struct {
    meili    *search.MeiliSearcher
    fallback *search.MySQLFallback
}

func NewSearchHandler(meili *search.MeiliSearcher, fallback *search.MySQLFallback) *SearchHandler {
    return &SearchHandler{meili: meili, fallback: fallback}
}

func (h *SearchHandler) Handle(c *fiber.Ctx) error {
    params := search.SearchParams{
        Query:      c.Query("q", ""),
        Category:   c.Query("cat", ""),
        Difficulty: c.Query("diff", ""),
        DocType:    c.Query("type", ""),
        Limit:      int64(c.QueryInt("limit", 10)),
        Offset:     int64(c.QueryInt("offset", 0)),
    }

    if len([]rune(params.Query)) > 200 {
        return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{
            "error": "query too long",
        })
    }

    result, err := h.meili.Search(params)
    if err != nil {
        log.Printf("Meilisearch error: %v — falling back to MySQL", err)
        result, err = h.fallback.Search(params)
        if err != nil {
            return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{
                "error": "search unavailable",
            })
        }
    }

    return c.JSON(result)
}

Wiring it up in main.go

// main.go
package main

import (
    "log"
    "os"

    "github.com/gofiber/fiber/v2"
    "search-api/handlers"
    "search-api/search"
)

func main() {
    meiliHost := os.Getenv("MEILI_HOST")       // e.g. "http://127.0.0.1:7700"
    meiliKey  := os.Getenv("MEILI_MASTER_KEY")
    mysqlDSN  := os.Getenv("MYSQL_DSN")        // e.g. "user:pass@tcp(127.0.0.1:3306)/dbname"

    meili, err := search.NewMeiliSearcher(meiliHost, meiliKey)
    if err != nil {
        log.Fatalf("Failed to connect to Meilisearch: %v", err)
    }

    fallback, err := search.NewMySQLFallback(mysqlDSN)
    if err != nil {
        log.Fatalf("Failed to connect to MySQL: %v", err)
    }

    app := fiber.New(fiber.Config{
        ErrorHandler: func(c *fiber.Ctx, err error) error {
            return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{
                "error": err.Error(),
            })
        },
    })

    searchHandler := handlers.NewSearchHandler(meili, fallback)
    app.Get("/api/search", searchHandler.Handle)

    // Reindex endpoint (protect with auth middleware in production)
    app.Post("/admin/search/reindex", func(c *fiber.Ctx) error {
        var articles []search.Article
        if err := c.BodyParser(&articles); err != nil {
            return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": err.Error()})
        }
        if err := meili.IndexDocuments(articles); err != nil {
            return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{"error": err.Error()})
        }
        return c.JSON(fiber.Map{"indexed": len(articles)})
    })

    log.Fatal(app.Listen(":4001"))
}

Test it

# Basic search
curl "http://localhost:4001/api/search?q=pentest"

# With filters
curl "http://localhost:4001/api/search?q=NIS+2&cat=guide&diff=intermediate&limit=5"

# Typo tolerance in action
curl "http://localhost:4001/api/search?q=penetartion+tesitng"

Key tuning decisions

SearchableAttributes order matters. Meilisearch's attribute ranking rule rewards matches in earlier attributes. Putting title first means a title match outranks a content match, which is almost always what you want.

Pagination cap. The MaxTotalHits: 10000 setting prevents Meilisearch from doing expensive full-index scans for pagination deep into results. If users never go past page 20 at 10 results/page, set this to 200.

Fallback opacity. The source field in SearchResult tells the frontend (and your monitoring) when it's getting degraded results. Log every fallback occurrence — if Meilisearch is down and you're not paged, you won't know until users complain.

On-startup sync. Pull all published articles from MySQL on startup and call IndexDocuments. For 10,000+ documents this takes 2–5 seconds; for 100,000+ batch in chunks of 5,000. This ensures your index is always consistent even after a Meilisearch restart.

This pattern — Meilisearch primary, MySQL LIKE fallback — gives you production-grade search with no single point of failure and a codebase any Go developer can reason about.