typesense-docs

Typesense de la documentación oficial

Resumen

Este skill contiene lo que la documentación de Typesense dice que es fácil malinterpretar: qué consume RAM, resultados de importación que ocultan fallos tras HTTP 200, precedencia de filtros, valores predeterminados que relajan los resultados, fugas de claves de búsqueda con ámbito, pesos de búsqueda híbrida y el cambio a v30 con conjuntos de sinónimos y conjuntos de curación. Se omite el asesoramiento genérico sobre búsqueda y bases de datos. Cada afirmación incluye la URL de la documentación de la que proviene.

Versión cubierta

Servidor Typesense 30.2, con el cliente JavaScript para ejemplos de código. Las banderas del servidor se aplican a servidores autogestionados. Typesense Cloud las gestiona. Antes de revisar código escrito para un servidor anterior, lea "Patrones antiguos" más abajo.

Cómo navegar

1. Lea la guía de inicio rápido a continuación. Cubre las reglas que importan en la mayoría de las tareas.
2. Abra el archivo de referencia cuyo dominio coincida con la tarea, de la tabla al final. Cada archivo es independiente.
3. Cada afirmación termina con su URL de origen. Vuelva a abrirla cuando un detalle decida el resultado.

Inicio rápido

Esquema y memoria

• Cada campo en el esquema se indexa en RAM. Los campos solo de visualización se mantienen fuera del esquema (aún se almacenan y devuelven) o se les asigna index: false. Prefiera un esquema predefinido sobre la detección automática .*. https://typesense.org/docs/30.2/api/collections.html y https://typesense.org/docs/guide/running-in-production.html
• No hay tipo de fecha: almacene marcas de tiempo Unix en int64. geopoint es [lat, lng], nunca el orden GeoJSON. https://typesense.org/docs/30.2/api/collections.html y https://typesense.org/docs/30.2/api/geosearch.html
• Se necesita facet: true para facet_by y group_by. La ordenación de cadenas necesita sort: true. https://typesense.org/docs/30.2/api/search.html
• Una alteración bloquea todas las escrituras en la colección. Valor predeterminado para cambios de esquema: una nueva colección versionada, reindexar y luego redirigir el alias que la aplicación usa siempre. https://typesense.org/docs/30.2/api/collections.html
• Los caracteres especiales se eliminan y la coincidencia es solo por prefijo: los SKU, correos electrónicos y URL necesitan token_separators. https://typesense.org/docs/guide/tips-for-searching-common-types-of-data.html

Escritura de datos

• Valor predeterminado: importación (JSONL) con action: 'upsert'. upsert reemplaza todo el documento, emplace o update toman documentos parciales. https://typesense.org/docs/30.2/api/documents.html
• La importación SIEMPRE responde con HTTP 200. Escanee cada línea de resultado en busca de success: false, con return_id=true. https://typesense.org/docs/30.2/api/documents.html y https://typesense.org/docs/guide/faqs.html
• Establezca su propio id de cadena. Dé a las importaciones un tiempo de espera de cliente de al menos 5 minutos (la guía de sincronización dice hasta 60 minutos para lotes grandes) y nunca reintente una escritura que aún se esté ejecutando. https://typesense.org/docs/30.2/api/documents.html y https://typesense.org/docs/guide/syncing-data-into-typesense.html
• 503 Not Ready or Lagging es contrapresión de escritura: escriba por lotes, agregue CPU, reintente con jitter. https://typesense.org/docs/guide/syncing-data-into-typesense.html

Búsqueda

