Guide

Typesense, un moteur de recherche sous licence GPL

Typesense est un moteur de recherche en mémoire, tolérant aux fautes de frappe. Licence GPL v3, vecteurs, cluster Raft, tarifs du cloud et alternatives.

L'équipe CodeWorlds20 min de lecture ·

Pratique HTML et CSS dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article9

Typesense est un moteur de recherche écrit en C++ qui garde son index en mémoire et pardonne par défaut les fautes de frappe dans la requête. La version actuelle est la 30.2, publiée le 19 avril 2026, le dépôt typesense/typesense compte environ 26,5 mille étoiles, et la licence est la version trois de la GPL, ce qui le distingue de ses concurrents à licence permissive et entraîne de vraies conséquences pour certaines formes de distribution.

Ce que fait vraiment Typesense

L'ensemble est un seul exécutable qui expose une API en HTTP et parle JSON dans les deux sens. Il n'y a pas de machine virtuelle à configurer, pas de processus de coordination séparé, pas de couche de plugins. Vous démarrez le binaire en lui indiquant un répertoire de données et une clé d'administration, et quelques instants plus tard il répond sur le port 8108.

Les données sont organisées en collections, l'équivalent des tables, avec un schéma de champs déclaré explicitement. Chaque champ a un type, et des options supplémentaires déterminent si l'on peut filtrer, faire des facettes et trier dessus. Les documents entrent un par un ou en masse au format JSONL, et l'index se met à jour immédiatement, sans étape distincte de fusion de segments.

La recherche couvre la correspondance tolérante aux fautes activée par défaut, le filtrage sur des champs, les facettes avec comptages, le regroupement des résultats, les synonymes, l'épinglage manuel d'enregistrements choisis en tête, les requêtes géographiques, la correspondance vectorielle et un mode hybride qui combine les deux dernières avec la première. Un endpoint séparé multi_search permet d'envoyer plusieurs requêtes dans une seule requête HTTP, ce qui économise beaucoup d'allers-retours réseau dans une interface qui a plus d'un champ de suggestion.

La caractéristique architecturale clé est simple à énoncer : l'index vit en mémoire principale. C'est de là que vient la latence prévisible, puisqu'aucune requête n'attend un disque, et c'est aussi de là que vient le principal coût d'exploitation, puisque la taille du jeu de données se traduit directement en taille de la machine. Planifier un déploiement de Typesense commence par la question de la quantité de mémoire que prendront les champs que vous indexez réellement.

Ce que Typesense ne fait pas compte tout autant. Ce n'est pas une base de données transactionnelle et il ne remplace pas PostgreSQL comme source de vérité, donc vos données vivent toujours ailleurs et sont synchronisées dans l'index. Ce n'est pas non plus une base vectorielle spécialisée au sens de Qdrant ou Pinecone, même s'il gère la recherche vectorielle. Il n'a pas non plus de couche d'analyse et d'agrégation dans le style d'Elasticsearch, car le périmètre est volontairement étroit.

La position de cet outil se situe précisément au milieu. Il diffère de Meilisearch en ce que la réplication et le fonctionnement en cluster font partie de la version ouverte. Il diffère d'Elasticsearch en ce qu'il n'est pas nécessaire d'apprendre un modèle de nœuds, de shards et de rôles avant d'exécuter sa première requête.

Version, licence et ce que la GPL change en pratique

La version 30.2 est arrivée le 19 avril 2026, le même jour que la version corrective 29.1. Le dépôt est vivant : le dernier changement sur la branche principale date du 18 août 2026, il y a 962 forks et 869 issues ouvertes, et le projet n'est pas archivé. Le calculateur de Typesense Cloud propose les versions 30.2, 29.1 et toute une série de candidates 31.0.rc, donc la prochaine version majeure peut être testée sur un cluster géré avant sa sortie.

La licence paraît identique sous tous les angles, ce qui après d'autres projets de cette collection est un changement agréable. Le fichier LICENSE.txt à la racine du dépôt contient le texte intégral de la GNU General Public License version 3 du 29 juin 2007, sans exceptions ajoutées ni clauses renvoyant à un autre fichier. L'interface de programmation de GitHub indique GPL-3.0 pour ce dépôt. Les bibliothèques clientes suivent une voie séparée et permissive : le paquet typesense en version 3.0.6 sur npm déclare Apache-2.0 et livre réellement un fichier LICENSE avec le texte d'Apache 2.0 dans l'archive publiée, tandis que le paquet typesense en version 2.0.0 sur PyPI indique Apache 2.0 avec le classifieur OSI correspondant.

