Typesense, silnik wyszukiwania na licencji GPL

Typesense, silnik wyszukiwania na licencji GPL

Typesense to napisany w C++ silnik wyszukiwania, który trzyma indeks w pamięci operacyjnej i domyślnie wybacza literówki w zapytaniu. Bieżąca wersja to 30.2 z 19 kwietnia 2026 roku, repozytorium typesense/typesense ma około 26,5 tysiąca gwiazdek, a licencja to GPL w wersji trzeciej, co odróżnia go od permisywnej konkurencji i ma realne konsekwencje przy niektórych sposobach dystrybucji.

Co Typesense właściwie robi

Całość to jeden plik wykonywalny, który wystawia API po HTTP i przyjmuje oraz zwraca JSON. Nie ma tu maszyny wirtualnej do skonfigurowania, nie ma osobnego procesu koordynującego, nie ma warstwy wtyczek. Uruchamiasz binarium ze wskazaniem katalogu na dane i klucza administracyjnego, a po chwili odpowiada na porcie 8108.

Dane organizujesz w kolekcje, czyli odpowiedniki tabel, z jawnie zadeklarowanym schematem pól. Każde pole ma typ, a dodatkowe flagi decydują o tym, czy da się po nim filtrować, fasetować i sortować. Dokumenty wrzucasz pojedynczo albo hurtowo w formacie JSONL, a indeks aktualizuje się od razu, bez osobnego kroku scalania segmentów.

Wyszukiwanie obsługuje dopasowanie z literówkami włączone domyślnie, filtrowanie po polach, fasety z licznikami, grupowanie wyników, synonimy, ręczne wypychanie wybranych rekordów na górę listy, zapytania geograficzne, dopasowanie wektorowe i tryb hybrydowy łączący jedno z drugim. Osobny punkt końcowy multi_search pozwala wysłać wiele zapytań w jednym żądaniu HTTP, co przy interfejsie z kilkoma polami podpowiedzi oszczędza sporo czasu na rundach sieciowych.

Kluczowa cecha architektury brzmi prosto: indeks siedzi w pamięci operacyjnej. Stąd bierze się przewidywalne opóźnienie, bo żadne zapytanie nie musi czekać na dysk, i stąd bierze się główny koszt eksploatacji, bo rozmiar zbioru danych przekłada się wprost na rozmiar maszyny. Planowanie wdrożenia Typesense zaczyna się od pytania, ile pamięci zajmą pola, które naprawdę indeksujesz.

Czego Typesense nie robi, jest równie istotne. Nie jest bazą transakcyjną i nie zastępuje PostgreSQL w roli źródła prawdy, więc dane wciąż trzymasz gdzie indziej i synchronizujesz je do indeksu. Nie jest też wyspecjalizowaną bazą wektorową w rozumieniu Qdranta czy Pinecone, choć wyszukiwanie po wektorach obsługuje. Nie ma również warstwy analitycznej i agregacji w stylu Elasticsearcha, bo to świadomie zawężony zakres.

Pozycja tego narzędzia jest właśnie pośrodku. Od Meilisearch różni się tym, że replikacja i praca w klastrze są częścią wersji otwartej. Od Elasticsearcha tym, że nie musisz uczyć się modelu węzłów, fragmentów i ról, żeby uruchomić pierwsze zapytanie.

Wersja, licencja i co GPL zmienia w praktyce

Wersja 30.2 ukazała się 19 kwietnia 2026 roku, tego samego dnia co poprawkowe 29.1. Repozytorium żyje: ostatnia zmiana w gałęzi głównej pochodzi z 18 sierpnia 2026 roku, jest 962 rozgałęzienia i 869 otwartych zgłoszeń, projekt nie jest zarchiwizowany. Kalkulator Typesense Cloud pozwala wybrać wersję 30.2, 29.1 oraz całą serię kandydatów 31.0.rc, więc następne wydanie główne można przetestować na zarządzanym klastrze przed premierą.

