globalSearch

Public search across titles and attribute values of visible records.

Description

This method searches names and attribute values of records across entity types. It returns a Promise that resolves to an IGlobalSearchResponse object - the query it was run for, plus the found records grouped by entity type, each item carrying the context of how it matched.

Search.globalSearch(

query*, types, visibility, offset, limit

);

Parameters schema

Schema

query(required): string
Search query.
example: "winter"

types: TGlobalSearchEntityType[]
Entity types to search in, sent comma-separated. Searches every type when omitted.
example:

["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'
Visibility filter of the searched records. Default: "all"
example: "visible"

offset: number
Drilldown mode offset. Pass it only together with a single accessible type in types.
example: 0

limit: number
Drilldown mode page size. Pass it only together with a single accessible type in types, otherwise the API answers 400 "Drilldown mode (limit/offset) requires exactly one accessible type in types". Without it every group is returned in full.
example: 20

Examples

Minimal example

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

Example with attributes

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

Rendering the groups

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

Example response

{
  "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
    }
  ]
}

Response schema

Schema: IGlobalSearchResponse

query: string
The query the results were produced for.
example: "winter"

groups: IGlobalSearchGroup[]
Found records grouped by entity type.

groups.type: TGlobalSearchEntityType
Entity type of the group.
example: "products"

groups.items: IGlobalSearchItem[]
Records found within this entity type.

groups.items.type: TGlobalSearchEntityType
Entity type of the found record.
example: "products"

groups.items.id: number | string
Entity id; a string for workflows and attributes.
example: 12345

groups.items.title: string
Display title; absent when the record has no own name (orders, users without login).
example: "Winter jacket"

groups.items.identifier: string
Machine identifier (marker) of the record.
example: "winter_jacket"

groups.items.subtitle: string
Secondary line (url, storage, node).
example: "catalog/winter"

groups.items.matchKind: TGlobalSearchMatchKind
How the record matched the query.
example: "title"

groups.items.matchedField: TGlobalSearchMatchedField
Concrete field that matched the query.
example: "title"

groups.items.matchedAttribute: Record<string, unknown>
Attribute the match occurred in.

groups.items.fragment: string
Plain-text context around the match, no markup.
example: "warm winter jacket"

groups.items.langCode: string
Language code of the matched value.
example: "en_US"

groups.items.isVisible: boolean
Visibility of the found record.
example: true

groups.items.parent: Record<string, unknown>
Owning record for entities without their own page (slides to block, orders to storage).

groups.items.attributeSetId: number
Owning attribute set id; only for type=attributes.
example: 12

groups.hasMore: boolean
Whether more records of this type are available beyond the requested page.
example: false

ℹ️ offset and limit require exactly one accessible type in types; any other combination answers 400. Omit both to get every group in full - see Drilldown mode.

---