Dowiedz się, jak dodać Meilisearch do backendu, by mieć szybkie, odporne na literówki wyszukiwanie: konfiguracja, indeksowanie, reguły rankingowe, filtry i podstawy skalowania.
Wyszukiwanie po stronie serwera oznacza, że zapytanie jest przetwarzane na Twoim serwerze (lub w dedykowanej usłudze wyszukiwania), a nie w przeglądarce. Twoja aplikacja wysyła żądanie wyszukiwania, serwer uruchamia je przeciwko indeksowi i zwraca posortowane wyniki.
To ma znaczenie, gdy Twoje dane są za duże, by wysyłać je do klienta, gdy potrzebujesz spójnej trafności na różnych platformach, albo gdy kontrola dostępu jest niezbędna (np. w narzędziach wewnętrznych, gdzie użytkownicy powinni widzieć tylko to, do czego mają dostęp). To też domyślny wybór, gdy chcesz mieć analitykę, logowanie i przewidywalną wydajność.
Ludzie nie myślą o silnikach wyszukiwania—oceniają doświadczenie. Dobry „błyskawiczny” przepływ zwykle oznacza:
Jeśli czegoś z tego brakuje, użytkownicy będą próbować innych zapytań, przewijać więcej albo porzucać wyszukiwanie.
Ten artykuł to praktyczny przewodnik po budowie takiego doświadczenia z Meilisearch. Omówimy bezpieczną konfigurację, strukturę i synchronizację danych, strojenie trafności i reguł rankingowych, dodawanie filtrów/sortowania/faset, oraz kwestie bezpieczeństwa i skalowania, by wyszukiwanie pozostało szybkie wraz z rozwojem aplikacji.
Meilisearch świetnie nadaje się do:
Celem jest: wyniki, które wydają się natychmiastowe, dokładne i wiarygodne—bez przemiany wyszukiwania w dużą pracę inżynierską.
Meilisearch to silnik wyszukiwania, który uruchamiasz obok swojej aplikacji. Wysyłasz mu dokumenty (np. produkty, artykuły, użytkowników, zgłoszenia), a on buduje indeks zoptymalizowany pod szybkie wyszukiwanie. Twój backend (lub frontend) zapytuje Meilisearch przez prosty HTTP API i otrzymuje posortowane wyniki w milisekundach.
Meilisearch koncentruje się na funkcjach, których oczekują użytkownicy nowoczesnego wyszukiwania:
Został zaprojektowany tak, by być responsywnym i wyrozumiałym, nawet gdy zapytanie jest krótkie, nieprecyzyjne lub niejasne.
Meilisearch nie zastępuje Twojej bazy danych. Baza pozostaje źródłem prawdy dla zapisów, transakcji i ograniczeń. Meilisearch przechowuje kopię tych pól, które wybierzesz jako przeszukiwalne, filtrowalne lub wyświetlane.
Dobry model myślowy: baza danych do przechowywania i aktualizacji, Meilisearch do szybkiego odnajdywania.
Meilisearch może być bardzo szybki, ale wyniki zależą od kilku praktycznych czynników:
Dla małych i średnich zestawów danych często wystarczy jedna maszyna. Wraz ze wzrostem indeksu warto staranniej wybierać, co indeksować i jak utrzymywać synchronizację — tematy, które omówimy dalej.
Zanim cokolwiek zainstalujesz, zdecyduj, czego faktycznie będziesz szukać. Meilisearch będzie „błyskawiczny” tylko wtedy, gdy Twoje indeksy i dokumenty będą odpowiadać na sposób, w jaki użytkownicy przeglądają aplikację.
Zacznij od listy przeszukiwalnych encji — zwykle produkty, artykuły, użytkownicy, dokumentacja, lokalizacje itd. W wielu aplikacjach najczystszym podejściem jest jeden indeks na typ encji (np. products, articles). Utrzymuje to reguły rankingowe i filtry przewidywalne.
Jeśli UX wymaga „szukaj wszystkiego” w jednym polu, możesz trzymać osobne indeksy i scalać wyniki na backendzie albo stworzyć dedykowany indeks „globalny” później. Nie zmuszaj wszystkiego do jednego indeksu, jeśli pola i filtry nie są zgodne.
Każdy dokument potrzebuje stabilnego identyfikatora (klucz główny). Wybierz coś, co:
id, sku, slug)Dla kształtu dokumentu preferuj pola płaskie. Są łatwiejsze do filtrowania i sortowania. Zagnieżdżone pola są ok, jeśli reprezentują zwartą, niezmienną paczkę (np. obiekt author), ale unikaj głębokiego zagnieżdżania, które odzwierciedla całą relacyjną strukturę bazy—dokumenty wyszukiwania powinny być optymalizowane pod odczyt, nie kształtem bazy.
Praktyczny sposób projektowania dokumentów to przypisanie roli każdemu polu:
To zapobiega powszechnemu błędowi: indeksowaniu pola „na wszelki wypadek” i późniejszemu zdziwieniu, dlaczego wyniki są hałaśliwe albo filtry wolne.
„Język” może oznaczać różne rzeczy w Twoich danych:
lang: "en")Zdecyduj wcześniej, czy użyjesz osobnych indeksów per język (proste i przewidywalne) czy jednego indeksu z polami językowymi (mniej indeksów, więcej logiki). Wybór zależy od tego, czy użytkownicy szukają zazwyczaj w jednym języku naraz i jak przechowujesz tłumaczenia.
Uruchomienie Meilisearch jest proste, ale „bezpieczne domyślnie” wymaga kilku świadomych decyzji: gdzie go wdrożyć, jak przechowywać dane i jak obsługiwać master key.
Storage: Meilisearch zapisuje indeks na dysku. Umieść katalog danych na niezawodnym, trwałym dysku (nie na efemerycznym storage kontenera). Planuj pojemność na wzrost: indeksy mogą szybko rosnąć przy dużych polach tekstowych i wielu atrybutach.
Pamięć: przydziel wystarczająco RAM, by wyszukiwanie było responsywne. Jeśli zauważysz swapowanie, wydajność spadnie.
Backupy: rób kopie katalogu danych Meilisearch (lub używaj snapshotów na poziomie storage). Przetestuj przywracanie przynajmniej raz; backup, którego nie da się przywrócić, to tylko plik.
Monitoring: monitoruj CPU, RAM, użycie dysku i I/O dysku. Również obserwuj zdrowie procesu i logi. Przynajmniej ustaw alerty na zatrzymanie usługi i niski wolny dysk.
Zawsze uruchamiaj Meilisearch z master key poza lokalnym developmentem. Przechowuj go w managerze sekretów lub zaszyfrowanym magazynie środowiskowym (nie w Git, nie w jawnych .env w repozytorium).
Przykład (Docker):
docker run -d --name meilisearch \\
-p 7700:7700 \\
-v meili_data:/meili_data \\
-e MEILI_MASTER_KEY="$(openssl rand -hex 32)" \\
getmeili/meilisearch:latest
Rozważ też reguły sieciowe: binduj na prywatny interfejs lub ogranicz dostęp tak, aby tylko backend mógł łączyć się z Meilisearch.
curl -s http://localhost:7700/version
Indeksowanie w Meilisearch jest asynchroniczne: wysyłasz dokumenty, Meilisearch dodaje zadanie do kolejki i dopiero po zakończeniu tego zadania dokumenty stają się przeszukiwalne. Traktuj indeksowanie jak system kolejkowy, nie pojedyncze żądanie.
id).curl -X POST 'http://localhost:7700/indexes/products/documents?primaryKey=id' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_WRITE_KEY' \\
--data-binary @products.json
taskUid. Polluj, aż będzie succeeded (lub failed).curl -X GET 'http://localhost:7700/tasks/123' \\
-H 'Authorization: Bearer YOUR_WRITE_KEY'
curl -X GET 'http://localhost:7700/indexes/products/stats' \\
-H 'Authorization: Bearer YOUR_WRITE_KEY'
Jeśli liczby się nie zgadzają, nie zgaduj—sprawdź najpierw szczegóły błędu zadania.
Batching polega na utrzymaniu zadań przewidywalnych i możliwych do odzyskania.
addDocuments działa jak upsert: dokumenty z tym samym kluczem głównym są aktualizowane, nowe wstawiane. Używaj tego do normalnych aktualizacji.
Przeprowadź pełny reindex gdy:
Aby usuwać, wywołaj deleteDocument(s); w przeciwnym razie stare rekordy mogą się utrzymywać.
Indeksowanie powinno być możliwe do powtórzenia. Kluczem są stabilne id dokumentów.
taskUid razem z id batcha/jobu i wykonuj retry na podstawie statusu zadania.Przed danymi produkcyjnymi zaindeksuj mały zestaw (200–500 elementów) odpowiadający prawdziwym polom. Przykład: zestaw products z id, name, description, category, brand, price, inStock, createdAt. To wystarczy, by zweryfikować flow zadań, liczniki i zachowanie update/delete—bez czekania na masowy import.
„Trafność” wyszukiwania to po prostu: co pojawia się pierwsze i dlaczego. Meilisearch pozwala to regulować bez konieczności tworzenia własnego systemu punktacji.
Dwa ustawienia określają, co Meilisearch może zrobić z Twoimi treściami:
searchableAttributes: pola, w których Meilisearch szuka, gdy użytkownik wpisuje zapytanie (np. title, summary, tags). Kolejność ma znaczenie: wcześniejsze pola są traktowane jako ważniejsze.displayedAttributes: pola zwracane w odpowiedzi. Ma to znaczenie dla prywatności i rozmiaru payloadu—jeśli pole nie jest wyświetlane, nie zostanie odesłane.Praktyczna baza to kilka pól o wysokim sygnale jako przeszukiwalne (tytuł, kluczowy tekst) i ograniczenie wyświetlanych pól do tego, czego UI potrzebuje.
Meilisearch sortuje pasujące dokumenty używając reguł rankingowych—potoku „rozstrzygaczy”. W uproszczeniu preferuje:
Nie musisz zapamiętywać szczegółów implementacji, by skutecznie je stroić; głównie wybierasz które pola są ważne i kiedy zastosować własne sortowanie.
Cel: „Dopasowania w tytule powinny wygrywać.” Umieść title jako pierwsze:
{
"searchableAttributes": ["title", "subtitle", "description", "tags"]
}
Cel: „Nowsza treść powinna być pierwsza.” Dodaj pole do sortowania i sortuj przy zapytaniu (lub ustaw custom ranking):
{
"sortableAttributes": ["publishedAt"],
"rankingRules": ["sort", "typo", "words", "proximity", "attribute", "exactness"]
}
Następnie wykonaj zapytanie:
{ "q": "release notes", "sort": ["publishedAt:desc"] }
Cel: „Promuj popularne pozycje.” Uczyń popularity sortowalnym i sortuj według niego, gdy to właściwe.
Wybierz 5–10 rzeczywistych zapytań użytkowników. Zapisz top wyniki przed zmianami, potem porównaj po.
Przykład:
"apple" → Apple Watch band, Pineapple slicer, Apple iPhone case"apple" → Apple iPhone case, Apple Watch band, Pineapple slicerJeśli lista „po” lepiej odzwierciedla intencję użytkownika, zachowaj ustawienia. Jeśli psuje przypadki brzegowe, zmieniaj jedną rzecz naraz (kolejność atrybutów, potem reguły sortowania), żeby wiedzieć, co spowodowało poprawę.
Dobre pole wyszukiwania to nie tylko „wpisz słowa, dostaniesz dopasowania”. Ludzie chcą też zawęzić wyniki („tylko dostępne”) i ustawić porządek („najtańsze najpierw”). W Meilisearch robisz to za pomocą filtrów, sortowania i faset.
Filtr to reguła, którą stosujesz do zbioru wyników. Faseta to to, co pokazujesz w UI, by pomóc użytkownikom budować te reguły (zwykle checkboxy lub liczniki).
Przykłady niefachowe:
Użytkownik może wyszukać „running”, a potem przefiltrować do category = Shoes i status = in_stock. Fasety pokażą liczniki jak „Shoes (128)”, „Jackets (42)”, by użytkownik wiedział, co jest dostępne.
Meilisearch wymaga, by pola używane do filtrowania i sortowania były jawnie udostępnione.
category, status, brand, price, created_at, tenant_id.price, rating, created_at, popularity.Utrzymaj tę listę zwartą. Uczynienie wszystkiego filtrowalnym/sortowalnym może zwiększyć rozmiar indeksu i spowolnić aktualizacje.
Nawet przy 50,000 dopasowań użytkownik widzi tylko pierwszą stronę. Używaj małych stron (często 20–50 wyników), ustaw sensowny limit i paginuj z offset (lub nowsze mechanizmy paginacji, jeśli wolisz). Ogranicz też maksymalną głębokość stron w aplikacji, by zapobiec kosztownym „strona 400”.
Czysty sposób dodania wyszukiwania po stronie serwera to traktować Meilisearch jako wyspecjalizowaną usługę danych za Twoim API. Aplikacja otrzymuje zapytanie wyszukiwania, wywołuje Meilisearch, a następnie zwraca klientowi przygotowaną odpowiedź.
Większość zespołów kończy z takim flow:
GET /api/search?q=wireless+headphones&limit=20).Ten wzorzec utrzymuje Meilisearch wymienialnym i zapobiega zależności frontendu od wewnętrznej struktury indeksu.
Jeśli budujesz nową aplikację (lub przebudowujesz narzędzie wewnętrzne) i chcesz szybko wdrożyć ten wzorzec, platforma vibe-coding jak Koder.ai może pomóc przygotować cały flow—React UI, backend w Go i PostgreSQL—a następnie zintegrować Meilisearch za jednym endpointem /api/search, by klient był prosty, a uprawnienia trzymane po stronie serwera.
Meilisearch obsługuje zapytania z klienta, ale zwykle bezpieczniej jest używać backendu, bo:
Zapytania z frontendu działają dla publicznych danych z ograniczonymi kluczami, ale jeśli masz reguły widoczności specyficzne dla użytkownika, kieruj wyszukiwanie przez serwer.
Ruch wyszukiwania często się powtarza („iphone case”, „return policy”). Dodaj cache na warstwie API:
Traktuj wyszukiwanie jako endpoint publiczny:
limit i maksymalną długość zapytania.Meilisearch często znajduje się „za” Twoją aplikacją, bo może zwracać wrażliwe dane szybko. Traktuj go jak bazę danych: zabezpiecz i udostępniaj tylko to, co powinno być widoczne dla danego klienta.
Meilisearch ma master key, który może wszystko: tworzyć/usuwać indeksy, zmieniać ustawienia i czytać/zapisywać dokumenty. Trzymaj go tylko po stronie serwera.
Dla aplikacji generuj klucze API z ograniczonymi uprawnieniami i indeksami. Częsty wzorzec:
Zasada najmniejszego przywileju sprawia, że wyciek klucza nie pozwoli na usunięcie danych ani odczyt z niezwiązanych indeksów.
Jeśli obsługujesz wielu klientów (tenantów), masz dwie główne opcje:
1) Jeden indeks na tenant.
Proste do rozumienia i zmniejsza ryzyko dostępu między tenantami. Minusy: więcej indeksów do zarządzania i konieczność stosowania ustawień konsekwentnie.
2) Wspólny indeks + filter po tenantId.
Przechowuj pole tenantId w każdym dokumencie i wymuszaj filtr tenantId = "t_123" dla wszystkich zapytań. To może skalować dobrze, ale tylko jeśli zapewnisz, że każde żądanie zawsze stosuje filtr (najlepiej poprzez scoped key, żeby wykluczyć jego usunięcie przez klienta).
Nawet jeśli wyszukiwanie jest poprawne, wyniki mogą ujawnić pola, których nie chciałeś pokazać (maile, notatki wewnętrzne, ceny kosztowe). Skonfiguruj, co można zwrócić:
Zrób szybki test „najgorszego scenariusza”: wyszukaj popularny termin i upewnij się, że żadne prywatne pola się nie pojawiają.
Jeśli nie jesteś pewien, czy klucz powinien być po stronie klienta—zakładaj „nie” i trzymaj wyszukiwanie po stronie serwera.
Meilisearch jest szybki, kiedy masz na uwadze dwa rodzaje obciążenia: indeksowanie (zapisy) i zapytania (odczyty). Większość „tajemniczych” spowolnień to po prostu konkurencja tych obciążeń o CPU, RAM lub dysk.
Obciążenie indeksowania może skakać przy dużych importach, częstych aktualizacjach lub wielu przeszukiwalnych polach. Indeksowanie jest zadaniem w tle, ale zużywa CPU i przepustowość dysku. Jeśli kolejka zadań rośnie, wyszukiwania mogą zacząć się wydawać wolniejsze, nawet jeśli ruch zapytań się nie zmienił.
Obciążenie zapytań rośnie wraz z ruchem, ale też wraz z funkcjami: więcej filtrów, więcej faset, większe zbiory wyników i większa tolerancja literówek zwiększają pracę na żądanie.
I/O dysku jest cichym winowajcą. Wolne dyski (lub „hałaśliwi sąsiedzi” na współdzielonych woluminach) mogą zmienić „błyskawiczne” w „w końcu”. NVMe/SSD to zwykle minimum dla produkcji.
Zacznij od prostego rozmiarowania: daj Meilisearch wystarczająco RAM, by indeksy były “hot” i CPU, by obsłużyć piki QPS. Potem oddziel obciążenia:
Śledź niewielki zestaw sygnałów:
Backupy powinny być rutyną, nie heroicznym wysiłkiem. Używaj funkcji snapshot Meilisearch w harmonogramie, przechowuj snapshoty poza serwerem i okresowo testuj przywracanie. Przy aktualizacjach czytaj release notes, testuj upgrade w środowisku nieprodukcyjnym i planuj czas na reindeksowanie, jeśli nowa wersja wpływa na indeksowanie.
Jeśli już używasz snapshotów środowisk i rollbacku w platformie aplikacyjnej (np. przez Koder.ai), zsynchronizuj rollout wyszukiwania z tym samym podejściem: snapshot przed zmianami, sprawdź health checks i miej szybki powrót do znanego stanu.
Nawet przy czystej integracji problemy z wyszukiwaniem zwykle wpadają w kilka powtarzalnych kategorii. Dobrą wiadomością jest to, że Meilisearch daje wystarczającą widoczność (zadania, logi, deterministyczne ustawienia), by szybko debugować—jeśli podejdziesz do tego systematycznie.
filterableAttributes, albo dokumenty mają inne kształty pól (string vs array vs nested object).sortableAttributes/rankingRules mogą wypychać „złe” elementy na górę.Zacznij od sprawdzenia, czy Meilisearch pomyślnie zastosował ostatnią zmianę.
filter, potem sort, potem facets.Jeśli nie potrafisz wyjaśnić wyniku, tymczasowo uprość konfigurację: usuń synonimy, zredukować zmiany w regułach rankingowych i testuj na małym zbiorze. Złożone problemy trafności są łatwiejsze do zdiagnozowania na 50 dokumentach niż na 5 milionach.
your_index_v2 równolegle, zastosuj ustawienia i odtwórz próbkę zapytań produkcyjnych.filterableAttributes i sortableAttributes odpowiadają wymaganiom UI.Related guides: /blog (search reliability, indexing patterns, and production rollout tips).
Server-side search means the query runs on your backend (or a dedicated search service), not in the browser. It’s the right choice when:
Users notice four things immediately:
If one is missing, people retype queries, over-scroll, or abandon search.
Treat it as a search index, not your source of truth. Your database handles writes, transactions, and constraints; Meilisearch stores a copy of selected fields optimized for retrieval.
A useful mental model is:
A common default is one index per entity type (e.g., products, articles). This keeps:
If you need “search everything,” you can query multiple indexes and merge results in your backend, or add a dedicated global index later.
Pick a primary key that is:
id, sku, slug)Stable IDs make indexing idempotent: if you retry an upload, you won’t create duplicates because updates become safe upserts.
Classify each field by purpose so you don’t over-index:
Keeping these roles explicit reduces noisy results and prevents slow or bloated indexes.
Indexing is asynchronous: document uploads create a task, and documents become searchable only after that task succeeds.
A reliable flow is:
succeeded or failedIf results look stale, check task status before debugging anything else.
Use many smaller batches instead of one huge upload. Practical starting points:
Smaller batches are easier to retry, easier to debug (find bad records), and less likely to time out.
Two high-impact levers are:
searchableAttributes: which fields are searched, and in what priority orderpublishedAt, price, or popularityA practical approach is to take 5–10 real user queries, record top results “before,” change one setting, then compare “after.”
Most filter/sort issues come from missing configuration:
filterableAttributes to filter on itsortableAttributes to sort by itAlso verify field shape and types in documents (string vs array vs nested object). If a filter fails, inspect the last settings/task status and confirm the indexed documents actually contain the expected field values.