Licencja wygląda tak samo z każdej strony, co po innych projektach w tej kolekcji jest przyjemną odmianą. Plik LICENSE.txt w katalogu głównym repozytorium zawiera dosłowny tekst GNU General Public License w wersji 3 z 29 czerwca 2007 roku, bez dopisanych wyjątków ani klauzul odsyłających do innego pliku. Interfejs programistyczny GitHuba zwraca dla tego repozytorium GPL-3.0. Biblioteki klienckie idą osobną ścieżką i są permisywne: pakiet typesense w wersji 3.0.6 na npm deklaruje Apache-2.0 i faktycznie zawiera plik LICENSE z tekstem Apache 2.0 w opublikowanym archiwum, a pakiet typesense w wersji 2.0.0 na PyPI podaje Apache 2.0 wraz z odpowiednim klasyfikatorem OSI.

Jedna rozbieżność jednak jest i dotyczy dystrybucji binariów. Wydanie na GitHubie nie ma dołączonych plików, a gotowe binarium pobiera się z dl.typesense.org. Archiwum typesense-server-30.2-linux-amd64.tar.gz waży około 133 MB i zawiera dokładnie dwa wpisy: plik wykonywalny typesense-server oraz typesense-server.md5.txt z sumą kontrolną. Pliku licencyjnego w tym archiwum nie ma w ogóle. GPL wymaga, żeby przekazując program, przekazać razem z nim kopię licencji, więc jeśli budujesz własny obraz kontenera albo paczkę systemową na bazie tego archiwum i wysyłasz ją dalej, dołóż LICENSE.txt z repozytorium samodzielnie.

Teraz sedno, czyli co GPL oznacza dla silnika wyszukiwania. GPL w wersji trzeciej to nie AGPL i ta różnica rozstrzyga większość obaw. Obowiązki tej licencji uruchamia przekazanie programu innej osobie, a nie udostępnienie go przez sieć. Jeśli uruchamiasz Typesense na własnym serwerze, Twoja aplikacja odpytuje go po HTTP, a użytkownicy widzą tylko wyniki wyszukiwania, to nie przekazujesz nikomu programu i nie masz z tego tytułu żadnych zobowiązań. Dotyczy to również sytuacji, w której zmodyfikowałeś kod silnika na własne potrzeby i trzymasz te zmiany u siebie.

Obowiązki zaczynają się w momencie dystrybucji. Jeśli sprzedajesz produkt instalowany u klienta, wysyłasz urządzenie z wgranym oprogramowaniem albo przekazujesz obraz kontenera zawierający Typesense, to przekazujesz program objęty GPL. Wtedy musisz udostępnić odbiorcy odpowiadający kod źródłowy silnika razem z Twoimi zmianami w nim, na tej samej licencji, i dołączyć tekst licencji. Sam kod Twojej aplikacji, która rozmawia z silnikiem wyłącznie przez API po HTTP, pozostaje osobnym dziełem, bo granicą jest tutaj protokół sieciowy, a nie konsolidacja z biblioteką. Biblioteki klienckie na Apache 2.0 również niczego nie przenoszą.

To opis mechanizmu, a nie porada prawna, i przy modelu z instalacją u klienta warto ten temat przepuścić przez dział prawny. Praktyczny wniosek jest jednak spokojny: dla typowego zespołu budującego aplikację internetową GPL przy silniku wyszukiwania nie zmienia niczego, natomiast dla producenta oprogramowania pudełkowego zmienia bardzo dużo. Dla porównania, rdzeń Meilisearch jest na MIT i nie nakłada tych obowiązków w żadnym z tych scenariuszy, a wybór AGPLv3 w Elasticsearchu rozciąga je również na udostępnianie przez sieć.

Instalacja i pierwszy indeks

Najkrótsza droga do działającej instancji prowadzi przez kontener, a produkcyjnie przez paczkę systemową albo binarium z katalogiem na dane.

docker run -d --name typesense -p 8108:8108 \
  -v /var/lib/typesense:/data \
  typesense/typesense:30.2 \
  --data-dir /data \
  --api-key=$TYPESENSE_ADMIN_KEY \
  --enable-cors

curl "http://localhost:8108/health"

curl "http://localhost:8108/collections" \
  -X POST \
  -H "X-TYPESENSE-API-KEY: $TYPESENSE_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d @products-schema.json

Schemat kolekcji to zwykły JSON, w którym każde pole dostaje typ i opcjonalne flagi.

