typesense-docs

Typesense d'après la documentation officielle

Présentation

Cette compétence regroupe ce que la documentation de Typesense indique et qu'il est facile de mal interpréter : ce qui coûte de la RAM, les résultats d'import qui cachent des échecs derrière un HTTP 200, la priorité des filtres, les valeurs par défaut qui élargissent les résultats, les fuites de clés de recherche limitées, les poids de la recherche hybride et le passage v30 vers les ensembles de synonymes et les ensembles de curation. Les conseils génériques sur la recherche et les bases de données sont laissés de côté. Chaque affirmation est accompagnée de l'URL de la documentation dont elle est issue.

Version couverte

Serveur Typesense 30.2, avec le client JavaScript pour les exemples de code. Les indicateurs de serveur s'appliquent aux serveurs auto-hébergés. Typesense Cloud les gère. Avant d'examiner du code écrit pour un serveur plus ancien, lisez la section « Anciens patterns » ci-dessous.

Comment naviguer

1. Lisez le démarrage rapide ci-dessous. Il couvre les règles qui comptent dans la plupart des tâches.
2. Ouvrez le fichier de référence dont le domaine correspond à la tâche, à partir du tableau en fin de document. Chaque fichier est autonome.
3. Chaque affirmation se termine par son URL source. Re-ouvrez-la lorsqu'un détail est déterminant.

Démarrage rapide

Schéma et mémoire

• Chaque champ dans le schéma est indexé en RAM. Les champs d'affichage seul restent en dehors du schéma (toujours stockés et retournés) ou obtiennent index: false. Préférez un schéma prédéfini plutôt que la détection automatique .*. https://typesense.org/docs/30.2/api/collections.html et https://typesense.org/docs/guide/running-in-production.html
• Pas de type date : stockez les timestamps Unix en int64. geopoint est [lat, lng], jamais l'ordre GeoJSON. https://typesense.org/docs/30.2/api/collections.html et https://typesense.org/docs/30.2/api/geosearch.html
• facet: true est nécessaire pour facet_by et group_by. Le tri de chaînes nécessite sort: true. https://typesense.org/docs/30.2/api/search.html
• Une opération alter bloque toutes les écritures sur la collection. Par défaut pour les modifications de schéma : une nouvelle collection versionnée, réindexation, puis redirection de l'alias que l'application utilise toujours. https://typesense.org/docs/30.2/api/collections.html
• Les caractères spéciaux sont supprimés et la correspondance est par préfixe uniquement : les SKU, e-mails et URL nécessitent token_separators. https://typesense.org/docs/guide/tips-for-searching-common-types-of-data.html

Écriture de données