Une divergence existe et elle concerne la distribution des binaires. La release GitHub ne porte aucun fichier joint, et le binaire prêt à l'emploi se télécharge depuis dl.typesense.org. L'archive typesense-server-30.2-linux-amd64.tar.gz pèse environ 133 Mo et contient exactement deux entrées : l'exécutable typesense-server et typesense-server.md5.txt avec une somme de contrôle. Il n'y a aucun fichier de licence dans cette archive. La GPL exige qu'une copie de la licence accompagne le programme que vous transmettez, donc si vous construisez votre propre image de conteneur ou paquet système à partir de cette archive et le transmettez, ajoutez vous-même le LICENSE.txt du dépôt.

Voici maintenant le cœur du sujet, c'est-à-dire ce que la GPL implique pour un moteur de recherche. La version trois de la GPL n'est pas l'AGPL, et cette différence règle l'essentiel de l'inquiétude. Ses obligations se déclenchent par la transmission du programme à une autre personne, pas par sa mise à disposition sur un réseau. Si vous faites tourner Typesense sur votre propre serveur, que votre application l'interroge en HTTP et que les utilisateurs ne voient que des résultats de recherche, vous ne transmettez le programme à personne et ne devez rien. Il en va de même si vous avez modifié le moteur pour vos besoins et gardez ces changements pour vous.

Les obligations commencent à la distribution. Si vous vendez un produit installé chez un client, livrez un appareil avec un logiciel chargé dessus ou remettez une image de conteneur contenant Typesense, vous transmettez un programme couvert par la GPL. Vous devez alors mettre à disposition du destinataire le code source correspondant du moteur, avec vos modifications, sous la même licence, et inclure le texte de la licence. Le code de votre propre application, qui ne parle au moteur que par une API HTTP, reste une œuvre distincte, car la frontière est ici un protocole réseau plutôt qu'une liaison avec une bibliothèque. Les bibliothèques clientes sous Apache 2.0 n'entraînent rien non plus.

Ceci décrit le mécanisme et ne constitue pas un conseil juridique, et avec un modèle d'installation chez le client, le sujet vaut d'être soumis à votre service juridique. La conclusion reste cependant sereine : pour une équipe typique qui construit une application web, un moteur de recherche GPL ne change rien, alors que pour un éditeur de logiciel livré il change beaucoup. Le cœur de Meilisearch, en comparaison, est sous MIT et n'impose rien de tout cela dans les deux scénarios, tandis que choisir l'AGPLv3 dans Elasticsearch étend les mêmes obligations à la mise à disposition sur un réseau.

Installation et premier index

Le chemin le plus court vers une instance en marche passe par un conteneur, et en production par un paquet système ou le binaire avec un répertoire de données.

Bash
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

Un schéma de collection est du JSON ordinaire dans lequel chaque champ reçoit un type et des options facultatives.

JSON
{
  "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"
}

Trois détails de ce fichier décident si vous reconstruirez la collection dans un mois. Le default_sorting_field doit pointer vers un champ int32 ou float et ordonne les résultats chaque fois qu'une requête ne fournit pas son propre sort_by, donc il doit exprimer une mesure de popularité. L'option sort est activée par défaut pour les nombres et désactivée pour les autres types, donc trier sur un champ texte doit être déclaré explicitement. L'option infix permet de faire correspondre un fragment à l'intérieur d'un mot et est désactivée par défaut, car la documentation avertit franchement de son coût en mémoire.

Les documents sont chargés en masse au format JSONL, un objet par ligne. L'import accepte un paramètre action avec les valeurs create, upsert, update et emplace, et les gros jeux de données sont découpés en lots de quelques milliers de lignes.

Bash
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=jacket&query_by=title,brand&filter_by=in_stock:true" \
  -H "X-TYPESENSE-API-KEY: $TYPESENSE_SEARCH_KEY"

Recherche, fautes de frappe et vecteurs

Une requête depuis l'intérieur d'une application passe généralement par une bibliothèque cliente. Voici un appel JavaScript avec les paramètres que l'on règle le plus souvent en pratique.

JavaScript
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 results = await client
  .collections('products')
  .documents()
  .search({
    q: 'wintr jacket',
    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
  })

