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.