• Valeur par défaut : import (JSONL) avec action: 'upsert'. upsert remplace tout le document, emplace ou update prennent des documents partiels. https://typesense.org/docs/30.2/api/documents.html
• L'import répond TOUJOURS HTTP 200. Examinez chaque ligne de résultat pour success: false, avec return_id=true. https://typesense.org/docs/30.2/api/documents.html et https://typesense.org/docs/guide/faqs.html
• Définissez votre propre id sous forme de chaîne. Donnez aux imports un délai d'attente client d'au moins 5 minutes (le guide de synchronisation indique jusqu'à 60 minutes pour les gros lots), et ne réessayez jamais une écriture qui est encore en cours. https://typesense.org/docs/30.2/api/documents.html et https://typesense.org/docs/guide/syncing-data-into-typesense.html
• 503 Not Ready or Lagging est une contre-pression d'écriture : regroupez les écritures, ajoutez du CPU, réessayez avec gigue. https://typesense.org/docs/guide/syncing-data-into-typesense.html

Recherche

• filter_by nécessite le deux-points : price:>=100. : fait correspondre des mots, := la valeur entière. && et || partagent une seule priorité, donc ajoutez des parenthèses. Les guillemets inverses échappent les valeurs avec des virgules ou des crochets. https://typesense.org/docs/guide/tips-for-filtering.html
• Conditions sur le même objet dans un object[] : ingredients.{name:=cheese && concentration:<50}. https://typesense.org/docs/guide/tips-for-filtering.html
• drop_tokens_threshold et typo_tokens_threshold valent par défaut 1, donc une requête avec peu de résultats supprime silencieusement des mots ou ajoute des fautes de frappe. Exigez tous les mots avec drop_tokens_threshold: 0. Désactivez les fautes de frappe avec num_typos: 0 ET typo_tokens_threshold: 0. https://typesense.org/docs/guide/ranking-and-relevance.html
• max_candidates vaut par défaut 4. Les requêtes courtes manquent des enregistrements sauf si vous l'augmentez ou définissez un champ de tri par défaut de popularité. https://typesense.org/docs/30.2/api/search.html
• Mélangez pertinence et popularité : _text_match(buckets: 10):desc,popularity:desc. Boostez sans filtrer : _eval(in_stock:true):desc. https://typesense.org/docs/guide/ranking-and-relevance.html
• Maximum 250 résultats par page. group_by retourne grouped_hits et un found approximatif. https://typesense.org/docs/30.2/api/search.html
• La multi-recherche avec union: true ignore la pagination par recherche et nécessite des types de champ de tri identiques. https://typesense.org/docs/30.2/api/federated-multi-search.html

Recherche vectorielle et IA

• Les requêtes vectorielles passent par multi_search, toujours avec exclude_fields sur le champ vectoriel. Limitez les résultats avec k ou distance_threshold. https://typesense.org/docs/30.2/api/vector-search.html
• Hybride : query_by: 'title,embedding'. La fusion est à 0.7 pour le texte et 0.3 pour le vecteur, et alpha dans vector_query est le poids VECTORIEL. query_by_weights nécessite un 0 comme espace réservé pour le champ d'embedding. https://typesense.org/docs/30.2/api/vector-search.html
• RAG : conversation=true avec exclude_fields: 'embedding', ou les flottants bruts remplissent le contexte du LLM. https://typesense.org/docs/30.2/api/conversational-search-rag.html

Clés et multi-location

• N'utilisez jamais la clé d'amorçage dans les applications. N'exposez jamais les clés administrateur, ni le parent des clés de recherche limitées. https://typesense.org/docs/guide/data-access-control.html
• Clé de recherche limitée : parent avec uniquement documents:search, générée côté serveur par utilisateur, intégrant filter_by ET filter_curated_hits: true, sinon les résultats épinglés et de curation fuient entre les locataires. https://typesense.org/docs/30.2/api/api-keys.html et https://typesense.org/docs/30.2/api/curation.html
• collections sur une clé ne restreint pas les points de terminaison globaux (keys, synonym_sets, stopwords). Un champ de référence expose la collection référencée via les jointures. https://typesense.org/docs/30.2/api/api-keys.html

Opérations

• Production : cluster HA de 3 ou 5 nœuds, clients configurés avec chaque nœud (plus nearestNode derrière un équilibreur de charge), RAM sous 85 %. https://typesense.org/docs/guide/high-availability.html et https://typesense.org/docs/guide/running-in-production.html
• Sauvegardez avec /operations/snapshot, jamais en copiant le répertoire de données en direct. Mettez à niveau les suiveurs en premier, le leader en dernier. https://typesense.org/docs/guide/backups.html et https://typesense.org/docs/guide/updating-typesense.html

Anciens patterns

Ancien	Actuel	Source
/collections/{c}/synonyms, actions de clé synonyms:*	/synonym_sets, synonym_sets:* et synonym_sets/items:*, liés par la collection synonym_sets	https://typesense.org/docs/30.2/api/synonyms.html
/collections/{c}/overrides, overrides:*	/curation_sets, curation_sets:* et curation_sets/items:*	https://typesense.org/docs/30.2/api/curation.html
override_tags	curation_tags	https://typesense.org/docs/30.2/api/curation.html
règles d'analyse avec params.source et params.destination	collection, event_type de premier niveau, params à plat	https://typesense.org/docs/30.2/api/analytics-query-suggestions.html
une règle de compteur avec source.events pondéré	une règle par type d'événement avec params.weight	https://typesense.org/docs/30.2/api/analytics-query-suggestions.html
found exact avec group_by	approximatif, group_max_candidates pour la précision	https://typesense.org/docs/30.2/api/search.html
Appel LLM dans l'application pour construire des filtres	nl_search_models + nl_query=true	https://typesense.org/docs/guide/natural-language-search.html
objets imbriqués aplatis	enable_nested_fields	https://typesense.org/docs/guide/tips-for-searching-common-types-of-data.html
une collection avec document_type pour une liste mixte	multi_search avec union: true	https://typesense.org/docs/guide/faqs.html
ancien tableau highlights	objet highlight, enable_highlight_v1=false	https://typesense.org/docs/30.2/api/search.html

Les clés ne peuvent pas être mises à jour : remplacez les anciennes clés en en créant de nouvelles. Les serveurs auto-hébergés prennent un instantané avant la mise à niveau afin que les synonymes et les overrides migrent. https://typesense.org/docs/30.2/api/synonyms.html

Fichiers de référence

Fichier	Lisez-le pour
references/schema-and-collections.md	paramètres de champ et valeurs par défaut, types, coût RAM, schéma automatique, objets imbriqués, alter, alias, clone, disposition de collection
references/tokenization-locale-stemming.md	token_separators, symbols_to_index, infixe, recettes pour SKU, e-mail et URL, locale et diacritiques, dictionnaires de radicalisation
references/documents-and-import.md	ids, actions d'import, lecture des résultats d'import, délais d'attente, dirty_values, mise à jour, suppression et export par requête
references/syncing-and-reindexing.md	stratégies de synchronisation depuis une base de données, écritures à fort volume, erreurs 503 et de ressource, réindexation par alias
references/search-parameters.md	q, query_by, tolérance aux fautes de frappe, suppression de tokens, préfixe, max_candidates, surbrillance, pagination, cache, préréglages
references/filtering-and-geo.md	syntaxe filter_by, priorité, échappement, tableaux, objets imbriqués, valeurs vides, filtres géo et tris
references/ranking-and-sorting.md	classement par défaut, sort_by, text_match_type, buckets, _eval, décroissance, valeurs manquantes, épinglage
references/faceting-grouping-multi-search.md	facettes et stratégies, group_by, multi-recherche fédérée et union, recherche par balises booléennes
references/synonyms-curation-stopwords.md	ensembles de synonymes, ensembles de curation, balises, règles dynamiques, curation avec clés de recherche limitées, mots vides
references/vector-and-hybrid-search.md	champs vectoriels, modèles d'auto-embedding, vector_query, fusion hybride et alpha, HNSW, mémoire
references/conversational-nl-image-voice.md	modèles de conversation RAG, recherche en langage naturel, requêtes image et voix, recommandations
references/api-keys-and-access-control.md	types de clés, actions, pièges de portée, clés de recherche limitées, modèles multi-location, rotation
references/clients-and-errors.md	bibliothèques clientes, configuration des nœuds et de l'équilibreur de charge, réglages JS, cache, codes d'erreur, recherches lentes
references/server-configuration.md	indicateurs de serveur et valeurs par défaut, CORS, TLS, journalisation, limites de ressources, indicateurs d'analyse, notes d'installation
references/cluster-ha-backups-upgrades.md	clusters HA, fichier de nœuds, récupération, API d'opérations, surveillance, sauvegardes, mises à niveau, dimensionnement, CI
references/analytics-and-query-suggestions.md	règles d'analyse et événements, requêtes populaires et sans résultats, compteurs, règles de journalisation, suggestions
references/joins-and-personalization.md	champs de référence, inclusives de jointure, filtres et tris, jointures gauche et anti, références asynchrones, personnalisation
references/ui-and-algolia-migration.md	adaptateur InstantSearch, différences Algolia, mappage de concepts, étapes de migration

Les sources et les détails de récupération sont listés dans SOURCES.md.