L'ordre des champs dans query_by compte, car il fixe la priorité de correspondance, et query_by_weights exprime cette priorité en nombres au lieu de se fier à l'ordre seul. Le paramètre num_typos prend une valeur distincte par champ, donc ci-dessus le titre tolère deux fautes, la marque une et les catégories aucune. Deux autres paramètres règlent le comportement sur les requêtes difficiles : typo_tokens_threshold décide à partir de quel nombre de résultats le moteur recourt à la version tolérante aux fautes de la requête, tandis que drop_tokens_threshold autorise à retirer des mots successifs de la requête quand l'ensemble complet ne renvoie rien. exclude_fields mérite aussi réflexion, car un champ de vecteur d'embedding peut peser plus dans la réponse que le reste du document.

La recherche sémantique se configure dans le schéma plutôt que dans la requête. Un champ float[] avec une section embed dit au moteur de calculer lui-même les embeddings pendant l'indexation.

JSON
{
  "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" }
      }
    }
  ]
}

Les modèles préfixés par ts/ viennent du dépôt Typesense sur Hugging Face et se téléchargent automatiquement à la première indexation. Les embeddings ne sont recalculés que lorsqu'un des champs listés dans embed.from change, donc une mise à jour du niveau de stock ne déclenche pas de recalcul coûteux. Quand vous mettez ensemble dans query_by des champs texte et le champ d'embedding, le moteur effectue une recherche hybride et combine les deux listes avec la formule rank_fusion_score = 0.7 * K + 0.3 * S, où K est le rang du document dans les résultats par mots-clés et S son rang dans les résultats sémantiques. Les proportions se changent avec le paramètre alpha. Si vous calculez les embeddings de votre côté, vous omettez le champ vectoriel de query_by et passez le vecteur prêt par vector_query.

Cluster, réplication et haute disponibilité

C'est là que Typesense se détache des options les plus simples. Un cluster fonctionne sur l'algorithme Raft, réplique tout le jeu de données sur chaque nœud, et le fait dans la version ouverte, sans module commercial ni changement de licence.

La configuration se résume à un seul fichier qui liste les nœuds, désigné par --nodes. Chaque entrée a la forme <peering_address>:<peering_port>:<api_port>, et les entrées sont séparées par des virgules.

Bash
# /etc/typesense/nodes
192.168.12.1:8107:8108,192.168.12.2:8107:8108,192.168.12.3:8107:8108
Bash
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

Plusieurs règles découlent de la nature de Raft et de la documentation. Un quorum a besoin d'une majorité, donc trois nœuds survivent à la panne d'un et cinq nœuds à la panne de deux, au prix d'une latence d'écriture légèrement plus élevée. Les écritures acceptées par n'importe quel nœud sont transmises en interne au leader, tandis que les lectures sont servies par le nœud qui les a reçues, donc ajouter des nœuds augmente le débit de recherche. Chaque nœud démarre avec la même clé d'administration. L'adresse de --peering-address doit être privée, car le trafic Raft entre nœuds n'est pas chiffré, alors que --api-address peut être publique et sert les clients.

Deux autres paramètres se rentabilisent lors des pannes. --snapshot-interval-seconds règle la fréquence des instantanés d'état, ceux à partir desquels un nœud qui rejoint le cluster se restaure, et --reset-peers-on-error permet à un cluster de reconstruire sa liste de membres après avoir perdu le quorum. Côté client, les bibliothèques officielles acceptent une liste de nœuds et en vérifient elles-mêmes la santé, et nearestNode oriente le trafic vers le plus proche, donc un répartiteur de charge n'est pas obligatoire.

En comparaison, dans la version ouverte de Meilisearch, la réplication et le sharding relèvent de conditions de licence séparées plutôt que du simple MIT. Si vous cherchez quelque chose de plus simple qu'Elasticsearch sans renoncer au passage la tolérance à la panne d'une machine, c'est cette différence qui tranche le choix.

Typesense Cloud, tarifs et fonctions réservées au cloud

Le service géré vend un cluster dédié plutôt qu'une offre avec des limites. La page des tarifs indique franchement qu'il n'y a pas de plafond sur les enregistrements ou les opérations, et le tarif horaire découle de la configuration : quantité de mémoire, nombre de cœurs virtuels, plus des options pour un disque plus performant, l'accélération GPU pour calculer les embeddings, la haute disponibilité et un réseau de diffusion de recherche. Il y a 26 emplacements de centres de données au choix.

Les tarifs ci-dessous ont été relevés sur le calculateur le 21 août 2026. L'arithmétique tient : le chiffre mensuel est le tarif horaire multiplié par 720 heures.

