Quick answer
Meilisearch is an open source search engine that runs as a single binary: download it, start it, send it documents over HTTP, and search them with typo tolerance built in. This post indexes a small product catalog for a clothing shop in Karachi, searches it with curl, and fixes the missing API key error that stops the first search.
A shopkeeper in Saddar has eight products and a simple website, and customers keep typing product names into the search box. The database answers with LIKE, which misses every misspelling, and there is no server team to run a big search cluster. The shop needs search that forgives a typo, ranks the closest match first, and runs without a week of setup. That is the gap Meilisearch fills, shown below on eight real products from the shop, with prices in rupees.
What I would check before using it
My first check is whether search is the problem. A shop with twenty products and a search box used twice a day does not need a search engine. Once customers type freely and misspell names, it earns its place. The Elasticsearch: Search That Understands Your Data post covers the heavier end of the same problem.
My second check is how the data changes. Meilisearch keeps its own copy, so every price or stock change has to be sent to it. Eight products updated by hand is trivial. Fifty thousand with hourly price changes needs a sync job, and that job is real work to count first.
My third check is who runs the server. The demo runs one binary on a laptop, and that is how it starts. In production, someone must keep the process alive, back up its data, and put it behind HTTPS. If nobody wants that job, hosted Meilisearch Cloud is worth pricing first.
My fourth check is what else search must do. Meilisearch handles typo tolerance, ranking, and simple filters well, and the demo proves all three. It is not an analytics database, so counting sales by city belongs in a tool built for that, like the DuckDB: Analytics Queries on a File Without a Server post describes.
My verdict, as judgement: adopt Meilisearch for a small to medium catalog where users type queries and typos are common. Keep database search when the catalog is tiny and the queries are exact. The recommendation flips if the catalog needs distributed search, or the team cannot run one more service.
Eight products, one binary, and a missing API key
Eight products go into products.json: id, name, category, city, price in rupees, and a stock flag.
[
{"id": 1, "name": "Embroidered lawn kurta", "category": "clothing",
"city": "Karachi", "price": 3499, "in_stock": true},
{"id": 2, "name": "Men's shalwar kameez, white cotton", "category": "clothing",
"city": "Lahore", "price": 4200, "in_stock": true},
{"id": 3, "name": "Chiffon dupatta with lace border", "category": "clothing",
"city": "Karachi", "price": 1299, "in_stock": true},
{"id": 4, "name": "Running sneakers, navy blue", "category": "footwear",
"city": "Islamabad", "price": 8900, "in_stock": true},
{"id": 5, "name": "Leather handbag, tan", "category": "accessories",
"city": "Karachi", "price": 6500, "in_stock": false},
{"id": 6, "name": "Winter jacket, padded, black", "category": "clothing",
"city": "Rawalpindi", "price": 9800, "in_stock": true},
{"id": 7, "name": "Printed lawn suit, three piece", "category": "clothing",
"city": "Karachi", "price": 5400, "in_stock": true},
{"id": 8, "name": "Peshawari chappal, brown leather", "category": "footwear",
"city": "Peshawar", "price": 3200, "in_stock": true}
]
Download the binary from the release page and check the version. No account or installer needed.
$ ./meilisearch --version
meilisearch 1.57.0
Start the server with a master key and a data directory, using a demo key locally only.
$ ./meilisearch --master-key devkey123 --db-path ./data.ms --http-addr 127.0.0.1:7700
Give the server a few seconds after starting: the first run of this demo curled too early and got nothing back, so poll /health until it answers.
$ curl -s http://127.0.0.1:7700/health
{"status":"available"}
The first search goes wrong, and the error is the lesson: with a master key set, every request needs an Authorization header, and this one has none.
$ curl -s -X POST http://127.0.0.1:7700/indexes/products/search \
-H "Content-Type: application/json" -d '{"q": "kurta"}'
{
"message": "The Authorization header is missing. It must use the bearer authentication method.",
"code": "missing_authorization_header",
"type": "auth",
"link": "https://docs.meilisearch.com/errors#missing_authorization_header"
}
The fix is the header. Add the documents with the key, and Meilisearch answers with a task: indexing runs in the background.
$ curl -s -X PUT http://127.0.0.1:7700/indexes/products/documents \
-H "Authorization: Bearer devkey123" \
-H "Content-Type: application/json" --data-binary @products.json
{
"taskUid": 0,
"indexUid": "products",
"status": "enqueued",
"type": "documentAdditionOrUpdate",
"enqueuedAt": "2026-11-21T03:09:38.388424985Z"
}
Check the task to see when the documents are searchable. The first check caught it still processing, with 8 received and none indexed; a later check showed all 8 indexed in 0.26 seconds. A search in between can return zero hits, and the task endpoint tells waiting from broken.
Next, mark city, category, and in_stock as filterable.
$ curl -s -X PUT http://127.0.0.1:7700/indexes/products/settings/filterable-attributes \
-H "Authorization: Bearer devkey123" \
-H "Content-Type: application/json" -d '["city", "category", "in_stock"]'
{"taskUid":1,"indexUid":"products","status":"enqueued","type":"settingsUpdate","enqueuedAt":"2026-11-21T03:09:38.563216955Z"}
One hit, the embroidered lawn kurta for Rs 3499, in 13 milliseconds.
$ curl -s -X POST http://127.0.0.1:7700/indexes/products/search \
-H "Authorization: Bearer devkey123" \
-H "Content-Type: application/json" -d '{"q": "kurta"}'
{
"hits": [
{
"category": "clothing",
"city": "Karachi",
"id": 1,
"in_stock": true,
"name": "Embroidered lawn kurta",
"price": 3499
}
],
"query": "kurta",
"processingTimeMs": 13,
"limit": 20,
"offset": 0,
"estimatedTotalHits": 1,
"requestUid": "01a1fc14-bf8e-7530-aa92-bc1862ce5645"
}
Typo tolerance is the feature the shop needs: "kurtah" with an extra h still returns the same kurta, in 0 milliseconds.
$ curl -s -X POST http://127.0.0.1:7700/indexes/products/search \
-H "Authorization: Bearer devkey123" \
-H "Content-Type: application/json" -d '{"q": "kurtah"}'
{
"hits": [
{
"category": "clothing",
"city": "Karachi",
"id": 1,
"in_stock": true,
"name": "Embroidered lawn kurta",
"price": 3499
}
],
"query": "kurtah",
"processingTimeMs": 0,
"limit": 20,
"offset": 0,
"estimatedTotalHits": 1,
"requestUid": "01a1fc14-bfb0-7b10-9300-cc40c877e329"
}
Filters narrow the same way. Sneakers filtered to Karachi return nothing, which is correct, since the only sneakers sit in Islamabad. Filtered to Islamabad, the same query returns them for Rs 8900.
$ curl -s -X POST http://127.0.0.1:7700/indexes/products/search \
-H "Authorization: Bearer devkey123" \
-H "Content-Type: application/json" -d '{"q": "sneakers", "filter": "city = Karachi"}'
{"hits":[],"query":"sneakers","processingTimeMs":0,"limit":20,"offset":0,"estimatedTotalHits":0,"requestUid":"01a1fc14-bfb9-7053-9f97-308b211e0745"}
$ curl -s -X POST http://127.0.0.1:7700/indexes/products/search \
-H "Authorization: Bearer devkey123" \
-H "Content-Type: application/json" -d '{"q": "sneakers", "filter": "city = Islamabad"}'
{"hits":[{"category":"footwear","city":"Islamabad","id":4,"in_stock":true,"name":"Running sneakers, navy blue","price":8900}],"query":"sneakers","processingTimeMs":1,"limit":20,"offset":0,"estimatedTotalHits":1,"requestUid":"01a1fc14-f980-7772-ad65-3171671cf6f7"}
Every number above came from the live server. Wrapping this search in a small API is the natural next step, and the FastAPI Explained: Python APIs at Full Speed post shows its shape.
Common mistakes and how to fix them
First, forgetting the Authorization header once a master key is set. The symptom is the 401 with code missing_authorization_header, exactly as the demo showed. The fix is adding the Bearer header to every request, and using a search-only key in the browser instead of the master key.
Second, searching before the indexing task finishes. The symptom is zero hits for a product you just added, even though the add request succeeded. The fix is checking GET /tasks/{taskUid} until the status reads succeeded, because the add call only enqueues the work.
Third, curling the server before it finishes starting. The symptom is an empty response or a connection refused error, which is what happened on the first run of this demo when the health check fired three seconds after launch. The fix is polling /health until it answers.
Fourth, using a short demo key in production. The symptom is the startup warning that the master key is considered unsafe, and production refuses keys under 16 bytes. The fix is generating a long random key and storing it outside the code.
Frequently Asked Questions
Does Meilisearch replace Elasticsearch? For a small or medium catalog it can: it covers typo tolerance, ranking, and filters with far less setup. Elasticsearch still fits teams needing distributed search or aggregations.
Do I still need my database if I use Meilisearch? Yes. Meilisearch holds a searchable copy, not the source of truth. Keep prices and stock in the database, and send updates when they change.
Is Meilisearch free to run? The engine is open source, and the binary costs nothing to run on your own machine. Managed hosting costs extra.
Can I call it straight from the browser? You can, but never with the master key. Create a search-only key for the frontend and keep the master key on the server.
How big a catalog can it handle? Eight products indexed in a quarter of a second, and the same binary serves far larger catalogs. Measure with your own catalog first.
What to remember
- Meilisearch runs as one binary: download it, start it, and search over HTTP.
- A master key means every request needs an Authorization header, or it fails with a 401.
- Adding documents only enqueues a task, so check its status first.
- Typo tolerance works out of the box: "kurtah" still found the kurta.
- Filters need their attributes marked filterable first.
Where this leaves you
Meilisearch turns search from a project into an afternoon. The demo proved the three things a small shop needs: the binary started with one command, the missing API key failed loudly instead of silently, and a misspelled query still found the right kurta in no measurable processing time. Keep the database as the source of truth, send it updates when prices change, and use a search-only key in the browser. If your users type product names by hand, give them search that forgives a typo.
Further reading
- Meilisearch documentation
- Meilisearch quick start
- Meilisearch on GitHub
- Meilisearch error reference
- Elasticsearch: Search That Understands Your Data
- FastAPI Explained: Python APIs at Full Speed
- DuckDB: Analytics Queries on a File Without a Server
- Redis Explained: The In-Memory Store That Makes Apps Fast
Waqas Shahid is a software engineer from Karachi with more than 12 years of experience, including 6+ years in engineering leadership. He writes The Practical Developer.
Top comments (0)