{
  "name": "products",
  "fields": [
    { "name": "title", "type": "string" },
    { "name": "brand", "type": "string", "facet": true },
    { "name": "categories", "type": "string[]", "facet": true },
    { "name": "price", "type": "float" },
    { "name": "in_stock", "type": "bool", "facet": true },
    { "name": "num_reviews", "type": "int32" }
  ],
  "default_sorting_field": "num_reviews"
}

Trzy szczegóły z tego pliku decydują o tym, czy za miesiąc będziesz przebudowywać kolekcję. Pole default_sorting_field musi wskazywać pole typu int32 albo float i porządkuje wyniki wtedy, gdy zapytanie nie podaje własnego sort_by, więc powinno oddawać jakąś miarę popularności. Flaga sort domyślnie jest włączona dla liczb i wyłączona dla pozostałych typów, więc sortowanie po polu tekstowym trzeba zadeklarować jawnie. Flaga infix pozwala dopasowywać fragment w środku wyrazu i jest domyślnie wyłączona, bo dokumentacja wprost ostrzega przed jej kosztem pamięciowym.

Dokumenty wgrywasz hurtowo w formacie JSONL, po jednym obiekcie w linii. Import przyjmuje parametr action z wartościami create, upsert, update i emplace, a przy dużych zbiorach dzieli się go na paczki po kilka tysięcy linii.

curl "http://localhost:8108/collections/products/documents/import?action=upsert" \
  -X POST \
  -H "X-TYPESENSE-API-KEY: $TYPESENSE_ADMIN_KEY" \
  --data-binary @products.jsonl

curl "http://localhost:8108/collections/products/documents/search\
?q=kurtka&query_by=title,brand&filter_by=in_stock:true" \
  -H "X-TYPESENSE-API-KEY: $TYPESENSE_SEARCH_KEY"

Wyszukiwanie, literówki i wektory

Zapytanie z poziomu aplikacji zwykle idzie przez bibliotekę kliencką. Poniżej wywołanie w JavaScripcie z parametrami, które w praktyce ustawia się najczęściej.

import Typesense from 'typesense'

const client = new Typesense.Client({
  nodes: [{ host: 'localhost', port: 8108, protocol: 'http' }],
  apiKey: process.env.TYPESENSE_SEARCH_KEY,
  connectionTimeoutSeconds: 2
})

const wyniki = await client
  .collections('products')
  .documents()
  .search({
    q: 'kurtak zimowa',
    query_by: 'title,brand,categories',
    query_by_weights: '4,2,1',
    filter_by: 'in_stock:true && price:<500',
    facet_by: 'brand,categories',
    sort_by: '_text_match:desc,num_reviews:desc',
    num_typos: '2,1,0',
    exclude_fields: 'embedding',
    per_page: 20
  })

Kolejność pól w query_by ma znaczenie, bo wyznacza priorytet dopasowania, a query_by_weights pozwala ten priorytet wyrazić liczbami zamiast samą kolejnością. Parametr num_typos przyjmuje osobną wartość dla każdego pola z listy, więc w powyższym przykładzie tytuł toleruje dwie literówki, marka jedną, a kategorie żadnej. Do strojenia zachowania przy trudnych zapytaniach służą jeszcze dwa parametry: typo_tokens_threshold decyduje, przy jakiej liczbie znalezionych trafień silnik w ogóle sięga po wersję zapytania z literówkami, a drop_tokens_threshold pozwala odrzucać kolejne słowa zapytania, gdy komplet słów nie daje wyników. Warto też pamiętać o exclude_fields, bo pole z wektorem osadzeń potrafi ważyć w odpowiedzi więcej niż cała reszta dokumentu.

Wyszukiwanie semantyczne konfiguruje się w schemacie, a nie w zapytaniu. Pole typu float[] z sekcją embed każe silnikowi policzyć osadzenia samodzielnie podczas indeksowania.

{
  "name": "products",
  "fields": [
    { "name": "title", "type": "string" },
    { "name": "description", "type": "string" },
    {
      "name": "embedding",
      "type": "float[]",
      "embed": {
        "from": ["title", "description"],
        "model_config": { "model_name": "ts/all-MiniLM-L12-v2" }
      }
    }
  ]
}