ConfigurationTarif horaireChiffre mensuel de la page
0,5 Go de RAM, 2 vCPU avec une heure de burst par jour0,03 USD21,60 USD
4 Go de RAM, 2 vCPU avec quatre heures de burst par jour0,10 USD72,00 USD
4 Go de RAM, la même configuration avec haute disponibilité sur trois nœuds0,33 USD237,60 USD
Trafic sortant0,09 USD par Godépend du trafic

La troisième ligne mérite attention, car trois nœuds coûtent 3,3 fois plus qu'un seul et non trois fois. Le surcoût est faible, mais il vaut mieux le connaître que le découvrir en établissant un budget. Le support de base est inclus, et les offres prioritaires se paient séparément.

Il y a une incohérence dans le message. La balise meta de description de la page des tarifs promet une généreuse offre gratuite, alors que le calculateur lui-même ne contient aucune option à coût nul, la configuration la moins chère étant les 0,03 USD par heure mentionnés plus haut. Si vous comptez sur un cluster gratuit permanent, comme en proposent Supabase ou le cloud de Qdrant, confirmez-le avant d'ouvrir un compte, car la page du calculateur ne le montre pas.

Certaines fonctions n'existent que dans le service géré, et la documentation les signale dans sa table des matières avec une note cloud : le réseau de diffusion de recherche, c'est-à-dire un cluster réparti sur trois ou cinq régions avec les requêtes dirigées vers la plus proche, les comptes d'équipe, le contrôle d'accès par rôles dans le tableau de bord d'administration et l'authentification unique. Le cloud prend aussi en charge la haute disponibilité et vous donne un seul point d'accès à répartition de charge, bien que la documentation précise que seuls les clusters créés après le 16 juin 2022 voient un tel point d'accès.

La dépendance à l'éditeur est ici modérée, car le même binaire ouvert tourne en dessous et les données sortent par un export de documents ordinaire. Ce que vous perdez, ce sont les quatre fonctions ci-dessus, et vous reconstruisez vous-même ce que le tableau de bord fournissait : sauvegardes, montées de version et supervision.

Typesense face aux alternatives

CaractéristiqueTypesenseMeilisearchElasticsearchPostgreSQLQdrant
Licence du moteurGPL-3.0MIT avec modules BSLAGPLv3, ELv2 ou SSPLlicence PostgreSQLApache 2.0
Déploiementun seul binaireun seul binaireun cluster sur la machine virtuelle Javaun serveur de base de donnéesun processus ou un conteneur
Réplication dans la version ouverteoui, Raft à partir de trois nœudslimitée par les conditions des modulesouioui, réplication en fluxoui
Fautes de frappe dans la requêteactivées par défautactivées par défautvia un paramètre de fuzzinessvia une extension de trigrammessans objet
Vecteursoui, avec embedding automatiqueoui, mode hybrideouivia l'extension pgvectorle cœur du produit
Cloud de l'éditeurTypesense Cloud, facturation horaireMeilisearch CloudElastic Cloudnombreux fournisseurs gérésQdrant Cloud avec une offre gratuite

Le choix se ramène à quelques questions. Si le jeu de données est petit, le trafic modeste et les données déjà dans une base relationnelle, commencez par la recherche plein texte de PostgreSQL et n'ajoutez pas un autre système à maintenir. Si vous avez besoin d'une recherche rapide tolérante aux fautes avec des facettes et qu'une seule machine suffit, Meilisearch et Typesense sont proches, avec des différences de licence et de contenu de la version ouverte. Si vous voulez la réplication sans frais de licence, Typesense l'emporte sur Meilisearch. Si vous avez besoin d'agrégations, d'analyse de logs, de nombreux types de requêtes et de tout un écosystème de plugins, aucun de ces deux ne remplace Elasticsearch. Et si le travail principal est la similarité vectorielle à grande échelle avec filtrage sur les métadonnées, prenez plutôt une base vectorielle.

Erreurs courantes

La première est de confondre la GPL et l'AGPL dans les deux sens. Des équipes renoncent à Typesense sans nécessité, craignant une obligation d'ouvrir le code de leur application web que la GPL n'impose tout simplement pas. Dans l'autre sens, des éditeurs de logiciels installés chez les clients sont parfois surpris que la remise d'une image contenant le moteur déclenche l'obligation de fournir le code source du moteur avec toutes les modifications.

La deuxième est de redistribuer l'archive de la version sans fichier de licence. L'archive de dl.typesense.org ne contient que le binaire et une somme de contrôle, donc une image de conteneur construite dessus a besoin que le texte de la licence du dépôt y soit rajouté.

