Pular para o conteúdo principal

Introdução

Uma consulta em todo o seu projeto - produtos, páginas, blocos, formulários, pedidos e mais, agrupados por tipo de entidade.

🎯 O que este módulo faz?​

O módulo Search envolve o endpoint público de busca entre entidades. Você passa uma consulta de texto e recebe de volta todos os registros cujo nome ou valor de atributo corresponda, de 18 tipos de entidades de uma só vez, agrupados por tipo e anotados com como cada registro correspondeu.

Use-o para alimentar uma caixa de "buscar tudo" global - do tipo que mostra alguns produtos, algumas páginas e um formulário correspondente em um único dropdown - e depois aprofunde-se em um único tipo quando o usuário pedir mais.

Esta é uma busca por palavras-chave: ela corresponde ao texto literal de títulos, identificadores, URLs e valores de atributos. Para busca baseada em significado (uma consulta como "jaqueta quente para o inverno" correspondendo a um produto chamado "parka isolada"), use a busca semântica dos módulos individuais - veja Busca vetorial vs busca global abaixo.

🚀 Início Rápido​

Inicialize o módulo a partir de defineOneEntry:


const { Search } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Busque tudo, depois percorra os grupos:

// Search every entity type for "winter".
const result = await Search.globalSearch('winter');

console.log(result.query); // "winter"

result.groups.forEach((group) => {
  console.log(group.type, group.items.length, group.hasMore);

  group.items.forEach((item) => {
    console.log(item.id, item.title, item.matchKind, item.fragment);
  });
});

✨ Conceitos Chave​

Grupos​

A resposta não é uma lista plana. É { query, groups }, onde cada grupo contém os registros de um tipo de entidade:

{
  query: "winter",
  groups: [
    { type: "products", items: [ /* … */ ], hasMore: false },
    { type: "pages",    items: [ /* … */ ], hasMore: false }
  ]
}

hasMore informa se existem mais registros desse tipo além da página retornada - a dica para oferecer um link "mostrar todos os produtos" que re-executa a consulta em modo de aprofundamento.

Contexto da correspondência​

Cada item carrega o contexto de como ele correspondeu, para que você possa renderizar uma linha de resultado significativa em vez de um título simples:

CampoO que ele te diz
matchKindTipo de classificação da correspondência: exata, título, nomeAtributo ou valorAtributo
matchedFieldO campo concreto que correspondeu: id, título, identificador, url, nomeAtributo, valorAtributo, importId, nomeDoNó
matchedAttributeO atributo em que a correspondência ocorreu (quando a correspondência veio de um atributo)
fragmentContexto em texto simples ao redor da correspondência, sem marcação - destaque você mesmo
langCodeIdioma do valor correspondente, para que você possa rotular correspondências entre idiomas
parentO registro proprietário para entidades que não têm uma página própria (um slide → seu bloco, um pedido → seu armazenamento)

Tipos de entidade​

types restringe a busca. Passe qualquer um deles, e o SDK os enviará separados por vírgula:

products, pages, blocks, slides, templates, discounts, user_groups, users, admins, menus, forms, attributes_sets, attributes, orders, workflows, events, subscriptions, collections.

Omitir types para buscar todos eles.

Modo de Aprofundamento​

offset e limit mudam o endpoint para modo de aprofundamento - paginando através de um tipo de entidade em vez de visualizar todos eles.

⚠️ Eles são aceitos apenas juntos com exatamente um tipo acessível em types. Qualquer outra combinação retorna 400 - O modo de aprofundamento (limite/deslocamento) requer exatamente um tipo acessível em types.

O SDK não os define como padrão: omita ambos e cada grupo retorna na íntegra.

// Overview: every type, every group complete.
const overview = await Search.globalSearch('winter');

// Drilldown: page 1 of the products only.
const products = await Search.globalSearch('winter', ['products'], 'visible', 0, 20);

Visibilidade​

visibility filtra os registros pesquisados: 'all' (padrão), 'visible' ou 'hidden'.

📋 O que você precisa saber​

  • id é um número para a maioria dos tipos, uma string para workflows e atributos - number | string, então não assuma ids numéricos ao construir chaves ou URLs.
  • title é opcional: registros sem nome próprio (pedidos, usuários sem login) retornam sem ele. Volte para identifier ou subtitle.
  • subtitle carrega a linha secundária que o tipo possui - uma URL de página, um armazenamento de pedido, um nome de nó.
  • attributeSetId está presente apenas para type: "attributes", apontando para o conjunto ao qual o atributo pertence.
  • Apenas registros que o chamador atual pode ver são retornados; a busca respeita as mesmas regras de acesso que o resto da API.

📊 Tabela de Referência Rápida​

MétodoDescrição
globalSearch()Pesquisar nomes e valores de atributos em todos os tipos de entidade

Busca vetorial vs busca global​

Ambas encontram registros a partir de uma consulta de texto, mas respondem a perguntas diferentes:

globalSearchget…ByVectorSearch
Corresponde aO texto literal de títulos, identificadores, URLs e valores de atributosSignificado - uma similaridade semântica (vetorial)
Escopo18 tipos de entidades em uma chamadaUm módulo por chamada
Retorna{ query, groups[] } - agrupados por tipo{ items, total } - um contêiner plano
Uso típicoUma caixa de busca global / paleta de comandos"Encontre algo como isso" em uma entidade

Os equivalentes semânticos vivem nos próprios módulos: products, pages, users, orders, discounts, admins e form data.

❓ Perguntas Comuns (FAQ)​

Por que meu offset / limit retorna 400?​

Porque eles só funcionam no modo de aprofundamento. Passe exatamente um tipo de entidade acessível em types junto com eles, ou omita-os completamente.

Como faço para destacar a correspondência na interface do usuário?​

Use fragment - é o contexto em texto simples ao redor da correspondência, deliberadamente livre de marcação, para que você possa destacar a consulta nele mesmo sem sanitizar nada.

Um item não tem title. Isso é um bug?​

Não. Pedidos e usuários sem login não têm nome próprio, então title simplesmente está ausente. Renderize identifier, subtitle ou um rótulo específico do tipo em vez disso.

Posso buscar registros ocultos?​

Passe visibility: 'hidden' (ou 'all') - sujeito às regras de acesso que se aplicam ao chamador.

🎓 Melhores Práticas​

  • Debounce a consulta em uma caixa de busca enquanto digita: cada tecla pressionada é uma solicitação.
  • Mostre a chamada de visão geral primeiro (sem offset/limit), depois mude para aprofundamento quando o usuário escolher um tipo - é exatamente para isso que serve hasMore.
  • Restringa types ao que sua interface pode realmente renderizar; buscar 18 tipos para exibir 2 é trabalho desperdiçado.
  • Trate id como number | string ao construir links e chaves React.

🔗 Documentação Relacionada​