Modele z przedrostkiem ts/ pochodzą z repozytorium Typesense na Hugging Face i pobierają się automatycznie przy pierwszym indeksowaniu. Osadzenia przeliczają się ponownie tylko wtedy, gdy zmieni się któreś z pól wymienionych w embed.from, więc aktualizacja stanu magazynowego nie uruchamia kosztownego przeliczania. Gdy do query_by wpiszesz razem pola tekstowe i pole z osadzeniami, silnik wykona wyszukiwanie hybrydowe i połączy obie listy wzorem rank_fusion_score = 0.7 * K + 0.3 * S, gdzie K to pozycja dokumentu w wynikach tekstowych, a S w semantycznych. Proporcje zmienia parametr alpha. Jeśli osadzenia liczysz po swojej stronie, pomijasz pole wektorowe w query_by i podajesz gotowy wektor przez vector_query.

Klaster, replikacja i wysoka dostępność

To jest miejsce, w którym Typesense odsuwa się od najprostszych rozwiązań. Klaster działa na algorytmie Raft, replikuje cały zbiór danych na wszystkie węzły i robi to w wersji otwartej, bez modułu komercyjnego i bez zmiany licencji.

Konfiguracja sprowadza się do jednego pliku z listą węzłów, wskazanego przez --nodes. Każdy wpis ma postać <peering_address>:<peering_port>:<api_port>, a wpisy rozdziela się przecinkami.

# /etc/typesense/nodes
192.168.12.1:8107:8108,192.168.12.2:8107:8108,192.168.12.3:8107:8108

typesense-server \
  --data-dir=/var/lib/typesense \
  --api-key=$TYPESENSE_ADMIN_KEY \
  --api-address=0.0.0.0 \
  --api-port=443 \
  --peering-address=192.168.12.1 \
  --peering-port=8107 \
  --nodes=/etc/typesense/nodes \
  --ssl-certificate=/etc/ssl/typesense.crt \
  --ssl-certificate-key=/etc/ssl/typesense.key

Kilka reguł wynika wprost z natury Raft i z dokumentacji. Kworum wymaga większości, więc trzy węzły przeżyją awarię jednego, a pięć węzłów awarię dwóch, przy nieco wyższym opóźnieniu zapisów. Zapisy przyjęte przez dowolny węzeł są wewnętrznie przekazywane do lidera, a odczyty obsługuje ten węzeł, który dostał żądanie, więc dokładanie węzłów zwiększa przepustowość wyszukiwania. Wszystkie węzły muszą startować z tym samym kluczem administracyjnym. Adres podany w --peering-address powinien być adresem prywatnym, bo ruch Raft między węzłami nie jest szyfrowany, natomiast --api-address może być publiczny i to on obsługuje klientów.

Przy awariach przydają się dwa dodatkowe parametry. --snapshot-interval-seconds steruje częstotliwością zrzutów stanu, z których odtwarza się węzeł dołączający do klastra, a --reset-peers-on-error pozwala klastrowi samodzielnie odbudować listę uczestników po utracie kworum. Po stronie klienta biblioteki oficjalne przyjmują listę węzłów i same sprawdzają ich zdrowie, a parametr nearestNode pozwala kierować ruch do najbliższego z nich, więc równoważnik obciążenia nie jest obowiązkowy.

Dla porównania, w wersji otwartej Meilisearch replikacja i podział na fragmenty są objęte osobnymi warunkami licencyjnymi, a nie zwykłym MIT. Jeśli szukasz czegoś prostszego od Elasticsearcha, ale nie chcesz przy okazji rezygnować z odporności na awarię jednej maszyny, to właśnie ta różnica przesądza wybór.

Typesense Cloud, cennik i funkcje tylko w chmurze

Usługa zarządzana sprzedaje dedykowany klaster, a nie plan z limitami. Strona cennika mówi wprost, że nie ma ograniczeń liczby rekordów ani operacji, a stawkę godzinową wyznacza konfiguracja: ilość pamięci, liczba rdzeni wirtualnych oraz przełączniki na dysk o wyższej wydajności, akcelerację GPU do liczenia osadzeń, wysoką dostępność i sieć dostarczania wyszukiwania. Do wyboru jest 26 lokalizacji centrów danych.

Poniższe stawki odczytałem z kalkulatora 21 sierpnia 2026 roku. Arytmetyka się zgadza: kwota miesięczna to stawka godzinowa razy 720 godzin.

