typesense-docs

Typesense a partir da documentação oficial

Visão geral

Este skill reúne o que a documentação do Typesense diz que é fácil de errar: o que consome RAM, resultados de importação que escondem falhas atrás de HTTP 200, precedência de filtros, padrões que afrouxam resultados, vazamentos de chaves de busca com escopo, pesos de busca híbrida e a mudança na v30 para conjuntos de sinônimos e conjuntos de curadoria. Conselhos genéricos de busca e banco de dados são deixados de fora. Cada afirmação traz a URL da documentação de onde veio.

Versão coberta

Typesense Server 30.2, com o cliente JavaScript para exemplos de código. Flags de servidor se aplicam a servidores auto-hospedados. O Typesense Cloud as gerencia. Antes de revisar código escrito para um servidor mais antigo, leia "Padrões antigos" abaixo.

Como navegar

1. Leia o início rápido abaixo. Ele cobre as regras que importam na maioria das tarefas.
2. Abra o arquivo de referência cujo domínio corresponda à tarefa, a partir da tabela no final. Cada arquivo é independente.
3. Cada afirmação termina com sua URL de origem. Reabra-a quando um detalhe decidir o resultado.

Início rápido

Schema e memória

• Todo campo no schema é indexado em RAM. Campos apenas para exibição ficam fora do schema (ainda armazenados e retornados) ou recebem index: false. Prefira um schema predefinido em vez da detecção automática .*. https://typesense.org/docs/30.2/api/collections.html e https://typesense.org/docs/guide/running-in-production.html
• Sem tipo date: armazene timestamps Unix como int64. geopoint é [lat, lng], nunca na ordem GeoJSON. https://typesense.org/docs/30.2/api/collections.html e https://typesense.org/docs/30.2/api/geosearch.html
• facet: true é necessário para facet_by e group_by. Ordenação de string precisa de sort: true. https://typesense.org/docs/30.2/api/search.html
• Uma alteração bloqueia todas as gravações na coleção. Padrão para mudanças de schema: uma nova coleção versionada, reindexação, depois redirecionamento do alias que o aplicativo sempre usa. https://typesense.org/docs/30.2/api/collections.html
• Caracteres especiais são descartados e a correspondência é apenas por prefixo: SKUs, emails e URLs precisam de token_separators. https://typesense.org/docs/guide/tips-for-searching-common-types-of-data.html

Gravando dados

• Padrão: importação (JSONL) com action: 'upsert'. upsert substitui o documento inteiro, emplace ou update aceitam parciais. https://typesense.org/docs/30.2/api/documents.html
• A importação SEMPRE responde com HTTP 200. Verifique cada linha de resultado para success: false, com return_id=true. https://typesense.org/docs/30.2/api/documents.html e https://typesense.org/docs/guide/faqs.html
• Defina seu próprio id como string. Dê às importações um timeout de cliente de pelo menos 5 minutos (o guia de sincronização menciona até 60 minutos para grandes lotes) e nunca tente novamente uma gravação ainda em execução. https://typesense.org/docs/30.2/api/documents.html e https://typesense.org/docs/guide/syncing-data-into-typesense.html
• 503 Not Ready or Lagging é contrapressão de gravação: escreva em lotes, adicione CPU, tente novamente com jitter. https://typesense.org/docs/guide/syncing-data-into-typesense.html

Buscando

• filter_by precisa dos dois pontos: price:>=100. : corresponde a palavras, := ao valor inteiro. && e || compartilham a mesma precedência, então adicione parênteses. Crases escapam valores com vírgulas ou colchetes. https://typesense.org/docs/guide/tips-for-filtering.html
• Condições de mesmo objeto em um object[]: ingredients.{name:=cheese && concentration:<50}. https://typesense.org/docs/guide/tips-for-filtering.html
• drop_tokens_threshold e typo_tokens_threshold padrão são 1, então uma consulta com poucos resultados silenciosamente descarta palavras ou adiciona erros de digitação. Exija todas as palavras com drop_tokens_threshold: 0. Desabilite erros de digitação com num_typos: 0 E typo_tokens_threshold: 0. https://typesense.org/docs/guide/ranking-and-relevance.html
• max_candidates padrão é 4. Consultas curtas perdem registros a menos que você o aumente ou defina um default_sorting_field de popularidade. https://typesense.org/docs/30.2/api/search.html
• Combine relevância e popularidade: _text_match(buckets: 10):desc,popularity:desc. Aumente sem 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 retorna grouped_hits e um found aproximado. https://typesense.org/docs/30.2/api/search.html
• union: true na multibusca ignora a paginação por busca e precisa de tipos de campo de ordenação idênticos. https://typesense.org/docs/30.2/api/federated-multi-search.html

Busca vetorial e IA

• Consultas vetoriais passam por multi_search, sempre com exclude_fields no campo vetorial. Limite resultados com k ou distance_threshold. https://typesense.org/docs/30.2/api/vector-search.html
• Híbrida: query_by: 'title,embedding'. Fusão é 0.7 palavra-chave e 0.3 vetor, e alpha em vector_query é o peso VETORIAL. query_by_weights precisa de um placeholder 0 para o campo embedding. https://typesense.org/docs/30.2/api/vector-search.html
• RAG: conversation=true com exclude_fields: 'embedding', ou floats brutos preenchem o contexto do LLM. https://typesense.org/docs/30.2/api/conversational-search-rag.html

Chaves e multi-tenancy

