globalSearch

Busca pública em títulos e valores de atributos de registros visíveis.

Descrição

Este método pesquisa nomes e valores de atributos de registros em tipos de entidades. Ele retorna uma Promise que resolve para um objeto IGlobalSearchResponse - a consulta para a qual foi executada, além dos registros encontrados agrupados por tipo de entidade, cada item carregando o contexto de como ele correspondeu.

Buscar.globalSearch(

query*, types, visibility, offset, limit

);

Esquema de parâmetros

Esquema

query(obrigatório): string
Consulta de busca.
exemplo: "inverno"

types: TGlobalSearchEntityType[]
Tipos de entidades para pesquisar, enviados separados por vírgula. Pesquisa todos os tipos quando omitido.
exemplo:

["products"]

Enum: [ products, pages, blocks, slides, templates, discounts, user_groups, users, admins, menus, forms, attributes_sets, attributes, orders, workflows, events, subscriptions, collections ]

visibility: 'all' | 'visible' | 'hidden'
Filtro de visibilidade dos registros pesquisados. Padrão: "todos"
exemplo: "visível"

offset: number
Deslocamento do modo de detalhamento. Passe apenas junto com um único tipo acessível em types.
exemplo: 0

limit: number
Tamanho da página do modo de detalhamento. Passe apenas junto com um único tipo acessível em types, caso contrário, a API responde 400 "Modo de detalhamento (limite/deslocamento) requer exatamente um tipo acessível em types". Sem isso, cada grupo é retornado na íntegra.
exemplo: 20

Exemplos

Exemplo mínimo

const response = await Search.globalSearch('winter');

Exemplo com atributos

// Drilldown: offset/limit are accepted only alongside exactly one type.
const response = await Search.globalSearch('winter', ['products'], 'visible', 0, 20);

Renderizando os grupos

const { query, groups } = await Search.globalSearch('test');

groups.forEach((group) => {
  console.log(`${group.type} (${group.items.length}${group.hasMore ? '+' : ''})`);

  group.items.forEach((item) => {
    // fragment is plain text — safe to highlight yourself
    console.log(item.title ?? item.identifier, item.matchKind, item.fragment);
  });
});

Exemplo de resposta

{
  "query": "test",
  "groups": [
    {
      "type": "pages",
      "items": [
        {
          "type": "pages",
          "id": 50,
          "title": "Test",
          "subtitle": "test",
          "matchKind": "exact",
          "matchedField": "url",
          "langCode": "en_US"
        }
      ],
      "hasMore": false
    },
    {
      "type": "blocks",
      "items": [
        {
          "type": "blocks",
          "id": 4,
          "title": "test",
          "identifier": "test",
          "matchKind": "exact",
          "matchedField": "identifier",
          "langCode": "en_US"
        }
      ],
      "hasMore": false
    },
    {
      "type": "discounts",
      "items": [
        {
          "type": "discounts",
          "id": 1,
          "title": "Example discount",
          "identifier": "example_discount",
          "matchKind": "attributeValue",
          "matchedField": "attributeValue",
          "matchedAttribute": {
            "identifier": "example_discount",
            "title": "example_discount"
          },
          "fragment": "test value",
          "langCode": "en_US"
        }
      ],
      "hasMore": false
    }
  ]
}

Esquema de resposta

Esquema: IGlobalSearchResponse

query: string
A consulta para a qual os resultados foram produzidos.
exemplo: "inverno"

groups: IGlobalSearchGroup[]
Registros encontrados agrupados por tipo de entidade.

groups.type: TGlobalSearchEntityType
Tipo de entidade do grupo.
exemplo: "products"

groups.items: IGlobalSearchItem[]
Registros encontrados dentro deste tipo de entidade.

groups.items.type: TGlobalSearchEntityType
Tipo de entidade do registro encontrado.
exemplo: "products"

groups.items.id: number | string
Id da entidade; uma string para fluxos de trabalho e atributos.
exemplo: 12345

groups.items.title: string
Título de exibição; ausente quando o registro não tem um nome próprio (pedidos, usuários sem login).
exemplo: "Jaqueta de inverno"

groups.items.identifier: string
Identificador de máquina (marcador) do registro.
exemplo: "jaqueta_inverno"

groups.items.subtitle: string
Linha secundária (url, armazenamento, nó).
exemplo: "catalogo/inverno"

groups.items.matchKind: TGlobalSearchMatchKind
Como o registro correspondeu à consulta.
exemplo: "title"

groups.items.matchedField: TGlobalSearchMatchedField
Campo concreto que correspondeu à consulta.
exemplo: "title"

groups.items.matchedAttribute: Record<string, unknown>
Atributo em que a correspondência ocorreu.

groups.items.fragment: string
Contexto em texto simples ao redor da correspondência, sem marcação.
exemplo: "jaqueta de inverno quente"

groups.items.langCode: string
Códigos de idioma do valor correspondente.
exemplo: "pt_BR"

groups.items.isVisible: boolean
Visibilidade do registro encontrado.
exemplo: true

groups.items.parent: Record<string, unknown>
Registro proprietário para entidades sem sua própria página (slides para bloco, pedidos para armazenamento).

groups.items.attributeSetId: number
Id do conjunto de atributos proprietário; apenas para tipo=attributes.
exemplo: 12

groups.hasMore: boolean
Se mais registros deste tipo estão disponíveis além da página solicitada.
exemplo: false

ℹ️ offset e limit requerem exatamente um tipo acessível em types; qualquer outra combinação responde 400. Omitir ambos para obter cada grupo na íntegra - veja Modo de detalhamento.

---