Trzeci wiersz zasługuje na uwagę, bo trzy węzły kosztują 3,3 razy więcej niż jeden, a nie trzykrotnie. Narzut jest niewielki, ale przy planowaniu budżetu lepiej go znać. Wsparcie podstawowe jest w cenie, a plany priorytetowe są płatne osobno.

Jest tu jedna rozbieżność w komunikacji. Znacznik opisu strony cennika obiecuje hojny plan darmowy, natomiast sam kalkulator nie zawiera żadnej opcji o zerowym koszcie, a najtańsza konfiguracja to wspomniane 0,03 USD za godzinę. Jeśli liczysz na darmowy klaster na stałe, tak jak w Supabase czy w chmurze Qdranta, potwierdź to przed założeniem konta, bo strona kalkulatora tego nie pokazuje.

Część funkcji istnieje wyłącznie w usłudze zarządzanej i dokumentacja oznacza je w spisie treści dopiskiem o chmurze. Są to: sieć dostarczania wyszukiwania, czyli rozłożenie klastra na trzy lub pięć regionów z kierowaniem zapytania do najbliższego, konta zespołowe, kontrola dostępu oparta na rolach w panelu administracyjnym oraz logowanie jednokrotne. Chmura zdejmuje też z Ciebie obsługę wysokiej dostępności i daje pojedynczy adres z równoważeniem obciążenia, przy czym dokumentacja zaznacza, że taki adres widzą tylko klastry utworzone po 16 czerwca 2022 roku.

Przywiązanie do dostawcy jest tu umiarkowane, bo pod spodem pracuje to samo otwarte binarium, a dane wyprowadzisz przez zwykły eksport dokumentów. Tracisz natomiast cztery funkcje wymienione wyżej i musisz samodzielnie zbudować to, co daje panel: kopie zapasowe, aktualizacje wersji i monitorowanie.

Typesense a alternatywy

Wybór rozstrzyga się na kilku pytaniach. Jeśli zbiór jest mały, ruch niewielki, a dane i tak leżą w bazie relacyjnej, zacznij od wyszukiwania pełnotekstowego w PostgreSQL i nie dokładaj kolejnego systemu do utrzymania. Jeśli potrzebujesz szybkiego wyszukiwania z literówkami i fasetami, a jedna maszyna wystarcza, Meilisearch i Typesense są blisko siebie, przy czym różni je licencja i to, co dostajesz w wersji otwartej. Jeśli chcesz replikacji bez opłat licencyjnych, Typesense wygrywa z Meilisearch. Jeśli potrzebujesz agregacji, analityki logów, wielu typów zapytań i całego ekosystemu wtyczek, żadne z tych dwóch narzędzi nie zastąpi Elasticsearcha. A jeśli głównym zadaniem jest podobieństwo wektorowe na dużą skalę z filtrowaniem po metadanych, sięgnij po bazę wektorową.

Typowe błędy

Pierwszy to mylenie GPL z AGPL w obie strony. Zespoły niepotrzebnie rezygnują z Typesense, bo obawiają się obowiązku otwarcia kodu aplikacji internetowej, którego przy GPL po prostu nie ma. Odwrotnie, producenci oprogramowania instalowanego u klienta bywają zaskoczeni, że przekazanie obrazu z silnikiem uruchamia obowiązek udostępnienia kodu źródłowego silnika razem z modyfikacjami.

Drugi to redystrybucja archiwum wydania bez pliku licencyjnego. W archiwum z dl.typesense.org są tylko binarium i suma kontrolna, więc własny obraz kontenera zbudowany na jego podstawie trzeba uzupełnić o tekst licencji z repozytorium.

Trzeci to niedoszacowanie pamięci. Indeks żyje w RAM, więc dobranie najtańszej konfiguracji do zbioru, który urośnie dwukrotnie w pół roku, kończy się przenoszeniem klastra. Zanim wybierzesz rozmiar, policz sumę rozmiarów pól, które faktycznie indeksujesz, i pamiętaj, że flaga infix ten rachunek zauważalnie podnosi.

Czwarty to klucz administracyjny w przeglądarce. Klucz z pełnymi uprawnieniami pozwala skasować kolekcję, więc do interfejsu użytkownika generuj klucz o zawężonych uprawnieniach do samego wyszukiwania, a przy wielu najemcach klucz ograniczony dodatkowym filtrem.