• filter_by necesita los dos puntos: price:>=100. : coincide con palabras, := coincide con el valor completo. && y || comparten una precedencia, así que agregue paréntesis. Las comillas invertidas escapan valores con comas o corchetes. https://typesense.org/docs/guide/tips-for-filtering.html
• Condiciones del mismo objeto en object[]: ingredients.{name:=cheese && concentration:<50}. https://typesense.org/docs/guide/tips-for-filtering.html
• drop_tokens_threshold y typo_tokens_threshold tienen un valor predeterminado de 1, por lo que una consulta con pocos resultados elimina palabras en silencio o agrega errores tipográficos. Exija todas las palabras con drop_tokens_threshold: 0. Deshabilite los errores tipográficos con num_typos: 0 Y typo_tokens_threshold: 0. https://typesense.org/docs/guide/ranking-and-relevance.html
• max_candidates tiene un valor predeterminado de 4. Las consultas cortas pierden registros a menos que lo aumente o establezca un campo default_sorting_field de popularidad. https://typesense.org/docs/30.2/api/search.html
• Combine relevancia y popularidad: _text_match(buckets: 10):desc,popularity:desc. Potencie sin filtrar: _eval(in_stock:true):desc. https://typesense.org/docs/guide/ranking-and-relevance.html
• Máximo de 250 resultados por página. group_by devuelve grouped_hits y un valor found aproximado. https://typesense.org/docs/30.2/api/search.html
• La búsqueda múltiple con union: true ignora la paginación por búsqueda y necesita tipos de campo de ordenación idénticos. https://typesense.org/docs/30.2/api/federated-multi-search.html

Búsqueda vectorial e IA

• Las consultas vectoriales pasan por multi_search, siempre con exclude_fields en el campo vectorial. Acote los resultados con k o distance_threshold. https://typesense.org/docs/30.2/api/vector-search.html
• Híbrida: query_by: 'title,embedding'. La fusión es 0.7 de palabra clave y 0.3 vectorial, y alpha en vector_query es el peso VECTORIAL. query_by_weights necesita un marcador de posición 0 para el campo de incrustación. https://typesense.org/docs/30.2/api/vector-search.html
• RAG: conversation=true con exclude_fields: 'embedding', o los valores flotantes sin procesar llenan el contexto del LLM. https://typesense.org/docs/30.2/api/conversational-search-rag.html

Claves y multiinquilino

• Nunca use la clave de arranque en aplicaciones. Nunca exponga claves de administrador, ni el padre de las claves de búsqueda con ámbito. https://typesense.org/docs/guide/data-access-control.html
• Clave de búsqueda con ámbito: padre con solo documents:search, generada en el backend por usuario, incrustando filter_by Y filter_curated_hits: true, o los resultados fijados y seleccionados se filtran entre inquilinos. https://typesense.org/docs/30.2/api/api-keys.html y https://typesense.org/docs/30.2/api/curation.html
• collections en una clave no restringe los puntos finales globales (keys, synonym_sets, stopwords). Un campo de referencia expone la colección referenciada a través de uniones. https://typesense.org/docs/30.2/api/api-keys.html

Operaciones

• Producción: 3 o 5 nodos HA, clientes configurados con cada nodo (más nearestNode detrás de un balanceador de carga), RAM por debajo del 85%. https://typesense.org/docs/guide/high-availability.html y https://typesense.org/docs/guide/running-in-production.html
• Realice copias de seguridad con /operations/snapshot, nunca copiando el directorio de datos en vivo. Actualice primero los seguidores y al líder al final. https://typesense.org/docs/guide/backups.html y https://typesense.org/docs/guide/updating-typesense.html

Patrones antiguos

Antiguo	Actual	Fuente
/collections/{c}/synonyms, acciones de clave synonyms:*	/synonym_sets, synonym_sets:* y synonym_sets/items:*, vinculados por synonym_sets de colección	https://typesense.org/docs/30.2/api/synonyms.html
/collections/{c}/overrides, overrides:*	/curation_sets, curation_sets:* y 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
reglas de análisis con params.source y params.destination	collection de nivel superior, event_type, params planos	https://typesense.org/docs/30.2/api/analytics-query-suggestions.html
una regla de contador con source.events ponderados	una regla por tipo de evento con params.weight	https://typesense.org/docs/30.2/api/analytics-query-suggestions.html
found exacto con group_by	aproximado, group_max_candidates para precisión	https://typesense.org/docs/30.2/api/search.html
Llamada LLM en la aplicación para construir filtros	nl_search_models + nl_query=true	https://typesense.org/docs/guide/natural-language-search.html
objetos anidados aplanados	enable_nested_fields	https://typesense.org/docs/guide/tips-for-searching-common-types-of-data.html
una colección con document_type para una lista mixta	multi_search con union: true	https://typesense.org/docs/guide/faqs.html
antiguo array highlights	objeto highlight, enable_highlight_v1=false	https://typesense.org/docs/30.2/api/search.html

