Introduction

Une requête à travers tout votre projet - produits, pages, blocs, formulaires, commandes et plus, regroupés par type d'entité.

---

🎯 Que fait ce module ?

Le module Search enveloppe le point de terminaison de recherche public inter-entities. Vous passez une requête textuelle et obtenez chaque enregistrement dont le nom ou la valeur d'attribut correspond, provenant de 18 types d'entités à la fois, regroupés par type et annotés avec comment chaque enregistrement a correspondu.

Utilisez-le pour alimenter une boîte de recherche globale "tout rechercher" - celle qui affiche quelques produits, quelques pages et un formulaire correspondant dans un seul menu déroulant - puis approfondissez un type unique lorsque l'utilisateur demande plus.

Il s'agit d'une recherche par mot-clé : elle correspond au texte littéral des titres, identifiants, urls et valeurs d'attribut. Pour une recherche basée sur le sens (une requête comme "veste chaude pour l'hiver" correspondant à un produit nommé "Parka isolée"), utilisez la recherche sémantique des modules individuels - voir Recherche vectorielle vs recherche globale ci-dessous.

🚀 Démarrage rapide

Initialisez le module à partir de defineOneEntry :

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

Recherchez tout, puis parcourez les groupes :

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

✨ Concepts clés

Groupes

La réponse n'est pas une liste plate. C'est { query, groups }, où chaque groupe contient les enregistrements d'un type d'entité :

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

hasMore vous indique s'il existe d'autres enregistrements de ce type au-delà de la page retournée - le signal pour offrir un lien "afficher tous les produits" qui relance la requête en mode drilldown.

Contexte de correspondance

Chaque élément porte le contexte de la manière dont il a correspondu, vous permettant de rendre une ligne de résultat significative au lieu d'un simple titre :

Champ	Ce qu'il vous dit
matchKind	Type de classement de la correspondance : exact, title, attributeName ou attributeValue
matchedField	Le champ concret qui a correspondu : id, title, identifier, url, attributeName, attributeValue, importId, nodeName
matchedAttribute	L'attribut dans lequel la correspondance a eu lieu (lorsque la correspondance provient d'un attribut)
fragment	Contexte en texte brut autour de la correspondance, sans balisage - mettez-le en surbrillance vous-même
langCode	Langue de la valeur correspondante, afin que vous puissiez étiqueter les correspondances inter-langues
parent	L'enregistrement propriétaire pour les entités qui n'ont pas de page propre (un diapositive → son bloc, une commande → son stockage)

Types d'entités

types restreint la recherche. Passez l'un de ceux-ci, et le SDK les enverra séparés par des virgules :

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

Omettez types pour rechercher tous.

Mode drilldown

offset et limit basculent le point de terminaison en mode drilldown - pagination à travers un type d'entité au lieu de prévisualiser tous.

⚠️ Ils sont acceptés uniquement ensemble avec exactement un type accessible dans types. Toute autre combinaison répond 400 - Le mode drilldown (limit/offset) nécessite exactement un type accessible dans types.

Le SDK ne les définit pas par défaut : omettez les deux et chaque groupe revient en entier.

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

Visibilité

visibility filtre les enregistrements recherchés : 'all' (par défaut), 'visible' ou 'hidden'.

📋 Ce que vous devez savoir

• id est un nombre pour la plupart des types, une chaîne pour les workflows et les attributs - number | string, donc ne supposez pas des ids numériques lors de la construction de clés ou d'urls.
• title est optionnel : les enregistrements sans nom propre (commandes, utilisateurs sans connexion) reviennent sans. Revenez à identifier ou subtitle.
• subtitle porte la ligne secondaire que le type a - une url de page, un stockage de commande, un nom de nœud.
• attributeSetId est présent uniquement pour type: "attributes", pointant vers l'ensemble auquel l'attribut appartient.
• Seuls les enregistrements que l'appelant actuel peut voir sont retournés ; la recherche respecte les mêmes règles d'accès que le reste de l'API.

---

📊 Tableau de référence rapide

Méthode	Description
globalSearch()	Rechercher des noms et des valeurs d'attribut à travers tous les types d'entités

Recherche vectorielle vs recherche globale

Les deux trouvent des enregistrements à partir d'une requête textuelle, mais ils répondent à des questions différentes :

	globalSearch	get…ByVectorSearch
Correspond à	Le texte littéral des titres, identifiants, urls et valeurs d'attribut	Sens - une similarité sémantique (vectorielle)
Portée	18 types d'entités en un appel	Un module par appel
Retourne	{ query, groups[] } - regroupé par type	{ items, total } - un conteneur plat
Utilisation typique	Une boîte de recherche globale / palette de commandes	"Trouvez-moi quelque chose comme ça" sur une entité

Les équivalents sémantiques vivent dans les modules eux-mêmes : products, pages, users, orders, discounts, admins et form data.

❓ Questions fréquentes (FAQ)

Pourquoi mon offset / limit répond-il avec un 400 ?

Parce qu'ils ne fonctionnent qu'en mode drilldown. Passez exactement un type d'entité accessible dans types à côté d'eux, ou laissez-les tomber complètement.

---

Comment puis-je mettre en surbrillance la correspondance dans l'interface utilisateur ?

Utilisez fragment - c'est le contexte en texte brut autour de la correspondance, délibérément exempt de balisage, afin que vous puissiez mettre en surbrillance la requête vous-même sans assainir quoi que ce soit.

---

Un élément n'a pas de title. Est-ce un bug ?

Non. Les commandes et les utilisateurs sans connexion n'ont pas de nom propre, donc title est simplement absent. Rendre identifier, subtitle ou une étiquette spécifique au type à la place.

---

Puis-je rechercher des enregistrements cachés ?

Passez visibility: 'hidden' (ou 'all') - sous réserve des règles d'accès qui s'appliquent à l'appelant.

---

🎓 Meilleures pratiques

• Débouncer la requête dans une boîte de recherche au fur et à mesure que vous tapez : chaque frappe est une demande.
• Montrez d'abord l'appel d'aperçu (pas de offset/limit), puis passez au drilldown lorsque l'utilisateur choisit un type - c'est exactement ce à quoi sert hasMore.
• Restreignez types à ce que votre interface utilisateur peut réellement rendre ; rechercher 18 types pour afficher 2 est un travail inutile.
• Traitez id comme number | string lors de la construction de liens et de clés React.

---

🔗 Documentation connexe

• Module Produits - Recherche sémantique de produits et le catalogue de produits
• Module Pages - Pages retournées dans le groupe pages
• Module Filtres - Arbres de filtres organisés pour la navigation par facettes

---