Piąty to klaster z dwóch węzłów. Raft wymaga większości, więc dwa węzły nie przeżyją awarii żadnego z nich i dają jedynie iluzję zapasu. Minimum, które cokolwiek zmienia, to trzy.

Szósty to publiczny adres w --peering-address. Ruch Raft nie jest szyfrowany, więc ten adres należy do sieci prywatnej, a na zewnątrz wystawiasz wyłącznie --api-address z certyfikatem.

Siódmy to schemat zaprojektowany bez myśli o fasetach i sortowaniu. Dołożenie flagi facet albo sort do istniejącego pola wymaga zmiany kolekcji i ponownego zaindeksowania tego pola, co przy dużym zbiorze jest operacją planowaną, a nie jednym żądaniem między jednym wdrożeniem a drugim.

FAQ

Czy licencja GPL zmusza mnie do otwarcia kodu mojej aplikacji?

Nie, jeśli tylko uruchamiasz Typesense na swoim serwerze i odpytujesz go przez API. GPL w wersji trzeciej wiąże obowiązki z przekazaniem programu, a nie z udostępnieniem go przez sieć, więc udostępnianie usługi użytkownikom nie jest dystrybucją. Obowiązek udostępnienia kodu źródłowego silnika wraz z Twoimi zmianami pojawia się dopiero wtedy, gdy przekazujesz komuś binarium, na przykład w produkcie instalowanym u klienta.

Czym Typesense różni się od Meilisearch?

Zakres funkcji jest podobny: oba mają tolerancję literówek domyślnie, fasety, filtry i wyszukiwanie hybrydowe, oba to pojedyncze binarium. Różnice są dwie i obie licencyjne. Typesense jest na GPL-3.0 i daje klastrowanie oparte na Raft w wersji otwartej. Meilisearch ma rdzeń na MIT, czyli licencję łagodniejszą przy dystrybucji, ale replikacja i podział na fragmenty są tam objęte osobnymi warunkami.

Czy Typesense zastąpi Elasticsearcha?

W zastosowaniach wyszukiwania w katalogu produktów, w dokumentacji albo w treściach serwisu zwykle tak, przy zauważalnie mniejszym nakładzie na utrzymanie. Nie zastąpi go tam, gdzie liczą się złożone agregacje, analiza logów, przetwarzanie strumieni i ekosystem wtyczek. Jeśli używasz Elasticsearcha wyłącznie jako wyszukiwarki tekstowej, migracja jest realna, a jeśli jako składnicy danych operacyjnych, to jest inna klasa systemu.

Ile pamięci potrzebuje klaster?

Tyle, ile zajmie indeks powiększony o zapas na wzrost i na operacje. Punktem wyjścia jest suma rozmiarów pól, które naprawdę indeksujesz, a nie rozmiar całych dokumentów, bo pola przechowywane bez indeksowania kosztują mniej. Kalkulator w chmurze ma asystenta, któremu podajesz liczbę rekordów i średni rozmiar jednego rekordu, i który proponuje konfigurację wyjściową.

Czy Typesense Cloud ma plan darmowy?

Kalkulator cennika nie pokazuje żadnej opcji o zerowym koszcie, a najtańsza konfiguracja z 0,5 GB pamięci kosztuje 0,03 USD za godzinę, co strona przelicza na 21,60 USD miesięcznie. Znacznik opisu tej samej strony wspomina jednak o hojnym planie darmowym, więc mamy tu dwie sprzeczne informacje od tego samego dostawcy i przed założeniem konta wypada to potwierdzić.

Czy da się przenieść klaster z chmury na własny serwer?

Tak, bo w chmurze pracuje to samo otwarte binarium w wybranej przez Ciebie wersji. Dokumenty eksportujesz przez punkt końcowy eksportu, schematy kolekcji pobierasz jako JSON i odtwarzasz je na własnej instancji. Poza usługą zarządzaną zostają sieć dostarczania wyszukiwania, konta zespołowe, role w panelu i logowanie jednokrotne, a obsługę kopii zapasowych oraz aktualizacji przejmujesz sam.

Dokumentację znajdziesz na stronie Typesense, cennik chmury na stronie cennika, a kod źródłowy w repozytorium na GitHubie.