La troisième est de sous-estimer la mémoire. L'index vit en RAM, donc choisir la configuration la moins chère pour un jeu de données qui doublera en six mois finit par un déménagement du cluster. Avant de choisir une taille, additionnez les tailles des champs que vous indexez réellement, et souvenez-vous que l'option infix alourdit sensiblement cette note.

La quatrième est une clé d'administration dans le navigateur. Une clé avec tous les droits peut supprimer une collection, donc générez pour l'interface utilisateur une clé limitée à la seule recherche, et pour les configurations multi-locataires une clé encore restreinte par un filtre intégré.

La cinquième est un cluster de deux nœuds. Raft exige une majorité, donc deux nœuds ne survivent à la panne d'aucun et ne procurent qu'une illusion de redondance. Le minimum qui change quelque chose est trois.

La sixième est une adresse publique dans --peering-address. Le trafic Raft n'est pas chiffré, donc cette adresse doit être sur un réseau privé, et ce que vous exposez vers l'extérieur est seulement --api-address avec un certificat.

La septième est un schéma conçu sans penser aux facettes ni au tri. Ajouter l'option facet ou sort à un champ existant exige de modifier la collection et de réindexer ce champ, ce qui sur un grand jeu de données est une opération planifiée plutôt qu'une requête glissée entre deux déploiements.

FAQ

La GPL m'oblige-t-elle à ouvrir le code de mon application ?

Non, pas si vous faites simplement tourner Typesense sur votre propre serveur et l'interrogez via l'API. La version trois de la GPL lie les obligations à la transmission du programme plutôt qu'à sa mise à disposition sur un réseau, donc proposer un service aux utilisateurs n'est pas de la distribution. L'obligation de fournir le code source du moteur avec vos modifications n'apparaît que lorsque vous remettez un binaire à quelqu'un, par exemple à l'intérieur d'un produit installé chez un client.

En quoi Typesense diffère-t-il de Meilisearch ?

L'étendue des fonctions est similaire : tous deux ont la tolérance aux fautes activée par défaut, des facettes, des filtres et la recherche hybride, et tous deux sont un seul binaire. Les différences sont de deux ordres et concernent toutes deux la licence. Typesense est sous GPL-3.0 et offre le clustering Raft dans la version ouverte. Meilisearch a un cœur MIT, une licence plus douce quant à la distribution, mais la réplication et le sharding y relèvent de conditions séparées.

Typesense remplacera-t-il Elasticsearch ?

Pour chercher dans un catalogue de produits, une documentation ou le contenu d'un site, il le fera généralement, à un coût de maintenance nettement plus bas. Il ne le remplacera pas là où comptent des agrégations complexes, l'analyse de logs, le traitement de flux et un écosystème de plugins. Si vous utilisez Elasticsearch uniquement comme moteur de recherche de texte, la migration est réaliste ; si vous l'utilisez comme magasin de données opérationnelles, c'est une autre classe de système.

De combien de mémoire un cluster a-t-il besoin ?

Autant que l'index en prend, plus une marge pour la croissance et pour les opérations. Le point de départ est la somme des tailles des champs que vous indexez réellement plutôt que la taille des documents entiers, car les champs stockés sans indexation coûtent moins. Le calculateur du cloud inclut un assistant qui prend le nombre d'enregistrements et la taille moyenne d'un enregistrement et propose une configuration de départ.

Typesense Cloud a-t-il une offre gratuite ?

Le calculateur de tarifs ne montre aucune option à coût nul, et la configuration la moins chère avec 0,5 Go de mémoire coûte 0,03 USD par heure, que la page convertit en 21,60 USD par mois. La balise meta de description de cette même page mentionne pourtant une généreuse offre gratuite, donc nous avons deux affirmations contradictoires d'un même éditeur, et il vaut la peine de confirmer laquelle est vraie avant d'ouvrir un compte.

Peut-on déplacer un cluster du cloud vers mon propre serveur ?

Oui, car le cloud fait tourner le même binaire ouvert dans la version que vous avez sélectionnée. Les documents sortent par l'endpoint d'export, les schémas de collections se téléchargent en JSON, et vous les recréez sur votre propre instance. Ce qui reste du côté du service géré, ce sont le réseau de diffusion de recherche, les comptes d'équipe, les rôles du tableau de bord et l'authentification unique, tandis que les sauvegardes et les montées de version deviennent votre travail.

La documentation se trouve sur le site de Typesense, les tarifs du cloud sur la page des tarifs, et le code source dans le dépôt GitHub.

À lire aussi