Las claves no se pueden actualizar: reemplace las claves antiguas creando otras nuevas. Los servidores autogestionados toman una instantánea antes de actualizar para que los sinónimos y las anulaciones migren. https://typesense.org/docs/30.2/api/synonyms.html

Archivos de referencia

Archivo	Léalo para
references/schema-and-collections.md	parámetros de campo y valores predeterminados, tipos, costo de RAM, esquema automático, objetos anidados, alteración, alias, clonación, diseño de colección
references/tokenization-locale-stemming.md	token_separators, symbols_to_index, infijo, recetas para SKU, correo electrónico y URL, configuración regional y diacríticos, diccionarios de derivación
references/documents-and-import.md	ids, acciones de importación, lectura de resultados de importación, tiempos de espera, dirty_values, actualización, eliminación y exportación por consulta
references/syncing-and-reindexing.md	estrategias de sincronización desde una base de datos, escrituras de alto volumen, errores 503 y de recursos, reindexación de alias
references/search-parameters.md	q, query_by, tolerancia a errores tipográficos, eliminación de tokens, prefijo, max_candidates, resaltado, paginación, caché, ajustes preestablecidos
references/filtering-and-geo.md	sintaxis de filter_by, precedencia, escape, arrays, objetos anidados, valores vacíos, filtros geo y ordenaciones
references/ranking-and-sorting.md	clasificación predeterminada, sort_by, text_match_type, cubos, _eval, decaimiento, valores faltantes, fijación
references/faceting-grouping-multi-search.md	facetas y estrategias, group_by, búsqueda múltiple federada y unida, búsqueda por etiquetas booleanas
references/synonyms-curation-stopwords.md	conjuntos de sinónimos, conjuntos de curación, etiquetas, reglas dinámicas, curación con claves de búsqueda con ámbito, palabras vacías
references/vector-and-hybrid-search.md	campos vectoriales, modelos de incrustación automática, vector_query, fusión híbrida y alpha, HNSW, memoria
references/conversational-nl-image-voice.md	modelos de conversación RAG, búsqueda en lenguaje natural, consultas de imagen y voz, recomendaciones
references/api-keys-and-access-control.md	tipos de clave, acciones, errores de ámbito, claves de búsqueda con ámbito, patrones multiinquilino, rotación
references/clients-and-errors.md	bibliotecas cliente, configuración de nodos y balanceadores de carga, ajuste de JS, caché, códigos de error, búsquedas lentas
references/server-configuration.md	banderas del servidor y valores predeterminados, CORS, TLS, registro, límites de recursos, banderas de análisis, notas de instalación
references/cluster-ha-backups-upgrades.md	clústeres HA, archivo de nodos, recuperación, API de operaciones, monitoreo, copias de seguridad, actualizaciones, dimensionamiento, CI
references/analytics-and-query-suggestions.md	reglas y eventos de análisis, consultas populares y sin resultados, contadores, reglas de registro, sugerencias
references/joins-and-personalization.md	campos de referencia, inclusiones unidas, filtros y ordenaciones, uniones izquierda y anti, referencias asíncronas, personalización
references/ui-and-algolia-migration.md	adaptador InstantSearch, diferencias de Algolia, mapeo de conceptos, pasos de migración

Las fuentes y los detalles de obtención se enumeran en SOURCES.md.