• Nunca use a chave bootstrap em aplicativos. Nunca exponha chaves de admin, nem a chave pai das chaves de busca com escopo. https://typesense.org/docs/guide/data-access-control.html
• Chave de busca com escopo: pai com apenas documents:search, gerada no backend por usuário, incorporando filter_by E filter_curated_hits: true, ou resultados fixados e curados vazam entre tenants. https://typesense.org/docs/30.2/api/api-keys.html e https://typesense.org/docs/30.2/api/curation.html
• collections em uma chave não restringe endpoints globais (keys, synonym_sets, stopwords). Um campo de referência expõe a coleção referenciada através de joins. https://typesense.org/docs/30.2/api/api-keys.html

Operações

• Produção: cluster HA de 3 ou 5 nós, clientes configurados com todos os nós (mais nearestNode atrás de um balanceador de carga), RAM abaixo de 85%. https://typesense.org/docs/guide/high-availability.html e https://typesense.org/docs/guide/running-in-production.html
• Backup com /operations/snapshot, nunca copiando o diretório de dados ativo. Atualize seguidores primeiro, o líder por último. https://typesense.org/docs/guide/backups.html e https://typesense.org/docs/guide/updating-typesense.html

Padrões antigos

Antigo	Atual	Fonte
/collections/{c}/synonyms, ações de chave synonyms:*	/synonym_sets, synonym_sets:* e synonym_sets/items:*, vinculados pela coleção synonym_sets	https://typesense.org/docs/30.2/api/synonyms.html
/collections/{c}/overrides, overrides:*	/curation_sets, curation_sets:* e 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
regras de analytics com params.source e params.destination	collection, event_type de nível superior, params planos	https://typesense.org/docs/30.2/api/analytics-query-suggestions.html
uma regra de contador com source.events ponderados	uma regra por tipo de evento com params.weight	https://typesense.org/docs/30.2/api/analytics-query-suggestions.html
found exato com group_by	aproximado, group_max_candidates para precisão	https://typesense.org/docs/30.2/api/search.html
Chamada LLM no aplicativo para construir filtros	nl_search_models + nl_query=true	https://typesense.org/docs/guide/natural-language-search.html
objetos aninhados achatados	enable_nested_fields	https://typesense.org/docs/guide/tips-for-searching-common-types-of-data.html
uma coleção com document_type para uma lista mista	multi_search com union: true	https://typesense.org/docs/guide/faqs.html
array highlights antigo	objeto highlight, enable_highlight_v1=false	https://typesense.org/docs/30.2/api/search.html

Chaves não podem ser atualizadas: substitua chaves antigas criando novas. Servidores auto-hospedados fazem um snapshot antes de atualizar para que sinônimos e overrides migrem. https://typesense.org/docs/30.2/api/synonyms.html

Arquivos de referência

Arquivo	Leia para
references/schema-and-collections.md	parâmetros e padrões de campo, tipos, custo de RAM, schema automático, objetos aninhados, alter, aliases, clone, layout de coleção
references/tokenization-locale-stemming.md	token_separators, symbols_to_index, infixo, receitas para SKU, email e URL, localidade e diacríticos, dicionários de stemming
references/documents-and-import.md	ids, ações de importação, leitura de resultados de importação, timeouts, dirty_values, atualização, exclusão e exportação por consulta
references/syncing-and-reindexing.md	estratégias de sincronização a partir de um banco de dados, gravações de alto volume, erros 503 e de recurso, reindexação por alias
references/search-parameters.md	q, query_by, tolerância a erros de digitação, descarte de tokens, prefixo, max_candidates, destaque, paginação, cache, presets
references/filtering-and-geo.md	sintaxe de filter_by, precedência, escape, arrays, objetos aninhados, valores vazios, filtros e ordenações geo
references/ranking-and-sorting.md	classificação padrão, sort_by, text_match_type, buckets, _eval, decaimento, valores ausentes, fixação
references/faceting-grouping-multi-search.md	facets e estratégias, group_by, multi-busca federada e union, busca por tags booleanas
references/synonyms-curation-stopwords.md	conjuntos de sinônimos, conjuntos de curadoria, tags, regras dinâmicas, curadoria com chaves de busca com escopo, stopwords
references/vector-and-hybrid-search.md	campos vetoriais, modelos de auto-embedding, vector_query, fusão híbrida e alpha, HNSW, memória
references/conversational-nl-image-voice.md	modelos de conversação RAG, busca em linguagem natural, consultas de imagem e voz, recomendações
references/api-keys-and-access-control.md	tipos de chave, ações, armadilhas de escopo, chaves de busca com escopo, padrões de multi-tenancy, rotação
references/clients-and-errors.md	bibliotecas cliente, configuração de nó e balanceador de carga, ajuste JS, cache, códigos de erro, buscas lentas
references/server-configuration.md	flags de servidor e padrões, CORS, TLS, logging, limites de recurso, flags de analytics, notas de instalação
references/cluster-ha-backups-upgrades.md	clusters HA, arquivo de nós, recuperação, API de operações, monitoramento, backups, upgrades, dimensionamento, CI
references/analytics-and-query-suggestions.md	regras e eventos de analytics, consultas populares e sem resultados, contadores, regras de log, sugestões
references/joins-and-personalization.md	campos de referência, includes de joins, filtros e ordenações, joins left e anti, referências assíncronas, personalização
references/ui-and-algolia-migration.md	adaptador InstantSearch, diferenças do Algolia, mapeamento de conceitos, etapas de migração

Fontes e detalhes de obtenção estão listados em SOURCES.md.