Saltar al contenido principal

Introducción

Una consulta a través de todo tu proyecto: productos, páginas, bloques, formularios, pedidos y más, agrupados por tipo de entidad.

🎯 ¿Qué hace este módulo?​

El módulo Search envuelve el punto de acceso público de búsqueda cruzada de entidades. Pasas una consulta de texto y obtienes cada registro cuyo nombre o valor de atributo coincida, de 18 tipos de entidades a la vez, agrupados por tipo y anotados con cómo coincidió cada registro.

Úsalo para alimentar un cuadro de "buscar todo" global: el tipo que muestra algunos productos, un par de páginas y un formulario coincidente en un solo menú desplegable, y luego profundiza en un solo tipo cuando el usuario pida más.

Esta es una búsqueda por palabra clave: coincide con el texto literal de títulos, identificadores, URLs y valores de atributos. Para búsquedas basadas en significado (una consulta como "chaqueta cálida para invierno" que coincide con un producto llamado "parka aislante"), utiliza la búsqueda semántica de los módulos individuales - consulta Búsqueda vectorial vs búsqueda global a continuación.

🚀 Inicio Rápido​

Inicializa el módulo desde defineOneEntry:


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

Busca todo, luego recorre los 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);
  });
});

✨ Conceptos Clave​

Grupos​

La respuesta no es una lista plana. Es { query, groups }, donde cada grupo contiene los registros de un tipo de entidad:

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

hasMore te indica si existen más registros de ese tipo más allá de la página devuelta: la señal para ofrecer un enlace de "mostrar todos los productos" que vuelve a ejecutar la consulta en modo de profundización.

Contexto de coincidencia​

Cada elemento lleva el contexto de cómo coincidió, para que puedas renderizar una fila de resultado significativa en lugar de un título desnudo:

CampoLo que te dice
matchKindTipo de clasificación de la coincidencia: exacta, título, nombreAtributo o valorAtributo
matchedFieldEl campo concreto que coincidió: id, título, identificador, url, nombreAtributo, valorAtributo, importId, nodeName
matchedAttributeEl atributo en el que ocurrió la coincidencia (cuando la coincidencia provino de un atributo)
fragmentContexto en texto plano alrededor de la coincidencia, sin marcado - resáltalo tú mismo
langCodeIdioma del valor coincidente, para que puedas etiquetar coincidencias entre idiomas
parentEl registro propietario para entidades que no tienen su propia página (una diapositiva → su bloque, un pedido → su almacenamiento)

Tipos de entidad​

types reduce la búsqueda. Pasa cualquiera de estos, y el SDK los envía separados por comas:

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 ellos.

Modo de profundización​

offset y limit cambian el punto de acceso a modo de profundización - paginando a través de un tipo de entidad en lugar de previsualizar todos ellos.

⚠️ Se aceptan solo juntos con exactamente un tipo accesible en types. Cualquier otra combinación responde 400 - El modo de profundización (limit/offset) requiere exactamente un tipo accesible en types.

El SDK no los establece por defecto: omite ambos y cada grupo regresa completo.

// 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);

Visibilidad​

visibility filtra los registros buscados: 'all' (por defecto), 'visible' o 'hidden'.

📋 Lo Que Necesitas Saber​

  • id es un número para la mayoría de los tipos, una cadena para flujos de trabajo y atributos - number | string, así que no asumas ids numéricos al construir claves o URLs.
  • title es opcional: los registros sin nombre propio (pedidos, usuarios sin inicio de sesión) regresan sin él. Recurre a identifier o subtitle.
  • subtitle lleva la línea secundaria que el tipo tiene - una URL de página, un almacenamiento de pedido, un nombre de nodo.
  • attributeSetId está presente solo para type: "attributes", apuntando al conjunto al que pertenece el atributo.
  • Solo se devuelven los registros que el llamador actual puede ver; la búsqueda respeta las mismas reglas de acceso que el resto de la API.

📊 Tabla de Referencia Rápida​

MétodoDescripción
globalSearch()Buscar nombres y valores de atributos en todos los tipos de entidad

Búsqueda vectorial vs búsqueda global​

Ambas encuentran registros a partir de una consulta de texto, pero responden a diferentes preguntas:

globalSearchget…ByVectorSearch
Coincide enEl texto literal de títulos, identificadores, URLs y valores de atributosSignificado - una similitud semántica (vector)
Alcance18 tipos de entidad en una llamadaUn módulo por llamada
Devuelve{ query, groups[] } - agrupados por tipo{ items, total } - un contenedor plano
Uso típicoUn cuadro de búsqueda global / paleta de comandos"Encuéntrame algo como esto" sobre una entidad

Los contrapartes semánticos viven en los módulos mismos: products, pages, users, orders, discounts, admins y form data.

❓ Preguntas Comunes (FAQ)​

¿Por qué mi offset / limit responde con un 400?​

Porque solo funcionan en modo de profundización. Pasa exactamente un tipo de entidad accesible en types junto a ellos, o déjalos caer por completo.

¿Cómo resalto la coincidencia en la interfaz de usuario?​

Usa fragment - es el contexto en texto plano alrededor de la coincidencia, deliberadamente libre de marcado, para que puedas resaltar la consulta en él sin sanitizar nada.

Un elemento no tiene title. ¿Es un error?​

No. Los pedidos y usuarios sin inicio de sesión no tienen nombre propio, así que title simplemente está ausente. Renderiza identifier, subtitle o una etiqueta específica del tipo en su lugar.

¿Puedo buscar registros ocultos?​

Pasa visibility: 'hidden' (o 'all') - sujeto a las reglas de acceso que se aplican al llamador.

🎓 Mejores Prácticas​

  • Debounce la consulta en un cuadro de búsqueda a medida que escribes: cada pulsación de tecla es una solicitud.
  • Muestra primero la llamada de resumen (sin offset/limit), luego cambia a profundización cuando el usuario elige un tipo - eso es exactamente para lo que sirve hasMore.
  • Reduce types a lo que tu interfaz puede realmente renderizar; buscar 18 tipos para mostrar 2 es trabajo desperdiciado.
  • Trata id como number | string al construir enlaces y claves de React.

🔗 Documentación Relacionada​